Class fmipp.IncrementalFMU

class IncrementalFMU([fmuDirUri, ]modelIdentifier[, loggingOn=False, timeDiffResolution=1e-4, integratorType=integratorBDF])

This class offers the possibility to combine the basic ability to integrate the state of an FMU for ME with advanced event handling capabilities. It implements a lookahead mechanism, where predictions of the FMU’s state are incrementally computed and stored. In case an event occurs, these predictions are used to interpolate and update the state of the FMU. If no event occurs, the latest prediction can be directly used to update the FMU’s state. More details can be found here. An example for using class IncrementalFMU can be found here

When creating the first instance of this class, the FMU has to be loaded. For this, the URI to the unzipped FMU has to be provided:

inc_fmu = fmipp.IncrementalFMU(fmuDirUri, modelIdentifier, False, 1e-4, integratorBDF)

In case you want to have more than one instance of the same FMU, just create another instance of this class without providing the URI to the unzipped FMU (the FMU will have already been loaded in the background the first time):

inc_fmu = fmipp.IncrementalFMU(modelIdentifier, False, 1e-4, integratorBDF)

Note

This class uses objects of type SwigPyObject as inputs and outputs, which are wrappers around C/C++ arrays. Instantiation of and data access to these objects should be done via the corresponding helper functions.

Parameters

  • fmuDirUri (str) – URI to the unzipped FMU

  • modelIdentifier (str) – model identifier of the FMU

  • loggingOn (bool) – enable logger for debugging

  • timeDiffResolution (float) – internal resolution for comparing time differences

  • integratorType (int) – the numerical integration method for solving ODEs (see list of available integrators here)

Methods for interacting with the FMU

init(instanceName, realVariableNames, realValues, nRealVars, [integerVariableNames, integerValues, nIntegerVars, booleanVariableNames, booleanValues, nBooleanVars, stringVariableNames, stringValues, nStringVars, ]startTime, lookAheadHorizon, lookAheadStepSize, integratorStepSize, toleranceDefined=False, tolerance=1e-5)

Initialize the internal FMU model.

Parameters

  • instanceName (str) – a unique identifier for a given FMI component instance, used to identify a component within a co-simulation graph model and for logging messages

  • realVariableNames (SwigPyObject) – names of real variables

  • realValues (SwigPyObject) – initial values of real variables

  • nRealVars (int) – number of real variables to be initialized

  • integerVariableNames (SwigPyObject) – names of integer variables

  • integerValues (SwigPyObject) – initial values of integer variables

  • nIntegerVars (int) – number of integer variables to be initialized

  • booleanVariableNames (SwigPyObject) – names of boolean variables

  • booleanValues (SwigPyObject) – initial values of boolean variables

  • nBooleanVars (int) – number of boolean variables to be initialized

  • stringVariableNames (SwigPyObject) – names of string variables

  • stringValues (SwigPyObject) – initial values of string variables

  • nStringVars (int) – number of string variables to be initialized

  • startTime (float) – starting time for the internal FMU model

  • lookAheadHorizon (float) – lookahead horizon, i.e., time interval for calculating predictions

  • lookAheadStepSize (float) – time interval between predictions

  • integratorStepSize (float) – starting step size to be used by the integrator, smaller values lead to more accuracy

  • toleranceDefined (bool) – if True, the model is called with a numerical integration scheme where the step size is controlled by using tolerance

  • tolerance (float) – relative tolerance for error estimation

Return type

int

Returns

1 on success, 0 on failure

updateState(t1)

Updates the state of the FMU to the specified time t1, i.e., it changes the actual state using the previous state prediction(s). The specified time must not be further ahead than the lookahead horizon. The function has to be called after predictState(...) was called.

Parameters

t1 (float) – synchronization time

Return type

float

Returns

the internal FMU model’s current simulation time

updateStateFromTheRight(t1)

Updates the FMU’s state to the predicted state at time t1. The specified time must not be further ahead than the lookahead horizon. In case of a discontinuity at t1, the FMU’s outputs will reflect the limit from the right. The function may enhance time by the timeDiffResulution set at construction time. The function has to be called after predictState(...) was called and may be used instead of updateState() which always sets the limit from the left.

Parameters

t1 (float) – synchronization time

Return type

float

Returns

the internal FMU model’s current simulation time

syncState(t1, realInputs, integerInputs, booleanInputs, stringInputs)

Sets the given inputs at the FMU at time t1 and fetches the updated current state. The function assumes that updateState() or updateStateFromTheRight() was called before.

Parameters

  • t1 (float) – synchronization time

  • realInputs (SwigPyObject) – real inputs, previously defined via defineRealInputs(...)

  • integerInputs (SwigPyObject) – integer inputs, previously defined via defineIntegerInputs(...)

  • booleanInputs (SwigPyObject) – boolean inputs, previously defined via defineBooleanInputs(...)

  • stringInputs (SwigPyObject) – string inputs, previously defined via defineStringInputs(...)

predictState(t1)

Compute the state predictions according to the latest inputs.

Return type

float

Returns

the time of the last state prediction, corresponding either to the lookahead horizon or the next encountered event time

sync(t0, t1[, realInputs, integerInputs, booleanInputs, stringInputs])

This method executes updateState(...), syncState(...) and predictState(...) in one go.

Parameters

  • t0 (float) – simulation interval start time

  • t1 (float) – simulation interval end time

  • realInputs (SwigPyObject) – real inputs, previously defined via defineRealInputs(...)

  • integerInputs (SwigPyObject) – integer inputs, previously defined via defineIntegerInputs(...)

  • booleanInputs (SwigPyObject) – boolean inputs, previously defined via defineBooleanInputs(...)

  • stringInputs (SwigPyObject) – string inputs, previously defined via defineStringInputs(...)

Return type

float

Returns

the time of the last state prediction, corresponding either to the lookahead horizon or the next encountered event time

Methods for defining inputs/outputs

defineBooleanInputs(inputs, nInputs)

Define boolean inputs to be applied to the FMU via the sync(...) method.

Parameters

  • inputs (SwigPyObject) – initial values of the input variables

  • nInputs (int) – number of boolean inputs

defineBooleanOutputs(outputs, nOutputs)

Define boolean outputs to be retrieved from the FMU via the getBooleanOutputs(...) method.

Parameters

  • outputs (SwigPyObject) – initial values of the output variables

  • nOutputs (int) – number of boolean outputs

defineIntegerInputs(inputs, nInputs)

Define integer inputs to be applied to the FMU via the sync(...) method.

Parameters

  • inputs (SwigPyObject) – initial values of the input variables

  • nInputs (int) – number of integer inputs

defineIntegerOutputs(outputs, nOutputs)

Define integer outputs to be retrieved from the FMU via the getIntegerOutputs(...) method.

Parameters

  • outputs (SwigPyObject) – initial values of the output variables

  • nOutputs (int) – number of integer outputs

defineRealInputs(inputs, nInputs)

Define real inputs to be applied to the FMU via the sync(...) method.

Parameters

  • inputs (SwigPyObject) – initial values of the input variables

  • nInputs (int) – number of real inputs

defineRealOutputs(outputs, nOutputs)

Define real outputs to be retrieved from the FMU via the getRealOutputs(...) method.

Parameters

  • outputs (SwigPyObject) – initial values of the output variables

  • nOutputs (int) – number of real outputs

defineStringInputs(inputs, nInputs)

Define string inputs to be applied to the FMU via the sync(...) method.

Parameters

  • inputs (SwigPyObject) – initial values of the input variables

  • nInputs (int) – number of string inputs

defineStringOutputs(outputs, nOutputs)

Define string outputs to be retrieved from the FMU via the getStringOutputs(...) method.

Parameters

  • outputs (SwigPyObject) – initial values of the output variables

  • nOutputs (int) – number of string outputs

Methods for getting variable values

getBooleanOutputs()
Return type

SwigPyObject

Returns

value of boolean outputs

getIntegerOutputs()
Return type

SwigPyObject

Returns

value of integer outputs

getRealOutputs()
Return type

SwigPyObject

Returns

value of real outputs

getStringOutputs()
Return type

SwigPyObject

Returns

value of string outputs

Miscellaneous methods

getTimeDiffResolution()
Returns

internal resolution for comparing time differences

Return type

float

getType(name)

Get information about the type of a variable.

Parameters

name (str) – variable name

Return type

int (typeReal, typeInteger, typeBoolean, typeString or typeUnknown)

getLastStatus()
Returns

status returned by latest internal FMU function call

Return type

int (statusOK, statusWarning, statusDiscard, statusError or statusFatal)