SystemInterface

class sim_explorer.system_interface.SystemInterface(structure_file: Path | str = '', name: str | None = None, description: str = '', log_level: str = 'fatal', **kwargs: Any)

Bases: object

Class providing the interface to the system itself, i.e. system information, component interface information and the system co-simulation orchestrator (if simulations shall be run).

This model provides the base class and is able to read system and component information. To run simulations it must be overridden by a super class, e.g. SystemInterfaceOSP

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:

  • structure_file (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

  • log_level (str) – 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)

  • **kwargs –

    Optional possibility to supply additional keyword arguments:

    • full_simulator_available=True to overwrite the oposite when called from a superclass

__init__(structure_file: Path | str = '', name: str | None = None, description: str = '', log_level: str = 'fatal', **kwargs: Any) → None

Methods

__init__([structure_file, name, ...])

action_step(act_info, typ)

Pre-compile the step action and return the partial function so that it can be called at communication points.

add_actions(actions, act_type, cvar, ...[, rng])

Add specified actions to the provided action dict.

allowed_action(action, comp, var, time)

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

comp_model_var(cref, vref)

Find the component name and the variable names from the provided reference(s).

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.

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

Return default initial setting as str.

do_action(time, act_info, typ)

Do the action described by the tuple using OSP functions.

init_simulator()

Instantiate and initialize the simulator, so that simulations can be run.

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'.

model_from_component(comp)

Find the model name from the component name or index.

pytype(fmu_type[, val])

Return the python type of the FMU type provided as string.

read_system_structure(file, *[, fmus_exist])

Read the systemStructure file and perform checks.

run_until(time)

Instruct the simulator to simulate until the given time.

update_refs_values(allrefs, baserefs, ...)

Update baserefs and basevals with refs and values according to all possible refs.

variable_iter(variables, flt)

Get the variable dicts of the variables refered to by ids.

variable_name_from_ref(comp, ref)

Get the variable name from its component instant (id or name) and its valueReference.

variables(comp)

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

Attributes

models

path

action_step(act_info: tuple[str, str, tuple[int, ...]] | tuple[str, str, tuple[int, ...], tuple[int | float | bool | str, ...]], typ: type) → Callable[[...], Any]

Pre-compile the step action and return the partial function so that it can be called at communication points.

add_actions(actions: dict[float, list[tuple[str, str, tuple[int, ...]]]] | dict[float, list[tuple[str, str, tuple[int, ...], tuple[int | float | bool | str, ...]]]], act_type: str, cvar: str, cvar_info: dict[str, Any], values: tuple[int | float | bool | str, ...] | None, at_time: float, stoptime: float, rng: tuple[int, ...] | None = None) → None

Add specified actions to the provided action dict. The action list is simulator-agnostic and need ‘compilation’ before they are used in a simulation.

Parameters:

  • actions (dict) – actions (‘get’ or ‘set’) registered so far

  • act_type (str) – action type ‘get’, ‘step’ or ‘set’

  • cvar (str) – name of the case variable

  • cvar_info (dict) – dict of variable info: {model, instances, names, refs, type, causality, variability} see Cases.get_case_variables() for details.

  • values (TValue) – Optional values (mandatory for ‘set’ actions)

  • at_time (float) – time at which actions shall be triggered (may be scaled)

  • stoptime (float) – simulation stop time (needed to handle ‘step’ actions)

  • rng (Iterable) – Optional range specification for compound variables (indices to address)

Returns:

  • Updated actions dict, where the whole dict is specific for get/set and new actions are added as

  • {at_time ([ (cvar, component-name, (variable-name-list)[, value-list, rng])},)

  • where value-list and rng are only present for set actions

  • at-time=-1 for get actions denote step actions

allowed_action(action: str, comp: int | str, var: int | str | Sequence[int] | Sequence[str], time: float) → bool

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

  • 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

comp_model_var(cref: int, vref: int | tuple[int]) → tuple[str, str, list[str]]

Find the component name and the variable names from the provided reference(s).

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. Return an empty string if not found.

static default_initial(causality: str, variability: str, *, only_default: bool = True) → str | int | tuple[int] | tuple[str, ...]

Return default initial setting as str. See p.50 FMI2. With only_default, the single allowed value, or ‘’ is returned. Otherwise a tuple of possible values is returned where the default value is always listed first.

do_action(time: int | float, act_info: tuple[str, str, tuple[int, ...]] | tuple[str, str, tuple[int, ...], tuple[int | float | bool | str, ...]], typ: type) → bool

Do the action described by the tuple using OSP functions.

init_simulator() → bool

Instantiate and initialize the simulator, so that simulations can be run. Perforemd separately from __init__ so that it can be repeated before simulation runs.

match_components(comps: str | tuple[str, ...]) → tuple[str, tuple[str, ...]]

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[tuple[str, Any], ...]

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 tuples (name,value reference)

model_from_component(comp: str | int) → str

Find the model name from the component name or index.

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

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

static read_system_structure(file: Path, *, fmus_exist: bool = True) → dict[str, Any]

Read the systemStructure file and perform checks.

Return type:

The system structure as (json) dict as if the structure was read through osp_system_structure_from_js5

run_until(time: int | float) → bool

Instruct the simulator to simulate until the given time.

classmethod update_refs_values(allrefs: Sequence[int], baserefs: Sequence[int], basevals: Sequence[int | float | bool | str], refs: Sequence[int], values: Sequence[int | float | bool | str]) → tuple[tuple[int, ...], tuple[int | float | bool | str, ...]]

Update baserefs and basevals with refs and values according to all possible refs.

variable_iter(variables: dict[str, dict[str, Any]], flt: int | str | Sequence[int] | Sequence[str]) → Generator[tuple[str, dict[str, Any]], None, None]

Get the variable dicts of the variables refered to by ids.

Returns: Iterator over the dicts of the selected variables

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

Get the variable name from its component instant (id or name) and its valueReference.

variables(comp: str | int) → dict[str, dict[str, Any]]

Get the registered variables for a given component from the system. This is the default version which works without the full modelDescription inside self._models. Can be overridden by super-classes which have the modelDescription available.

Parameters:

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

Returns:

A dictionary of variable {names

Return type:

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

property models: dict[str, dict[str, Any]]
property path: Path