---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.13.8
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

(interaction)=

# Interacting with SHOP

+++

While the main functionality of SHOP lies in the SHOP core, several libraries are implemented for interacting with it. In this document the following ways of interaction are described.

```{contents}
:local:
```

Proprietary **ASCII** file formats used to be the only way for sending data to the SHOP core and getting results back. After introduction of the SHOP API, several open standards for interacting with the SHOP core have been added. Currently, the **pyshop** Python wrapper has gained popularity among users, students and developers. The new **YAML** file format is included as an open standard alternative to the ASCII format. All functionality in SHOP is accessible by any of these three ways of interacting with the core. By accessing the SHOP core through the API, as is done in pyshop and for YAML, all data that is loaded into the SHOP core can also be retrieved and stored. Figure 1 shows the different ways of interacting with SHOP.

+++

| ![](./img/shop_api.png)                                                             |
| ----------------------------------------------------------------------------------- |
| <b>Figure 1: A visualization of different interaction methods to and from SHOP.</b> |

+++

(proprietary-ascii-interaction)=

## Proprietary (ASCII) interaction

The proprietary interaction with SHOP is done by a set of **command**-files, **input data**-files and **output result**-files. The command files control which files are read into the SHOP core, which processing is done in the core, and which results files that are written from the SHOP core. Commands can also be entered directly in the built-in SHOP command interpreter. Input data files can include any of the [](ascii-data).

Commands are written in the format

command /(option1) /(option2) (object1) (object2)

Valid commands and related options and objects are found in the [](command-table).

ASCII files can be read directly by the SHOP core compiled as a standalone executable, or sent to the SHOP core via any of the APIs, either as a string or as a path to a file.

+++

(yaml-interaction)=

## YAML interaction

All input data, output data and commands are part of the same YAML structure. This structure is explained in the [](yaml-standard).
YAML files can be read and written directly by the SHOP core compiled as a standalone executable, or sent and retrieved via any of the APIs as strings. Note that YAML is an [open source standard](https://yaml.org/) which is not developed by SINTEF, but the way of defining SHOP input and output data in YAML is defined and maintained as part of the SHOP source code.

+++

(pyshop-interaction)=

## pyshop interaction

pyshop is a wrapper in Python written on top of the SHOP API functions exposed in the [pybind11](https://pybind11.readthedocs.io/en/stable/basics.html) translation layer between C++ and Python. It makes interacting with the SHOP core more efficient by providing helpful classes and functions to exchange data and execute commands. The data handling in pyshop uses the Python pandas package in most cases. pyshop is developed and maintained by SINTEF as an open source Python module, while pybind11 is an open source project for exposing C++ code in Python not developed by SINTEF.

The typical workflow in pyshop starts by creating a ShopSession and defining the optimization time and resolution. Next, the topology is added before time-dependent data is generated or loaded from files or a database. When all data is sent to the SHOP core, commands for optimization are executed before results are extracted. Note that it is possible to read and write to both ASCII and YAML files through pyshop, see the [](pyshop) specification for further details.

+++

(shop-server-interaction)=

## SHOP Server interaction

Not yet documented.

(cpp-api-interaction)=

## C++ API interaction

As indicated in Figure 1, it is possible to create a SHOP client in C/C++ that directly uses the inner SHOP API. The functions exposed in the SHOP API are defined in the shop_lib_interface.h header file which is part of the C-API distribution of all SHOP releases. A complete documentation of the functions are not yet available on the Portal.