FMI Documentation¶

This page contains the Fmi Module documentation.

The `fmi` Module¶

Module containing the FMI interface Python wrappers.

jmodelica.fmi.FMI_DERIVATIVES¶: Evaluate Jacobian of outputs.

jmodelica.fmi.FMI_INPUTS¶: Evaluate Jacobian of derivatives.

jmodelica.fmi.FMI_STATES¶: Evaluate Jacobian w.r.t. inputs.

exception jmodelica.fmi.FMUException[source]¶

Bases: exceptions.Exception

An FMU exception.

class jmodelica.fmi.FMUModel(fmu, path='.', reload_dll=True, enable_logging=False)[source]¶

Bases: jmodelica.core.BaseModel

A JMI Model loaded from a DLL.

completed_integrator_step()[source]¶

This method must be called by the environment after every completed step of the integrator. If the return is True, then the environment must call event_update() otherwise, no action is needed.

Returns:

True -> Call event_update().
False -> Do nothing.

Calls the low-level FMI function: fmiCompletedIntegratorStep.

continuous_states¶: Property for accessing the current values of the continuous states. Calls the low-level FMI function: fmiSetContinuousStates/fmiGetContinuousStates.

event_update(intermediateResult=False)[source]¶

Updates the event information at the current time-point. If intermediateResult is set to True the update_event will stop at each event iteration which would require to loop until event_info.iterationConverged == fmiTrue.

Parameters:

intermediateResult -- 
    If set to True, the update_event will stop at each event 
    iteration.
    Default: False.

Example:

model.event_update()

Calls the low-level FMI function: fmiEventUpdate

fmiCallbackAllocateMemory(nobj, size)[source]¶: Callback function for the FMU which allocates memory needed by the model.

fmiCallbackFreeMemory(obj)[source]¶: Callback function for the FMU which deallocates memory allocated by fmiCallbackAllocateMemory.

fmiCallbackLogger(c, instanceName, status, category, message)[source]¶: Logg the information from the FMU.

get_alias_for_variable(aliased_variable, ignore_cache=False)[source]¶

Return list of all alias variables belonging to the aliased variable along with a list of booleans indicating whether the alias variable should be negated or not.

Returns:

A list consisting of the alias variable names and another list 
consisting of booleans indicating if the corresponding alias is 
negated.

Raises:

XMLException if alias_variable is not in model.

get_boolean(valueref)[source]¶

Returns the boolean-values from the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.

Returns:

values -- 
    The values retrieved from the FMU.

Example:

val = model.get_boolean([232])

Calls the low-level FMI function: fmiGetBoolean/fmiSetBoolean

get_data_type(variablename)[source]¶: Get data type of variable.

get_derivatives()[source]¶

Returns the derivative of the continuous states.

Returns:

dx -- 
    The derivative as an array.

Example:

dx = model.get_derivatives()

Calls the low-level FMI function: fmiGetDerivatives

get_directional_derivative(z_vref, v_vref, dz, dv)¶

Evaluate directional derivative of the ODE.

Paramters:

z_vref --
    Value references of the directional derivative result vector dz.
    These are defined by a subset of the derivative and output variable
    value references.

v_ref --
    Value reference of the input seed vector dv. These are defined by a
    subset of the state and input variable value references.

dz --
    Output argument containing the directional derivative vector.

dv -- Input argument containing the input seed vector.

Calls the low-level FMI function: fmiGetDirectionalDerivative

get_event_indicators()[source]¶

Returns the event indicators at the current time-point.

Return:

evInd -- 
    The event indicators as an array.

Example:

evInd = model.get_event_indicators()

Calls the low-level FMI function: fmiGetEventIndicators

get_event_info()[source]¶

Returns the event information from the FMU.

Returns:

The event information, a struct which contains:

iterationConverged -- 
    Event iteration converged (if True).
    
stateValueReferencesChanged -- 
    ValueReferences of states x changed (if True).
    
stateValuesChanged -- 
    Values of states x have changed (if True).
    
terminateSimulation -- 
    Error, terminate simulation (if True).
    
upcomingTimeEvent - 
    If True, nextEventTime is the next time event.
    
nextEventTime -- 
    The next time event.

Example:

event_info    = model.event_info
nextEventTime = model.event_info.nextEventTime

get_integer(valueref)[source]¶

Returns the integer-values from the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.

Return:

values -- 
    The values retrieved from the FMU.

Example:

val = model.get_integer([232])

Calls the low-level FMI function: fmiGetInteger/fmiSetInteger

get_jacobian(independents, dependents, jac)¶

Evaluate Jacobian(s) of the ODE.

This function evaluates one or several of the A, B, C, D Jacobian matrices in the linearized ODE:

dx = A*x + B*u y = C*x + D*u

where dx are the derivatives, u are the inputs, y are the top level outputs and x are the states. The arguments ‘independents’ and ‘dependents’ are used to specify which Jacobian(s) to compute: independents=FMI_STATES and dependents=FMI_DERIVATIVES gives the A matrix, and independents=FMI_STATES|FMI_INPUTS and dependents=FMI_DERIVATIVES|FMI_OUTPUTS gives the A, B, C and D matrices in block matrix form:

C | D

Parameters:

independents --
    Should be FMI_STATES and/or FMI_INPUTS.

dependents --
    Should be be FMI_DERIVATIVES and/or FMI_OUTPUTS.

jac --
    A vector representing a matrix on column major format.

Example:

jac = model.get_jacobian(jmodelica.fmi.FMI_STATES,
                         jmodelica.fmi.FMI_DERIVATIVES, jac)

Calls the low-level FMI function: fmiGetJacobian

get_log()[source]¶

Returns the log information as a list. To turn on the logging use the method, set_debug_logging(True). The log is stored as a list of lists. For example log[0] are the first log message to the log and consists of, in the following order, the instance name, the status, the category and the message.

Returns:

log - A list of lists.

get_name()[source]¶: Return the name of the model.

get_nominal(valueref)[source]¶: Returns the nominal value from valueref.

get_ode_sizes()[source]¶

Returns the number of continuous states and the number of event indicators.

Returns:

nbr_cont -- 
    The number of continuous states.
    
nbr_ind -- 
    The number of event indicators.

Example:

[nCont, nEvent] = model.get_ode_sizes()

get_real(valueref)[source]¶

Returns the real-values from the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.

Returns:

values -- 
    The values retrieved from the FMU.

Example:

val = model.get_real([232])

Calls the low-level FMI function: fmiGetReal/fmiSetReal

get_state_value_references()[source]¶

Returns the continuous states valuereferences.

Returns:

val -- 
    The references to the continuous states.

Example:

val = model.get_continuous_value_reference()

Calls the low-level FMI function: fmiGetStateValueReferences

get_string(valueref)[source]¶

Returns the string-values from the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.

Returns:

values -- 
    The values retrieved from the FMU.

Example:

val = model.get_string([232])

Calls the low-level FMI function: fmiGetString/fmiSetString

get_tolerances()[source]¶

Returns the relative and absolute tolerances. If the relative tolerance is defined in the XML-file it is used, otherwise a default of 1.e-4 is used. The absolute tolerance is calculated and returned according to the FMI specification, atol = 0.01*rtol*(nominal values of the continuous states).

Returns:

rtol -- 
    The relative tolerance.
    
atol -- 
    The absolute tolerance.

Example:

[rtol, atol] = model.get_tolerances()

get_valueref(variablename=None, type=None)[source]¶

Extract the ValueReference given a variable name.

Parameters:

variablename -- 
    The name of the variable.

Returns:

The ValueReference for the variable passed as argument.

get_variability(variablename)[source]¶

Get variability of variable.

Parameters:

variablename --

    The name of the variable.

Returns:

The variability of the variable, CONTINUOUS(0), CONSTANT(1), 
PARAMETER(2) or DISCRETE(3)

get_variable_aliases()[source]¶

Extract the alias data for each variable in the model.

Returns:

A list of tuples containing value references and alias data 
respectively.

get_variable_descriptions(include_alias=True)[source]¶

Extract the descriptions of the variables in a model.

Returns:

Dict with ValueReference as key and description as value.

get_variable_names(type=None, include_alias=True)[source]¶

Extract the names of the variables in a model.

Returns:

Dict with variable name as key and value reference as value.

initialize(tolControlled=True, relativeTolerance=None)[source]¶

Initializes the model and computes initial values for all variables, including setting the start values of variables defined with a the start attribute in the XML-file.

Parameters:

tolControlled -- 
    If the model are going to be called by numerical solver using
    step-size control. Boolean flag.
relativeTolerance --
    If the model are controlled by a numerical solver using
    step-size control, the same tolerance should be provided here.
    Else the default tolerance from the XML-file are used.

Calls the low-level FMI function: fmiInitialize.

instantiate_model(name='Model', logging=False)[source]¶

Instantiate the model.

Parameters:

name -- 
    The name of the instance.
    Default: 'Model'
            
logging -- 
    Defines if the logging should be turned on or off.
    Default: False, no logging.

Calls the low-level FMI function: fmiInstantiateModel.

model_types_platform¶

Returns the set of valid compatible platforms for the Model, extracted from the XML.

Returns:

model_types_platform -- 
    The valid platforms.

Example:

model.model_types_platform

nominal_continuous_states¶: Property for accessing the nominal values of the continuous states. Calls the low-level FMI function: fmiGetNominalContinuousStates.

reset()[source]¶: Calling this function is equivalent to reopening the model.

save_time_point()[source]¶

Retrieves the data at the current time-point of the variables defined to be continuous and the variables defined to be discrete. The information about the variables are retrieved from the XML-file.

Returns:

sol_real -- 
    The Real-valued variables.
    
sol_int -- 
    The Integer-valued variables.
    
sol_bool -- 
    The Boolean-valued variables.

Example:

[r,i,b] = model.save_time_point()

set_boolean(valueref, values)[source]¶

Sets the boolean-values in the FMU as defined by the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.
    
values -- 
    Values to be set.

Example:

model.set_boolean([234,235],[True,False])

Calls the low-level FMI function: fmiGetBoolean/fmiSetBoolean

set_debug_logging(flag)[source]¶

Specifies if the debugging should be turned on or off.

Parameters:

flag -- 
    Boolean value.

Calls the low-level FMI function: fmiSetDebuggLogging

set_integer(valueref, values)[source]¶

Sets the integer-values in the FMU as defined by the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.
    
values -- 
    Values to be set.

Example:

model.set_integer([234,235],[12,-3])

Calls the low-level FMI function: fmiGetInteger/fmiSetInteger

set_real(valueref, values)[source]¶

Sets the real-values in the FMU as defined by the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.
    
values -- 
    Values to be set.

Example:

model.set_real([234,235],[2.34,10.4])

Calls the low-level FMI function: fmiGetReal/fmiSetReal

set_string(valueref, values)[source]¶

Sets the string-values in the FMU as defined by the valuereference(s).

Parameters:

valueref -- 
    A list of valuereferences.
    
values -- 
    Values to be set.

Example:

model.set_string([234,235],['text','text'])

Calls the low-level FMI function: fmiGetString/fmiSetString

simulate(start_time=0.0, final_time=1.0, input=(), algorithm='AssimuloFMIAlg', options={})[source]¶

Compact function for model simulation.

The simulation method depends on which algorithm is used, this can be set with the function argument ‘algorithm’. Options for the algorithm are passed as option classes or as pure dicts. See FMUModel.simulate_options for more details.

The default algorithm for this function is AssimuloFMIAlg.

Parameters:

start_time --
    Start time for the simulation.
    Default: 0.0
    
final_time --
    Final time for the simulation.
    Default: 1.0
    
input --
    Input signal for the simulation. The input should be a 2-tuple 
    consisting of first the names of the input variable(s) and then 
    the data matrix.
    Default: Empty tuple.
    
algorithm --
    The algorithm which will be used for the simulation is specified 
    by passing the algorithm class as string or class object in this 
    argument. 'algorithm' can be any class which implements the 
    abstract class AlgorithmBase (found in algorithm_drivers.py). In 
    this way it is possible to write own algorithms and use them 
    with this function.
    Default: 'AssimuloFMIAlg'
    
options -- 
    The options that should be used in the algorithm. For details on 
    the options do:
    
        >> myModel = FMUModel(...)
        >> opts = myModel.simulate_options()
        >> opts?

    Valid values are: 
        - A dict which gives AssimuloFMIAlgOptions with 
          default values on all options except the ones 
          listed in the dict. Empty dict will thus give all 
          options with default values.
        - An options object.
    Default: Empty dict

Returns:

Result object, subclass of algorithm_drivers.ResultBase.

simulate_options(algorithm='AssimuloFMIAlg')[source]¶

Get an instance of the simulate options class, prefilled with default values. If called without argument then the options class for the default simulation algorithm will be returned.

Parameters:

algorithm --
    The algorithm for which the options class should be fetched. 
    Possible values are: 'AssimuloFMIAlg'.
    Default: 'AssimuloFMIAlg'

Returns:

Options class for the algorithm specified with default values.

time¶: Property for accessing the current time of the simulation. Calls the low-level FMI function: fmiSetTime.

version¶

Returns the FMI version of the Model which it was generated according.

Returns:

version -- 
    The version.

Example:

model.version

jmodelica.fmi.compile_fmu(class_name, file_name=[], compiler='modelica', target='model_noad', compiler_options={}, compile_to='.', compiler_log_level='warning')[source]¶

Compile a Modelica model to an FMU.

A model class name must be passed, all other arguments have default values. The different scenarios are:

Only class_name is passed:
- Class is assumed to be in MODELICAPATH.
class_name and file_name is passed:
- file_name can be a single file as a string or a list of file_names (strings).

Library directories can be added to MODELICAPATH by listing them in a special compiler option ‘extra_lib_dirs’, for example:

compiler_options =

{‘extra_lib_dirs’:[‘c:MyLibsMyLib1’,’c:MyLibsMyLib2’]}

Other options for the compiler should also be listed in the compiler_options dict.

The compiler target is ‘model_noad’ by default which means that libraries for AD and optimization/initialization algortihms will not be available. This is currently the only target that is possible to use.

Parameters:

class_name -- 
    The name of the model class.
    
file_name -- 
    Model file (string) or files (list of strings), can be both .mo or 
    .mop files.
    Default: Empty list.
    
compiler -- 
    The compiler used to compile the model. The only possible compiler 
    that can be used currently is ModelicaCompiler.
    Default: 'modelica'
    
target --
    Compiler target.
    Note: Needs to be 'model_noad' at the moment.
    Default: 'model_noad'
    
compiler_options --
    Options for the compiler.
    Default: Empty dict.
    
compile_to --
    Specify location of the compiled FMU. Directory will be created if 
    it does not exist.
    Default: Current directory.

compiler_log_level --
    Set the log level for the compiler. Valid options are 'warning'/'w', 
    'error'/'e' or 'info'/'i'.
    Default: 'warning'

Returns:

Name of the FMU which has been created.

jmodelica.fmi.compile_fmux(class_name, file_name=[], compiler='auto', compiler_options={}, compile_to='.', compiler_log_level='warning')¶

Compile a Modelica model to an FMUX.

A model class name must be passed, all other arguments have default values. The different scenarios are:

Only class_name is passed:
- Class is assumed to be in MODELICAPATH.
class_name and file_name is passed:
- file_name can be a single file as a string or a list of file_names (strings).

Library directories can be added to MODELICAPATH by listing them in a special compiler option ‘extra_lib_dirs’, for example:

compiler_options =

{‘extra_lib_dirs’:[‘c:MyLibsMyLib1’,’c:MyLibsMyLib2’]}

Other options for the compiler should also be listed in the compiler_options dict.

Parameters:

class_name -- 
    The name of the model class.
    
file_name -- 
    Model file (string) or files (list of strings), can be both .mo or 
    .mop files.
    Default: Empty list.
    
compiler -- 
    The compiler used to compile the model.
    Default: 'auto'
    
compiler_options --
    Options for the compiler.
    Default: Empty dict.
    
compile_to --
    Specify location of the compiled FMU. Directory will be created if 
    it does not exist.
    Default: Current directory.

compiler_log_level --
    Set the log level for the compiler. Valid options are 'warning'/'w', 
    'error'/'e' or 'info'/'i'.
    Default: 'warning'

Returns:

Name of the FMUX which has been created.

jmodelica.fmi.get_fmu_name(class_name)[source]¶

Computes the FMU name from a class name.

Parameters:

class_name -- 
    The name of the model.

Returns:

The FMU name (replaced dots with underscores).

jmodelica.fmi.get_fmux_name(class_name)¶

Computes the FMUX name from a class name.

Parameters:

class_name -- 
    The name of the model.

Returns:

The FMUX name (replaced dots with underscores).

jmodelica.fmi.unzip_fmu(archive, path='.', random_name=True)¶

jmodelica.fmi.unzip_fmux(archive, path='.')¶

Navigation

FMI Documentation¶

The fmi Module¶

Navigation

The `fmi` Module¶