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 | 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: start_time,stop_time,step_size,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 | None = None, flags: dict | None = None, guid=None, **kwargs)

Methods

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

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(time, dt)

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

ref_to_var(vr)

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

register_variable(var, start[, value_reference])

Register the variable 'var' as model variable.

set_boolean(vrs, values)

set_integer(vrs, values)

set_real(vrs, values)

set_string(vrs, values)

setup_experiment(start)

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[, msg])

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

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.

static build(script: str = '', project_files: list[str | Path] | None = None, dest: str | PathLike[str] = '.', documentation_folder: Path | 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.

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.

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.

do_step(time, dt)

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.

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

Return the path to the component-model requirements file.

exit_initialization_mode()

Initialize the model after initial variables are set.

get_boolean(vrs)
get_integer(vrs)
get_real(vrs)
get_string(vrs)

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.

ref_to_var(vr: int)

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

register_variable(var: Variable, start: tuple | list | ndarray, value_reference: int | None = None)

Register the variable ‘var’ as model variable. Set the initial value and add the unit if not yet used. Perform some checks and register the value_reference. The following should be noted.

  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: list, values: list)
set_integer(vrs: list, values: list)
set_real(vrs: list, values: list)
set_string(vrs: list, values: list)
setup_experiment(start: float)

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, msg: str | None = None)

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