SHOP C++ API reference

iLab Assistant

This is the reference documentation for the customer-facing C++ API declared in shop_lib_interface.h that is shipped with SHOP releases. All other ways of interfacing with SHOP will go through this API layer under the hood, but it is also possible to directly integrate SHOP in C++. The following code snippet shows a simple C++ program interfacing with SHOP:

#include <shop_lib_interface.h>

int main()
{
    // Create a SHOP model
    ShopSystem *libSys = ShopInit();

    // Set an hourly time resolution for 24 hours
    ShopSetTimeResolution(libSys, "202601010000", "202601020000", "hour");

    // Add objects and set input attributes
    int rsv_idx = ShopAddObject(libSys, "reservoir", "rsv1");
    int start_vol_idx = ShopGetAttributeIndex(libSys, "reservoir", "start_vol");
    if (ShopSetDoubleAttribute(libSys, rsv_idx, start_vol_idx, 10.2) == false)
    {
        // Handle issue if setting the attribute failed
    }
    // ...

    int plant_idx = ShopAddObject(libSys, "plant", "plant1");
    // ...

    // Connect rsv1 -> plant1
    ShopAddRelation(libSys, rsv_idx, "connection_standard", plant_idx);
    // ...

    // Execute commands
    ShopExecuteCommand(libSys, "set code /full");
    // ...

    // Get model results after optimization/simulation has finished
    int level_idx = ShopGetAttributeIndex(libSys, "reservoir", "level");
    std::string start_time;
    auto rsv_level = ShopGetTxyAttribute(libSys, rsv_idx, level_idx, start_time);
    if (!rsv_level)
    {
        // Handle issue if getting the attribute failed
    }
    else
    {
        // Unpack the t and y vectors of the timeseries
        const auto &[t, y] = *rsv_level;
    }
 
    // Release the SHOP model
    ShopFree(libSys);
    
    return 0;
}

Deprecated functions (marked SHOP_DEPRECATED_DANGEROUS / SHOP_DEPRECATED_BROKEN) are not documented here; they are listed in the Deprecated (not documented) appendix.

Common types¶

Global SHOP model handling¶

ShopSystem *ShopInit(bool silentConsole = true, bool silentLog = true, std::string_view license_path = "")¶

Creates and initializes a new SHOP system instance.

• silentConsole: true to suppress console output, false to print it.

• silentLog: true to suppress the log file, false to write it.

• license_path: Path to the SHOP license file (may be empty if set through environment variables).

Returns A pointer to the newly created ShopSystem, or throws ShopCoreException (“Unable to instantiate model”) if the model cannot be instantiated (typically a license problem).

bool ShopFree(ShopSystem* libSys)¶

Releases the SHOP system. Safe to call on a nullptr handle.

• libSys: The SHOP system to free (may be nullptr).

Returns true on success.

bool ShopFlushObjects(ShopSystem *libSys)¶

Removes all objects from the system and re-initializes the base system, clearing the current case while keeping the same handle.

Returns true on success. Throws ShopCoreException (“Unable to instantiate model”) if the re-initialization fails.

bool ShopSetSilentConsole(ShopSystem *libSys, bool silenceConsoleOutput)¶

Toggles whether console output from SHOP is suppressed.

• silenceConsoleOutput: true to silence the console, false to enable it.

Returns true.

bool ShopSetSilentLog(ShopSystem *libSys, bool suppressLogOutput)¶

Toggles whether SHOP writes its log file. Disabling it closes the open log file and clears the solver log name; re-enabling it restores the default solver log name for the active solver (cplex.log, gurobi.log, osi.log or highs.log) if none was set.

• suppressLogOutput: true to suppress log-file output, false to enable it.

Returns true.

void ShopAddDllPath(ShopSystem *libSys, const std::string_view dllPath)¶

Sets the path to shop_solver_interface.dll/.so to override default lookup paths (see the “Environment variables” section in the documentation).

• dllPath: Path to the solver interface dynamic library.

void ShopAddCplexDllPath(ShopSystem *libSys, const std::string_view dllPath)¶

Sets the path to the CPLEX solver DLL to override default lookup paths (see the “Environment variables” section in the documentation). Only applicable when running on Windows.

• dllPath: Path to the CPLEX dynamic library.

void ShopAddGurobiDllPath(ShopSystem *libSys, const std::string_view dllPath)¶

Sets the path to the Gurobi solver DLL to override default lookup paths (see the “Environment variables” section in the documentation). Only applicable when running on Windows.

• dllPath: Path to the Gurobi dynamic library.

std::string_view ShopGetVersionInfo()¶

Returns the SHOP core version string.

Returns The version string.

std::string_view ShopArmadilloVersion()¶

Returns the version of the Armadillo linear-algebra library in use.

Returns The Armadillo version string.

std::string_view ShopIntelMKLVersion()¶

Returns the version of the Intel MKL library in use.

Returns The MKL version string.

Time resolution¶

bool ShopSetTimeResolution(const ShopSystem *libSys, const char *startTime, const char *endTime, const char *timeUnit)¶

Sets the optimization horizon with a constant time resolution.

• startTime: Horizon start time (YYYYMMDDhhmmss).

• endTime: Horizon end time (YYYYMMDDhhmmss), strictly after startTime.

• timeUnit: Time unit: hour, minute, or second (case-insensitive).

Returns true on success. Throws on invalid input (end not after start, unknown time unit) when exceptions are enabled. Resetting the horizon on an already-configured model requires the SHOP_ONLINE_OPTIMIZATION functionality.

bool ShopSetTimeResolution(const ShopSystem *libSys, std::string_view start_time, std::string_view end_time, std::string_view time_unit, std::span<const int> t, std::span<const double> y)¶

Sets the optimization horizon, optionally with a non-constant time resolution step size. If t/y are empty a constant resolution is used. When a non-constant resolution is supplied, each y[i] step length must be integral in the chosen time_unit, and each segment must contain a whole number of intervals before the next t step (a warning is raised otherwise). Changing the horizon on an already-configured model resamples all time series and requires the SHOP_ONLINE_OPTIMIZATION functionality.

• start_time: Horizon start time (YYYYMMDDhhmmss).

• end_time: Horizon end time (YYYYMMDDhhmmss), strictly after start_time.

• time_unit: hour, minute, or second (case-insensitive).

• t: Optional interval indices at which the step length changes.

• y: Optional step length for each interval (must be integral in time_unit).

Returns true on success.

std::optional<shop_time_horizon> ShopGetTimeHorizon(const ShopSystem *libSys)¶

Returns the optimization horizon as a shop_time_horizon (start time, end time, time unit).

Returns The horizon, or std::nullopt if the time domain is not set (any of start/end/unit missing).

std::optional<shop_time_resolution> ShopGetTimeResolutionStepSize(const ShopSystem *libSys)¶

Returns the optimization time resolution as a shop_time_resolution (the interval t vector and step-length y vector).

Returns The resolution, or std::nullopt if the time resolution has not been set.

bool ShopSetTimeZone(ShopSystem *libSys, const char *timeZone)¶

Saves the time zone in the SHOP core. SHOP does not use any time zone information, but the user can set and retrieve the time zone for convenience.

• timeZone: The time zone to set.

Returns true.

std::string ShopGetTimeZone(const ShopSystem *libSys)¶

Returns the currently configured time zone.

Returns The time-zone string (empty if none has been set).

Commands¶

bool ShopExecuteCommand(ShopSystem *libSys, std::string_view command_string, std::span<const std::string> option_list, std::span<const std::string> value_list)¶

Executes a SHOP command given its name, options, and values separately. The executed command is recorded for later retrieval via ShopGetExecutedCommands.

• command_string: The command name (e.g. "start sim").

• option_list: Command options (leading / is not required).

• value_list: Positional values/arguments for the command.

Returns true on success. Throws ShopCoreException for an unknown command or option when exceptions are enabled. Returns early (as true) if the session has already been terminated.

bool ShopExecuteCommand(ShopSystem* libSys, const char* fullCommand)¶

Executes a complete SHOP command given as a single command string (e.g. "set code /incremental"): the command keywords are the first one or two words, words beginning with / are options (abbreviations to a unique prefix are accepted) and the remaining words are values. The executed command is recorded for later retrieval.

• fullCommand: The full command string.

Returns true on success. Throws ShopCoreException for an unparseable command or unknown command/option when exceptions are enabled.

bool ShopGetExecutedCommands(const ShopSystem *libSys, std::vector<std::string> &commands)¶

Returns the list of commands executed in this session as full command strings (out-parameter version).

• commands: Receives the executed command strings.

Returns true on success, false if libSys is nullptr.

std::vector<std::string> ShopGetExecutedCommands(const ShopSystem *libSys)¶

Returns the list of commands executed in this session as full command strings.

Returns The executed command strings.

std::vector<std::string> ShopGetCommandTypesInSystem(const ShopSystem *libSys)¶

Returns the list of commands recognized by SHOP.

Returns The available command strings.

Object types¶

int ShopGetObjectTypeCount(const ShopSystem *libSys)¶

Returns the number of object types defined in SHOP.

Returns The object-type count.

const char *ShopGetObjectTypeName(const ShopSystem *libSys, const int objectTypeIndex)¶

Returns the name of the object type at the given index.

• objectTypeIndex: The object-type index.

Returns The object-type name, or an empty string if the index is out of range.

int ShopGetObjectTypeIndex(const ShopSystem *libSys, const char *objectType)¶

Returns the index of the object type with the given name.

• objectType: The object-type name.

Returns The object-type index, or -1 if the type is unknown.

bool ShopGetObjectTypeIsInput(const ShopSystem *libSys, const int objectTypeIndex)¶

Reports whether the object type at the given index is an input object type that can be created by the user (output objects are automatically created by SHOP).

• objectTypeIndex: The object-type index.

Returns true if the object type is an input type.

bool ShopGetObjectTypeIsOutput(const ShopSystem *libSys, const int objectTypeIndex)¶

Reports whether the object type at the given index is an output object type that can only be automatically created by SHOP. Returns true only for object types that are not input types.

• objectTypeIndex: The object-type index.

Returns true if the object type is an output type.

bool ShopGetObjectTypeAttributeIndices(ShopSystem *libSys, const char *objectType, int &nAttributes, int *const attributeIndexList)¶

Writes the attribute indices belonging to the object type named objectType.

• objectType: The object-type name.

• nAttributes: In/out: the buffer capacity; on return, the number of attributes written.

• attributeIndexList: Output array that receives the attribute indices.

Returns true on success, false if the object type is unknown.

bool ShopGetObjectTypeAttributeIndices(ShopSystem *libSys, const int objectTypeIndex, int &nAttributes, int *const attributeIndexList)¶

Writes the attribute indices belonging to the object type at the given index.

• objectTypeIndex: The object-type index.

• nAttributes: In/out: the buffer capacity; on return, the number of attributes written.

• attributeIndexList: Output array that receives the attribute indices.

Returns true on success, false if the index is out of range.

Object handling¶

int ShopAddObject(ShopSystem *libSys, const int objectTypeIndex, const char *objectName)¶

Adds a new object of the given type index.

• objectTypeIndex: The index of the object type.

• objectName: Name for the new object.

Returns The index of the new object, -2 on a name conflict, or -1 if the object type index is invalid. Throws ShopCoreException on an invalid type/name conflict when exceptions are enabled.

int ShopAddObject(ShopSystem *libSys, const char *objectType, const char *objectName)¶

Adds a new object of the given type name and object name.

• objectType: The object-type name (e.g. "reservoir").

• objectName: Name for the new object.

Returns The index of the new object, -2 on a name conflict, or -1 if the object type is unknown.

bool ShopRemoveObject(ShopSystem* libSys, int objectIndex)¶

Removes an object of the index. Upon success, the indices for objects that were previously added after this object are decremented by one.

• objectIndex: The object index.

Returns true on success; false on failure when exceptions are disabled.

int ShopGetObjectCount(const ShopSystem *libSys)¶

Returns the number of objects currently in the SHOP model.

Returns The object count.

int ShopGetObjectIndex(ShopSystem *libSys, const char *objectType, const char *objectName)¶

Returns the index of the object with the given type and name.

• objectType: The object-type name.

• objectName: The object name.

Returns The object index, or -1 if the type or object is unknown. Throws ShopCoreException on an unknown type/object when exceptions are enabled.

const char *ShopGetObjectName(const ShopSystem *libSys, const int objectIndex)¶

Returns the name of the object at the given index.

• objectIndex: The object index.

Returns The object name.

bool ShopObjectIsDefined(ShopSystem* libSys, const char* objectType, const char* objectName)¶

Reports whether an object of the given type and name exists in the system.

• objectType: The object-type name.

• objectName: The object name.

Returns true if the object exists, false otherwise. Throws ShopCoreException if the object type is unknown.

const char *ShopGetObjectType(const ShopSystem *libSys, const int objectIndex)¶

Returns the type name of the object at the given index.

• objectIndex: The object index.

Returns The object-type name, or nullptr if libSys is nullptr or the index is out of range.

Attribute info¶

int ShopGetAttributeCount(const ShopSystem* libSys)¶

Returns the number of attribute types defined in SHOP.

Returns The attribute count.

int ShopGetAttributeIndex(const ShopSystem *libSys, const char *objectType, const char *attributeName)¶

Returns the index of the attribute with the given name for the given object type.

• objectType: The object-type name (e.g. "reservoir").

• attributeName: The attribute name (e.g. "start_vol").

Returns The attribute index. Throws ShopCoreException if the object type or attribute is unknown.

int ShopGetAttributeIndex(ShopSystem *libSys, int objectIndex, const char *attributeName)¶

Returns the index of the attribute with the given name for the given object.

• objectIndex: The object index.

• attributeName: The attribute name.

Returns The attribute index, or -1 if the object index is invalid or the attribute is unknown for the object’s type. Throws ShopCoreException in those cases when exceptions are enabled.

bool ShopResetAttributeToDefault(ShopSystem *libSys, std::size_t object_index, std::size_t attribute_index)¶

Resets the given attribute on the given object back to its default value.

• object_index: The object index.

• attribute_index: The attribute index.

Returns true on success, false on failure.

std::string ShopGetAttributeDatatype(const ShopSystem* libSys, int attributeIndex)¶

Returns the data-type name (e.g. "int", "double", "xy", "timeseries", etc.) for the attribute at the given index.

• attributeIndex: The attribute index.

Returns The data-type name, or an empty string if the index is invalid.

const char* ShopGetAttributeName(const ShopSystem* libSys, int attributeIndex)¶

Returns the name of the attribute at the given index.

• attributeIndex: The attribute index.

Returns The attribute name.

const char* ShopGetAttributeAlias(ShopSystem* libSys, int attributeIndex)¶

Returns the alias of the attribute at the given index.

• attributeIndex: The attribute index.

Returns The attribute alias.

void ShopGetAttributeXunit(ShopSystem* libSys, int attributeIndex, char* xUnit)¶

Writes the x-unit name for the attribute at the given index into the caller’s buffer.

• attributeIndex: The attribute index.

• xUnit: Output buffer that receives the unit name.

void ShopGetAttributeYunit(ShopSystem* libSys, int attributeIndex, char* yUnit)¶

Writes the y-unit name for the attribute at the given index into the caller’s buffer.

• attributeIndex: The attribute index.

• yUnit: Output buffer that receives the unit name.

const char* ShopGetAttributeLicenseName(ShopSystem* libSys, int attributeIndex)¶

Returns the name of the license required to use the attribute at the given index.

• attributeIndex: The attribute index.

Returns The license name (or the open-functionality marker if no license is required).

int ShopGetAttributeInfoMaxLength(ShopSystem* libSys, int attributeIndex)¶

Returns the maximum length (in characters) that attribute-info fields can hold.

• attributeIndex: The attribute index.

Returns The maximum field length.

void ShopGetAttributeInfo(ShopSystem* libSys, int attributeIndex, char* objectType, bool& isObjectParam, char* attributeName, char* alias, char* attributeDatatype, char* xUnit, char* yUnit, bool& isInput, bool& isOutput)¶

Fills the provided buffers with the description of the attribute type at the given index.

• attributeIndex: The attribute index.

• objectType: Receives the object-type name.

• isObjectParam: Deprecated, set to false.

• attributeName: Receives the attribute name.

• alias: Receives the attribute name alias.

• attributeDatatype: Receives the attribute data type.

• xUnit: Receives the x unit.

• yUnit: Receives the y unit.

• isInput: Set to true if the attribute is an input.

• isOutput: Set to true if the attribute is an output.

bool ShopAttributeIsInput(ShopSystem* libSys, int attributeIndex)¶

Reports whether the attribute at the given index is an input attribute.

• attributeIndex: The attribute index.

Returns true if the attribute is an input.

bool ShopAttributeIsOutput(ShopSystem* libSys, int attributeIndex)¶

Reports whether the attribute at the given index is an output attribute.

• attributeIndex: The attribute index.

Returns true if the attribute is an output or input/output.

bool ShopAttributeIsRequired(ShopSystem* libSys, int attributeIndex)¶

Reports whether the attribute at the given index is required.

• attributeIndex: The attribute index.

Returns true if the attribute is required.

bool ShopAttributeIsDefault(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reports whether the given attribute on the given object is still at its default value.

• objectIndex: The object index.

• attributeIndex: The attribute index.

Returns true if the value is the default (also true for out-of-range indices).

bool ShopCheckAttributeToSet(ShopSystem *libSys, int attributeIndex)¶

Checks whether the attribute at the given index may be set, considering its input/output flag and the available license. Emits a diagnostic warning on failure.

• attributeIndex: The attribute index.

Returns true if the attribute can be set, false otherwise (invalid index, output-only attribute, or missing license).

bool ShopCheckAttributeToGet(ShopSystem *libSys, int attributeIndex, bool suppressWarnings = false, bool allowInternal = true)¶

Checks whether the attribute at the given index may be read.

• attributeIndex: The attribute index.

• suppressWarnings: true to suppress diagnostic warnings on failure.

• allowInternal: true to also permit reading internal attributes (default, requires a SINTEF internal license).

Returns true if the attribute can be read, false otherwise.

const char *ShopGetAttributeTypeDescription(ShopSystem *libSys, int attributeIndex)¶

Returns the description text for the attribute type at the given index.

• attributeIndex: The attribute index.

Returns The description string, or a “could not retrieve” message if the index is invalid.

const char *ShopGetAttributeTypeVersionAdded(ShopSystem *libSys, int attributeIndex)¶

Returns the SHOP version in which the attribute type at the given index was added.

• attributeIndex: The attribute index.

Returns The version string, or an empty string if the index is invalid.

const char *ShopGetAttributeDefaultValue(const ShopSystem *libSys, int attributeIndex)¶

Returns the default value (as a string) for the attribute type at the given index.

• attributeIndex: The attribute index.

Returns The default value string, or an empty string if the index is invalid.

bool ShopGetAttributeIsRequired(ShopSystem *libSys, int attributeIndex)¶

Reports whether the attribute type at the given index is required.

• attributeIndex: The attribute index.

Returns true if the attribute is required, false otherwise (also false for an invalid index).

bool ShopAttributeExists(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reports whether a value has been set for the given attribute on the given object. int and double attributes always exist; other types are checked for actual stored data.

• objectIndex: The object index.

• attributeIndex: The attribute index.

Returns true if the attribute has a value for the object, false otherwise (also false for out-of-range indices).

int attributes¶

bool ShopSetIntAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, int attributeValue)¶

Sets an int attribute value on an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValue: The value to store.

Returns true on success, false if the indices are invalid or the attribute can’t be set (output-only / no license).

bool ShopGetIntAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, int &attributeValue)¶

Reads an int attribute value from an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValue: Receives the attribute value.

Returns true on success, false if the indices are invalid or the attribute can’t be read.

std::optional<int> ShopGetIntAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads an int attribute value from an object.

Returns The value, or std::nullopt if the indices are invalid or the attribute can’t be read.

int_array attributes¶

bool ShopSetIntArrayAttribute(ShopSystem* libSys, int objectIndex, int attributeIndex, const std::span<const int> attributeValues)¶

Sets an int_array attribute value on an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValues: The values to store.

Returns true on success, false if the indices are invalid, the span is empty, or the attribute can’t be set.

std::optional<std::vector<int>> ShopGetIntArrayAttribute(ShopSystem* libSys, int objectIndex, int attributeIndex)¶

Reads an int_array attribute value from an object.

Returns The vector of values, or std::nullopt if the indices are invalid or the attribute can’t be read. May return an empty vector if no data is set.

double attributes¶

bool ShopSetDoubleAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, double attributeValue)¶

Sets a double attribute value on an object. If the value is NaN and the attribute does not permit NaN, a diagnostic is raised and the call fails.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValue: The value to store.

Returns true on success, false if the indices are invalid, the attribute can’t be set, or a non-NaN-permitted attribute was given NaN.

bool ShopGetDoubleAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, double &attributeValue)¶

Reads a double attribute value from an object (out-parameter version).

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValue: Receives the attribute value.

Returns true on success, false if the indices are invalid or the attribute can’t be read.

std::optional<double> ShopGetDoubleAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads a double attribute value from an object.

Returns The value, or std::nullopt if the indices are invalid or the attribute can’t be read.

double_array attributes¶

bool ShopSetDoubleArrayAttribute(ShopSystem* libSys, int objectIndex, int attributeIndex, std::span<const double> attributeValues)¶

Sets a double_array attribute value on an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValues: The values to store.

Returns true on success, false if the indices are invalid, the span is empty, or the attribute can’t be set.

std::optional<std::vector<double>> ShopGetDoubleArrayAttribute(ShopSystem* libSys, int objectIndex, int attributeIndex)¶

Reads a double_array attribute value from an object.

Returns The vector of values, or std::nullopt if the indices are invalid or the attribute can’t be read. May return an empty vector if no data is set.

xy attributes¶

bool ShopSetXyAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, double refValue, std::span<const double> x, std::span<const double> y)¶

Sets an xy curve attribute (reference value plus x/y value vectors) on an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• refValue: The reference value for the curve.

• x: The x-values.

• y: The y-values (must have the same size as x).

Returns true on success, false if the indices are invalid, the span is empty, or the x/y sizes differ.

std::optional<shop_xy_vectors> ShopGetXyAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, double &refValue)¶

Reads an xy curve attribute (the x/y value vectors) and its reference value from an object.

• refValue: Output: receives the reference value.

Returns The (x, y) vector pair, or std::nullopt if the indices are invalid, the curve is empty, or x/y sizes differ.

std::optional<std::vector<double>> ShopGetXyAttributeXValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads only the x-values of an xy curve attribute.

Returns The x-value vector, or std::nullopt if the indices are invalid or the curve is empty.

std::optional<std::vector<double>> ShopGetXyAttributeYValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads only the y-values of an xy curve attribute.

Returns The y-value vector, or std::nullopt if the indices are invalid or the curve is empty.

std::optional<double> ShopGetXyAttributeRefValue(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads the reference value of an xy curve attribute.

Returns The reference value, or std::nullopt if the indices are invalid or the curve is empty.

sy attributes¶

bool ShopSetSyAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, std::span<const shop_sy_pair> values)¶

Sets an sy attribute (a list of string to double pairs) on an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• values: The (string, double) pairs to store.

Returns true on success, false if the indices are invalid, the span is empty, or the attribute can’t be set.

bool ShopGetSyAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, std::vector<shop_sy_pair> &values)¶

Reads an sy attribute (a list of string to double pairs) from an object into the provided vector (out-parameter version).

• objectIndex: The object index.

• attributeIndex: The attribute index.

• values: Receives the (string, double) pairs.

Returns true on success, false if the indices are invalid or the attribute is empty/unavailable.

std::optional<std::vector<shop_sy_pair>> ShopGetSyAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads an sy attribute (a list of string to double pairs) from an object.

Returns The vector of (string, double) pairs, or std::nullopt if the indices are invalid or the attribute is empty/unavailable.

xy_array attributes¶

bool ShopSetXyArrayAttribute(ShopSystem* libSys, int objectIndex, int attributeIndex, std::span<const double> refValues, std::span<const std::vector<double>> x_values_list, std::span<const std::vector<double>> y_values_list)¶

Sets an xy_array attribute (a list of xy curves) on an object. The curves are sorted by ascending reference value before storage.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• refValues: One reference value per curve.

• x_values_list: One x-value vector per curve.

• y_values_list: One y-value vector per curve.

Returns true on success, false if the indices are invalid, the lists have mismatched sizes, or any curve is empty.

std::optional<std::vector<int>> ShopGetXyArrayAttributeDimensions(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Returns the number of points in each curve of an xy_array attribute.

Returns A vector with one entry per curve (the point count), or std::nullopt if the indices are invalid, the array is empty, or any curve is empty.

std::optional<shop_xy_array_vectors> ShopGetXyArrayAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads an xy_array attribute (a list of xy curves) from an object.

Returns The (vector of x-value vectors, vector of y-value vectors, vector of reference values) tuple, or std::nullopt if the components are missing or inconsistent in size.

std::optional<std::vector<std::vector<double>>> ShopGetXyArrayAttributeXValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads the x-values of every curve in an xy_array attribute.

Returns A vector of x-value vectors (one per curve), or std::nullopt if the indices are invalid or any curve is empty.

std::optional<std::vector<std::vector<double>>> ShopGetXyArrayAttributeYValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads the y-values of every curve in an xy_array attribute.

Returns A vector of y-value vectors (one per curve), or std::nullopt if the indices are invalid or any curve is empty.

std::optional<std::vector<double>> ShopGetXyArrayAttributeRefValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads the reference value of every curve in an xy_array attribute.

Returns A vector of reference values (one per curve), or std::nullopt if the indices are invalid or any curve is empty.

timeseries (TXY) attributes¶

bool ShopSetTxyAttribute(ShopSystem* libSys, int objectIndex, int attributeIndex, std::string_view startTime, std::span<const int> t, std::span<const std::vector<double>> y)¶

Sets a timeseries attribute on an object. y may hold a single scenario or exactly the same number of scenarios as there are scenario objects in the SHOP model (for a stochastic series). NaN values are rejected for attributes that do not permit NaN (a diagnostic is raised).

• objectIndex: The object index.

• attributeIndex: The attribute index.

• startTime: Start time of the series.

• t: The time steps.

• y: One value vector per scenario (each must match t’s size).

Returns true on success, false if the indices are invalid, the sizes are inconsistent, the scenario count is invalid, or a NaN-disallowed attribute was given NaN.

std::optional<std::string> ShopGetTxyAttributeStartTime(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Returns the start time of a timeseries attribute.

Returns The start-time string, or std::nullopt if the indices are invalid or the series is unavailable.

std::string ShopGetTxyAttributeTimeUnit(const ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Returns the time unit of a timeseries attribute.

Returns "hour", "minute", or "second", or an empty string if the indices are invalid or the series is unavailable. Throws ShopCoreException for an unrecognized internal time unit.

std::optional<shop_timeseries_vectors> ShopGetTxyAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, std::string &start_time)¶

Reads a timeseries attribute (the t vector and the per-scenario y vectors) plus its start time.

• start_time: Output: receives the start-time string of the timeseries.

Returns The (t, y) vector pair, or std::nullopt if the components are missing or inconsistent.

std::optional<std::vector<int>> ShopGetTxyAttributeTimeSteps(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Returns the time steps of a timeseries attribute. Historical values are scaled to the model time unit (hour/minute) and prepended to the optimization horizon steps.

Returns The t vector, or std::nullopt if the indices are invalid or the series is unavailable.

std::optional<std::vector<std::vector<double>>> ShopGetTxyAttributeValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Returns the per-scenario values of a timeseries attribute, with historical values prepended.

Returns A vector of per-scenario value vectors, or std::nullopt if the indices are invalid or the series is unavailable.

string attributes¶

bool ShopSetStringAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, const char *attributeValue)¶

Sets a string attribute value on an object (C-string version).

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValue: The string to store.

Returns true on success, false if the indices are invalid or the attribute can’t be set.

bool ShopSetStringAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, std::string_view attributeValue)¶

Sets a string attribute value on an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValue: The string to store.

Returns true on success, false if the indices are invalid or the attribute can’t be set.

bool ShopGetStringAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, std::string &attributeValue)¶

Reads a string attribute value from an object (out-parameter version).

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValue: Receives the attribute value.

Returns true on success, false if the indices are invalid or the attribute can’t be read.

std::optional<std::string> ShopGetStringAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads a string attribute value from an object.

Returns The value, or std::nullopt if the indices are invalid, the attribute can’t be read, or it is empty.

string_array attributes¶

bool ShopSetStringArrayAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, std::span<const std::string> attributeValues)¶

Sets a string_array attribute value on an object.

• objectIndex: The object index.

• attributeIndex: The attribute index.

• attributeValues: The strings to store.

Returns true on success, false if the indices are invalid, the span is empty, or the attribute can’t be set.

std::optional<std::vector<std::string>> ShopGetStringArrayAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads a string_array attribute value from an object.

Returns The vector of strings, or std::nullopt if the indices are invalid or the attribute can’t be read.

xyt attributes¶

bool ShopSetXytAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex, std::span<const std::string> timeStrings, std::span<const std::vector<double>> x_values_list, std::span<const std::vector<double>> y_values_list)¶

Sets an xyt attribute — a set of xy curves, each keyed by a time string — on an object. NaN values are rejected for attributes that do not permit NaN (a diagnostic is raised).

• objectIndex: The object index.

• attributeIndex: The attribute index.

• timeStrings: One time string per curve.

• x_values_list: One x-value vector per curve.

• y_values_list: One y-value vector per curve.

Returns true on success, false if the indices are invalid, the lists are inconsistent, a curve is empty, or a NaN-disallowed attribute was given NaN.

std::optional<shop_xyt_vectors> ShopGetXytAttribute(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads an xyt attribute (a set of xy curves keyed by time string) from an object.

Returns The (vector of x-value vectors, vector of y-value vectors, vector of timestamps) tuple, or std::nullopt if the components are missing or inconsistent in size.

std::optional<std::vector<std::vector<double>>> ShopGetXytAttributeXValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads the x-values of every curve in an xyt attribute (empty curves are skipped).

Returns A vector of x-value vectors, or std::nullopt if the indices are invalid or the attribute is empty.

std::optional<std::vector<std::vector<double>>> ShopGetXytAttributeYValues(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Reads the y-values of every curve in an xyt attribute (empty curves are skipped).

Returns A vector of y-value vectors, or std::nullopt if the indices are invalid or the attribute is empty.

std::optional<std::vector<int>> ShopGetXytTimesIntArray(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Returns the time index of every curve in an xyt attribute (empty curves are skipped).

Returns The vector of time indices, or std::nullopt if the indices are invalid or the attribute is unavailable.

std::optional<std::vector<std::string>> ShopGetXytTimesStringArray(ShopSystem *libSys, int objectIndex, int attributeIndex)¶

Returns the time string of every curve in an xyt attribute (empty curves are skipped).

Returns The vector of time strings, or std::nullopt if the indices are invalid or the attribute is empty.

bool ShopGetXytAttributeNPoints(ShopSystem *libSys, int objectIndex, int attributeIndex, int &nPoints, int t)¶

Returns the number of points in the xy curve of an xyt attribute at the given time index.

• nPoints: Output: receives the point count.

• t: The time index of the curve to query.

Returns true on success, false if the indices are invalid or no curve exists at time t.

int ShopConvertStringToTimeIndex(ShopSystem *libSys, std::string_view time)¶

Converts a time string to an optimization time index.

• time: The time string (YYYYMMDDhhmmss).

Returns The 1-based time index, -1 if the time is before the optimization start, or -2 if it is after the optimization end.

Connections¶

bool ShopAddRelation(ShopSystem* libSys, int objectIndex, const char* relationType, int relatedIndex)¶

Adds a connection (relation) from objectIndex to relatedIndex. The relation type selects the connection kind: "connection_bypass"/"bypass" and "connection_spill"/"spill" must be used when connecting the deprecated gate object as a bypass or spill gate to the upstream reservoir, any other connection should use "connection_standard"/"standard".

• objectIndex: The source object index.

• relationType: The relation/connection type.

• relatedIndex: The target object index.

Returns true on success, false on failure.

bool ShopRemoveRelation(const ShopSystem *libSys, int objectIndex, int relatedIndex)¶

Removes a connection (relation) from objectIndex to relatedIndex.

• objectIndex: The source object index.

• relationType: The relation/connection type.

• relatedIndex: The target object index.

Returns true on success, false on failure.

std::vector<int> ShopGetInputRelations(const ShopSystem *libSys, int objectIndex, std::string_view relationType)¶

Returns the indices of objects connected into objectIndex of the given relation type. For the default (standard) type, logical relations are included in addition to standard connections.

• objectIndex: The object index.

• relationType: "connection_bypass", "connection_spill", or any other value for standard connections.

Returns A vector of related object indices (empty for an invalid input).

std::vector<int> ShopGetOutputRelations(const ShopSystem *libSys, int objectIndex, std::string_view relationType)¶

Returns the indices of objects connected out of objectIndex of the given relation type. For the default (standard) type, logical relations are included in addition to standard connections.

• objectIndex: The object index.

• relationType: "connection_bypass", "connection_spill", or any other value for standard connections.

Returns A vector of related object indices (empty for an invalid input).

std::vector<int> ShopGetRelations(const ShopSystem *libSys, int objectIndex, std::string_view relationType)¶

Alias for ShopGetOutputRelations: returns the indices of objects connected out of objectIndex.

Returns A vector of related object indices.

bool ShopGetRelationTypesDimensions(ShopSystem* libSys, const char* objectType, int& nRelationTypes, int& maxStringLength)¶

Returns the number of relation types defined for an object type and the length of the longest relation-type name.

• objectType: The object-type name.

• nRelationTypes: Receives the number of relation types.

• maxStringLength: Receives the length of the longest relation-type name.

Returns true if the object type is known. Throws ShopCoreException if the object type is unknown and exceptions are enabled.

std::vector<std::string> ShopGetRelationTypes(ShopSystem *libSys, const char *object_type)¶

Returns the list of relation types available for the given object type.

• object_type: The object-type name.

Returns The list of relation-type strings. Throws ShopCoreException for an unknown object type.

const char* ShopGetDefaultRelationType(const char* fromObjectType, const char* toObjectType)¶

Returns the default relation type used between two object types.

• fromObjectType: The source object-type name.

• toObjectType: The target object-type name.

Returns The default relation-type name.

std::optional<std::string> ShopGetRelationCategory(ShopSystem *libSys, int fromObjectTypeIndex, int toObjectTypeIndex)¶

Returns the relation category for a connection between two object types.

• fromObjectTypeIndex: The source object-type index.

• toObjectTypeIndex: The target object-type index.

Returns The relation-category string, or std::nullopt if libSys is null, either object type is invalid, or the pair has no defined relation.

Serialization¶

bool ShopSaveState(const ShopSystem* libSys, const std::filesystem::path& filePath, bool partial = false)¶

Saves the SHOP model state to a binary file. Requires the SHOP_ONLINE_OPTIMIZATION license.

• filePath: Destination file path (must not be a directory).

• partial: If true, save only the partial state which makes the user responsible for reconstructing the time horizon, objects, connections, and setting all input and output attributes when loading the state at a later point in time; otherwise the full state. The value of the partial argument must match between the call to save and load the state.

Returns true on success, false on failure (missing license, path is a directory, or I/O error). Throws ShopCoreException on failure when exceptions are enabled.

std::optional<std::vector<std::byte>> ShopSaveState(const ShopSystem* libSys, bool partial = false)¶

Saves the SHOP model state to an in-memory byte buffer. Requires the SHOP_ONLINE_OPTIMIZATION license.

• partial: If true, save only the partial state which makes the user responsible for reconstructing the time horizon, objects, connections, and setting all input and output attributes when loading the state at a later point in time; otherwise the full state. The value of the partial argument must match between the call to save and load the state.

Returns The serialized state bytes, or std::nullopt on failure. Throws ShopCoreException on failure when exceptions are enabled.

bool ShopLoadState( ShopSystem* libSys, const std::filesystem::path& filePath, bool partial = false)¶

Loads SHOP model state from a binary file. Requires the SHOP_ONLINE_OPTIMIZATION license.

• filePath: Source file path (must not be a directory).

• partial: If true, load only the partial state after the user has set the time horizon, objects, connections, and input and output attributes; otherwise the full model is recreated. The value of the partial argument must match between the call to save and load the state.

Returns true on success, false on failure. Throws ShopCoreException on failure when exceptions are enabled.

bool ShopLoadState( ShopSystem* libSys, std::span<const std::byte> state, bool partial = false)¶

Loads SHOP model state from an in-memory byte buffer. Requires the SHOP_ONLINE_OPTIMIZATION license.

• state: The serialized state bytes.

• partial: If true, load only the partial state after the user has set the time horizon, objects, connections, and input and output attributes; otherwise the full state. The value of the partial argument must match between the call to save and load the state.

Returns true on success, false on failure. Throws ShopCoreException on failure when exceptions are enabled.

bool ShopDumpYamlString(ShopSystem* libSys, char* yamlString, int& allocSize, bool inputOnly, bool outputOnly, bool compressTxy, bool compressConnection, bool escapeNonASCII)¶

Serializes the model to a YAML string. If yamlString is nullptr, allocSize is set to the required buffer size and true is returned; otherwise the YAML is written if the buffer is large enough (with allocSize updated on failure).

• yamlString: Output buffer (or nullptr to query the required size).

• allocSize: In/out: buffer size; updated to the required size if the buffer was too small.

• inputOnly: Include only input data.

• outputOnly: Include only output data.

• compressTxy: Compress timeseries data.

• compressConnection: Compress connection data.

• escapeNonASCII: Escape non-ASCII characters.

Returns true if the YAML was written (or the size was queried), false if the buffer was too small.

bool ShopSetAsciiFileString(ShopSystem *libSys, const char *fileAsString)¶

Sets the contents of an ASCII data file as a string so it can later be parsed.

• fileAsString: The full contents of the ASCII data file.

Returns true.

bool ShopReadAsciiStringFile(ShopSystem *libSys)¶

Parses the ASCII data file previously set with ShopSetAsciiFileString, then clears the stored string.

Returns true.

Licenses¶

std::vector<std::string> ShopGetLicenses(const ShopSystem *libSys)¶

Returns the list of licenses currently active for this SHOP session.

Returns The active license strings (empty if libSys is nullptr).

Log messages¶

bool ShopGetProgress(const ShopSystem *libSys, std::vector<std::string>& descriptionList, std::vector<int>& percentList, std::vector<long long>& timestampList, std::vector<std::string>& severityList, std::vector<int>& codeList)¶

Drains and returns all progress messages that have been written to the log file (unless it is disabled). The progress list is cleared after the call, so each message is delivered exactly once.

• descriptionList: Output: message description texts.

• percentList: Output: completion percentages.

• timestampList: Output: message timestamps (seconds).

• severityList: Output: severity codes.

• codeList: Output: message codes.

Returns true on success.

int ShopGetMessageCallCount(const ShopSystem *libSys, int codeNumber)¶

Returns the number of times the log message with the given code has been emitted.

• codeNumber: The log message code.

Returns The call count.

const char *ShopGetMessageText(const ShopSystem *libSys, int messageNumber)¶

Returns the template text for the log message with the given code.

• messageNumber: The log message code.

Returns The log message text.

int ShopGetMessageType(const ShopSystem *libSys, int messageNumber)¶

Returns the numeric type of the log message with the given code.

• messageNumber: The log message code.

Returns The log message-type code (see ShopMessageTypeToString).

const char *ShopGetMessageTypeString(const ShopSystem *libSys, int messageNumber)¶

Returns the string name of the log message type for the given code.

• messageNumber: The log message code.

Returns The type string (e.g. "OK", "WARNING", "ERROR").

const char* ShopMessageTypeToString(int messageTypeCode)¶

Converts a numeric log message-type code to its string name.

• messageTypeCode: The type code.

Returns "OK", "DIAG OK", "DIAG WARNING", "WARNING", "DIAG ERROR", or "ERROR"; nullptr for an unrecognized code.

std::vector<int> ShopGetAllMessageCodes(const ShopSystem *libSys)¶

Returns the codes of all log messages known to SHOP.

Returns The log message codes (empty if libSys is nullptr).

std::vector<std::string> ShopGetAllMessageTexts(const ShopSystem *libSys)¶

Returns the template texts of all log messages known to SHOP.

Returns The log message texts (empty if libSys is nullptr).

std::vector<std::string> ShopGetAllMessageTypes(const ShopSystem *libSys)¶

Returns the type strings of all log messages known to SHOP.

Returns The log message-type strings (empty if libSys is nullptr).

std::vector<int> ShopGetAllMessageCallCounts(const ShopSystem *libSys)¶

Returns the call counts of all log messages known to SHOP.

Returns The per-message call counts (empty if libSys is nullptr).

std::vector<std::string> ShopGetPrintedMessagesForCode(const ShopSystem *libSys, int code)¶

Returns the concrete (formatted) log messages that have been printed for the given code.

• code: The log message code.

Returns The printed log message strings (empty if libSys is nullptr or no such message).

Deprecated (not documented)¶

Functions marked SHOP_DEPRECATED_DANGEROUS / SHOP_DEPRECATED_BROKEN. They are excluded from the reference above.