Model

class component_model.model.Model(name, description: str = 'A component model', author: str = 'anonymous', version: str = '0.1', unit_system='SI', license: str | None = None, copyright: str | None = None, default_experiment: dict[str, float] | None = None, flags: dict | None = None, guid=None, **kwargs)

Bases: Fmi2Slave

Defines a model complying to the FMI standard, including some common model concepts, like variables and units. The package extends the PythonFMU package.

The model interface and the inner working of the model is missing here and must be defined in a given application, extending Model.

A fully defined model shall at least:

  • Define a full set of interface variables, including default start values, setter and getter functions. See variable module.

  • Extend the do_step(time, dt) member function, running the application model in isolation for a time interval. Make sure that super().do_step(time, dt) is always called first in the extended function.

  • Optionally extend any other fmi2 function, i.e.

    • def setup_experiment(self, start)

    • def enter_initialization_mode(self):

    • def exit_initialization_mode(self):

    • def terminate(self):

The following FMI concepts are (so far) not implemented:

  • TypeDefinitions. Instead of defining SimpleType variables, ScalarVariable variables are always based on the pre-defined types and details provided there.

  • Explicit <Derivatives> (see <ModelStructure>) are so far not implemented. This could be done as an additional (optional) property in Variable.

Parameters:

  • name (str) – name of the model. The name is also used to construct the FMU file name.

  • author (str) – The author of the model

  • version (str) – The version number of the model

  • unit_system (str) – The unit system to be used. self.ureg.default_system contains this information for all variables

  • license (str) – License text or file name (relative to source files). If None, the BSD-3-Clause license as also used in the component_model package is used, with a modified copyright line

  • copyright (str) – Copyright line for use in full license text. If None, an automatic copyright line is constructed from the author name and the file date.

  • default_experiment (dict) – key/value dictionary for the default experiment setup. Valid keys: startTime,stopTime,stepSize,tolerance

  • guid (str) – Unique identifier of the model (supplied or automatically generated)

  • flags (dict) – Any of the defined FMI flags with a non-default value (see FMI 2.0.4, Section 4.3.1)

__init__(name, description: str = 'A component model', author: str = 'anonymous', version: str = '0.1', unit_system='SI', license: str | None = None, copyright: str | None = None, default_experiment: dict[str, float] | None = None, flags: dict | None = None, guid=None, **kwargs)

Methods

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

add_derivative(var, order)

Add the derivative of var to the exposed Variables as virtual variable.

add_variable(*args, **kwargs)

Add a variable, automatically including the owner model in the instantiation call.

build([script, project_files, dest, ...])

Build the FMU, resulting in the model-name.fmu file.

check_flags(flags)

Check and collect provided flags dictionary and return the non-default flags.

dirty_do()

Run on_set on all dirty variables.

dirty_ensure(var)

Ensure that the variable var is registered in self._dirty.

do_step(current_time, step_size)

Do a simulation step of size 'step_size at time 'currentTime.

ensure_requirements(existing_file, temp_file)

Return the path to the component-model requirements file.

enter_initialization_mode()

exit_initialization_mode()

Initialize the model after initial variables are set.

get_boolean(vrs)

get_integer(vrs)

get_real(vrs)

get_string(vrs)

log(msg[, status, category, debug])

Log a message to the FMU logger.

make_copyright_license([copyright, license])

Prepare a copyright notice (one line) and a license text (without copyright line).

owner_hierarchy(parent)

Analyse the parent of a variable down to the Model and return the owners as list.

ref_to_var(vr)

Find Variable and sub-index (for compound variable), based on a value_reference value.

register_variable(var[, nested])

Register a variable as FMU interface.

set_boolean(vrs, values)

set_integer(vrs, values)

set_real(vrs, values)

set_string(vrs, values)

setup_experiment([start_time])

Minimum version of setup_experiment, just setting the start_time.

terminate()

to_xml([model_options])

Build the XML FMI2 modelDescription.xml tree.

variable_by_name(name)

Return Variable object related to name, or None, if not found.

vars_iter([key])

Iterate over model variables ('vars').

xml_unit_definitions()

Make the xml element for the unit definitions used in the model.

Attributes

dirty

instances

log_categories

units

static build(script: str | Path = '', project_files: list[str | Path] | None = None, dest: str | PathLike[str] = '.', documentation_folder: Path | None = None, newargs: dict | None = None)

Build the FMU, resulting in the model-name.fmu file.

!!Note: Since the build process is linked to the script and not to the class, it is currently not possible to define several FMUs in one script. Max 1 per file.

Parameters:

  • script (str) – The scriptfile (xxx.py) in which the model class is defined. This file if “”

  • project_files (list) – Optional list of additional files to include in the build (relative to script)

  • dest (str) – Optional destination folder for the FMU.

  • documentation_folder (Path) – Optional folder with additional model documentation files.

  • newargs (dict) – Optional possibility to provide new keyword arguments to the model class

static check_flags(flags: dict | None)

Check and collect provided flags dictionary and return the non-default flags. Any of the defined FMI flags with a non-default value (see FMI 2.0.4, Section 4.3.1). .. todo:: Check also whether the model actually provides these features.

static ensure_requirements(existing_file: str | Path | None, temp_file: Path) → Path

Return the path to the component-model requirements file.

add_derivative(var: Variable, order: int)

Add the derivative of var to the exposed Variables as virtual variable.

This is convenient as many physical systems do not tolerate to abruptly change variable values, but require to ramp up/down values by setting the derivative to suitable values. This can be achieved without adding an internal variable to the model. The model will in this case do the ramping when the derivative is set != 0.0.

add_variable(*args, **kwargs)

Add a variable, automatically including the owner model in the instantiation call. The function represents an alternative method for defining interface variables automatically adding the mandatory first model argument.

dirty_do()

Run on_set on all dirty variables.

dirty_ensure(var: Variable)

Ensure that the variable var is registered in self._dirty.

The dirty mechanism is used when elements of compound variables are changed and a on_set function is defined, such that on_set() is run exactly once and when all elements are changed.

abstractmethod do_step(current_time: float, step_size: float) → bool

Do a simulation step of size ‘step_size at time ‘currentTime. Note: this is only the generic part of this function. Models should call this first through super().do_step and then do their own stuff.

enter_initialization_mode()
exit_initialization_mode()

Initialize the model after initial variables are set.

get_boolean(vrs: Sequence[int])
get_integer(vrs: Sequence[int])
get_real(vrs: Sequence[int])
get_string(vrs: Sequence[int])

Prepare a copyright notice (one line) and a license text (without copyright line). If license is None, the license text of the component_model package is used (BSD-3-Clause). If copyright is None, a copyright text is construced from self.author and the file date.

owner_hierarchy(parent: str | None) → list

Analyse the parent of a variable down to the Model and return the owners as list.

ref_to_var(vr: int) → tuple[Variable, int]

Find Variable and sub-index (for compound variable), based on a value_reference value.

register_variable(var: Variable, nested: bool = True)

Register a variable as FMU interface.

Parameters:

  • var (ScalarVariable) – The variable to be registered

  • nested (bool) – With respect to FMI standard this is not conformant. To make it behave conformant we treat False as VariableNamingConvention.flat and True as VariableNamingConvention.structured Variable name parsing and setting of related properties is expected beforehand, outside this function.

  1. Only the first element of compound variables includes the variable reference, while the following sub-elements contain None, so that a (ScalarVariable) index is reserved.

  2. The variable var.name and var.unit must be set before calling this function.

  3. The call to super()… sets the value_reference, getter and setter of the variable

set_boolean(vrs: Sequence[int], values: Sequence[bool])
set_integer(vrs: Sequence[int], values: Sequence[int])
set_real(vrs: Sequence[int], values: Sequence[float])
set_string(vrs: Sequence[int], values: Sequence[str])
setup_experiment(start_time: float = 0.0)

Minimum version of setup_experiment, just setting the start_time. Derived models may need to extend this.

to_xml(model_options: dict | None = None) → Element

Build the XML FMI2 modelDescription.xml tree. (adapted from PythonFMU).

Parameters:

model_options ({str, str}) – Dict of FMU model options

Return type:

(xml.etree.TreeElement.Element) XML description of the FMU

variable_by_name(name: str) → Variable

Return Variable object related to name, or None, if not found. For compound variables, the parent variable is returned irrespective of whether an index ([#]) is included or not If msg is not None, an error is raised and the message provided.

vars_iter(key=None)

Iterate over model variables (‘vars’). The returned variables depend on ‘key’ (see below).

Parameters:

key –

filter for returned variables. The following possibilities exist:

  • None: All variables are returned

  • type: A type designator (int, float, bool, Enum, str), returning only variables matching on this type

  • causality: A Causality value, returning only one causality type, e.g. Causality.input

  • variability: A Variability value, returning only one variability type, e.g. Variability.fixed

  • callable: Any bool function of model variable object

The iterator yields variable objects

xml_unit_definitions()

Make the xml element for the unit definitions used in the model. See FMI 2.0.4 specification 2.2.2.

property dirty
instances: list[str] = []
property units