GitHub

FMI for Model Exchange

This chapter contains the interface description to access the equations of a dynamic system from a C program.

Providing Independent Variables and Re-initialization of Caching

Depending on the situation, different variables need to be computed. In order to be efficient, it is important that the interface requires only the computation of variables that are needed in the present context. The state derivatives shall be reused from the previous call. This feature is called “caching of variables” in the sequel. Caching requires that the model evaluation can detect when the input arguments, like time or states, have changed.

FMICore.fmi3SetTime — Function

Source: FMISpec3.0, Version D5ef1c1: 3.2.1. State: Continuous-Time Mode

Set a new time instant and re-initialize caching of variables that depend on time, provided the newly provided time value is different to the previously set time value (variables that depend solely on constants or parameters need not to be newly computed in the sequel, but the previously computed values can be reused).

source
fmi3SetTime(c::FMU3Instance, time::fmi3Float64)

Set a new time instant and re-initialize caching of variables that depend on time, provided the newly provided time value is different to the previously set time value (variables that depend solely on constants or parameters need not to be newly computed in the sequel, but the previously computed values can be reused).

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.
  • time::fmi3Float64: Argument time contains a value of type fmi3Float64 which is a alias type for Real data type. time sets the independent variable time t.

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3SetTime.

source
fmi3SetTime(c::FMU3Instance, time::Real)

Set a new time instant and re-initialize caching of variables that depend on time, provided the newly provided time value is different to the previously set time value (variables that depend solely on constants or parameters need not to be newly computed in the sequel, but the previously computed values can be reused).

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.
  • t::Real: Argument t contains a value of type Real which is a alias type for Real data type. time sets the independent variable time t.

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3SetTime.

source
FMICore.fmi3SetContinuousStates — Function

Source: FMISpec3.0, Version D5ef1c1: 3.2.1. State: Continuous-Time Mode

Set a new (continuous) state vector and re-initialize caching of variables that depend on the states. Argument nx is the length of vector x and is provided for checking purposes

source
fmi3SetContinuousStates(c::FMU3Instance,
    x::AbstractArray{fmi3Float64},
    nx::Csize_t)

Set a new (continuous) state vector and re-initialize caching of variables that depend on the states. Argument nx is the length of vector x and is provided for checking purposes

If fmi3UpdateDiscreteStates returned with nominalsOfContinuousStatesChanged == fmi3True, then at least one nominal value of the states has changed and can be inquired with fmi3GetNominalsOfContinuousStates. Not allowed in Co-Simulation and Scheduled Execution.

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 2.0.2 Standard.
  • x::AbstractArray{fmi3Float64}: Argument x contains values of type fmi3Float64 which is a alias type for Real data type. x is the AbstractArray which contains the Real values of the vector that represent the nominal values of the continuous states.
  • nx::Csize_t: Argument nx defines the length of vector x and is provided for checking purposes

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3SetContinuousStates.

source
fmi3SetContinuousStates(c::FMU3Instance, x::Union{AbstractArray{Float32}, AbstractArray{Float64}})

Set a new (continuous) state vector and re-initialize caching of variables that depend on the states. Argument nx is the length of vector x and is provided for checking purposes

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 2.0.2 Standard.
  • x::Union{AbstractArray{Float32},AbstractArray{Float64}}:Argument x is the AbstractArray of the vector values of Float64 or Float32.

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3SetContinuousStates.

source
FMIImport.fmi3GetEventIndicators — Function
fmi3GetEventIndicators(c::FMU3Instance)

Returns the event indicators of the FMU

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.

Returns

  • eventIndicators::Array{fmi3Float64}:The event indicators are returned as a vector represented by an array of "fmi3Float64" values.

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3GetEventIndicators.

source
FMICore.fmi3GetEventIndicators! — Function

Source: FMISpec3.0, Version D5ef1c1: 3.2.1. State: Continuous-Time Mode

Compute event indicators at the current time instant and for the current states. EventIndicators signal Events by their sign change.

source
fmi3GetEventIndicators!(c::FMU3Instance, eventIndicators::AbstractArray{fmi3Float64}, ni::Csize_t)

Compute event indicators at the current time instant and for the current states. EventIndicators signal Events by their sign change.

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.
  • eventIndicators::AbstractArray{fmi3Float64}: Argument eventIndicators contains values of type fmi3Float64 which is a alias type for Real data type.eventIndicators is the AbstractArray which contains the Real values of the vector that represent the event indicators.
  • ni::Csize_t: Argument ni defines the length of vector eventIndicators and is provided for checking purposes

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3GetEventIndicators!.

source

Evaluation of Model Equations

FMICore.fmi3EnterEventMode — Function

Source: FMISpec3.0, Version D5ef1c1: 3.2.1. State: Continuous-Time Mode

The model enters Event Mode from the Continuous-Time Mode in ModelExchange oder Step Mode in CoSimulation and discrete-time equations may become active (and relations are not “frozen”).

source
fmi3EnterEventMode(c::FMU3Instance, stepEvent::fmi3Boolean, stateEvent::fmi3Boolean, rootsFound::AbstractArray{fmi3Int32}, nEventIndicators::Csize_t, timeEvent::fmi3Boolean; soft::Bool=false)

The model enters Event Mode from the Continuous-Time Mode in ModelExchange oder Step Mode in CoSimulation and discrete-time equations may become active (and relations are not “frozen”).

TODO argmuents

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.
  • stepEvent::fmi3Boolean:
  • stateEvent::fmi3Boolean:
  • rootsFound::AbstractArray{fmi3Int32}:
  • nEventIndicators::Csize_t:
  • timeEvent::fmi3Boolean:
  • soft::Bool=false:

Keywords

  • soft::Bool=false: If the Keyword soft = true the fmi3Teminate needs to be called in state fmi3InstanceStateContinuousTimeMode or fmi3InstanceStateEventMode.

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3EnterEventMode.

source
fmi3EnterEventMode(c::FMU3Instance, stepEvent::Bool, stateEvent::Bool, rootsFound::AbstractArray{fmi3Int32}, nEventIndicators::Csize_t, timeEvent::Bool)

The model enters Event Mode from the Continuous-Time Mode in ModelExchange oder Step Mode in CoSimulation and discrete-time equations may become active (and relations are not “frozen”).

TODO argmuents

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.
  • stepEvent::Bool:
  • stateEvent::Bool:
  • rootsFound::AbstractArray{fmi3Int32}:
  • nEventIndicators::Csize_t:
  • timeEvent::Bool:

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3EnterEventMode.

source
FMICore.fmi3EnterContinuousTimeMode — Function

Source: FMISpec3.0, Version D5ef1c1: 2.3.5. State: Event Mode

The model enters Continuous-Time Mode and all discrete-time equations become inactive and all relations are “frozen”. This function has to be called when changing from Event Mode (after the global event iteration in Event Mode over all involved FMUs and other models has converged) into Continuous-Time Mode.

source
fmi3EnterContinuousTimeMode(c::FMU3Instance; soft::Bool=false)

The model enters Continuous-Time Mode and all discrete-time equations become inactive and all relations are “frozen”. This function has to be called when changing from Event Mode (after the global event iteration in Event Mode over all involved FMUs and other models has converged) into Continuous-Time Mode.

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.

Keywords

  • soft::Bool=false: If the Keyword soft = true the fmi3Teminate needs to be called in state fmi3InstanceStateContinuousTimeMode or fmi3InstanceStateEventMode.

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 2.3.5. State: Event Mode

See also fmi3EnterContinuousTimeMode.

source
FMICore.fmi3CompletedIntegratorStep! — Function

Source: FMISpec3.0, Version D5ef1c1: 3.2.1. State: Continuous-Time Mode

This function must be called by the environment after every completed step of the integrator provided the capability flag needsCompletedIntegratorStep = true. If enterEventMode == fmi3True, the event mode must be entered If terminateSimulation == fmi3True, the simulation shall be terminated

source
fmi3CompletedIntegratorStep!(c::FMU3Instance,
                                  noSetFMUStatePriorToCurrentPoint::fmi3Boolean,
                                  enterEventMode::Ref{fmi3Boolean},
                                  terminateSimulation::Ref{fmi3Boolean})

This function must be called by the environment after every completed step of the integrator provided the capability flag needsCompletedIntegratorStep == true. If enterEventMode == fmi3True, the event mode must be entered If terminateSimulation == fmi3True, the simulation shall be terminated

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.
  • noSetFMUStatePriorToCurrentPoint::fmi3Boolean: Argument noSetFMUStatePriorToCurrentPoint = fmi3True if fmi3SetFMUState will no longer be called for time instants prior to current time in this simulation run.
  • enterEventMode::Ref{fmi3Boolean}: Argument enterEventMode points to the return value (fmi3Boolean) which signals to the environment if the FMU shall call fmi3EnterEventMode. fmi3Boolean is an alias type for Boolean data type.
  • terminateSimulation::Ref{fmi3Boolean}: Argument terminateSimulation points to the return value (fmi3Boolean) which signals signal if the simulation shall be terminated. fmi3Boolean is an alias type for Boolean data type.

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 3.2.1. State: Continuous-Time Mode

See also fmi3CompletedIntegratorStep!.

source
FMIImport.fmi3GetContinuousStates — Function
fmi3GetContinuousStates(c::FMU3Instance)

Return the new (continuous) state vector x

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 2.0.2 Standard.

Returns

  • x::Array{fmi3Float64}: Returns an array of fmi3Float64 values representing the new continuous state vector x.

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.3.3. State: Initialization Mode

See also fmi3GetContinuousStates.

source
FMICore.fmi3GetContinuousStates! — Function

Source: FMISpec3.0, Version D5ef1c1: 2.3.3. State: Initialization Mode

Return the states at the current time instant.

This function must be called if fmi3UpdateDiscreteStates returned with valuesOfContinuousStatesChanged == fmi3True. Not allowed in Co-Simulation and Scheduled Execution.

source
fmi3GetContinuousStates!(c::FMU3Instance, nominals::AbstractArray{fmi3Float64}, nContinuousStates::Csize_t)

Return the states at the current time instant.

This function must be called if fmi3UpdateDiscreteStates returned with valuesOfContinuousStatesChanged == fmi3True. Not allowed in Co-Simulation and Scheduled Execution.

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 2.0.2 Standard.
  • nominals::AbstractArray{fmi3Float64}: Argument nominals contains values of type fmi3Float64 which is a alias type for Real data type. nominals is the AbstractArray which contains the Real values of the vector that represent the new state vector.
  • nContinuousStates::Csize_t: Argument nContinuousStates defines the length of vector nominals and is provided for checking purposes

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 2.3.3. State: Initialization Mode

See also fmi3GetContinuousStates!.

source
FMICore.fmi3GetNominalsOfContinuousStates! — Function

Source: FMISpec3.0, Version D5ef1c1: 2.3.3. State: Initialization Mode

Return the nominal values of the continuous states.

If fmi3UpdateDiscreteStates returned with nominalsOfContinuousStatesChanged == fmi3True, then at least one nominal value of the states has changed and can be inquired with fmi3GetNominalsOfContinuousStates. Not allowed in Co-Simulation and Scheduled Execution.

source
fmi3GetNominalsOfContinuousStates!(c::FMU3Instance, x_nominal::AbstractArray{fmi3Float64}, nx::Csize_t)

Return the nominal values of the continuous states.

If fmi3UpdateDiscreteStates returned with nominalsOfContinuousStatesChanged == fmi3True, then at least one nominal value of the states has changed and can be inquired with fmi3GetNominalsOfContinuousStates. Not allowed in Co-Simulation and Scheduled Execution.

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 2.0.2 Standard.
  • x_nominal::AbstractArray{fmi3Float64}: Argument x_nominal contains values of type fmi3Float64 which is a alias type for Real data type. x_nominal is the AbstractArray which contains the Real values of the vector that represent the nominal values of the continuous states.
  • nx::Csize_t: Argument nx defines the length of vector x_nominal and is provided for checking purposes

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 2.3.3. State: Initialization Mode

See also fmi3GetNominalsOfContinuousStates!.

source
FMIImport.fmi3GetNumberOfContinuousStates — Function
fmi3GetNumberOfContinuousStates(c::FMU3Instance)

This function returns the number of continuous states. This function can only be called in Model Exchange.

fmi3GetNumberOfContinuousStates must be called after a structural parameter is changed. As long as no structural parameters changed, the number of states is given in the modelDescription.xml, alleviating the need to call this function.

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.

Returns

  • size::Integer: Return size is the number of continuous states of this instance

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.3.2. State: Instantiated

See also fmi3GetNumberOfContinuousStates.

source
FMICore.fmi3GetNumberOfContinuousStates! — Function

Source: FMISpec3.0, Version D5ef1c1: 2.3.2. State: Instantiated

This function returns the number of continuous states. This function can only be called in Model Exchange.

fmi3GetNumberOfContinuousStates must be called after a structural parameter is changed. As long as no structural parameters changed, the number of states is given in the modelDescription.xml, alleviating the need to call this function.

source
fmi3GetNumberOfContinuousStates!(c::FMU3Instance, nContinuousStates::Ref{Csize_t})

This function returns the number of continuous states. This function can only be called in Model Exchange.

fmi3GetNumberOfContinuousStates must be called after a structural parameter is changed. As long as no structural parameters changed, the number of states is given in the modelDescription.xml, alleviating the need to call this function.

Arguments

  • c::FMU3Instance: Mutable struct represents an instantiated instance of an FMU in the FMI 3.0 Standard.
  • nContinuousStates::Ref{Csize_t}: Stores the number of continuous states returned by the function

Returns

  • status::fmi3Status: Return status is an enumeration of type fmi3Status and indicates the success of the function call.

More detailed:

  • fmi3OK: all well
  • fmi3Warning: things are not quite right, but the computation can continue
  • fmi3Discard: if the slave computed successfully only a subinterval of the communication step
  • fmi3Error: the communication step could not be carried out at all
  • fmi3Fatal: if an error occurred which corrupted the FMU irreparably

Source

  • FMISpec3.0 Link: https://fmi-standard.org/
  • FMISpec3.0: 2.2.3 Platform Dependent Definitions
  • FMISpec3.0: 2.2.4 Status Returned by Functions
  • FMISpec3.0: 2.3.2. State: Instantiated

See also fmi3GetNumberOfContinuousStates!.

source

fmi3CompletedIntegratorStep