pyfmu.fmi2

Package Contents

class pyfmu.fmi2.Fmi2Causality

Bases: enum.Enum

Defines the causality of the variable, that is whether it is an input, output, parameter, etc.

Values:

  • parameter: a value set by the environment which remains constant during the simulation.

  • calculatedParameter: ?

  • input: An input from another model.

  • output: An output to other models.

  • local: ?

  • independent: Independent variable, typically time. At most one variable of an FMU may be declared as independent.

parameter = parameter
calculatedParameter = calculatedParameter
input = input
output = output
local = local
independent = independent
class pyfmu.fmi2.Fmi2DataTypes

Bases: enum.Enum

Defines the type of a variable.

Values:

  • real: a real numbered value.

  • integer: a interger value.

  • boolean: a boolean value.

  • string: a text string.

real = Real
integer = Integer
boolean = Boolean
string = String
class pyfmu.fmi2.Fmi2Initial

Bases: enum.Enum

Defines how the initial value of a variable is initialized.

Values:

exact: The variable is initialised with the provided start value. calculated: The variable is defined based on other variables during initialisation. “approx”: The variable is defined based on the an iteration of an algebraic loop with the provided start value.

exact = exact
approx = approx
calculated = calculated
class pyfmu.fmi2.Fmi2Variability

Bases: enum.Enum

Defines the time instants where the variable can change value.

Values:

  • constant: The variable never changes.

  • fixed: The variable never changes after initialization, specifically after exit_initialization_mode has been called.

  • tunable: ?

  • discrete : ?

  • continuous : No restriction on when the variable can change.

constant = constant
fixed = fixed
tunable = tunable
discrete = discrete
continuous = continuous
class pyfmu.fmi2.Fmi2Status

Bases: enum.Enum

Represents the status of the FMU or the results of function calls.

Values:

  • ok: all well

  • warning: an issue has arisen, but the computation can continue.

  • discard: an operation has resulted in invalid output, which must be discarded

  • error: an error has ocurred for this specific FMU instance.

  • fatal: an fatal error has ocurred which has corrupted ALL FMU instances.

  • pending: indicates that the FMu is doing work asynchronously, which can be retrived later.

Notes:

FMI section 2.1.3

ok = 0
warning = 1
discard = 2
error = 3
fatal = 4
pending = 5
pyfmu.fmi2._vc_combinations
pyfmu.fmi2._a_error = The combinations “constant / parameter”, “constant / calculatedParameter” and “constant /

input” do not make sense, since parameters and inputs are set from the environment, whereas a constant has always a value.

pyfmu.fmi2._b_error = The combinations “discrete / parameter”, “discrete / calculatedParameter”, “continuous /

parameter” and continuous / calculatedParameter do not make sense, since causality = “parameter” and “calculatedParameter” define variables that do not depend on time, whereas “discrete” and “continuous” define variables where the values can change during simulation.

pyfmu.fmi2._c_error = For an “independent” variable only variability = “continuous” makes sense.
pyfmu.fmi2._d_error = A fixed or tunable “input” has exactly the same properties as a fixed or tunable parameter.

For simplicity, only fixed and tunable parameters shall be defined.

pyfmu.fmi2._e_error = A fixed or tunable “output” has exactly the same properties as a fixed or tunable

calculatedParameter. For simplicity, only fixed and tunable calculatedParameters shall be defined.

pyfmu.fmi2._A_initial
pyfmu.fmi2._B_initial
pyfmu.fmi2._C_initial
pyfmu.fmi2._D_initial
pyfmu.fmi2._E_initial
pyfmu.fmi2.get_default_initial(variability: Fmi2Variability, causality: Fmi2Causality)
pyfmu.fmi2.get_possible_initial(variability: Fmi2Variability, causality: Fmi2Causality)

Returns the set of initial types that are valid for the combination of specific variability and causality.

pyfmu.fmi2.validate_vc(variability: Fmi2Variability, causality: Fmi2Causality)

Validate combinations of variablity and causality

Arguments:

variability {Fmi2Variability} – [description] causality {Fmi2Causality} – [description]

Returns:

[type] – [description]

class pyfmu.fmi2.Fmi2ScalarVariable(name: str, data_type: Fmi2DataTypes, initial: Fmi2Initial = None, causality=Fmi2Causality.local, variability=Fmi2Variability.continuous, start=None, description: str = '', value_reference: int = None)

Bases: abc.ABC

is_type(self, t: Fmi2DataTypes)
is_real(self)
is_integer(self)
is_boolean(self)
is_string(self)
static validate_start_value(data_type, causality, initial, variability, start)
static should_define_start(variability: Fmi2Variability, causality: Fmi2Causality, initial: Fmi2Initial)

Returns true if the combination requires that a start value is defined, otherwise false.

For reference check the FMI2 specification p.54 for a description of which combination are allowed.

__repr__(self)
__str__(self)
pyfmu.fmi2._internal_log_catergory = pyfmu
pyfmu.fmi2._default_category = events
class pyfmu.fmi2.Fmi2StdLogCats

Bases: enum.Enum

Standard log categories defined in the FMI2 specification.

logEvents = logEvents
logSingularLinearSystems = logSingularLinearSystems
logNonlinearSystems = logNonlinearSystems
logDynamicStateSelection = logDynamicStateSelection
logStatusWarning = logStatusWarning
logStatusDiscard = logStatusDiscard
logStatusError = logStatusError
logStatusFatal = logStatusFatal
logStatusPending = logStatusPending
logAll = logAll
class pyfmu.fmi2.Fmi2LoggerBase

Bases: abc.ABC

set_debug_logging(self, logging_on: bool, categories: Iterable[str])
register_log_category(self, category: str, aliases=None, predicate=None)

Registers a new log category

Arguments:

category {str} – [description]

Keyword Arguments:

aliases {[type]} – a list of aliases for the category (default: {None}) predicate {[type]} – a predicate function which takes as input a message and whether it should be logged. (default: {None})

log(self, message: str, category: str = _default_category, status=Fmi2Status.ok)
_do_log(self, message: str, category: str, status: Fmi2Status)
register_standard_categories(self, categories: Iterable[str])

Registers the standard log categories defined by FMI2.

Arguments:

categories {Iterable[str]} – A list of standard categories register. Possible values are: * logEvents * logNonlinearSystems * logNonlinearSystems * logDynamicStateSelection, * logStatusWarning * logStatusDiscard * logStatusError * logStatusFatal * logStatusPending * logAll

See 2.2.4 p.42 for reference

register_all_standard_categories(self)

Convenience method used to register all standard FMI2 log categories

property active_categories(self)

Categories which are marked as active.

property available_categories(self)

Categories which have been declared by the FMU.

class pyfmu.fmi2.Fmi2CallbackLogger(callback, log_stdout=False)

Bases: pyfmu.fmi2.fmi2logging.Fmi2LoggerBase

Class implementing the FMI2 logging system by providing methods to register and enable specific categories.

_do_log(self, status, category, message)
class pyfmu.fmi2.Fmi2NullLogger

Bases: pyfmu.fmi2.fmi2logging.Fmi2LoggerBase

log(self, message, category: str = '', status=None)
pyfmu.fmi2._slave_configuration_name = slave_configuration.json
pyfmu.fmi2._internal_log_catergory = fmi2slave
pyfmu.fmi2._internal_throw_category
pyfmu.fmi2._internal_invalid_status_category
pyfmu.fmi2._logging_override_name = pyfmu_log_all_override
pyfmu.fmi2.log
pyfmu.fmi2._uninitialized_variables_status
pyfmu.fmi2._read_wrong_type_status
pyfmu.fmi2._invalid_fmi_invalid_arguments
pyfmu.fmi2._invalid_return_type_status
pyfmu.fmi2._invalid_external_call_status
class pyfmu.fmi2._Fmi2SlaveErrorDefinitions

Bases: enum.Enum

Defines which FMI2 error codes should be raised in response to various inconsistencies

uninitialized_variables
internal_log_catergory = fmi2slave
class pyfmu.fmi2.Fmi2Slave(modelName: str, author='', copyright='', version='', description='', logging_callback=None, logging_logAll=False, logging_stdout=False, logging_add_standard_categories=True, logging_slave_fmi_calls=True, check_uninitialized_variables=True)
_configure(self)

Performs configuration of the FMI slave based on the contents of the slave configuration file.

The configuration function is only available for Fmi2Slaves which are running from inside an FMU, e.g. they have a slave_configuration.json

Options:

  1. Logging, allows the user to override log settings.

_set_resources_path(self, path)

Called by the wrapper to set the path to resource folder.

This is used for configuration.

Arguments:

path {[str]} – Path to the resources folder

_is_running_as_project(self)

Returns true if the Fmi2Slave is running inside a project that has not yet been exported.

_is_running_as_fmu(self)

Returns true if the FMI2Slave is running from inside an exported FMU

register_variable(self, name: str, data_type: Fmi2DataTypes = None, causality=Fmi2Causality.local, variability=Fmi2Variability.continuous, initial: Fmi2Initial = None, start=None, description: str = '', define_attribute: bool = True, value_reference: int = None)

Add a variable to the model such as an input, output or parameter.

Arguments:

name {str} – [description] data_type {Fmi2DataTypes} – [description]

Keyword Arguments:

causality {[type]} – defines the type of the variable, such as input, output or parameter (default: {Fmi2Causality.local}) variability {[type]} – defines the time dependency of the variable. (default: {Fmi2Variability.continuous}) initial {Fmi2Initial} – defines how the variable is initialized (default: {None}) start {[type]} – start value of the variable. (default: {None}) description {str} – a description of the variable which is added to the model description (default: {“”}) define_attribute {bool} – if true, automatically add the specified attribute to instance if it does not already exist. (default: {True})

Inference Rules:
i1. shorthands and aliases:

data_type,causality,initial and variablity can be defined using string shorthands.

i2. default start values:

if data_type is defined but start is undefined, default values are used based on data_type

i3. data type inference:

if data_type is undefined but start is defined, data_type is inferred from start’s type.

i4. initial based on causality and variability (2.2.7 p.49)
Default initial are defined based on the combination of causality and variability:

  • exact : constant[local|output], [fixed|tunable]parameter

  • calculated : [fixed|tunable][calculatedParameter|local], [continous|discrete][local|output]

  • (do not define) : [discrete|continuous]input, continous independent.

Validation Rules:
v1: data type and causality (2.2.7 p.48)

only real valued variables may have causality continuous

v2: causality and variablity (2.2.7 p.48-49)

Only the following combinations of variability and causality are allowed: * calculatedParameter: {fixed,tunable} * independent: {continuous} * input : {continuous,discrete} * local : {continuous,constant,discrete,fixed,tuneable} * output : {continuous,constant,discrete} * parameter : {fixed,tuneable}

v3: initial allowed (2.2.7 p.49)

Only certain certain intials are allowed for a given combination of varability and causality.

v4: should define start (2.2.7 p.47)

Only certain combinations of causality, intial are allowed to provide start values. * [exact|approx] -> must define start * calculated -> must not define start *

Ordering: i1 -> i2 -> i3 -> v2 -> i4 -> v1 -> v3

register_log_category(self, name: str)

Registers a new log category which will be visible to the simulation tool.. This information is used by co-simulation engines to filter messages.

Arguments:

name {str} – name of the category.

Examples:

``` self.register_log_category(‘runtime validation’)

```

_acquire_unused_value_reference(self)

Returns the an unused value reference

_setup_experiment(self, start_time: float, tolerance: float = None, stop_time: float = None)
setup_experiment(self, start_time: float, tolerance: float = None, stop_time: float = None)
_enter_initialization_mode(self)
enter_initialization_mode(self)
_exit_initialization_mode(self)
exit_initialization_mode(self)
_do_step(self, current_time: float, step_size: float, no_set_fmu_state_prior: bool)
do_step(self, current_time: float, step_size: float, no_set_fmu_state_prior: bool)
_reset(self)
reset(self)
_terminate(self)
terminate(self)
_set_debug_logging(self, logging_on: bool, categories: Iterable[str])
set_debug_logging(self, logging_on: bool, categories: Iterable[str])

Defines the set of active log categories for which log messages will logged. Messages logged to any other categories will be ignored.

This function is called by the tool though the fmi2SetDebugLogging function.

Note that the tool can only “see” categories registered in the model description using the register_log_category.

Arguments:

categories {Iterable[str]} – a set of categories which are set to be active logging_on {bool} – if true, enable the categories, otherwise disable them

Defaults category mapping:

FMI2 specifies several standardized categories.

  • logEvents : Log all events (during initialization and simulation).

  • logSingularLinearSystemsLog the solution of linear systems of equations if the solution is singular

    (and the tool picked one solution of the infinitely many solutions).

  • logNonlinearSystems : Log the solution of nonlinear systems of equations.

  • logDynamicStateSelection : Log the dynamic selection of states.

  • logStatusWarning : Log messages when returning fmi2Warning status from any function.

  • logStatusDiscard : Log messages when returning fmi2Discard status from any function.

  • logStatusError : Log messages when returning fmi2Error status from any function.

  • logStatusFatal : Log messages when returning fmi2Fatal status from any function.

  • logStatusPending : Log messages when returning fmi2Pending status from any function.

  • logAll : Log all messages.

The standard standard leaves it up to the implementation to decide which “categories” map to each of the log-categories.

` Python self.log(Fmi2Status.OK,"events","initialized FMU") `

Examples: ``` Python

# standard logging fmu = MyFMU() fmu.standard_log_catgories() fmu._set_debug_logging({‘LogAll’})

fmu.log(Fmi2Status.ok,’logEvents’,)

```

_get_xxx(self, vrs, values, data_type: Fmi2DataTypes)
_get_integer(self, vrs, values)
get_integer(self, vrs, values)
_get_real(self, vrs, values)
get_real(self, vrs, values)
_get_boolean(self, vrs, values)
get_boolean(self, vrs, values)
_get_string(self, vrs, values)
get_string(self, vrs, values)
_set_xxx(self, vrs, values, data_type: Fmi2DataTypes)

Generic implementation of setter methods used for set_real, set_integer, set_boolean and set_string

Arguments:

vrs {List[int]} – List of value references of the variables to be set values {List[]} – List of the values which must be assigned to the specified references. data_type {Fmi2DataTypes} – The datatype “expected” data type of the variable, used for validation.

Returns:

[FmiStatus] – a status indicating whether the call was succesful

_set_integer(self, vrs, values)
set_integer(self, vrs, values)
_set_real(self, vrs, values)
set_real(self, vrs, values)
_set_boolean(self, vrs, values)
set_boolean(self, vrs, values)
_set_string(self, vrs, values)
set_string(self, vrs, values)
_do_fmi_call(self, f, *args, **kwargs)

Performs the call to the fmi function implemented by the subclass and returns the status.

Purpose of the function is: 1. logging of the function calls 2. handle exceptions in implementation 3. convert return values to FMI status values

Arguments:

f {[type]} – the function to be invoked.

_define_variable(self, sv: Fmi2ScalarVariable)
_do_check_variable_initialization(self)

Check if variables with initial “calculated” and “approx” are initialized correctly.

log(self, message: str, category=None, status=Fmi2Status.ok)

Logs a message to the fmi interface.

Note that only categories which are set as active using the __set_debug_logging__, are propageted to the tool. The function is called by the tool using with the categories which the user wishes to be active.

Arguments:

status {Fmi2Status} – The current status of the FMU. category {str} – The category of the log message. message {str} – The log message itself.

Logging categories mappings:

_format_exc(self)
property available_categories(self)