loadFMU(pathToFMU; unpackPath, cleanup, type)

Loads an FMU, independent of the used FMI-version (the version is checked during unpacking the archive).

Arguments

• path::String the path pointing on the FMU file.

Keywords

• unpackPath::Union{String, Nothing}=nothing the optional unpack path, if nothing a temporary directory depending on the OS is picked.
• cleanup::Bool=true a boolean indicating whether the temporary directory should be cleaned automatically.
• type::Union{Symbol, Nothing}=nothing the type of FMU (:CS, :ME, :SE), if multiple types are available. If nothing one of the available types is chosen automatically with the priority CS > ME > SE.

simulate(fmu, instance=nothing; tspan=nothing, kwargs...)
simulate(instance; tspan=nothing, kwargs...)

Starts a simulation of the FMU2 for the instantiated type: CS, ME or SE (this is selected automatically or during loading of the FMU). You can force a specific simulation mode by calling simulateCS, simulateME or simulateSE directly.

Arguments

• fmu::FMU: The FMU to be simulated.
• c::Union{FMUInstance, Nothing}=nothing: The instance (FMI3) or component (FMI2) of the FMU, nothing if not available.

Keyword arguments

• tspan::Union{Tuple{Float64, Float64}, Nothing}=nothing: Simulation-time-span as tuple (default = nothing: use default value from FMU's model description or (0.0, 1.0) if not specified)
• recordValues::fmi2ValueReferenceFormat = nothing: Array of variables (Strings or variableIdentifiers) to record. Results are returned as DiffEqCallbacks.SavedValues
• saveat = nothing: Time points to save (interpolated) values at (default = nothing: save at each solver timestep)
• setup::Bool: call fmi2SetupExperiment, fmi2EnterInitializationMode and fmi2ExitInitializationMode before the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• reset::Bool: call fmi2Reset before each the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• instantiate::Bool: call fmi2Instantiate! simulate on a new created instance (default = nothing: use value from fmu's FMUExecutionConfiguration)
• freeInstance::Bool: call fmi2FreeInstance at the end of the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• terminate::Bool: call fmi2Terminate at the end of the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• inputValueReferences::fmi2ValueReferenceFormat = nothing: Input variables (Strings or variableIdentifiers) to set at each simulation step
• inputFunction = nothing: Function to get values for the input variables at each simulation step.
• parameters::Union{Dict{<:Any, <:Any}, Nothing} = nothing: Dict of parameter variables (strings or variableIdentifiers) and values (Real, Integer, Boolean, String) to set parameters during initialization
• showProgress::Bool = true: print simulation progress meter in REPL

Input function pattern

[c: current component, u: current state ,t: current time, returning array of values to be passed to fmi2SetReal(..., inputValueReferences, inputFunction(...)) or fmi3SetFloat64]:

• inputFunction(t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, x::AbstractVector{<:Real}, u::AbstractVector{<:Real})
• inputFunction(x::AbstractVector{<:Real}, t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, x::AbstractVector{<:Real}, t::Real, u::AbstractVector{<:Real})

Returns:

• A FMUSolution struct.

See also simulate, simulateME, simulateCS, simulateSE.

simulateCS(fmu, instance=nothing; tspan=nothing, kwargs...)
simulateCS(instance; tspan=nothing, kwargs...)

Simulate CS-FMU for the given simulation time interval. State- and Time-Events are handled internally by the FMU.

Arguments

• fmu::FMU: The FMU to be simulated.
• c::Union{FMUInstance, Nothing}=nothing: The instance (FMI3) or component (FMI2) of the FMU, nothing if not available.

Keyword arguments

• tspan::Union{Tuple{Float64, Float64}, Nothing}=nothing: Simulation-time-span as tuple (default = nothing: use default value from FMU's model description or (0.0, 1.0) if not specified)
• tolerance::Union{Real, Nothing} = nothing: The tolerance for the internal FMU solver.
• recordValues::fmi2ValueReferenceFormat = nothing: Array of variables (Strings or variableIdentifiers) to record. Results are returned as DiffEqCallbacks.SavedValues
• saveat = nothing: Time points to save (interpolated) values at (default = nothing: save at each solver timestep)
• setup::Bool: call fmi2SetupExperiment, fmi2EnterInitializationMode and fmi2ExitInitializationMode before the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• reset::Bool: call fmi2Reset before each the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• instantiate::Bool: call fmi2Instantiate! simulate on a new created instance (default = nothing: use value from fmu's FMUExecutionConfiguration)
• freeInstance::Bool: call fmi2FreeInstance at the end of the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• terminate::Bool: call fmi2Terminate at the end of the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• inputValueReferences::fmi2ValueReferenceFormat = nothing: Input variables (Strings or variableIdentifiers) to set at each simulation step
• inputFunction = nothing: Function to get values for the input variables at each simulation step.
• parameters::Union{Dict{<:Any, <:Any}, Nothing} = nothing: Dict of parameter variables (strings or variableIdentifiers) and values (Real, Integer, Boolean, String) to set parameters during initialization
• showProgress::Bool = true: print simulation progress meter in REPL

Input function pattern

[c: current component, u: current state ,t: current time, returning array of values to be passed to fmi2SetReal(..., inputValueReferences, inputFunction(...)) or fmi3SetFloat64]:

• inputFunction(t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, x::AbstractVector{<:Real}, u::AbstractVector{<:Real})
• inputFunction(x::AbstractVector{<:Real}, t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, x::AbstractVector{<:Real}, t::Real, u::AbstractVector{<:Real})

Returns:

• A FMUSolution struct.

See also simulate, simulateME, simulateSE.

simulateSE(fmu, instance=nothing; tspan=nothing, kwargs...)
simulateSE(instance; tspan=nothing, kwargs...)

To be implemented ...

Arguments

• fmu::FMU3: The FMU to be simulated. Note: SE is only available in FMI3.
• c::Union{FMU3Instance, Nothing}=nothing: The instance (FMI3) of the FMU, nothing if not available.

Keyword arguments

• tspan::Union{Tuple{Float64, Float64}, Nothing}=nothing: Simulation-time-span as tuple (default = nothing: use default value from FMU's model description or (0.0, 1.0) if not specified)
• To be implemented ...

Returns:

• A FMUSolution struct.

See also simulate, simulateME, simulateCS.

simulateME(fmu, instance=nothing; tspan=nothing, kwargs...)
simulateME(instance; tspan=nothing, kwargs...)

Simulate ME-FMU for the given simulation time interval. State- and Time-Events are handled correctly.

Arguments

• fmu::FMU: The FMU to be simulated.
• c::Union{FMUInstance, Nothing}=nothing: The instance (FMI3) or component (FMI2) of the FMU, nothing if not available.

Keyword arguments

• tspan::Union{Tuple{Float64, Float64}, Nothing}=nothing: Simulation-time-span as tuple (default = nothing: use default value from FMU's model description or (0.0, 1.0) if not specified)
• solver = nothing: Any Julia-supported ODE-solver (default = nothing: use DifferentialEquations.jl default solver)
• recordValues::fmi2ValueReferenceFormat = nothing: Array of variables (Strings or variableIdentifiers) to record. Results are returned as DiffEqCallbacks.SavedValues
• recordEventIndicators::Union{AbstractArray{<:Integer, 1}, UnitRange{<:Integer}, Nothing} = nothing: Array or Range of event indicators to record
• recordEigenvalues::Bool=false: compute and record eigenvalues
• saveat = nothing: Time points to save (interpolated) values at (default = nothing: save at each solver timestep)
• x0::Union{AbstractArray{<:Real}, Nothing} = nothing: initial fmu State (default = nothing: use current or default-initial fmu state)
• setup::Bool: call fmi2SetupExperiment, fmi2EnterInitializationMode and fmi2ExitInitializationMode before the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• reset::Bool: call fmi2Reset before each the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• instantiate::Bool: call fmi2Instantiate! simulate on a new created instance (default = nothing: use value from fmu's FMUExecutionConfiguration)
• freeInstance::Bool: call fmi2FreeInstance at the end of the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• terminate::Bool: call fmi2Terminate at the end of the simulation (default = nothing: use value from fmu's FMUExecutionConfiguration)
• inputValueReferences::fmi2ValueReferenceFormat = nothing: Input variables (Strings or variableIdentifiers) to set at each simulation step
• inputFunction = nothing: Function to get values for the input variables at each simulation step.
• parameters::Union{Dict{<:Any, <:Any}, Nothing} = nothing: Dict of parameter variables (strings or variableIdentifiers) and values (Real, Integer, Boolean, String) to set parameters during initialization
• callbacksBefore = []: callbacks to call before the internal callbacks for state- and time-events are called
• callbacksAfter = []: callbacks to call after the internal callbacks for state- and time-events are called
• showProgress::Bool = true: print simulation progress meter in REPL
• solveKwargs...: keyword arguments that get passed onto the solvers solve call

Input function pattern

[c: current component, u: current state ,t: current time, returning array of values to be passed to fmi2SetReal(..., inputValueReferences, inputFunction(...)) or fmi3SetFloat64]:

• inputFunction(t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, x::AbstractVector{<:Real}, u::AbstractVector{<:Real})
• inputFunction(x::AbstractVector{<:Real}, t::Real, u::AbstractVector{<:Real})
• inputFunction(c::Union{FMUInstance, Nothing}, x::AbstractVector{<:Real}, t::Real, u::AbstractVector{<:Real})

Returns:

• A FMUSolution struct.

See also simulate, simulateCS, simulateSE.

unloadFMU(fmu::FMU2, cleanUp::Bool=true; secure_pointers::Bool=true)

Unload a FMU. Free the allocated memory, close the binaries and remove temporary zip and unziped FMU model description.

Arguments

• fmu::FMU2: Mutable struct representing a FMU and all it instantiated instances in the FMI 2.0.2 Standard.
• cleanUp::Bool= true: Defines if the file and directory should be deleted.

Keywords

• secure_pointers=true whether pointers to C-functions should be overwritten with dummies with Julia assertions, instead of pointing to dead memory (slower, but more user safe)

reload(fmu::FMU2)

Reloads the FMU-binary. This is useful, if the FMU does not support a clean reset implementation.

Arguments

• fmu::FMU2: Mutable struct representing a FMU and all it instantiated instances in the FMI 2.0.2 Standard.

FMUProblem(fmu, tspan=nothing; kwargs...)
FMUProblem(instance, tspan=nothing; kwargs...)

A SciML-style problem wrapper for simulating FMUs.

For Model Exchange FMUs, solve(::FMUProblem) prepares an internal ODEProblem and returns the resulting SciML ODESolution. For Co-Simulation FMUs, solve uses the FMU's own do-step interface instead of an ODE algorithm.

The simulation mode must be one of :ME, :CS or :SE. If no mode is given, :CS is used if the FMU supports Co-Simulation, otherwise :ME (or :SE for FMI3 FMUs that only support Scheduled Execution).

stringToValueReference(obj, names)

Finds the value reference for a given name.

Arguments

• obj ∈ (fmi2ModelDescription, fmi3ModelDescription, FMU2, FMU3) the FMI object
• names ∈ (String, AbstractVector{String}) the value refernce name or multiple names

Return

Returns a single or an array of fmi2ValueReferences (FMI2) or fmi3ValueReferences (FMI3) corresponding to the variable name(s).

 info(fmu)

Print information about the FMU.

Arguments

• fmu::FMU: The FMU you are interessted in.

Further reading

• FMISpec2.0.2 Link: https://fmi-standard.org/

getModelName(md::fmi2ModelDescription)

Returns the tag 'modelName' from the model description.

Arguments

• md::fmi2ModelDescription: Struct which provides the static information of ModelVariables.

Returns

• modelName::String: Returns the tag 'modelName' from the model description.

getNumberOfStates(md::fmi2ModelDescription)

Returns the number of states of the FMU.

Arguments

• md::fmi2ModelDescription: Struct which provides the static information of ModelVariables.

Returns

• Returns the number of states of the FMU.

isModelExchange(md::fmi2ModelDescription)

Returns true, if the FMU supports model exchange

Arguments

• md::fmi2ModelDescription: Struct which provides the static information of ModelVariables.

Returns

• ::Bool: Returns true, if the FMU supports model exchange

Returns true, if the FMU supports scheduled execution

isCoSimulation(md::fmi2ModelDescription)

Returns true, if the FMU supports co simulation

Arguments

• md::fmi2ModelDescription: Struct which provides the static information of ModelVariables.

Returns

• ::Bool: Returns true, if the FMU supports co simulation

getState(solution::FMUSolution, vr::fmi2ValueReferenceFormat; isIndex::Bool=false)

Returns the solution state.

Arguments

• solution::FMUSolution: Struct contains information about the solution value, success, state and events of a specific FMU.
• vr::fmi2ValueReferenceFormat: wildcards for how a user can pass a fmi[X]ValueReference (default = md.valueReferences)

More detailed: fmi2ValueReferenceFormat = Union{Nothing, String, Array{String,1}, fmi2ValueReference, Array{fmi2ValueReference,1}, Int64, Array{Int64,1}, Symbol}

• isIndex::Bool=false: Argument isIndex exists to check if vr ist the specific solution element ("index") that equals the given fmi2ValueReferenceFormat

Return

• If he length of the given references equals 1, each element u in the collection solution.states.u, it is selecting the element at the index represented by indices[1] and returns it.

Thus, the collect() function is taking the generator expression and returning an array of the selected elements.

• If more than one reference is given, the same process takes place as before. The difference is that now more than one index is accessed.

Source

• FMISpec2.0.2 Link: https://fmi-standard.org/
• FMISpec2.0.2[p.22]: 2.1.2 Platform Dependent Definitions (fmi2TypesPlatform.h)

getTime(solution::FMUSolution)

Returns the Solution time.

Arguments

• solution::FMUSolution: Struct contains information about the solution value, success, state and events of a specific FMU.

Return

• solution.states.t::tType: solution.state is a struct ODESolution with attribute t. t is the time points corresponding to the saved values of the ODE solution.
• solution.values.t::tType: solution.value is a struct ODESolution with attribute t.t the time points corresponding to the saved values of the ODE solution.
• If no solution time is found nothing is returned.

#Source

• using OrdinaryDiffEq: ODESolution (SciML/SciMLBase.jl)
• FMISpec2.0.2 Link: https://fmi-standard.org/
• FMISpec2.0.2[p.22]: 2.1.2 Platform Dependent Definitions (fmi2TypesPlatform.h)

getStateDerivative(solution::FMUSolution, vr::fmi2ValueReferenceFormat; isIndex::Bool=false)

Returns the solution state derivative.

Arguments

• solution::FMUSolution: Struct contains information about the solution value, success, state and events of a specific FMU.
• vr::fmi2ValueReferenceFormat: wildcards for how a user can pass a fmi[X]ValueReference (default = md.valueReferences)

More detailed: fmi2ValueReferenceFormat = Union{Nothing, String, Array{String,1}, fmi2ValueReference, Array{fmi2ValueReference,1}, Int64, Array{Int64,1}, Symbol}

• isIndex::Bool=false: Argument isIndex exists to check if vr ist the specific solution element ("index") that equals the given fmi2ValueReferenceFormat

Return

• If the length of the given references equals 1, each element myt in the collection solution.states.t is selecting the derivative of the solution states represented by indices[1] in respect to time, at time myt and returns its it.

Thus, the collect() function is taking the generator expression and returning an array of the selected derivatives.

• If more than one reference is given, the same process takes place as before. The difference is that now more than one index is accessed.

Source

• FMISpec2.0.2 Link: https://fmi-standard.org/
• FMISpec2.0.2[p.22]: 2.1.2 Platform Dependent Definitions (fmi2TypesPlatform.h)

saveSolution(solution::FMUSolution, filepath::AbstractString [; keyword="solution"])

Saves a solution of an FMU simulation at filepath.

Currently .mat, .jld2 and .csv are supported for saving and selected by the ending of filepath. For JLD2 the keyword is used as key.

See also saveSolutionCSV, saveSolutionMAT, saveSolutionJLD2, and loadSolutionJLD2.

loadSolution(filepath::AbstractString; keyword="solution")

Loads a solution of an FMU simulation at filepath.

Currently only .jld2 is implemented for loading. For JLD2 the keyword is used as key.

See also saveSolutionCSV, saveSolutionMAT, saveSolutionJLD2, and loadSolutionJLD2.