SimulatorInterface

class sim_explorer.simulator_interface.SimulatorInterface(system: Path | str = '', name: str | None = None, description: str = '', simulator: CosimExecution | None = None, log_level: CosimLogLevel = CosimLogLevel.FATAL)

Bases: object

Class providing the interface to the simulator itself. This is designed for OSP and needs to be overridden for other types of simulator.

Provides the following functions:

  • set_variable_value: Set variable values initially or at communication points

  • get_variable_value: Get variable values at communication points

  • match_components: Identify component instances based on (tuple of) (short) names

  • match_variables: Identify component variables of component (instance) matching a (short) name

A system model might be defined through an instantiated simulator or explicitly through the .fmu files. Unfortunately, an instantiated simulator does not seem to have functions to access the FMU, therefore only the (reduced) info from the simulator is used here (FMUs not used directly).

Parameters:

  • system (Path) – Path to system model definition file

  • name (str) – Possibility to provide an explicit system name (if not provided by system file)

  • description (str) – Optional possibility to provide a system description

  • simulator (CosimExecution) – Optional possibility to insert an existing simulator object. Otherwise this is generated through CosimExecution.from_osp_config_file().

  • log_level (CosimLogLevel) – Per default the level is set to FATAL, but it can be set to TRACE, DEBUG, INFO, WARNING, ERROR or FATAL (e.g. for debugging purposes)

__init__(system: Path | str = '', name: str | None = None, description: str = '', simulator: CosimExecution | None = None, log_level: CosimLogLevel = CosimLogLevel.FATAL)

Methods

__init__([system, name, description, ...])

allowed_action(action, comp, var, time)

Check whether the action would be allowed according to FMI2 rules, see FMI2.01, p.49.

component_id_from_name(name)

Get the component id from the name.

component_name_from_id(idx)

Retrieve the component name from the given index, or an empty string if not found.

default_initial(causality, variability[, ...])

Return default initial setting as int, as initial setting is not explicitly available in OSP.

get_components([model])

Provide a dict of { component_instances_name : model_ID, ...} in the system model.

get_models()

Get the list of basic models based on self.components.

get_variable_value(instance, typ, var_refs)

Provide an observer function which gets the 'variable' value (of the given 'instance' model) at the time when called.

get_variables(comp[, single, as_numbers])

Get the registered variables for a given component from the simulator.

is_output_var(comp, ref)

match_components(comps)

Identify component (instances) based on 'comps' (component alias or tuple of aliases).

match_variables(component, varname)

Based on an example component (instance), identify unique variables starting with 'varname'.

pytype(fmu_type[, val])

Return the python type of the FMU type provided as string or int (CosimEnums).

reset()

Reset the simulator interface, so that a new simulation can be run.

same_model(ref, refs)

set_initial(instance, typ, var_ref, var_val)

Provide an _initial_value set function (OSP only allows simple variables).

set_variable_value(instance, typ, var_refs, ...)

Provide a manipulator function which sets the 'variable' (of the given 'instance' model) to 'value'.

variable_name_from_ref(comp, ref)

Attributes

path

allowed_action(action: str, comp: int | str, var: int | str | tuple, time: float)

Check whether the action would be allowed according to FMI2 rules, see FMI2.01, p.49.

  • Unfortunately, the OSP interface does not explicitly provide the ‘initial’ setting, such that we need to assume the default value as listed on p.50.

  • OSP does not provide explicit access to ‘before initialization’ and ‘during initialization’. The rules for these two stages are therefore not distinguished

  • if a tuple of variables is provided, the variables shall have equal properties in addition to the normal allowed rules.

Parameters:

  • action (str) – Action type, ‘set’, ‘get’, including init actions (set at time 0)

  • comp (int,str) – The instantiated component within the system (as index or name)

  • var (int,str,tuple) – The variable(s) (of component) as reference or name

  • time (float) – The time at which the action will be performed

component_id_from_name(name: str) → int

Get the component id from the name. -1 if not found.

component_name_from_id(idx: int) → str

Retrieve the component name from the given index, or an empty string if not found.

static default_initial(causality: int, variability: int, max_possible: bool = False) → int

Return default initial setting as int, as initial setting is not explicitly available in OSP. See p.50 FMI2. maxPossible = True chooses the the initial setting with maximum allowance.

  • Causality: input=0, parameter=1, output=2, calc.par.=3, local=4, independent=5 (within OSP)

  • Initial: exact=0, approx=1, calculated=2, none=3.

get_components(model: int = -1) → dict

Provide a dict of { component_instances_name : model_ID, …} in the system model. For each component a unique ID per basic model (FMU) is used. In this way, if comps[x]==comps[y] the components x and y relate to the same basic model. If model != -1, only the components (instances) related to model are returned.

get_models() → list

Get the list of basic models based on self.components.

get_variable_value(instance: int, typ: int, var_refs: tuple[int, ...])

Provide an observer function which gets the ‘variable’ value (of the given ‘instance’ model) at the time when called.

Parameters:

  • instance (int) – identifier of the instance model for which the variable is to be set

  • var_refs (tuple) – Tuple of variable references for which the values shall be retrieved

get_variables(comp: str | int, single: int | str | None = None, as_numbers: bool = True) → dict

Get the registered variables for a given component from the simulator.

Parameters:

  • component (str, int) – The component name or its index within the model

  • single (int,str) – Optional possibility to return a single variable. If int: by valueReference, else by name.

  • as_numbers (bool) – Return the enumerations as integer numbers (if True) or as names (if False)

Returns:

A dictionary of variable {names

Return type:

info, …}, where info is a dictionary containing reference, type, causality and variability

is_output_var(comp: int, ref: int) → bool
match_components(comps: str | tuple[str, ...]) → tuple[str, tuple]

Identify component (instances) based on ‘comps’ (component alias or tuple of aliases). comps can be a (tuple of) full component names or component names with wildcards. Returned components shall be based on the same model.

match_variables(component: str, varname: str) → tuple[int]

Based on an example component (instance), identify unique variables starting with ‘varname’. The returned information applies to all instances of the same model. The variables shall all be of the same type, causality and variability.

Parameters:

  • component – component instance varname.

  • varname (str) – the varname to search for. This can be the full varname or only the start of the varname If only the start of the varname is supplied, all matching variables are collected.

Return type:

Tuple of value references

static pytype(fmu_type: str | int, val: str | float | int | bool | None = None)

Return the python type of the FMU type provided as string or int (CosimEnums). If val is None, the python type object is returned. Else if boolean, true or false is returned.

reset()

Reset the simulator interface, so that a new simulation can be run.

same_model(ref: int, refs: list[int] | set[int])
set_initial(instance: int, typ: int, var_ref: int, var_val: str | float | int | bool)

Provide an _initial_value set function (OSP only allows simple variables). The signature is the same as the manipulator functions slave_real_values()…, only that variables are set individually and the type is added as argument.

set_variable_value(instance: int, typ: int, var_refs: tuple[int], var_vals: tuple[str | float | int | bool]) → bool

Provide a manipulator function which sets the ‘variable’ (of the given ‘instance’ model) to ‘value’.

Parameters:

  • instance (int) – identifier of the instance model for which the variable is to be set

  • var_refs (tuple) – Tuple of variable references for which the values shall be set

  • var_vals (tuple) – Tuple of values (of the correct type), used to set model variables

variable_name_from_ref(comp: int | str, ref: int) → str
property path