Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/1___overview.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Clarifications and fixes of all FMI 3.0 patch releases (FMI 3.0.x) are listed in
=== Overview

The Functional Mock-up Interface (FMI) defines a ZIP archive and an application programming interface (API) to exchange dynamic models using a combination of XML files, binaries and C code: the Functional Mock-up Unit (FMU).
The API is used by a simulation environment, the importer, to create one or more instances of an FMU and to simulate them, typically together with other models.
The API is used by a simulator, the importer, to create one or more instances of an FMU and to simulate them, typically together with other models.
The FMI defines three interface types:

* <<fmi-for-co-simulation,Co-Simulation (CS)>> where the FMU typically contains its own solver or scheduler,
Expand Down Expand Up @@ -107,7 +107,7 @@ image::images/model-exchange-data-flow.svg[width=40%, align="center"]

==== FMI for Co-Simulation (CS)

The Co-Simulation interface is designed both for the coupling of simulation tools, and the coupling of subsystem models, exported by a modeling environment together with their solvers as runnable code.
The Co-Simulation interface is designed both for the coupling of _simulators_, and the coupling of subsystem models, exported by a modeling environment together with their solvers as runnable code.
(See <<fmi-for-co-simulation>>.)

.Schematic view of data flow between user, the co-simulation algorithm of the importer and the FMU for Co-Simulation
Expand Down Expand Up @@ -197,7 +197,7 @@ Expressivity::
The FMI provides the necessary features to package models of different domains, such as multi-body and virtual ECUs, into an FMU.

Stability::
The FMI is expected to be supported by many simulation tools worldwide.
The FMI is expected to be supported by many _simulators_ worldwide.
Implementing such support is a major investment for tool vendors.
Stability and backwards compatibility of the FMI has therefore high priority.

Expand Down
8 changes: 4 additions & 4 deletions docs/2_2_common_mechanisms.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The following general requirements for implementations of FMUs and importers mus

* FMI functions of one instance are not required to be thread-safe. +
_[For example, if the functions of one instance of an FMU are accessed from more than one thread;
the multi-threaded simulation environment that uses the FMU must guarantee that there are no race conditions while invoking the FMI functions.
the multi-threaded simulator that uses the FMU must guarantee that there are no race conditions while invoking the FMI functions.
The FMU itself does not implement any services to support this.]_

* The following FMI callback functions must not call back into the FMU:
Expand Down Expand Up @@ -66,7 +66,7 @@ include::../headers/fmi3FunctionTypes.h[tags=SetTime]
_]_

`fmi3Functions.h`::
contains the function prototypes of an FMU that may be accessed in simulation environments.
contains the function prototypes of an FMU that may be accessed in simulator.
+
This header file includes `fmi3PlatformTypes.h` and `fmi3FunctionTypes.h`.
The header file version number for which the model was compiled, may be inquired by the importer with <<fmi3GetVersion>>. +
Expand Down Expand Up @@ -109,14 +109,14 @@ A function that is defined as `fmi3GetFloat64` is changed by the macros to a fun
- If the FMU is shipped with C source code or with static link library: +
The constructed function name is `MyModel_fmi3GetFloat64`.
In other words, the function name is prefixed with the model name and an `pass:[_]`.
A simulation environment may therefore construct the relevant function names by generating code for the actual function call.
A simulator may therefore construct the relevant function names by generating code for the actual function call.
In case of a static link library, the name of the library must be `MyModel.lib` on Windows and `libMyModel.a` on Linux; in other words the <<modelIdentifier>> attribute is used to create the library name.

- If the FMU is shipped with DLL/SharedObject: +
The constructed function name is `fmi3GetFloat64`, in other words, it is not changed.
_[This can be realized in the case of a source code FMU with a target-specific version of `fmi3Functions.h` that does not use FMI3_FUNCTION_PREFIX to construct the function names._
_Using the standard-supplied version of `fmi3Functions.h`, the same effect can be achieved by defining the `FMI3_OVERRIDE_FUNCTION_PREFIX` precompiler macro prior to the inclusion of the `fmi3Functions.h` header, for example using precompiler command-line flags.]_
A simulation environment dynamically loads this library and explicitly imports the function pointers by providing the FMI function names as strings.
A simulator dynamically loads this library and explicitly imports the function pointers by providing the FMI function names as strings.
The name of the library must be `MyModel.dll` on Windows or `MyModel.so` on Linux; in other words the <<modelIdentifier>> attribute is used as library name.

Since <<modelIdentifier>> may be used as prefix of a C-function name it must fulfill the restrictions on C-function
Expand Down
6 changes: 3 additions & 3 deletions docs/2_3_common_states.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ For FMUs that have clocks, `eventModeUsed = fmi3True` is required.
* [[earlyReturnAllowed,`earlyReturnAllowed`]]If `earlyReturnAllowed = fmi3True` the importer can handle <<early-return,early return>>.
Only in this case, <<fmi3DoStep>> may return with <<earlyReturn,`earlyReturn = fmi3True`>>.

* `instanceEnvironment` is a pointer that must be passed to <<fmi3IntermediateUpdateCallback>>, <<fmi3ClockUpdateCallback>>, and <<logMessage,`fmi3LogMessageCallback`>> to allow the simulation environment an efficient way to identify the calling FMU.
* `instanceEnvironment` is a pointer that must be passed to <<fmi3IntermediateUpdateCallback>>, <<fmi3ClockUpdateCallback>>, and <<logMessage,`fmi3LogMessageCallback`>> to allow the simulator an efficient way to identify the calling FMU.

* [[requiredIntermediateVariables,`requiredIntermediateVariables`]] `requiredIntermediateVariables` is an array of the value references of all <<input>> variables that the simulation algorithm intends to set and all <<output>> variables it intends to get during intermediate updates.
This set may be empty (<<nRequiredIntermediateVariables>> = 0) when the simulation algorithm does not intend to use intermediate update.
Expand Down Expand Up @@ -122,7 +122,7 @@ If the FMU does not define any log categories, `category` must be `NULL`.

+
All string-valued arguments passed by the FMU to the <<logMessage>> may be deallocated by the FMU directly after function <<logMessage>> returns.
_[The simulation environment must therefore create copies of these strings if it needs to access these strings later.]_ +
_[The simulator must therefore create copies of these strings if it needs to access these strings later.]_ +
Variables can be referenced in a message with `pass:[#]<ValueReference>pass:[#]`.
If the character `pass:[#]` shall be included in the message, it has to be prefixed with `pass:[#]`, so `pass:[#]` is an escape character. +
_[Example: The message `\#1365# must be larger than zero (used in IO channel ##4)` might be changed by the <<logMessage>> function to `body.m must be larger than zero (used in IO channel #4)` if `body.m` is the name of the variable with value reference 1365.]_
Expand All @@ -137,7 +137,7 @@ See <<fmi3ClockUpdateCallback>> for details.
See <<preemption-support>> for details.

+
The arguments <<logMessage>>, <<fmi3IntermediateUpdateCallback,`intermediateUpdate`>>, <<fmi3ClockUpdateCallback,`clockUpdate`>>, <<preemption-support,`lockPreemption`>>, and <<preemption-support,`unlockPreemption`>>, are function pointers provided by the simulation environment to be used by the FMU.
The arguments <<logMessage>>, <<fmi3IntermediateUpdateCallback,`intermediateUpdate`>>, <<fmi3ClockUpdateCallback,`clockUpdate`>>, <<preemption-support,`lockPreemption`>>, and <<preemption-support,`unlockPreemption`>>, are function pointers provided by the simulator to be used by the FMU.
Each of these pointers can be NULL to indicate missing support for the respective functionality.
If such functionality is used anyway, undefined behavior results.
_[For example, if <<logMessage,`logMessage = NULL`>>, calls to <<fmi3SetDebugLogging>> result in undefined behavior of the FMU._
Expand Down
2 changes: 1 addition & 1 deletion docs/2_4_common_schema.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2340,7 +2340,7 @@ _This header file is not included in the `binaries` directory, because it is imp
_pass:[]`fmi3FunctionTypes.h` / `fmi3Functions.h` are not needed in the `sources` directory, because they are implicitly defined by attribute `fmiVersion` in file <<modelDescription.xml>>._
_Furthermore, in order that the C compiler can check for consistent function arguments, the header file from the importer should be used when compiling the C sources._
_It would therefore be counter-productive (unsafe) if this header file was present._ +
_These header files are not included in the `binaries` directory, since they are already utilized to build the executable of the simulation environment._
_These header files are not included in the `binaries` directory, since they are already utilized to build the executable of the simulator._
_The version number of the header file used to construct the FMU can be deduced via attribute `fmiVersion` in file <<modelDescription.xml>> or via function call <<fmi3GetVersion>>.]_

===== Library
Expand Down
4 changes: 2 additions & 2 deletions docs/3_3_model_exchange_example.adoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
=== Code Example

In the following example, the usage of the `fmi3XXX` functions is sketched in order to clarify the typical calling sequence of the functions in a simulation environment.
Furthermore, it is assumed that one FMU is directly integrated in a simulation environment.
In the following example, the usage of the `fmi3XXX` functions is sketched in order to clarify the typical calling sequence of the functions in a simulator.
Furthermore, it is assumed that one FMU is directly integrated in a simulator.
If the FMU would be used inside another model, additional code is needed, especially initialization and event iteration have to be adapted.

[source, c]
Expand Down
2 changes: 1 addition & 1 deletion docs/4_3_co-simulation_example.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ image::images/cs_intermediate_update.svg[width=100%]

==== Connected FMUs

In the following example, the usage of the FMI functions is sketched in order to clarify the typical calling sequence of the functions in a simulation environment.
In the following example, the usage of the FMI functions is sketched in order to clarify the typical calling sequence of the functions in a simulator.
We consider two FMUs, where both have one <<continuous>> floating point <<input>> and one <<continuous>> floating point <<output>> which are connected in the following way:

.Connection graph of FMUs.
Expand Down
2 changes: 1 addition & 1 deletion docs/4___co-simulation.adoc
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
== FMI for Co-Simulation [[fmi-for-co-simulation]]

FMI for Co-Simulation provides a standardized interface for execution of simulation models or tools in a co-simulation environment.
FMI for Co-Simulation provides a standardized interface for execution of simulation models or _simulators_ in a co-simulation environment.
In contrast to FMI for Model Exchange, a Co-Simulation FMU implements not only the model algorithm, but also the required solution method.
The data exchange between FMUs is restricted to discrete communication points latexmath:[t_i] (unless <<IntermediateUpdateMode>> is used).
In the time between two communication points (or between entering <<IntermediateUpdateMode>>), the subsystem inside an FMU is solved independently by internal means.
Expand Down
27 changes: 9 additions & 18 deletions docs/7___appendix.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,10 @@ A <<Clock>> tick causes a <<Clock>> activation at that time instant, except for
|See <<time-instant>>.

|_co-simulation_
|Coupling of several _simulation programs_ in order to compute the global behavior of a system that consists of several subsystems.
|Coupling of several _simulators_ in order to compute the global behavior of a system that consists of several subsystems.
The subsystems are coupled in the sense that the behavior of each subsystem depends on the behavior of the remaining subsystems, so that the co-simulation must be computed in a step-by-step fashion.
Each simulation program is responsible for computing the behavior of a subsystem, using the outputs produced by the other simulation programs.
Synonyms: dynamic mutual-exchange, simulator coupling, and coupled simulation.
Each simulator is responsible for computing the behavior of a subsystem, using the outputs produced by the other simulators.
Synonyms: dynamic mutual-exchange, and coupled simulation.

|_direct feedthrough_
|Direct feedthrough describes that values of output variables depend directly on values of input variables.
Expand Down Expand Up @@ -113,7 +113,7 @@ It may contain multiple FMI types, see <<multipleInterfaceTypes>>.

|[[importer, importer]]_importer_
|The tool that imports or loads one or more FMUs.
Also called simulation environment, environment, calling environment, (co-)simulation algorithm, target platform, target environment, integrator (in ME).
Also called simulator, (co-)simulation algorithm, target platform, target environment, integrator (in ME).

|_independent variable_
|All variables are a function of this <<independent>> variable, typically time.
Expand Down Expand Up @@ -153,7 +153,7 @@ It can be used to compute its expected behavior under specified conditions.
|The model description file is an XML file named <<modelDescription.xml>>, which supplies a description of all properties of a _model_ (for example, <<input>> / <<output>> variables).

|_Model Description Schema_
|An _XML_ schema that defines how all relevant, non-executable, information about a "model class" (_FMU)_ is stored in a text file in _XML_ format.
|An _XML_ schema that defines how all relevant, non-executable, information about a "model class" (_FMU_) is stored in a text file in _XML_ format.
Most important, data for every variable is defined (variable name, handle, data type, variability, unit, etc.), see <<modelDescription.xml>>.

|[[model-partition,model partition]]_model partition_
Expand Down Expand Up @@ -185,7 +185,7 @@ These parameters are different from <<calculatedParameter,calculated parameters>
|Recalculation of <<state,continuous-time states>> by the model.

|_runtime environment_
|See co-simulation environment
|See _simulator_

|_simulation_
|Compute the behavior of one or several _models_ under specified conditions. +
Expand All @@ -194,18 +194,9 @@ These parameters are different from <<calculatedParameter,calculated parameters>
|_simulation model_
|see _model_

|_simulation program_
|Software to develop and/or solve simulation _models_.
The software includes a _solver_, may include a user interface and methods for post processing (see also: _simulation tool_, _simulation environment_). +

|_simulation tool_
|see _simulation program_

|_simulator_
|A simulator can include one or more _simulation programs_.

|_simulator coupling_
|See _tool coupling_.
|Software to develop and/or solve simulation _models_.
The software includes a _solver_, may include a user interface and methods for post processing.

|_solver_
|_Software component,_ which includes algorithms to solve _models_, for example, _integration algorithms_ and _event handling_ methods.
Expand Down Expand Up @@ -252,7 +243,7 @@ Therefore, this event can be handled efficiently.
Also known as the _bi-lateral delay line_ method. For more details see <<FBH18>>.

|_user interface_
|The part of the simulation program that gives the user control over the simulation and allows watching results.
|The part of a _simulator_ that gives the user control over the simulation and allows watching results.

|_XML_
|eXtensible Markup Language (https://www.w3.org/XML/[www.w3.org/XML], https://en.wikipedia.org/wiki/Xml[en.wikipedia.org/wiki/XML]) - An open standard to store information in text files in a structured form.
Expand Down