From c62548b0f20f88bd3e4649378207b215cbe6d075 Mon Sep 17 00:00:00 2001 From: Torsten Sommer Date: Tue, 4 Nov 2025 08:55:48 +0100 Subject: [PATCH 1/3] Use Modelica theme --- .gitignore | 4 +- docs/0___preamble.adoc | 5 - docs/1___overview.adoc | 12 +- docs/2_1_common_math.adoc | 31 +- docs/2_2_common_mechanisms.adoc | 354 ++++-- docs/2_3_common_states.adoc | 155 ++- docs/2_4_common_schema.adoc | 1017 +++++++++-------- docs/2_5_fmu_distribution.adoc | 51 +- docs/2_6_versioning_layered_standards.adoc | 8 +- docs/3_1_model_exchange_math.adoc | 28 +- docs/3_2_model_exchange_api.adoc | 53 +- docs/3_4_model_exchange_schema.adoc | 2 +- docs/4_1_co-simulation_math.adoc | 21 +- docs/4_2_co-simulation_api.adoc | 46 +- docs/4_3_co-simulation_example.adoc | 10 +- docs/4_4_co-simulation_schema.adoc | 11 +- docs/4___co-simulation.adoc | 5 +- docs/5_1_scheduled_execution_math.adoc | 33 +- docs/5_2_scheduled_execution_api.adoc | 31 +- docs/5_3_scheduled_execution_example.adoc | 2 +- docs/5_4_scheduled_execution_schema.adoc | 2 +- docs/5___scheduled_execution.adoc | 5 +- docs/docinfo.html | 102 -- docs/fmi-spec.css | 468 -------- docs/images/favicon.ico | Bin 15086 -> 7821 bytes docs/index.adoc | 7 +- docs/ma-asciidoctor-theme/css/modelica.css | 332 ++++++ .../docinfo/docinfo-header.html | 23 + .../ma-asciidoctor-theme/docinfo/docinfo.html | 5 + docs/ma-asciidoctor-theme/js/color-theme.js | 78 ++ docs/ma-asciidoctor-theme/js/scrollspy.js | 64 ++ docs/ma-asciidoctor-theme/js/toggle-toc.js | 13 + 32 files changed, 1660 insertions(+), 1318 deletions(-) delete mode 100644 docs/docinfo.html delete mode 100644 docs/fmi-spec.css create mode 100644 docs/ma-asciidoctor-theme/css/modelica.css create mode 100644 docs/ma-asciidoctor-theme/docinfo/docinfo-header.html create mode 100644 docs/ma-asciidoctor-theme/docinfo/docinfo.html create mode 100644 docs/ma-asciidoctor-theme/js/color-theme.js create mode 100644 docs/ma-asciidoctor-theme/js/scrollspy.js create mode 100644 docs/ma-asciidoctor-theme/js/toggle-toc.js diff --git a/.gitignore b/.gitignore index d2167e2d0..f552ff60e 100644 --- a/.gitignore +++ b/.gitignore @@ -11,8 +11,8 @@ xsddiagram/ # build artifacts build/ -# keep docinfo -!docinfo.html +# keep docinfo files +!docinfo*.html # custom automation scripts *.bat diff --git a/docs/0___preamble.adoc b/docs/0___preamble.adoc index 2090c1281..c421e4e70 100644 --- a/docs/0___preamble.adoc +++ b/docs/0___preamble.adoc @@ -2,9 +2,6 @@ The https://fmi-standard.org/[Functional Mock-up Interface (FMI)] is a free stan [[MAP,MAP]]It is supported by https://fmi-standard.org/tools/[more than 230 tools] and maintained as a https://www.modelica.org/association/[Modelica Association Project] (MAP FMI). https://github.com/modelica/fmi-standard/releases[Releases] and https://github.com/modelica/fmi-standard/issues[issues] can be found on https://github.com/modelica/fmi-standard[github.com/modelica/fmi-standard]. -{empty} + -{empty} - Copyright (C) 2008-2011 MODELISAR Consortium and 2012-2025 The Modelica Association Project FMI. This document is licensed under the Attribution-ShareAlike 4.0 International license. @@ -14,5 +11,3 @@ The licenses text can be found in the https://raw.githubusercontent.com/modelica Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. Modelica Association shall not be held responsible for identifying such patent rights. All contributors to this specification have signed the https://github.com/modelica/fmi-standard.org/blob/main/static/assets/FMI_CCLA_v1.0_2016_06_21.pdf[Corporate Contributor License Agreement of the FMI Project] or the https://github.com/modelica/ModelicaAssociationCLA/releases/download/1.1.1/ModelicaAssociationCLA_1.1.1.pdf[Contributor License Agreement of the Modelica Association]. - -{empty} diff --git a/docs/1___overview.adoc b/docs/1___overview.adoc index 7d82cf83f..9667d15a3 100644 --- a/docs/1___overview.adoc +++ b/docs/1___overview.adoc @@ -103,7 +103,7 @@ That integration algorithm of the importer, usually a ODE/DAE solver, is respons .Schematic view of data flow between user, the solver of the importer and the FMU for Model Exchange [#figure-model-exchange-data-flow] -image::images/model-exchange-data-flow.svg[width=40%, align="center"] +image::images/model-exchange-data-flow.svg[width=450] ==== FMI for Co-Simulation (CS) @@ -112,7 +112,7 @@ The Co-Simulation interface is designed both for the coupling of simulation tool .Schematic view of data flow between user, the co-simulation algorithm of the importer and the FMU for Co-Simulation [#figure-co-simulation-data-flow] -image::images/co-simulation-data-flow.svg[width=40%, align="center"] +image::images/co-simulation-data-flow.svg[width=450] ==== FMI for Scheduled Execution (SE) @@ -123,7 +123,7 @@ _[See also https://modelica.github.io/fmi-guides/main/fmi-guide/#_use_cases_for_ .Schematic view of data flow between user, the scheduler of the importer and model partitions of the FMU for Scheduled Execution [#figure-scheduled-execution-data-flow] -image::images/scheduled-execution-data-flow.svg[width=40%, align="center"] +image::images/scheduled-execution-data-flow.svg[width=600] ==== Feature Overview of the Interface Types @@ -131,7 +131,7 @@ Co-Simulation FMUs contain all code necessary to abstract away the details of th This simplifies the importer compared to Model Exchange and Scheduled Execution, at the cost of reduced flexibility of use. .Simplicity of import versus flexibility of use -image::images/fmi-types-overview.svg[width=50%, align="center"] +image::images/fmi-types-overview.svg[width=550] <> gives a non-normative overview of the features of the different interface types. @@ -336,7 +336,9 @@ Contrary to the standard, the FMI Implementer's Guide will be a living document, Conventions used in this document: -* Non-normative text is given in square brackets in italic font: _[Especially examples are defined in this style.]_ +* Non-normative text is given in a gray box like this one: ++ +NOTE: Especially examples are defined in this style. * The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in https://tools.ietf.org/html/rfc2119[RFC 2119] (regardless of formatting and capitalization). diff --git a/docs/2_1_common_math.adoc b/docs/2_1_common_math.adoc index 5ee6f6f8d..4f41f5245 100644 --- a/docs/2_1_common_math.adoc +++ b/docs/2_1_common_math.adoc @@ -66,8 +66,11 @@ latexmath:[t_{\mathit{Imax}}] is the largest occurring integer index of super-de a|previous value |==== -_[Assume that an FMU has an event at latexmath:[t_R=2.1s] and here a variable changes discontinuously._ -_If no event iteration occurs, the time instant when the event occurs is defined as (2.1, 0), and the time instant when the integration is restarted is defined as (2.1, 1).]_ +[NOTE] +==== +Assume that an FMU has an event at latexmath:[t_R=2.1s] and here a variable changes discontinuously. +If no event iteration occurs, the time instant when the event occurs is defined as (2.1, 0), and the time instant when the integration is restarted is defined as (2.1, 1). +==== The hybrid differential equations exposed by FMI for Model Exchange or wrapped by FMI for Co-Simulation are described as piecewise continuous-time systems. Discontinuities can occur at time instants latexmath:[t_0, t_1, \ldots, t_n] where latexmath:[t_i < t_{i+1}]. @@ -112,7 +115,11 @@ These variables are continuous-time variables. |`attribute = value` |A set of variables which have an XML attribute-value combination as defined. -_[Example:_ latexmath:[\mathbf{v}_{\mathit{initial=exact}}] _are variables defined with attribute <> = <> (see <>).]_ + +[NOTE] +==== +Example: latexmath:[\mathbf{v}_{\mathit{initial=exact}}] are variables defined with attribute <> = <> (see <>). +==== |==== @@ -120,7 +127,7 @@ At every event instant latexmath:[t_i], continuous-time variables might change d .Piecewise-continuous variables of an FMU: continuous-time (latexmath:[\mathbf{v}_c]), discrete-time (latexmath:[\mathbf{v}_d]) and clocked (latexmath:[\mathbf{v}_k]). [#figure-piecewise-continuous-variables] -image::images/PieceWiseContinuousVariables.svg[width=40%] +image::images/PieceWiseContinuousVariables.svg[width=400] The mathematical description of an FMU uses the following variables, where bold variables (e.g. latexmath:[\mathbf{v}]) indicate vectors and italic variables (e.g. latexmath:[t]) denote scalars: @@ -132,7 +139,11 @@ The mathematical description of an FMU uses the following variables, where bold |Description a|latexmath:[t] -a|<> variable _[typically: time]_ latexmath:[\in \mathbb{T}]. +a|<> variable + +NOTE: typically: time + +latexmath:[\in \mathbb{T}]. This variable is defined with <> = <>. All other variables are functions of this independent variable. @@ -190,13 +201,15 @@ latexmath:[{}^{\bullet}\mathbf{x}_d] is the value of latexmath:[\mathbf{x}_d] at Every event removes automatically a previous definition of latexmath:[T_{\mathit{next}}], and it must be explicitly defined again, even if a previously defined latexmath:[T_{\mathit{next}}] was not yet reached (see <>). |[[relations,relations]] latexmath:[\mathbf{r}] -|A vector of Boolean variables representing relations: latexmath:[\mathbf{r}_j := \mathbf{z}_j > 0]. +a|A vector of Boolean variables representing relations: latexmath:[\mathbf{r}_j := \mathbf{z}_j > 0]. When entering <> all relations reported via the event indicators latexmath:[\mathbf{z}] are fixed and during this mode these relations are replaced by latexmath:[^{\bullet}\mathbf{r}]. Only during <> or <> the domains latexmath:[\mathbf{z}_j > 0] can change. -_[For more details, see <> below.]_ + +NOTE: For more details, see <> below. |[[buffers,buffers]] latexmath:[\mathbf{b}] -|Hidden data of the FMU. -_[For example, delay buffers in Model Exchange FMUs that are used in <>]_. +a|Hidden data of the FMU. + +NOTE: For example, delay buffers in Model Exchange FMUs that are used in <>. |==== diff --git a/docs/2_2_common_mechanisms.adoc b/docs/2_2_common_mechanisms.adoc index b4546722f..7693d9263 100644 --- a/docs/2_2_common_mechanisms.adoc +++ b/docs/2_2_common_mechanisms.adoc @@ -4,10 +4,14 @@ The following general requirements for implementations of FMUs and importers must be followed: -* 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; +* FMI functions of one instance are not required to be thread-safe. ++ +[NOTE] +==== +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 FMU itself does not implement any services to support this.]_ +The FMU itself does not implement any services to support this. +==== * The following FMI callback functions must not call back into the FMU: ** <>, and @@ -21,14 +25,22 @@ The following callback functions lead to well-defined states and may call FMI fu * FMI functions must not change global settings which affect other processes/threads. An FMI function may change settings of the thread in which it is called (such as floating point control registers), provided these changes are restored before leaving the function or before a callback function is called. -To prepare the FMU code to run reliably on <> FMI functions must not change global settings. + -_[This property ensures that functions of different FMU instances can be called safely in any order._ -_Additionally, they can be called in parallel provided the functions are called in different processes._ -_If an FMI function changes, for example, the floating point control word of the CPU, it must restore the previous value before return of the function.]_ - -* FMI function arguments must not to be `NULL`, unless explicitly allowed by the standard document where `NULL` will be assigned a specific semantic. + -_[For an example of `NULL` being explicitly allowed see <>._ -_Defensive implementations should still guard against `NULL` pointers.]_ +To prepare the FMU code to run reliably on <> FMI functions must not change global settings. ++ +[NOTE] +==== +This property ensures that functions of different FMU instances can be called safely in any order. +Additionally, they can be called in parallel provided the functions are called in different processes. +If an FMI function changes, for example, the floating point control word of the CPU, it must restore the previous value before return of the function. +==== + +* FMI function arguments must not to be `NULL`, unless explicitly allowed by the standard document where `NULL` will be assigned a specific semantic. ++ +[NOTE] +==== +For an example of `NULL` being explicitly allowed see <>. +Defensive implementations should still guard against `NULL` pointers. +==== * The FMI Standard does not provide a runtime platform or portability layer. Access to operating system resources and services, such as memory, network or file system, should be implemented with special care because the availability of such resources and services is not guaranteed on every target platform and/or simulator. @@ -41,51 +53,61 @@ By convention, all function declarations and type definitions in these header fi `fmi3PlatformTypes.h`:: contains the type definitions of the input and output arguments of the functions as well as some C preprocessor macro definitions for constants. -This header file must be used both by the FMU and by the importer. + -_[Example of a definition in this header file:_ +This header file must be used both by the FMU and by the importer. + +[NOTE] +==== +Example of a definition in this header file: + [source, C] ---- include::../headers/fmi3PlatformTypes.h[tags=fmi3Float64] ---- -+ -_]_ +==== `fmi3FunctionTypes.h`:: contains `typedef` definitions of all function prototypes of an FMU as well as enumerations for constants. This header file includes `fmi3PlatformTypes.h`. When dynamically loading an FMU, these definitions can be used to type-cast the function pointers to the respective function definition. -For simplicity, the function type for each function is composed of the function name itself with the suffix `TYPE`. + -_[Example of a definition in this header file:_ +For simplicity, the function type for each function is composed of the function name itself with the suffix `TYPE`. + +[NOTE] +==== +Example of a definition in this header file: + [source, C] ---- include::../headers/fmi3FunctionTypes.h[tags=SetTime] ---- -+ -_]_ +==== `fmi3Functions.h`:: contains the function prototypes of an FMU that may be accessed in simulation environments. + 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 <>. + -+ -_[Example of a definition in this header file:_ +The header file version number for which the model was compiled, may be inquired by the importer with <>. + +[NOTE] +==== +Example of a definition in this header file: + [source, C] ---- include::../headers/fmi3Functions.h[tags=SetTimeTYPE] ---- -+ -_For Microsoft and Cygwin compilers `FMI3_Export` is defined as_ `pass:[__]declspec(dllexport)` _and for Gnu-Compilers as_ `pass:[__]attribute__ ( ( visibility("default") ) )` _in order to export the name for dynamic loading._ -_Otherwise it is an empty definition.]_ + +For Microsoft and Cygwin compilers `FMI3_Export` is defined as_ `pass:[__]declspec(dllexport)` _and for Gnu-Compilers as_ `pass:[__]attribute__ ( ( visibility("default") ) )` _in order to export the name for dynamic loading. +Otherwise it is an empty definition. +==== The goal is that both source code and binary representations of FMUs are supported and that several FMUs might be present at the same time in an executable (for example, FMU A may use an FMU B). In order for this to be possible, the names of the functions in different FMUs must be different, or function pointers must be used. To support the source code representation of FMUs, macros are provided in `fmi3Functions.h` to build the actual function names by using a function prefix that depends on how the FMU is shipped (shared object or static library). -_[These macros can be defined differently in a target specific variant of `fmi3Functions.h` to adjust them to the requirements of the supported compilers and platforms of the importer, e.g. one can remove the use of the `FMI3_FUNCTION_PREFIX` macro in the `fmi3Function.h` file of the importer to compile function names without prefix for building shared objects (DLL/SO).]_ +[NOTE] +==== +These macros can be defined differently in a target specific variant of `fmi3Functions.h` to adjust them to the requirements of the supported compilers and platforms of the importer, e.g. one can remove the use of the `FMI3_FUNCTION_PREFIX` macro in the `fmi3Function.h` file of the importer to compile function names without prefix for building shared objects (DLL/SO). +==== When compiling an FMU C-file the macro `FMI3_FUNCTION_PREFIX` must be defined before the `#include ` or on precompiler level with the same value as the value of the <> attribute defined in ``, ``, and `` together with `pass:[_]` at the end (see <>, <>, <>). @@ -114,18 +136,32 @@ In case of a static link library, the name of the library must be `MyModel.lib` - 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.]_ ++ +[NOTE] +==== +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. The name of the library must be `MyModel.dll` on Windows or `MyModel.so` on Linux; in other words the <> attribute is used as library name. Since <> may be used as prefix of a C-function name it must fulfill the restrictions on C-function names (only letters, digits and/or underscores are allowed). -_[For example, if `modelName = "A.B.C"`, then <> might be "A_B_C".]_ + +[NOTE] +==== +For example, if `modelName = "A.B.C"`, then <> might be "A_B_C". +==== + Since <> is also used as name in a file system, it must also fulfill the restrictions of the targeted operating system. Basically, this means that it should be short. These restrictions apply to all interface types and for binary and source-code FMUs. -_[For example, the Windows API only supports full path-names of a file up to 260 characters (see: https://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx).]_ + +[NOTE] +==== +For example, the Windows API only supports full path-names of a file up to 260 characters (see: https://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx). +==== ==== Platform Dependent Definitions @@ -201,9 +237,10 @@ The output argument values are defined. `fmi3Warning`:: A non-critical problem was detected, but the computation may continue. The output argument values are defined. -Function <> should be called by the FMU with further information before returning this status, respecting the current logging settings. + -_[In certain applications, e.g. in a prototyping environment, warnings may be acceptable._ -_For production environments warnings should be treated like errors unless they can be safely ignored.]_ +Function <> should be called by the FMU with further information before returning this status, respecting the current logging settings. ++ +NOTE: In certain applications, e.g. in a prototyping environment, warnings may be acceptable. +For production environments warnings should be treated like errors unless they can be safely ignored. [[fmi3Discard,`fmi3Discard`]] `fmi3Discard`:: @@ -211,10 +248,15 @@ The call was not successful and the FMU is in the same state as before the call. The output argument values are undefined, but the computation may continue. Function <> should be called by the FMU with further information before returning this status, respecting the current logging settings. Advanced importers may try alternative approaches to continue the simulation by calling the function with different arguments or calling another function - except in FMI for Scheduled Execution where repeating failed function calls is not allowed. -Otherwise the simulation algorithm must treat this return code like <> and must terminate the simulation. + -_[Examples for usage of <> are_ - * _handling of <>, or_ - * _signal numerical problems during model evaluation forcing smaller step sizes.]_ +Otherwise the simulation algorithm must treat this return code like <> and must terminate the simulation. ++ +[NOTE] +==== +Examples for usage of <> are + +* handling of <>, or +* signal numerical problems during model evaluation forcing smaller step sizes. +==== [[fmi3Error,`fmi3Error`]] `fmi3Error`:: @@ -223,13 +265,16 @@ The output argument values are undefined and the simulation must not be continue Function <> should be called by the FMU with further information before returning this status, respecting the current logging settings. If a function returns <>, it is possible to restore a previously retrieved FMU state by calling <> or to reset the instance by calling <>. When detecting illegal arguments or a function call not allowed in the current state according to the respective state machine, the FMU must return <>. -Other instances of this FMU are not affected by the error. + -_[For example, when setting a constant with a call to <>, then the function must return with an error (<>.]_ +Other instances of this FMU are not affected by the error. ++ +NOTE: For example, when setting a constant with a call to <>, then the function must return with an error (<>). [[fmi3Fatal,`fmi3Fatal`]] `fmi3Fatal`:: The state of all instances of the model is irreparably corrupted. -_[For example, due to a runtime exception such as access violation or integer division by zero during the execution of an FMI function.]_ ++ +NOTE: For example, due to a runtime exception such as access violation or integer division by zero during the execution of an FMI function. ++ Function <> should be called by the FMU with further information before returning this status, respecting the current logging settings, if still possible. The importer must not call any other function for any instance of the FMU. @@ -269,12 +314,16 @@ By scheduling the exposed <> of an FMU and ex These points in time are <> defined by time-based or triggered <>. The time itself is communicated to the FMU as <> argument of <>. -_[Examples for Scheduled Execution:_ +[NOTE] +==== +Examples for Scheduled Execution: + +* A simple scheduler calls the model partitions of periods 5 ms and 10 ms of an FMU in a loop. +The latter one is activated only every second loop iteration. +Thus the time of the simulation advances discretely by 5 ms in every step of the loop. -* _A simple scheduler calls the model partitions of periods 5 ms and 10 ms of an FMU in a loop._ -_The latter one is activated only every second loop iteration._ -_Thus the time of the simulation advances discretely by 5 ms in every step of the loop._ -* _A scheduler of a real-time simulator activates the model partitions whenever wall-clock time has progressed for 5 ms or 10 ms.]_ +* A scheduler of a real-time simulator activates the model partitions whenever wall-clock time has progressed for 5 ms or 10 ms. +==== ==== Variables [[fmu-variables]] @@ -298,7 +347,10 @@ The order of dimensions is defined as follows: * For the C-language it is defined from left to right (e.g. `array[dim1][dim2]...[dimN]`). * In <> it is defined by the order of the <> elements. -_[Example: A 2D matrix_ +[NOTE] +==== +Example: A 2D matrix + [latexmath] ++++ A = \left( \begin{array}{cc} a_{11}&a_{12}\\ @@ -306,7 +358,9 @@ A = \left( \begin{array}{cc} a_{11}&a_{12}\\ a_{31}&a_{32}\\ \end{array} \right) ++++ -_is serialized as follows:_ + +is serialized as follows: + [frame="none",grid="none"] |======================================== |_A[0][0]=a11_ | _memory address: A_ | @@ -318,18 +372,19 @@ _is serialized as follows:_ |======================================== Corresponding definition in C: + [source, C] ---- include::examples/snippets.c[tags=structuralParameterExample] ---- Corresponding <> definition in <>: + [source, xml] ---- include::examples/structural_parameter_example.xml[tags=structuralParameterExample] ---- - -_]_ +==== For this serialization of array variables the sparsity pattern of the array is not taken into account. All elements of the array, including structural zeros, are serialized. @@ -342,8 +397,12 @@ In addition to those state-specific restrictions, setting and getting of <> defined in the <> determines the function <> (see also <> and <>) that must be used for accessing the respective variable values. To set or inquire variables of type <>, `fmi3SetInt64` and `fmi3GetInt64` must be used. + -_[Since C allows negative values for enumerations, signed integers are used._ -_With enums being defined as int in the programming language C and compilers are free to choose any bit-width for int, 64 bit getters and setters are needed to be platform and compiler agnostic.]_ + +[NOTE] +==== +Since C allows negative values for enumerations, signed integers are used. +With enums being defined as int in the programming language C and compilers are free to choose any bit-width for int, 64 bit getters and setters are needed to be platform and compiler agnostic. +==== The current values of the variables may be inquired with the following functions: @@ -361,9 +420,13 @@ include::../headers/fmi3FunctionTypes.h[tags=GetClock] * `valueSizes` is a vector with the actual sizes of the values for binary variables. * `nValues` provides the number of values in the `values` vector (and `valueSizes` vector, where applicable) which is only equal to `nValueReferences` if all <>pass:[s] point to scalar variables. -_[The passing of `nValues` is redundant: ++ +[NOTE] +==== +The passing of `nValues` is redundant: The number of values can be reconstructed from the value references passed in and their corresponding variable definitions and (potentially dynamic) array sizes. -It is added to enable memory safety and other sanity checks.]_ +It is added to enable memory safety and other sanity checks. +==== The strings returned by `fmi3GetString`, as well as the binary values returned by `fmi3GetBinary`, must be copied by the importer because the allocated memory for these strings might be deallocated or overwritten by the next call of an FMU function. @@ -392,8 +455,11 @@ Exceptions: All strings passed as arguments to `fmi3SetString`, as well as all binary values passed as arguments to `fmi3SetBinary`, must be copied during these function calls by the FMU, because there is no guarantee of the lifetime of strings or binary values, when these functions return. -_[Note: In Scheduled Execution, Clocks are neither activated nor deactivated by the importer using <>._ -_Instead: The activation of a clock requires the importer to call <>.]_ +[NOTE] +==== +Note: In Scheduled Execution, Clocks are neither activated nor deactivated by the importer using <>. +Instead: The activation of a clock requires the importer to call <>. +==== ===== Handling min/max Range Violations [[min-max-violations]] @@ -424,18 +490,25 @@ This internal state consists especially of the values of the continuous states, Depending on the FMI type, only a subset of this data is directly accessible via the FMI C-API. With the functions of this section, the entire internal FMU state can be stored and reapplied to continue the simulation from this state. -_[Examples for using this feature:_ +[NOTE] +==== +Examples for using this feature: -* _For variable step-size control of co-simulation algorithms: get the FMU state for every accepted communication step; if the follow-up step is not accepted, restart co-simulation from this FMU state._ +* For variable step-size control of co-simulation algorithms: get the FMU state for every accepted communication step; if the follow-up step is not accepted, restart co-simulation from this FMU state. -* _For nonlinear Kalman filters: get the FMU state just before initialization; in every sample period, set new continuous states from the Kalman filter algorithm based on measured values; integrate to the next sample instant and inquire the predicted continuous states that are used in the Kalman filter algorithm as basis to set new continuous states._ +* For nonlinear Kalman filters: get the FMU state just before initialization; in every sample period, set new continuous states from the Kalman filter algorithm based on measured values; integrate to the next sample instant and inquire the predicted continuous states that are used in the Kalman filter algorithm as basis to set new continuous states. -* _For nonlinear model predictive control: get the FMU state just before initialization; in every sample period, set new continuous states from an observer, initialize and get the FMU state after initialization._ -_From this state, perform many simulations that are restarted after the initialization with new input variables proposed by the optimizer.]_ +* For nonlinear model predictive control: get the FMU state just before initialization; in every sample period, set new continuous states from an observer, initialize and get the FMU state after initialization. +From this state, perform many simulations that are restarted after the initialization with new input variables proposed by the optimizer. +==== Furthermore, the FMU state can be serialized and copied in a byte vector. -_[This can be, for example, used to perform an expensive steady-state initialization, copy the received FMU state in a byte vector and store this vector on file._ -_Whenever needed, the byte vector can be loaded from file and deserialized, and the simulation can be restarted from this FMU state, in other words, from the steady-state initialization.]_ + +[NOTE] +==== +This can be, for example, used to perform an expensive steady-state initialization, copy the received FMU state in a byte vector and store this vector on file. +Whenever needed, the byte vector can be loaded from file and deserialized, and the simulation can be restarted from this FMU state, in other words, from the steady-state initialization. +==== [[fmi3GetFMUState, `fmi3GetFMUState`]] Function `fmi3GetFMUState`:: @@ -450,7 +523,11 @@ include::../headers/fmi3FunctionTypes.h[tags=GetFMUState] If on entry `*FMUState = NULL`, a new allocation is required. If `*FMUState != NULL`, then `*FMUState` points to a previously returned <> that is no longer needed and can be overwritten. In particular, <> had not been called with this <> as an argument. -_[Function <> typically reuses the memory of this <> in this case and returns the same pointer to it, but with the current <>.]_ + +[NOTE] +==== +Function <> typically reuses the memory of this <> in this case and returns the same pointer to it, but with the current <>. +==== [[fmi3SetFMUState, `fmi3SetFMUState`]] Function `fmi3SetFMUState`:: @@ -541,7 +618,11 @@ In Scheduled Execution, when input Clocks tick, the importer will activate the a The importer is the source of the actual Clock activations of input Clocks. For time-based input Clocks, the timing is defined by the FMU, either through the <> or by the importer calling <>. For <> input clocks, the timing is determined by the importer. -_[The timing could be given by a triggered output Clock, or a time-based input Clock of a connected FMU, or any other source.]_ + +[NOTE] +==== +The timing could be given by a triggered output Clock, or a time-based input Clock of a connected FMU, or any other source. +==== Output Clock:: [[outputClock, `output Clock`]] @@ -652,7 +733,6 @@ latexmath:[T_{\mathit{interval, i}}] can be set with <> |latexmath:[t_{\mathit{event}}] |The current event time in <>, or the current time in Scheduled Execution. - |=== Periodic Clock:: @@ -686,7 +766,10 @@ If <> is specified, the importer sets the Clo If the function is not called the value given in <> and <> is used. + -_[Calling <> informs the FMU about the interval determined by the importer to enable the FMU to adapt internal computations to this `fixed` interval.]_ +[NOTE] +==== +Calling <> informs the FMU about the interval determined by the importer to enable the FMU to adapt internal computations to this `fixed` interval. +==== + If <> is not specified, then the importer must use <> and <> to retrieve the Clock interval and shift in <> because they depend on <> <>. @@ -700,7 +783,10 @@ It can later change this interval in <> or <>. If the function is not called, the value given in <> and <> is used by the importer. + -_[Calling <> informs the FMU about the interval determined by the importer to enable the FMU to adapt internal computations to this `tunable` interval.]_ +[NOTE] +==== +Calling <> informs the FMU about the interval determined by the importer to enable the FMU to adapt internal computations to this `tunable` interval. +==== + If <> is not specified, then the importer must use <> to retrieve the Clock interval in <>, and later in <> or <>, if any of the <> <> the Clock's interval depends on was changed. @@ -776,9 +862,12 @@ Only local variables can be clocked variables of local Clocks. Like all local variables, local Clocks must not be used as inputs to other FMUs and must not be listed in the <>. This clock type is not allowed in Scheduled Execution. -_[<> enable an FMU to provide a trigger to the outside world, e.g. to a <> of another FMU._ + -_If an FMU wants to actively trigger a model partition (Clock) of itself, it should use a <>._ -_An example is provided in <>.]_ +[NOTE] +==== +<> enable an FMU to provide a trigger to the outside world, e.g. to a <> of another FMU. + +If an FMU wants to actively trigger a model partition (Clock) of itself, it should use a <>. +An example is provided in <>. +==== ===== Model Partitions and Clocked Variables [[clocked-variable]] @@ -802,11 +891,19 @@ When latexmath:[k] is active (i.e., ticking) invoking the FMI functions `fmi3Get If <> is `false`, then latexmath:[\mathbf{f}_{\mathit{disc}}] cannot be called explicitly using <>, but will be implicitly executed during latexmath:[\mathbf{f}_{\mathit{event}}]. When <> is called, the state vector latexmath:[\mathbf{x}_k] is updated according to state transition function latexmath:[\mathbf{f}_{\mathit{disc}}]. -_[Separating_ latexmath:[\mathbf{f}_{\mathit{disc}}] _from_ latexmath:[\mathbf{f}_{\mathit{event}}] _allows manipulation of the current (discrete) state and compute the corresponding outputs, for instance for model-based control applications.]_ +[NOTE] +==== +Separating latexmath:[\mathbf{f}_{\mathit{disc}}] from latexmath:[\mathbf{f}_{\mathit{event}}] allows manipulation of the current (discrete) state and compute the corresponding outputs, for instance for model-based control applications. +==== The discrete-time variables latexmath:[\mathbf{x}_k] and latexmath:[\mathbf{y}_k] are called clocked variables. Clocked variables latexmath:[\mathbf{v}_k] can acquire new values and can be queried only when their Clock latexmath:[k] is active, except during <>. -_[This is common in clock semantics, see for example <>.]_ + +[NOTE] +==== +This is common in clock semantics, see for example <>. +==== + During <>, if a clocked variable is declared as an <>, then it must be initialized as all other discrete variable of the FMU. Declaring a clocked variable as an <> is optional. Uninitialized clocked variables must be initialized in the corresponding Clock's first tick. @@ -816,15 +913,23 @@ Clocked states declare the <> of their previous variable using t The association between <> and their <> is defined by the attribute <>. <> can depend on multiple Clocks. -_[For example, a global counter could be incremented by multiple model partitions, each controlled by a different Clock.]_ + +[NOTE] +==== +For example, a global counter could be incremented by multiple model partitions, each controlled by a different Clock. +==== Output clocks may depend on input Clocks and other variables. Such <> are declared in the <>. A Clock latexmath:[k] depends on a Clock or variable latexmath:[v] if a tick or the value of latexmath:[v] may trigger a tick of latexmath:[k] during the same super-dense time instant. Declaring a variable as <> using the <> attribute specifies a <> too, but also declares that such a clocked variable can only be <> when one of the referenced Clocks is active. -This also holds for <> of type <>. + -_[This means that variables referenced by <> and <> are not strict subsets of one another because <> may list output Clocks that are not part of the_ latexmath:[{\mathbf{v}_{\mathit{known}}}] _.]_ +This also holds for <> of type <>. + +[NOTE] +==== +This means that variables referenced by <> and <> are not strict subsets of one another because <> may list output Clocks that are not part of the latexmath:[{\mathbf{v}_{\mathit{known}}}]. +==== ===== Clocks specific API @@ -834,9 +939,12 @@ For restrictions on when to call which of the following functions for <> must not be called in Scheduled Execution, instead <> must be called. -_[The Clocks API function argument names <>, <>, <> and <> are chosen to match the naming used in link:https://specification.modelica.org/maint/3.6/synchronous-language-elements.html#clock-constructors[Modelica Clock Constructors]._ -_This commonality of naming does not imply any normative reference to the semantics of Modelica._ -_Mathematically speaking, the arguments <> and <> in the fraction variant of these functions serve as numerators and denominators of fractional representations of the corresponding floating-point number arguments of the decimal variant.]_ +[NOTE] +==== +The Clocks API function argument names <>, <>, <> and <> are chosen to match the naming used in link:https://specification.modelica.org/maint/3.6/synchronous-language-elements.html#clock-constructors[Modelica Clock Constructors]. +This commonality of naming does not imply any normative reference to the semantics of Modelica. +Mathematically speaking, the arguments <> and <> in the fraction variant of these functions serve as numerators and denominators of fractional representations of the corresponding floating-point number arguments of the decimal variant. +==== [[fmi3SetInterval,`fmi3SetInterval`]] For <>, the interval must be set by the environment for the current time instant by the function <> or <>. @@ -864,7 +972,14 @@ include::../headers/fmi3FunctionTypes.h[tag=SetIntervalFraction] * `valueReferences` is an array of size `nValueReferences` holding the value references of the Clock variables. [[counters,`counters`]] -* <> _[Note: This variable may increment by values other than 1.]_ and +* <> ++ +[NOTE] +==== +Note: This variable may increment by values other than 1. +==== ++ +and [[resolutions,`resolutions`]] * <> are arrays of size `nValueReferences` holding the Clock <> and <> to be set. @@ -1045,9 +1160,12 @@ In all tables describing the mathematical model of a state (e.g. <>. -_[The functions above have the slight drawback that values must always be copied._ -_For example, a call to_ <> _provides the new continuous states in a vector._ -_This function must copy the state values into an internal data structure such that subsequent computations triggered by get functions will utilize these values.]_ +[NOTE] +==== +The functions above have the slight drawback that values must always be copied. +For example, a call to <> provides the new continuous states in a vector. +This function must copy the state values into an internal data structure such that subsequent computations triggered by get functions will utilize these values. +==== ==== Algebraic Loops [[algebraic-loops]] @@ -1056,39 +1174,41 @@ In order to detect and solve such systems of equations efficiently, information This data may be provided in the <> under element <>. If this data is not provided, the worst case must be assumed: all <> variables depend algebraically on all <> variables. -_[Example: In <> two different types of connected FMUs are shown (the "dotted lines" characterize the dependency information):_ +[NOTE] +==== +Example: In <> two different types of connected FMUs are shown (the "dotted lines" characterize the dependency information): .Calling sequences for FMUs that are connected in a loop. [#figure-connected-fmus] -image::images/ArtificialAlgebraicLoops.svg[width=80%, align="center"] +image::images/ArtificialAlgebraicLoops.svg[width=800] -_Since different variables are computed in every mode and the causality of variable computation can be different in <> compared to other modes, it might be necessary to solve different kinds of loops in the different modes._ + -_Artificial algebraic loops (see left diagram of <>) can be solved in the modes <>, <>, and <> by an appropriate sequence of <> and <> calls:_ +Since different variables are computed in every mode and the causality of variable computation can be different in <> compared to other modes, it might be necessary to solve different kinds of loops in the different modes. + +Artificial algebraic loops (see left diagram of <>) can be solved in the modes <>, <>, and <> by an appropriate sequence of <> and <> calls: [source, C] ---- include::examples/snippets.c[tags=AlgebraicLoop1] ---- -_In the right diagram of <>, FMUs `M3` and `M4` are connected in such a way that a real algebraic loop is formed._ -_This loop might be solved iteratively, for example with a Newton method._ -_In every iteration the iteration variable `s` is provided by the solver, and via the shown sequence of <> and <> calls, the `residual` is computed and used by the solver to determine a new value of `s` as input `u` of `M4`._ -_The iteration is terminated when the `residual` is small enough._ -_This method works for <>, <>, and <>._ +In the right diagram of <>, FMUs `M3` and `M4` are connected in such a way that a real algebraic loop is formed. +This loop might be solved iteratively, for example with a Newton method. +In every iteration the iteration variable `s` is provided by the solver, and via the shown sequence of <> and <> calls, the `residual` is computed and used by the solver to determine a new value of `s` as input `u` of `M4`. +The iteration is terminated when the `residual` is small enough. +This method works for <>, <>, and <>. [source, C] ---- include::examples/snippets.c[tags=AlgebraicLoop2] ---- -_In <>, <> is required to restore the FMU state before the next iteration with <>, <>, and <> is executed._ +In <>, <> is required to restore the FMU state before the next iteration with <>, <>, and <> is executed. -_In <>, the algorithms from above must be embedded in an event iteration:_ +In <>, the algorithms from above must be embedded in an event iteration: [source, C] ---- include::examples/snippets.c[tags=AlgebraicLoop3] ---- -_]_ +==== When solving algebraic loops in <>, limitations to variable manipulations declared with attribute <> must be observed. @@ -1128,13 +1248,25 @@ Each continuous state derivative variable listed as elements <> in <>. -* latexmath:[{\mathbf{v}_{\mathit{rest}}}] is the set of <> variables and discrete-time states of function latexmath:[\mathbf{f}] which cannot be set by the importer in the current state, but in other states _[for example, discrete-time <> in <>]_. +* latexmath:[{\mathbf{v}_{\mathit{rest}}}] is the set of <> variables and discrete-time states of function latexmath:[\mathbf{f}] which cannot be set by the importer in the current state, but in other states ++ +[NOTE] +==== +for example, discrete-time <> in <>. +==== -* <> must not be included among latexmath:[\mathbf{v}_{\mathit{unknown}}]. + -_[This is intentional as their dependencies listed in <> are intended for debugging purposes and not for partial derivatives.]_ +* <> must not be included among latexmath:[\mathbf{v}_{\mathit{unknown}}]. ++ +[NOTE] +==== +This is intentional as their dependencies listed in <> are intended for debugging purposes and not for partial derivatives. +==== -_[The variable relationships are different in different states._ -_For example, during <>, the partial derivate of a continuous-time output_ latexmath:[\mathbf{y}] _with respect to discrete-time <> is undefined, because discrete-time <> cannot be set between events.]_ +[NOTE] +==== +The variable relationships are different in different states. +For example, during <>, the partial derivate of a continuous-time output_ latexmath:[\mathbf{y}] _with respect to discrete-time <> is undefined, because discrete-time <> cannot be set between events. +==== There are two access functions for partial derivatives: @@ -1183,23 +1315,29 @@ Both functions have the same arguments: * `sensitivity` contains the <> components of the sensitivity vector. * `nSensitivity` contains the length of `sensitivity`. -_[Note that array variables will be serialized, so `nSeed` is only equal to `nKnowns` in the case of directional derivatives (resp., equal to `nUnknowns` in the case of adjoint derivatives) if all value references of `knowns` (resp., `unknowns`) point to scalar variables._ -_Likewise `nSensitivity` is only equal to `nUnknowns` (resp., `nKnowns`) if all value references of `unknowns` (resp., `knowns`) point to scalar variables.]_ +[NOTE] +==== +Note that array variables will be serialized, so `nSeed` is only equal to `nKnowns` in the case of directional derivatives (resp., equal to `nUnknowns` in the case of adjoint derivatives) if all value references of `knowns` (resp., `unknowns`) point to scalar variables. +Likewise `nSensitivity` is only equal to `nUnknowns` (resp., `nKnowns`) if all value references of `unknowns` (resp., `knowns`) point to scalar variables. +==== ===== Directional Derivatives [[directionDerivatives]] -_[For some examples on the usage of <>, please look at the https://modelica.github.io/fmi-guides/main/fmi-guide/#directionDerivatives[examples in the implementers' guide].]_ +NOTE: For some examples on the usage of <>, please look at the https://modelica.github.io/fmi-guides/main/fmi-guide/#directionDerivatives[examples in the implementers' guide]. -_[Note, function <> can be utilized for the following purposes:_ +[NOTE] +==== +Note, function <> can be utilized for the following purposes: -- _Numerical integrators of stiff methods need matrix latexmath:[{\frac{\partial \mathbf{f}}{\partial \mathbf{x}}}]._ +- Numerical integrators of stiff methods need matrix latexmath:[{\frac{\partial \mathbf{f}}{\partial \mathbf{x}}}]. -- _If the FMU is connected with other FMUs, the partial derivatives of the state derivatives and outputs with respect to the continuous states and the <> are needed in order to compute the Jacobian for the system of the connected FMUs._ +- If the FMU is connected with other FMUs, the partial derivatives of the state derivatives and outputs with respect to the continuous states and the <> are needed in order to compute the Jacobian for the system of the connected FMUs. -- _If the FMU shall be linearized, the same <> as in the previous item are needed._ +- If the FMU shall be linearized, the same <> as in the previous item are needed. -- _If the FMU is used as the model for an extended Kalman filter, latexmath:[{\frac{\partial \mathbf{f}}{\partial \mathbf{x}}}] and latexmath:[{\frac{\partial \mathbf{g}}{\partial \mathbf{x}}}] are needed._] +- If the FMU is used as the model for an extended Kalman filter, latexmath:[{\frac{\partial \mathbf{f}}{\partial \mathbf{x}}}] and latexmath:[{\frac{\partial \mathbf{g}}{\partial \mathbf{x}}}] are needed. +==== ===== Adjoint Derivatives [[adjointDerivatives]] -_[For some hints on adjoint derivatives, their calculation and usage, and an example, see the corresponding https://modelica.github.io/fmi-guides/main/fmi-guide/#adjointDerivatives[section in the implementers' guide].]_ +NOTE: For some hints on adjoint derivatives, their calculation and usage, and an example, see the corresponding https://modelica.github.io/fmi-guides/main/fmi-guide/#adjointDerivatives[section in the implementers' guide]. diff --git a/docs/2_3_common_states.adoc b/docs/2_3_common_states.adoc index 51c4db508..47b314240 100644 --- a/docs/2_3_common_states.adoc +++ b/docs/2_3_common_states.adoc @@ -11,7 +11,7 @@ Each state description lists the governing equations and actions and the corresp .Common calling sequence for C functions of common states for at least two of the interface types. [#figure-common-state-machine] -image::images/state-machines-common-states.svg[width=80%, align="center"] +image::images/state-machines-common-states.svg[width=900] The state machine is given here as UML 2.0 state machine. If a transition is labeled with one or more function names (for example, <>, <>), the transition is taken if the function call returns successfully (not `NULL` for <> or <> and <> for all other functions). @@ -58,20 +58,33 @@ The arguments of the instantiation functions are detailed as follows: * `instanceName` is a unique identifier for the FMU instance. It is used to name the instance, for example, in error or information messages generated by one of the `fmi3XXX` functions. The argument `instanceName` must be a non empty string (in other words, must have at least one character that is not a white space). -_[If only one FMU is simulated, either the attribute `modelName` of <> or the attribute <> of `` can be used as `instanceName`.]_ ++ +[NOTE] +==== +If only one FMU is simulated, either the attribute `modelName` of <> or the attribute <> of `` can be used as `instanceName`. +==== * <> can be used by the FMU to check that the <> file (see <>) is compatible with the implementation of the FMU. It is an opaque string generated by the FMU exporter that is stored in the xml file as mandatory attribute <> (see <>). It must be passed unchanged to the FMU. This argument must not be a NULL pointer. -* [[resourcePath,`resourcePath`]] `resourcePath` is the absolute file path (with a trailing file separator) of the `resources` directory of the extracted FMU archive. + -_[Example: An FMU is extracted to the directory `C:\temp\MyFMU`, then <> = `C:\temp\MyFMU\resources\`.]_ + +* [[resourcePath,`resourcePath`]] `resourcePath` is the absolute file path (with a trailing file separator) of the `resources` directory of the extracted FMU archive. ++ +[NOTE] +==== +Example: An FMU is extracted to the directory `C:\temp\MyFMU`, then <> = `C:\temp\MyFMU\resources\`. +==== ++ <> must be `NULL`, if no resource path can be provided to the FMU, which may occur if ** the FMU does not contain a `resources` folder, or -** the environment is not able to provide the file path to the resources folder _[e.g., if the environment does not have a file system.]._ - +** the environment is not able to provide the file path to the resources folder ++ +[NOTE] +==== +e.g., if the environment does not have a file system. +==== + If the FMU cannot work without content of the `resources` folder, <> must return NULL. @@ -83,7 +96,6 @@ If `visible = fmi3True`, the FMU is executed in interactive mode, and the FMU mi If `loggingOn = fmi3True`, then all `` are enabled. The function <> gives more detailed control about enabling specific `` (see <>). - + * [[eventModeUsed,`eventModeUsed`]]If `eventModeUsed = fmi3True` the importer can handle events. The flag may only be `fmi3True`, if <>, otherwise the FMU must raise an error. @@ -120,12 +132,20 @@ The allowed values for `category` are defined in the <> fi If the FMU does not define any log categories, `category` must be `NULL`. ** `message` is a string that contains the message to log. It may contain line-breaks (`\n`), but should not have a trailing line break. -+ All string-valued arguments passed by the FMU to the <> may be deallocated by the FMU directly after function <> returns. -_[The simulation environment must therefore create copies of these strings if it needs to access these strings later.]_ + + +[NOTE] +==== +The simulation environment must therefore create copies of these strings if it needs to access these strings later. +==== + Variables can be referenced in a message with `pass:[#]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 <> 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.]_ +If the character `pass:[#]` shall be included in the message, it has to be prefixed with `pass:[#]`, so `pass:[#]` is an escape character. + +[NOTE] +==== +Example: The message `\#1365# must be larger than zero (used in IO channel ##4)` might be changed by the <> 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. +==== * Callback function `intermediateUpdate` + See <> for details. @@ -140,10 +160,16 @@ See <> for details. The arguments <>, <>, <>, <>, and <>, are function pointers provided by the simulation environment 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 <>, calls to <> result in undefined behavior of the FMU._ -_If <> and arguments <> and/or <> the behavior of the FMU is undefined.]_ ++ +[NOTE] +==== +For example, if <>, calls to <> result in undefined behavior of the FMU. +If <> and arguments <> and/or <> the behavior of the FMU is undefined. +==== ++ Additionally, a pointer to the environment is provided (`instanceEnvironment`) that needs to be passed to the callback functions <>, <>, <>, in order that those functions can utilize data from the environment, such as mapping a <> to a string, or assigning memory to a certain FMU instance. + Allowed Function Calls:: [[fmi3SetDebugLogging,`fmi3SetDebugLogging`]] @@ -166,9 +192,14 @@ If `nCategories = 0`, <> applies to all log categories and the value ** `categories` is an array of `nCategories` elements. The importer must only use values specified in the <> via element <`>> as elements of argument `categories`. -_[For example: If <> shall be called only for log category `logStatusFatal`, two calls are required:_ -* _first, all log categories are turned off using <> with `nCategories = 0`, and_ -* _second, only `logStatusFatal` is placed in `categories` with <>.]_ +[NOTE] +==== +For example, if <> shall be called only for log category `logStatusFatal`, two calls are required: + +* first, all log categories are turned off using <> with `nCategories = 0`, and + +* second, only `logStatusFatal` is placed in `categories` with <>. +==== [[fmi3Reset,`fmi3Reset`]] Function `fmi3Reset`:: @@ -227,9 +258,13 @@ a| Allowed Function Calls:: Function <>:: - This function can be called for variables with <> latexmath:[\neq] <> and with <> = <> or <>. -_[<> latexmath:[\mathbf{u}], <> latexmath:[\mathbf{p}] and continuous-time <> latexmath:[\mathbf{x}_{c,\mathit{initial=exact}}] are included here.]_ ++ +[NOTE] +==== +<> latexmath:[\mathbf{u}], <> latexmath:[\mathbf{p}] and continuous-time <> latexmath:[\mathbf{x}_{c,\mathit{initial=exact}}] are included here. +==== ++ The intention is to set <> and guess values for these variables. [[fmi3EnterConfigurationMode,`fmi3EnterConfigurationMode`]] @@ -305,8 +340,11 @@ An FMU for Co-Simulation might ignore this argument. * [[stopTime,`stopTime`]]`stopTime` can be used to check whether the model is valid within the given boundaries, or to allocate the necessary memory for storing results. <> is the <> <> value of the <> variable and inherits its unit. + -_[It is defined with <> = <> in the <>._ -_If the <> variable is `time`, <> is the starting time of initialization.]_ +[NOTE] +==== +It is defined with <> = <> in the <>. +If the <> variable is `time`, <> is the starting time of initialization. +==== * [[stopTimeDefined,`stopTimeDefined`]] If `stopTimeDefined = fmi3True`, then <> is the final value of the <> variable and inherits its unit. If the environment tries to compute past <>, the FMU has to return <>. @@ -355,11 +393,19 @@ Allowed Function Calls:: Function <>:: This function can be called for variables with <> latexmath:[\neq] <> and with <> = <>. -_[<> latexmath:[\mathbf{u}], <> latexmath:[\mathbf{p}] and continuous-time <> latexmath:[\mathbf{x}_{c,\mathit{initial=exact}}] are included here.]_ ++ +[NOTE] +==== +<> latexmath:[\mathbf{u}], <> latexmath:[\mathbf{p}] and continuous-time <> latexmath:[\mathbf{x}_{c,\mathit{initial=exact}}] are included here. +==== Functions <>:: -Getting variables might trigger <>. + -_[For variables not computed by_ latexmath:[\mathbf{f}_{\mathit{init}}] _their <> values will be returned.]_ +Getting variables might trigger <>. ++ +[NOTE] +==== +For variables not computed by_ latexmath:[\mathbf{f}_{\mathit{init}}] _their <> values will be returned. +==== Function <>:: See <> for Model Exchange only. @@ -397,7 +443,13 @@ It is required that `nominals[i] > 0.0`. * Argument `nContinuousStates` is the size of the `nominals` vector. + -This function should always be called after calling function <>, if `nominalsOfContinuousStatesChanged = fmi3True`, since then the nominal values of the continuous <> have changed _[for example, because the mapping of the continuous <> to variables has changed because of internal <>]_. +This function should always be called after calling function <>, if `nominalsOfContinuousStatesChanged = fmi3True`, since then the nominal values of the continuous <> have changed + ++ +[NOTE] +==== +for example, because the mapping of the continuous <> to variables has changed because of internal <>. +==== Function <>:: See <>. @@ -560,6 +612,8 @@ Getting variables might trigger <>. [[fmi3SetClockEM,`fmi3SetClock`]] Function <>:: ++ +-- For <>, <> is called to set the activation status of <> to `fmi3ClockActive` or `fmi3ClockInactive`. During the solution of algebraic loops, the activation condition of triggered input clocks may change and therefore <> can be called multiple times per super-dense time instant. When a Clock latexmath:[k] is deactivated, the FMU must @@ -567,17 +621,19 @@ When a Clock latexmath:[k] is deactivated, the FMU must * reset all clocked states of this Clock to the values computed during the last <> when this Clock was active (latexmath:[{}^\bullet\mathbf{v}_{\mathit{k}}]); and, as a result: * deactivate all Clocks that were activated as a result of latexmath:[k]'s activation during the current super-dense time instant. -+ -_[Rationale: a triggered <> latexmath:[c] may depend on some variable latexmath:[v] that is involved in an algebraic loop._ -_As part of the iterations to solve the algebraic loop, latexmath:[v] acquires a value that activates the Clock._ -_If the final (or some intermediate) value of latexmath:[v] no longer activates the Clock, then this Clock must be deactivated by the Importer during the same super-dense time instant.]_ + +NOTE: Rationale: a triggered <> latexmath:[c] may depend on some variable latexmath:[v] that is involved in an algebraic loop. +As part of the iterations to solve the algebraic loop, latexmath:[v] acquires a value that activates the Clock. +If the final (or some intermediate) value of latexmath:[v] no longer activates the Clock, then this Clock must be deactivated by the Importer during the same super-dense time instant. + The importer can set a Clock to `fmi3ClockInactive` only if the Clock has the attribute <>. Any Clock active during <> must be deactivated by the FMU itself. + <> must not be active for more than one call of <> per <>. -This restriction does not apply to <>, nor does it apply to <>, for which latexmath:[T_{\mathit{interval}} = 0] can be returned by <>. + -_[The event iteration for handling discontinuities of the continuous part of the FMU should precede handling of time-based Clocks._ -_No further constraints on activations of <> are defined, e.g. activating at the first instant of super-dense time._ -_If the semantics of some Clocks require any specific treatment, e.g. activation at the same super-dense time instant, only the importer will know and must therefore enforce proper activation of the respective Clocks.]_ +This restriction does not apply to <>, nor does it apply to <>, for which latexmath:[T_{\mathit{interval}} = 0] can be returned by <>. + +NOTE: The event iteration for handling discontinuities of the continuous part of the FMU should precede handling of time-based Clocks. +No further constraints on activations of <> are defined, e.g. activating at the first instant of super-dense time. +If the semantics of some Clocks require any specific treatment, e.g. activation at the same super-dense time instant, only the importer will know and must therefore enforce proper activation of the respective Clocks. +-- Function <>:: is used to inquire the status of <>. @@ -653,13 +709,17 @@ This argument is only valid in Model Exchange. [[nextEventTime,`nextEventTime`]] * The return argument <> contains the absolute time of the next time event latexmath:[T_{\mathit{next}}] if <>. The importer must compute up to <> (or if needed slightly further) and then enter <> using <>. -The FMU must handle this time event during the <> that is entered by the first call to <>, at or after <>. + -_[This might be needed if, for example, the time resolution of the importer does not allow hitting the precise <>._ -_If the time offset proves to be too large, the FMU could issue a log message and return <>._ -_The user can improve time settings of the importer to alleviate the issues.]_ + +The FMU must handle this time event during the <> that is entered by the first call to <>, at or after <>. ++ +[NOTE] +==== +This might be needed if, for example, the time resolution of the importer does not allow hitting the precise <>. +If the time offset proves to be too large, the FMU could issue a log message and return <>. +The user can improve time settings of the importer to alleviate the issues. +==== ++ If another (e.g. <>) event happens before that <>, the previous definition of <> becomes obsolete. -[[dummy1]] Function <>:: <> changes state to <> in Model Exchange. <> must not be called if the FMU contains no <> <> (i.e. with <>= <> and <> = <>). @@ -690,13 +750,14 @@ The <> allows setting <> must not be called if the FMU contains no <>. [#table-math-configurationMode] -[cols="2,1",options="header"] +[cols="2a,1a",options="header"] |==== |<> |Functions Influencing Equations -|Set latexmath:[\mathbf{v}_{\mathit{causality=structuralParameter}}] + -_[<> with_ latexmath:[\mathbf{p}_{\mathit{variability=fixed}}] _or_ latexmath:[\mathbf{p}_{\mathit{variability=tunable}}] _are included here]_ +|Set latexmath:[\mathbf{v}_{\mathit{causality=structuralParameter}}] + +NOTE: <> with latexmath:[\mathbf{p}_{\mathit{variability=fixed}}] or latexmath:[\mathbf{p}_{\mathit{variability=tunable}}] are included here |<> |Resize arrays with dimensions that just changed. @@ -718,20 +779,20 @@ include::../headers/fmi3FunctionTypes.h[tags=ExitConfigurationMode] + Exits the <> and returns to state <>. - ==== State: Reconfiguration Mode [[ReconfigurationMode,*Reconfiguration Mode*]] The <> allows setting <> <> for example to resize array variables during the simulation. This state must not be entered, if the FMU contains no <> <>. [#table-math-reconfigurationMode] -[cols="2,1",options="header"] +[cols="2a,1a",options="header"] |==== |<> |Functions Influencing Equations -|Set latexmath:[\mathbf{v}_{\mathit{causality=structuralParameter}}] + -_[<> with_ latexmath:[\mathbf{p}_{\mathit{variability=tunable}}] _are included here]_ +|Set latexmath:[\mathbf{v}_{\mathit{causality=structuralParameter}}] + +NOTE: <> with latexmath:[\mathbf{p}_{\mathit{variability=tunable}}] are included here |<> |Resize arrays with dimensions that just changed. @@ -763,7 +824,11 @@ Allowed Function Calls:: Functions <>:: Getting variables might trigger <>. -_[If <> is entered because of an `fmi3Error` return value, retrieved values should only be used for debugging purposes.]_ ++ +[NOTE] +==== +If <> is entered because of an `fmi3Error` return value, retrieved values should only be used for debugging purposes. +==== Function <>:: Not allowed in Co-Simulation and Scheduled Execution. diff --git a/docs/2_4_common_schema.adoc b/docs/2_4_common_schema.adoc index 772c08260..422e975a6 100644 --- a/docs/2_4_common_schema.adoc +++ b/docs/2_4_common_schema.adoc @@ -9,8 +9,9 @@ Additional optional information about the graphical representation and the group Build information for source code FMUs is provided together with a <> file in the `sources` directory that adheres to the `fmi3BuildDescription.xsd` schema file. It is not allowed to change the <> file within an FMU. -_[Reason: The <> file has to be consistent with the binary or source code implementations._ -_Specifically, changes to the start values would introduce such inconsistencies.]_ + +NOTE: Reason: The <> file has to be consistent with the binary or source code implementations. +Specifically, changes to the start values would introduce such inconsistencies. In this section the schema files mentioned above, including their helper schema files, are discussed. In the graphical representation of the schemata, optional elements are marked with a dashed box (e.g., see <>). @@ -27,14 +28,20 @@ The types used in the FMI schema files are: |Mapping to FMI |`double` -|IEEE 754 double-precision 64-bit floating point type _[An IEEE 754 double-precision floating point value can have up to 17 significant digits in its decimal representation. -In order to not loose precision, either an appropriate minimal printer algorithm should be used, or alternatively a number of this type should be stored in XML files with at least 17 significant digits.]_ +a|IEEE 754 double-precision 64-bit floating point type + +NOTE: An IEEE 754 double-precision floating point value can have up to 17 significant digits in its decimal representation. +In order to not loose precision, either an appropriate minimal printer algorithm should be used, or alternatively a number of this type should be stored in XML files with at least 17 significant digits. + |`double` |`fmi3Float64` |`single` -|IEEE 754 single-precision 32-bit floating point type _[An IEEE 754 single-precision floating point value can have up to 9 significant digits in its decimal representation. -In order to not loose precision, either an appropriate minimal printer algorithm should be used, or alternatively a number of this type should be stored in XML files with at least 9 significant digits.]_ +a|IEEE 754 single-precision 32-bit floating point type + +NOTE: An IEEE 754 single-precision floating point value can have up to 9 significant digits in its decimal representation. +In order to not loose precision, either an appropriate minimal printer algorithm should be used, or alternatively a number of this type should be stored in XML files with at least 9 significant digits. + |`float` |`fmi3Float32` @@ -114,18 +121,19 @@ It is required that the encoding scheme is always UTF-8: include::examples/co_simulation.xml[lines=1] ---- -The FMI schema files (`fmi3*.xsd`) are also stored in UTF-8. + -_[Note that the definition of an encoding scheme is a prerequisite in order for the XML file to contain letters outside of the 7-bit ANSI ASCII character set, such as German umlauts, or Asian characters._ -_Furthermore, note the FMI calling interface requires that strings are encoded in UTF-8._ -_Since the XML files are also required to be encoded in UTF-8, string variables need not to be transformed when reading from the XML files in to C string variables.]._ +The FMI schema files (`fmi3*.xsd`) are also stored in UTF-8. + +NOTE: Note that the definition of an encoding scheme is a prerequisite in order for the XML file to contain letters outside of the 7-bit ANSI ASCII character set, such as German umlauts, or Asian characters. +Furthermore, note the FMI calling interface requires that strings are encoded in UTF-8. +Since the XML files are also required to be encoded in UTF-8, string variables need not to be transformed when reading from the XML files in to C string variables. [[uniqueNameAttribute]] `name` attributes of list elements (for example <> or <>) must be unique within that list and must not be empty strings. Additional restrictions for these `name` attributes are listed in their respective sections. -_[Note that child information items, such as elements in a sequence are ordered lists according to document order, whereas attribute information items are unordered sets (see https://www.w3.org/TR/XML-infoset/#infoitem.element)._ -_The FMI schema is based on ordered lists in a sequence and therefore parsing must preserve this order._ -_For example, the order of the <> elements define the order to be used in <>, <>, and <>.]_ +NOTE: Note that child information items, such as elements in a sequence are ordered lists according to document order, whereas attribute information items are unordered sets (see https://www.w3.org/TR/XML-infoset/#infoitem.element). +The FMI schema is based on ordered lists in a sequence and therefore parsing must preserve this order. +For example, the order of the <> elements define the order to be used in <>, <>, and <>. [[Annotations,``]] All XML-based file formats defined in this standard allow optional `Annotation` elements to be inserted in certain XML elements. @@ -133,7 +141,7 @@ This is achieved through the `Annotations` element: .Annotations Element. [#figure-schema-Annotations] -image::images/schema/Annotations.png[width=80%] +image::images/schema/Annotations.png[width=800] Each `Annotation` element contains a required `type` attribute, which contains the namespace for that annotation. The content of the `Annotation` element can be arbitrary XML data, and can make use of XML namespaces and XML schemas for combined validation where appropriate. @@ -151,9 +159,9 @@ All annotations may safely be ignored by implementations that just implement the .`fmiModelDescription` element. [[system_overview]] -image::images/schema/fmiModelDescription.png[width=70%] +image::images/schema/fmiModelDescription.png[width=750] -_[If an optional element is present and defines a list (such as ``), the list must have at least one element (such as ``).]_ +NOTE: If an optional element is present and defines a list (such as ``), the list must have at least one element (such as ``). .`fmiModelDescription` element details. [[table-schema-fmiModelDescription]] @@ -172,7 +180,10 @@ _[If an optional element is present and defines a list (such as `>). |`` -|A list of unit and display unit definitions _[for example, used to convert display units into the units used in the model equations]_. +a|A list of unit and display unit definitions + +NOTE: for example, used to convert display units into the units used in the model equations. + These definitions are used in the XML element <>. |`` @@ -205,7 +216,7 @@ The XML attributes of `` are: .`fmiModelDescription` attribute details. [[table-schema-fmiModelDescription-attributes]] -[cols="1,3",options="header"] +[cols="1a,3a",options="header"] |==== |Attribute |Description @@ -215,8 +226,8 @@ The XML attributes of `` are: The value for this version is `3.0`. Future minor revisions will be denoted as `3.1`, `3.2` ... -_[During development prototype FMU implementations can indicate compliance with a certain development version based on the tags available at https://github.com/modelica/fmi-standard/tags._ -_For example the value for the FMI 3.0 Alpha 2 release is `3.0-alpha.2`.]_ +NOTE: During development prototype FMU implementations can indicate compliance with a certain development version based on the tags available at https://github.com/modelica/fmi-standard/tags. +For example the value for the FMI 3.0 Alpha 2 release is `3.0-alpha.2`. |`modelName` |The name of the model as used in the modeling environment that generated the XML file, such as `Modelica.Mechanics.Rotational.Examples.CoupledClutches`. @@ -232,22 +243,29 @@ For this purpose the importer must pass the <> from the <`._ -_If more space is required, the folder <> should be used.]_ +|Optional information on the intellectual property licensing for this FMU. + +NOTE: For example `BSD license `. +If more space is required, the folder <> should be used. |`generationTool` |Optional name of the tool that generated the XML file. |`generationDateAndTime` |Optional date and time when the XML file was generated. -The format is a subset of `dateTime` and should be: `YYYY-MM-DDThh:mm:ssZ` (with one `T` between date and time; `Z` characterizes the Zulu time zone, in other words, Greenwich meantime) _[for example `2009-12-08T14:33:22Z`, according to ISO 8601]_. +The format is a subset of `dateTime` and should be: `YYYY-MM-DDThh:mm:ssZ` (with one `T` between date and time; `Z` characterizes the Zulu time zone, in other words, Greenwich meantime) + +NOTE: for example `2009-12-08T14:33:22Z`, according to ISO 8601. |[[variableNamingConvention,`variableNamingConvention`]]`variableNamingConvention` |Defines whether the variable names in <> and in `` follow the `flat` or `structured` convention as defined in <>. @@ -267,7 +285,7 @@ For all Boolean attributes the default is `false`. .Common attributes and capability flags. [[table-common-capability-flags]] -[cols="1,1",options="header"] +[cols="2a,3a",options="header"] |==== |Attribute |Description @@ -282,8 +300,9 @@ See also <>. |[[needsExecutionTool,`needsExecutionTool`]]If `true`, a tool is needed to execute the FMU. The FMU implements the communication to this tool. These tool dependencies must be <>. -_[Typically, this information is only utilized for information purposes._ -_For example, when loading an FMU with `needsExecutionTool = true`, the importer should inform the user that a tool has to be available on the computer where the FMU is instantiated.]_ + +NOTE: Typically, this information is only utilized for information purposes. +For example, when loading an FMU with `needsExecutionTool = true`, the importer should inform the user that a tool has to be available on the computer where the FMU is instantiated. |`canBeInstantiatedOnlyOncePerProcess` |If `true`, the FMU must be instantiated only once per process. @@ -321,20 +340,22 @@ Element `` is defined as: .`UnitDefinitions` element. [[figure-schema-UnitDefinitions]] -image::images/schema/UnitDefinitions.png[width=90%] +image::images/schema/UnitDefinitions.png[width=1000] Units are referenced via its <> attribute `name` by the attribute `unit` and `displayUnit` of <> and <>. The `name` of a `Unit` must be <> with respect to all other `` elements. If a variable is associated with a `Unit`, the value passed to <> (resp. retrieved with <>) has this unit. -_[The purpose of the name is to uniquely identify a unit and, for example, use it to display the unit in menus or in plots._ -_Since there is no standard to represent units in strings, and there are different ways how this is performed in different tools, no specific format for the string representation of the unit is required.]_ + +NOTE: The purpose of the name is to uniquely identify a unit and, for example, use it to display the unit in menus or in plots. +Since there is no standard to represent units in strings, and there are different ways how this is performed in different tools, no specific format for the string representation of the unit is required. The `Unit` definition consists of the exponents of the seven SI base units `kg`, `m`, `s`, `A`, `K`, `mol`, `cd`, the exponent of the SI derived unit `rad`, and optionally a `factor` and an `offset`. -_[The additional `rad` base unit helps to handle the often occurring quantities in technical systems that depend on an angle.]_ + +NOTE: The additional `rad` base unit helps to handle the often occurring quantities in technical systems that depend on an angle. .`BaseUnit` element. [[figure-schema-BaseUnit]] -image::images/schema/BaseUnit.png[width=50%, align="center"] +image::images/schema/BaseUnit.png[width=500] A value latexmath:[v_{\mathit{unit}}] in `Unit` is converted to the base unit latexmath:[v_{\mathit{base}}] by the equation @@ -349,17 +370,12 @@ v_{\mathit{base}} = \texttt{factor} \cdot v_{\mathit{unit}} + \left\{ ++++ where `factor` and `offset` are attributes of the ``, and `relativeQuantity` an attribute of the `TypeDefinition` of a variable. -_[For example, if_ latexmath:[{p_{\mathit{bar}}}] _is a pressure value in unit `bar`, and_ latexmath:[{p_{\mathit{Pa}}}] _is the pressure value in ``, then_ - -[latexmath] -++++ -{p_{\mathit{Pa}} = 10^5 \cdot p_{\mathit{bar}}} -++++ - -_and therefore, `factor = 1.0e5` and `offset = 0.0`._ +[NOTE] +==== +For example, if latexmath:[{p_{\mathit{bar}}}] is a pressure value in unit `bar`, and latexmath:[{p_{\mathit{Pa}}}] is the pressure value in ``, then latexmath:[p_{\mathit{Pa}} = 10^5 \cdot p_{\mathit{bar}}] and therefore, `factor = 1.0e5` and `offset = 0.0`. -_In the following table several unit examples are given._ -_Note that if in column `exponents` the definition_ latexmath:[\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] _is present, then the attributes of `` are `kg=1, m=2, s=-2`._ +In the following table several unit examples are given. +Note that if in column `exponents` the definition latexmath:[\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] is present, then the attributes of `` are `kg=1, m=2, s=-2`. .Unit examples. [[table-unit-examples]] @@ -373,122 +389,128 @@ h|exponents h|factor h|offset -|_Torque_ +|Torque |`N.m` |latexmath:[\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] |latexmath:[1.0] |latexmath:[0.0] -|_Energy_ +|Energy |`J` |latexmath:[\mathrm{kg} \cdot \mathrm{m}^2 \cdot \mathrm{s}^{-2}] |latexmath:[1.0] |latexmath:[0.0] -|_Pressure_ +|Pressure |`bar` |latexmath:[\mathrm{kg} \cdot \mathrm{m}^{-1} \cdot \mathrm{s}^{-2}] |latexmath:[1.0 \cdot 10^5] |latexmath:[0.0] -|_Angle_ +|Angle |`deg` |latexmath:[\mathrm{rad}] -|latexmath:[0.01745329251994330 \ \left(= \frac{\pi}{180}\right)] +|latexmath:[0.01745329251994330 \\ \left(= \frac{\pi}{180}\right)] |latexmath:[0.0] -|_Angular velocity_ +|Angular velocity |`rad/s` |latexmath:[\mathrm{rad} \cdot \mathrm{s}^{-1}] |latexmath:[1.0] |latexmath:[0.0] -|_Angular velocity_ +|Angular velocity |`rpm` |latexmath:[\mathrm{rad} \cdot \mathrm{s}^{-1}] -|latexmath:[0.1047197551196598 \ \left(= 2 \cdot \frac{\pi}{60}\right)] +|latexmath:[0.1047197551196598 \\ \left(= 2 \cdot \frac{\pi}{60}\right)] |latexmath:[0.0] -|_Frequency_ +|Frequency |`Hz` |latexmath:[\mathrm{rad} \cdot \mathrm{s}^{-1}] -|latexmath:[6.283185307179586 \ \left(= 2 \cdot \pi\right)] +|latexmath:[6.283185307179586 \\ \left(= 2 \cdot \pi\right)] |latexmath:[0.0] -|_Temperature_ +|Temperature |`°F` |latexmath:[\mathrm{K}] -|latexmath:[0.5555555555555556 \ \left(= \frac{5}{9}\right)] -|latexmath:[255.3722222222222 \ \left(= 273.15 - 32 \cdot \frac{5}{9}\right)] +|latexmath:[0.5555555555555556 \\ \left(= \frac{5}{9}\right)] +|latexmath:[255.3722222222222 \\ \left(= 273.15 - 32 \cdot \frac{5}{9}\right)] -|_Percent by length_ +|Percent by length |`%/m` |latexmath:[\mathrm{m}^{-1}] |latexmath:[0.01] |latexmath:[0.0] -|_Parts per million_ +|Parts per million |`ppm` |latexmath:[1] |latexmath:[1.0 \cdot 10^{-6}] |latexmath:[0.0] -|_Length_ +|Length |`km` |latexmath:[\mathrm{m}] |latexmath:[1000] |latexmath:[0.0] -|_Length_ +|Length |`yd` |latexmath:[\mathrm{m}] |latexmath:[0.9144] |latexmath:[0.0] |==== -_Note that `Hz` is typically used as `Unit.name` for a frequency quantity, but it can also be used as `` for an angular velocity quantity (since `revolution/s`)._ +Note that `Hz` is typically used as `Unit.name` for a frequency quantity, but it can also be used as `` for an angular velocity quantity (since `revolution/s`). -_The `` definitions can be utilized for different purposes (the following application examples are optional and a tool may also completely ignore the `Unit` definitions):_ +The `` definitions can be utilized for different purposes (the following application examples are optional and a tool may also completely ignore the `Unit` definitions): Unit check when connecting variables of different FMUs:: + -_When only one of <> `v2` and <> `v1`, connected with equation `v2 = v1`, defines a `` element, <> must be used to get the value of `v1` to then set it with <> for `v2`._ -+ -_When two variables v1 and v2 are connected and for both of them `` elements are defined, then they must have identical exponents of their ``._ -_If `factor` and `offset` are also identical, again the connection equation `v2 = v1` holds._ -_If `factor` and `offset` are not identical, the tool may either trigger an error or, if supported, perform a conversion; in other words, use the connection equation (in this case the `relativeQuantity` of the ``, see below, has to be taken into account in order to determine whether `offset` shall or shall not be utilized):_ +-- +When only one of <> `v2` and <> `v1`, connected with equation `v2 = v1`, defines a `` element, <> must be used to get the value of `v1` to then set it with <> for `v2`. + +When two variables `v1` and `v2` are connected and for both of them `` elements are defined, then they must have identical exponents of their ``. +If `factor` and `offset` are also identical, again the connection equation `v2 = v1` holds. +If `factor` and `offset` are not identical, the tool may either trigger an error or, if supported, perform a conversion; in other words, use the connection equation (in this case the `relativeQuantity` of the ``, see below, has to be taken into account in order to determine whether `offset` shall or shall not be utilized): [latexmath] ++++ -\texttt{factor(v1)} \cdot \texttt{v1} + \left\{ +\begin{align*} +&\texttt{factor(v1)} \cdot \texttt{v1} + \left\{ \begin{array}{ll} 0 & \texttt{if relativeQuantity(v1) = true} \\ \texttt{offset(v1)} & \texttt{if relativeQuantity(v1) = false} \end{array} \right. -= -\texttt{factor(v2)} \cdot \texttt{v2} + \left\{ +\\ +\\ +=\ &\texttt{factor(v2)} \cdot \texttt{v2} + \left\{ \begin{array}{ll} 0 & \texttt{if relativeQuantity(v2) = true} \\ \texttt{offset(v2)} & \texttt{if relativeQuantity(v2) = false} \end{array} \right. +\end{align*} ++++ -_where_ `relativeQuantity(v1) = relativeQuantity(v2)` _is required_. -_As a result, wrong connections can be detected (for example, connecting a force with an angle-based variable would trigger an error) and conversions between, say, US and SI units can be either automatically performed or, if not supported, an error is triggered as well._ -+ -_This approach is not satisfactory for variables belonging to different quantities that have, however, the same ``, such as quantities `Energy` and `Torque`, or `AngularVelocity` and `Frequency`._ -_To handle such cases, quantity definitions have to be taken into account (see ``) and quantity names need to be standardized._ -+ -_This approach allows a general treatment of units, without being forced to standardize the grammar and allowed values for units (for example, in FMI 1.0, a unit could be defined as `N.m` in one FMU and as `N*m` in another FMU, and a tool would have to reject a connection, since the units are not identical._ -_In FMI 2.0, the connection would be accepted, provided both elements have the same `` definition)._ +where `relativeQuantity(v1) = relativeQuantity(v2)` is required. + +As a result, wrong connections can be detected (for example, connecting a force with an angle-based variable would trigger an error) and conversions between, say, US and SI units can be either automatically performed or, if not supported, an error is triggered as well. + +This approach is not satisfactory for variables belonging to different quantities that have, however, the same ``, such as quantities `Energy` and `Torque`, or `AngularVelocity` and `Frequency`. +To handle such cases, quantity definitions have to be taken into account (see ``) and quantity names need to be standardized. + +This approach allows a general treatment of units, without being forced to standardize the grammar and allowed values for units (for example, in FMI 1.0, a unit could be defined as `N.m` in one FMU and as `N*m` in another FMU, and a tool would have to reject a connection, since the units are not identical. +In FMI 2.0, the connection would be accepted, provided both elements have the same `` definition). +-- Dimensional analysis of equations:: + -_In order to check the validity of equations in a modeling language, the defined units can be used for dimensional analysis, by using the `` definition of the respective unit._ -_For this purpose, the `` `rad` has to be treated as `1`._ -_Example:_ +In order to check the validity of equations in a modeling language, the defined units can be used for dimensional analysis, by using the `` definition of the respective unit. +For this purpose, the `` `rad` has to be treated as `1`. +Example: + [latexmath] ++++ @@ -500,31 +522,35 @@ J \cdot \alpha = f \rightarrow [\mathrm{kg} \cdot \mathrm{m}^2] \cdot [\mathrm{r Unit propagation:: + -_If unit definitions are missing for variables, they might be deduced from the equations where the variables are used._ -_If no unit computation is needed, `rad` is propagated._ -_If a unit computation is needed and one of the involved units has `rad` as a ``, then unit propagation is not possible._ -_Examples:_ +If unit definitions are missing for variables, they might be deduced from the equations where the variables are used. +If no unit computation is needed, `rad` is propagated. +If a unit computation is needed and one of the involved units has `rad` as a ``, then unit propagation is not possible. +Examples: + -- _latexmath:[a = b + c], and `Unit` of c is provided, but not `Unit` of a and b:_ + -_The Unit definition of `c` (in other words, `Unit.name`, ``, ``) is also used for `a` and `b`._ -_For example, if BaseUnit(c) = `rad/s`, then BaseUnit(a) = BaseUnit(b) = `rad/s`._ +- latexmath:[a = b + c], and `Unit` of c is provided, but not `Unit` of a and b: + +The Unit definition of `c` (in other words, `Unit.name`, ``, ``) is also used for `a` and `b`. +For example, if BaseUnit(c) = `rad/s`, then BaseUnit(a) = BaseUnit(b) = `rad/s`. + -- _latexmath:[a = b \cdot c], and `Unit` of a and of c is provided, but not `Unit` of b:_ + -_If `rad` is either part of the `` of `a` and/or of `c`, then the `` of `b` cannot be deduced (otherwise it can be deduced)._ -_Example: If `BaseUnit(a) = kg.m/s2` and `BaseUnit(c) = m/s2`, then the `BaseUnit(b)` can be deduced to be `kg`._ -_In such a case `Unit.name` of b cannot be deduced from the `Unit.name` of `a` and `c`, and a tool would typically construct the `Unit.name` of `b` from the deduced ``.]_ +- latexmath:[a = b \cdot c], and `Unit` of a and of c is provided, but not `Unit` of b: + +If `rad` is either part of the `` of `a` and/or of `c`, then the `` of `b` cannot be deduced (otherwise it can be deduced). +Example: If `BaseUnit(a) = kg.m/s2` and `BaseUnit(c) = m/s2`, then the `BaseUnit(b)` can be deduced to be `kg`. +In such a case `Unit.name` of b cannot be deduced from the `Unit.name` of `a` and `c`, and a tool would typically construct the `Unit.name` of `b` from the deduced ``. +==== A `` can contain any number of `` elements. .DisplayUnit element. [[figure-schema-DisplayUnit]] -image::images/schema/DisplayUnit.png[width=70%, align="center"] +image::images/schema/DisplayUnit.png[width=700] A `` is defined by `name`, `factor`, `offset`, and `inverse`. The attribute `name` must be unique with respect to all other names of the `` definitions of the same `Unit`. -_[Different `Unit` elements may have the same `` names]._ + -`inverse = true` is only allowed if `offset = 0`. + -_[Reason: no use case is known for the combination of inverse and offset, which would also be more complicated.]_ + +NOTE: Different `Unit` elements may have the same `` names. + +`inverse = true` is only allowed if `offset = 0`. + +NOTE: Reason: no use case is known for the combination of inverse and offset, which would also be more complicated. A value latexmath:[v_{\mathit{unit}}] in `Unit` is converted to a value latexmath:[v_{\mathit{display}}] in `DisplayUnit` by the equation: @@ -537,26 +563,28 @@ v_{\mathit{display}} = \end{array}\right. ++++ -_[`offset` is needed for temperature units like `F` (Fahrenheit), `inverse` for inverse display units like `mpg` (miles per gallon) or `S` (Siemens)._ +[NOTE] +==== +`offset` is needed for temperature units like `F` (Fahrenheit), `inverse` for inverse display units like `mpg` (miles per gallon) or `S` (Siemens). -_For example, if latexmath:[{T_K}] is the temperature value of `Unit.name` (in `K`) and latexmath:[{T_F}] is the temperature value of `` (in `°F`), then_ +For example, if latexmath:[{T_K}] is the temperature value of `Unit.name` (in `K`) and latexmath:[{T_F}] is the temperature value of `` (in `°F`), then [latexmath] ++++ T_F = \frac{9}{5} \cdot (T_K - 273.15) + 32 ++++ -_and therefore, latexmath:[\texttt{factor} = 1.8 \ \left(= \frac{9}{5}\right)] and latexmath:[\texttt{offset} = -459.67 \ \left(= 32 - 273.15 \cdot \frac{9}{5}\right)]._ +and therefore, latexmath:[\texttt{factor} = 1.8 \ \left(= \frac{9}{5}\right)] and latexmath:[\texttt{offset} = -459.67 \ \left(= 32 - 273.15 \cdot \frac{9}{5}\right)]. -_Both the `DisplayUnit.name` definitions as well as the `Unit.name` definitions are used in the variable elements._ +Both the `DisplayUnit.name` definitions as well as the `Unit.name` definitions are used in the variable elements. -_Example of a definition:_ +Example of a definition: [source, xml] ---- include::examples/unit_definition.xml[tags=UnitDefinitions] ---- -_]_ +==== ==== Variable Types [[definition-of-types]] @@ -564,7 +592,7 @@ Element `` is defined as: .TypeDefinitions element. [[figure-schema-TypeDefinitions]] -image::images/schema/TypeDefinitions.png[width=70%, align="center"] +image::images/schema/TypeDefinitions.png[width=700] This element consists of a set of `` elements according to schema `fmi3TypeDefinition` in file `fmi3Type.xsd`. @@ -573,52 +601,57 @@ Each variable type has its own set of attributes. .Float64Type element. [[figure-schema-Float64Type]] -image::images/schema/Float64Type.png[width=90%, align="center"] +image::images/schema/Float64Type.png[width=1000] .Int32Type element. [[figure-schema-Int32Type]] -image::images/schema/Int32Type.png[width=90%, align="center"] +image::images/schema/Int32Type.png[width=1000] .BooleanType element. [[figure-schema-BooleanType]] -image::images/schema/BooleanType.png[width=90%, align="center"] +image::images/schema/BooleanType.png[width=1000] .BinaryType element. [[figure-schema-BinaryType]] -image::images/schema/BinaryType.png[width=100%, align="center"] +image::images/schema/BinaryType.png[width=1000] .EnumerationType element. [[figure-schema-EnumerationType]] -image::images/schema/EnumerationType.png[width=100%, align="center"] +image::images/schema/EnumerationType.png[width=1000] .ClockType element. [[figure-schema-ClockType]] -image::images/schema/ClockType.png[width=100%, align="center"] +image::images/schema/ClockType.png[width=1000] The `` elements are referred to in variable elements to declare their type. -_[The alternative would be to define a type per variable._ -_However, this would lead to a situation where, e.g., the definition of a `Torque` type would have to be repeated over and over.]_ + +NOTE: The alternative would be to define a type per variable. +However, this would lead to a situation where, e.g., the definition of a `Torque` type would have to be repeated over and over. + The attributes and elements have the following meaning: .Type element and attribute details. [[table-type-details]] -[cols="1,5",options="header"] +[cols="1,5a",options="header"] |==== |Attribute or Element |Description |`name` |The <> name of the variable type referenced using the attribute <>. -This attribute must be different to all `name` attributes of variables _[if the same names would be used, then this would nearly always give problems when importing the FMU in an environment using the Modelica language, where a type name cannot be used as instance name]_. +This attribute must be different to all `name` attributes of variables + +NOTE: if the same names would be used, then this would nearly always give problems when importing the FMU in an environment using the Modelica language, where a type name cannot be used as instance name. |`description` |An optional description string describing the meaning of the variable type. |`quantity` |Physical quantity of the variable. -_[For example, `Angle`, or `Energy`._ -_The quantity names are not standardized.]_ + +NOTE: For example, `Angle`, or `Energy`. +The quantity names are not standardized. |`unit` |Unit of the variable referencing to a `` with the same `name`, which must exist. @@ -639,32 +672,37 @@ Implementations may use this information to provide guidance about valid/useful |`relativeQuantity` |If this attribute is `true`, then the `offset` of `BaseUnit` and `displayUnit` must be ignored. -_[For example, 10 degree Celsius = 10 Kelvin if `relativeQuantity = true` and not 283.15 Kelvin.]_ + +NOTE: For example, 10 degree Celsius = 10 Kelvin if `relativeQuantity = true` and not 283.15 Kelvin. |`min` |[[min,`min`]]Minimum value of variable (variable value latexmath:[\geq] `min`). If not defined, the minimum is the largest negative number that can be represented on the machine for that ``. The `min` defines the region in which the FMU is designed to operate (see <>). -_[If, for example, an `` is defined with `name1 = -4`, `name2 = 1`, `name3 = 5`, `name4 = 11` and `min = -2`, `max = 5`, then only `name2` and `name3` are allowed.]_ + +NOTE: If, for example, an `` is defined with `name1 = -4`, `name2 = 1`, `name3 = 5`, `name4 = 11` and `min = -2`, `max = 5`, then only `name2` and `name3` are allowed. |`max` |[[max,`max`]]Maximum value of variable (variable value latexmath:[\leq] `max`). If not defined, the maximum is the largest positive number that can be represented on the machine for that ``. The `max` defines the region in which the FMU is designed to operate (see <>). -_[If, for example, an `` is defined with `name1 = -4`, `name2 = 1`, `name3 = 5`, `name4 = 11` and `min = -2`, `max = 5`, then only `name2` and `name3` are allowed.]_ + +NOTE: If, for example, an `` is defined with `name1 = -4`, `name2 = 1`, `name3 = 5`, `name4 = 11` and `min = -2`, `max = 5`, then only `name2` and `name3` are allowed. |`nominal` |Nominal value of variable. If not defined and no other information about the nominal value is available, then `nominal = 1` is assumed. For array variables, this nominal value applies to all elements of the array. + -_[The nominal value of a variable can be, for example, used to determine the absolute tolerance for this variable as needed by numerical algorithms:_ + + +NOTE: The nominal value of a variable can be, for example, used to determine the absolute tolerance for this variable as needed by numerical algorithms: + `absoluteTolerance = nominal \cdot tolerance \cdot 0.01` + -_where `tolerance` is, for example, the relative tolerance defined in <>.]_ +_where `tolerance` is, for example, the relative tolerance defined in <>. |`unbounded` |If `true`, indicates that during time integration, the variable gets a value much larger than its nominal value `nominal`. -_[Typical examples are the monotonically increasing rotation angles of crank shafts and the longitudinal position of a vehicle along the track in long distance simulations._ -_This information can, for example, be used to increase numerical stability and accuracy by setting the corresponding bound for the relative error to zero (relative tolerance = 0.0), if the corresponding variable is a continuous <> variable.]_ + +NOTE: Typical examples are the monotonically increasing rotation angles of crank shafts and the longitudinal position of a vehicle along the track in long distance simulations. +This information can, for example, be used to increase numerical stability and accuracy by setting the corresponding bound for the relative error to zero (relative tolerance = 0.0), if the corresponding variable is a continuous <> variable. |`Item` |An `` must have a non-empty sequence of `` elements with attributes `name` and `value`. @@ -746,7 +784,7 @@ Element `` is defined as: .LogCategories element. [[figure-schema-LogCategories]] -image::images/schema/LogCategories.png[width=80%, align="center"] +image::images/schema/LogCategories.png[width=900] `` defines an unordered set of category strings that classify output of the callback function <>. The importer may use the function <> to control for which `` the callback function <> is allowed to be called. @@ -791,14 +829,17 @@ Any other FMU specific `` may be defined. The optional attribute `description` shall contain a description of the respective log category. -_[Typically, this string can be shown by a tool if more details for a log category are presented._ -_This approach to define `` has the following advantages:_ +[NOTE] +==== +Typically, this string can be shown by a tool if more details for a log category are presented. +This approach to define `` has the following advantages: -* _An importer may present the possible log categories in a menu and the user can select the desired one._ + +* An importer may present the possible log categories in a menu and the user can select the desired one. -* _The log output is drastically reduced, because via <> the categories are set that shall be logged and therefore the FMU will print only the messages with the corresponding categories to the <> function._ +* The log output is drastically reduced, because via <> the categories are set that shall be logged and therefore the FMU will print only the messages with the corresponding categories to the <> function. -_Note that since element `` is optional, an FMU does not need to expose its log categories.]_ +Note that since element `` is optional, an FMU does not need to expose its log categories. +==== ==== Default Experiment [[DefaultExperiment]] @@ -806,18 +847,21 @@ Element `` is defined as: .DefaultExperiment element. [[figure-schema-DefaultExperiment]] -image::images/schema/DefaultExperiment.png[width=60%, align="center"] +image::images/schema/DefaultExperiment.png[width=550] [[stepSize,`stepSize`]]`` consists of the optional default start time, stop time, relative tolerance, and step size for a simulation run. -A tool may ignore this information. + -_[However, it is convenient for a user that <>, <>, <> and <> have already a meaningful default value for the model at hand.]_ + +A tool may ignore this information. + +NOTE: However, it is convenient for a user that <>, <>, <> and <> have already a meaningful default value for the model at hand. + <>, <> and <> refer to the unit of the <> variable. <> defines the preferred <> for Co-Simulation. -For Model Exchange and Scheduled Execution <> has no defined meaning. -_[This does not prohibit the use of <> in the context of Model Exchange._ -_For example, a fixed step size solver can use it as a default step size._ -_A variable step size solver can use the <> as an initial step size or as result grid for the output._ -_Since the required <> depends on the solver itself a defined meaning of <> for Model Exchange is impossible.]_ +For Model Exchange and Scheduled Execution <> has no defined meaning. + +NOTE: This does not prohibit the use of <> in the context of Model Exchange. +For example, a fixed step size solver can use it as a default step size. +A variable step size solver can use the <> as an initial step size or as result grid for the output. +Since the required <> depends on the solver itself a defined meaning of <> for Model Exchange is impossible. [[ModelVariables,``]] ==== Model Variables @@ -829,7 +873,7 @@ It provides the static information of all exposed variables and is defined as fo .ModelVariables element. [[figure-schema-ModelVariables]] -image::images/schema/ModelVariables.png[width=60%, align="center"] +image::images/schema/ModelVariables.png[width=600] The <> element consists of an arbitrary number of `` elements (see <>). `` elements represent scalars or arrays of an arbitrary (but fixed) number of dimensions for variables of different types, like single-precision floating point, string or binary. @@ -855,22 +899,23 @@ However different <> sizes for the same variable may be specified usi All initial dimension sizes (defined by <> values either directly or indirectly in the <>) must be positive integers (i.e. not zero), so that no dimension is initially vanished. -_[This allows importers to ignore <> because their <> values reflect the internal default settings of <>._ -_If we allowed 0 dimension sizes for initial values, tools that do not even care about changing dimension sizes would need to be able to handle vanishing arrays.]_ +NOTE: This allows importers to ignore <> because their <> values reflect the internal default settings of <>. +If we allowed 0 dimension sizes for initial values, tools that do not even care about changing dimension sizes would need to be able to handle vanishing arrays. -_[Example:_ -_The variable `V` is a floating point vector parameter._ -_The length of the vector depends on the <> `len`, connected via the `valueReference = "100"`._ -_The default length of the vector is 7._ -_This length can be changed in <> because the <> of the <> `len` is <>._ -_The values of `V` can be changed whenever <> parameters can be changed._ +[NOTE] +==== +Example: + +The variable `V` is a floating point vector parameter. +The length of the vector depends on the <> `len`, connected via the `valueReference = "100"`. +The default length of the vector is 7. +This length can be changed in <> because the <> of the <> `len` is <>. +The values of `V` can be changed whenever <> parameters can be changed. [source, xml] ---- include::examples/structural_parameter_example.xml[tags=structuralParameter] ---- - -_]_ +==== Changes to dimension sizes are constrained by the `min`/`max` attributes of the referenced <>, which can be any non-negative integer, including zero. Specifying a minimum size of zero on a <> allows any related dimension sizes to be changed to zero in <> or <>, thus causing the respective array size to go to zero, which leaves the respective array variable without any active elements. @@ -889,13 +934,15 @@ A variable can have any number of `` elements that define a variable alia Each variable alias has a required attribute `name` whose value must be unique among all variables and variable aliases, and an optional attribute `description`. Variable aliases of floating point variables may additionally have a <> that follows the same rules as for variables. -_[ Example:_ +[NOTE] +==== +Example: [source, xml] ---- include::examples/alias_example.xml[tags=VariableAliases] ---- -_]_ +==== ===== Variable Attributes @@ -903,7 +950,7 @@ The common attributes of variables are shown in <> <> change. [[input,`input`]] -`= input`: The variable value may be provided by the importer. + -_[For example, the importer could forward the output of another FMU into this input.]_ +`= input`: The variable value may be provided by the importer. + +NOTE: For example, the importer could forward the output of another FMU into this input. [[output,`output`]] -`= output`: The variable value may be used by the importer. + -_[For example, this value can be forwarded to an input of another FMU.]_ + +`= output`: The variable value may be used by the importer. + +NOTE: For example, this value can be forwarded to an input of another FMU. + The algebraic relationships to the <> may be defined via the <> attribute of <`>>. [[local,`local`]] @@ -969,7 +1019,11 @@ Only in Model Exchange, continuous <> can be set with <> variable. Exactly one variable of an FMU must be defined as <>. If the unit for the independent variable is not defined, it is implicitly `s` (seconds). @@ -998,7 +1052,7 @@ Only for triggered Clocks, the <> also indicates the information flow [[variability,`variability`]] Enumeration that defines the time dependency of the variable, in other words, it defines the time instants when a variable may be changed by the importer or may change its value due to FMU internal computations, depending on their <>. -_[For example, <> variables change their values only at event instants (ME) or at communication points (CS and SE) and it is therefore only necessary to inquire them with <> them at these points in time.]_ +NOTE: For example, <> variables change their values only at event instants (ME) or at communication points (CS and SE) and it is therefore only necessary to inquire them with <> them at these points in time. Allowed combinations of <> and <> and their semantics are defined in <>. @@ -1042,10 +1096,10 @@ Only for variables with <> = <>. + The default value is `true`. If `canHandleMultipleSetPerTimeInstant = false`, then only one <> call is allowed for this variable per super-dense time instant in <>. -_[This flag can be set to `false` for variables where discrete-time states are directly updated when assigned (_ latexmath:[\mathbf{x}_{d} := f(\mathbf{x}_{d},\mathbf{u}_{c+d})] _instead of_ latexmath:[\mathbf{x}_{d} := f({}^\bullet\mathbf{x}_{d},\mathbf{u}_{c+d})] _)._ -_If an <> depends on this <> and on discrete-time states, then an algebraic loop could be formed with such an <>._ -_Such loops cannot be solved iteratively because of the limitation on <>._ -_Therefore, such an <> should not appear in an algebraic loop.]_ +NOTE: This flag can be set to `false` for variables where discrete-time states are directly updated when assigned (latexmath:[\mathbf{x}_{d} := f(\mathbf{x}_{d},\mathbf{u}_{c+d})] instead of latexmath:[\mathbf{x}_{d} := f({}^\bullet\mathbf{x}_{d},\mathbf{u}_{c+d})]). +If an <> depends on this <> and on discrete-time states, then an algebraic loop could be formed with such an <>. +Such loops cannot be solved iteratively because of the limitation on <>. +Therefore, such an <> should not appear in an algebraic loop. |`intermediateUpdate` | @@ -1071,9 +1125,9 @@ The following constraints apply: * A variable must not refer to itself in the <> attribute. * The variable referenced by the <> attribute must have the same numeric type, <>, and must not have <>. -_[For example, if `previous = 3` for variable `8`, then variable `3` is the previous value of variable `8`._ -_See also <>._ -_Note: This is reverse compared to the <> attribute.]_ +NOTE: For example, if `previous = 3` for variable `8`, then variable `3` is the previous value of variable `8`. +See also <>. +Note: This is reverse compared to the <> attribute. |`clocks` | @@ -1081,10 +1135,11 @@ _Note: This is reverse compared to the <> attribute.]_ If present, this variable is clocked. The value of the attribute <> is a non-empty list of value references of <> this variable belongs to. Only variables with <> or <> can have this attribute. -_[Some importers might require a variable to be dependent on a single Clock for technical reasons._ -_They could reject FMUs violating this restriction._ -_Note: It is not further restricted, which variables can be clocked to not restrict currently unknown use cases._ -_For example, an <> Clock could be a clocked variable of another (<> or <>) clock to indicate that it can only be activated when that Clock is active.]_ + +NOTE: Some importers might require a variable to be dependent on a single Clock for technical reasons. +They could reject FMUs violating this restriction. +Note: It is not further restricted, which variables can be clocked to not restrict currently unknown use cases. +For example, an <> Clock could be a clocked variable of another (<> or <>) clock to indicate that it can only be activated when that Clock is active. |==== @@ -1152,152 +1207,155 @@ _For example, an <> Clock could be a clocked variable of another (<> / <>, <> / <>, <> / <> and <> / <> do not make sense, since <> and <> are set by the importer, whereas <> variables have an unchangeable value._ +^|(a) +|The combinations <> / <>, <> / <>, <> / <> and <> / <> do not make sense, since <> and <> are set by the importer, whereas <> variables have an unchangeable value. -^|_(b)_ -|_The combinations <> / <>, <> / <>, <> / <>, <> / <>, <> / <> and <> / <> do not make sense, since <> = <>, <> = <> and <> = <> define variables that do not depend on time, whereas <> and <> define variables where the values can change during simulation._ +^|(b) +|The combinations <> / <>, <> / <>, <> / <>, <> / <>, <> / <> and <> / <> do not make sense, since <> = <>, <> = <> and <> = <> define variables that do not depend on time, whereas <> and <> define variables where the values can change during simulation. -^|_(c)_ -|_For an <> variable only <> = <> makes sense._ +^|(c) +|For an <> variable only <> = <> makes sense. -^|_(d)_ -|_A <> or <> <> has exactly the same properties as a <> or <> <>._ -_For simplicity, only <> and <> <> are allowed._ +^|(d) +|A <> or <> <> has exactly the same properties as a <> or <> <>. +For simplicity, only <> and <> <> are allowed. -^|_(e)_ -|_A <> or <> <> has exactly the same properties as a <> or <> <>._ -_For simplicity, only <> and <> <> are allowed._ +^|(e) +|A <> or <> <> has exactly the same properties as a <> or <> <>. +For simplicity, only <> and <> <> are allowed. |==== -_Discussion of the combinations that are allowed_: +Discussion of the combinations that are allowed: .Combinations of variability and causality that are allowed and why. [[table-Combinations-allowed]] [cols="1,3,8", options="header"] |==== | -|_Setting_ -|_Example_ - ->|_(1)_ -|_<> <>_ -|_Non-<> <>_ - ->|_(2)_ -|_<> <>_ -|_<> <> (<>)._ - ->|_(3)_ -|_<> <>_ -|_Non-<> <> (variable that depends directly or indirectly on constants or <> <>)._ - ->|_(4)_ -|_<> <>_ -|_<> <> (variable that depends directly or indirectly on constants or <> and <> <>)._ - ->|_(5)_ -|_<> <>_ -|_<> <> variable from the importer._ - ->|_(6)_ -|_<> <>_ -|_<> <> variable from the importer._ - ->|_(7)_ -|_<> <>_ -|_Variable where the value never changes and that can be used in another model._ - ->|_(8)_ -|_<> <>_ -|_<> variable that is computed in the FMU._ -_Can be used by the importer._ - ->|_(9)_ -|_<> <>_ -|_<> variable that is computed in the FMU and can be used by the importer._ - ->|_(10)_ -|_<> <>_ -|_Variable that never changes its value._ -_Cannot be used in another model._ - ->|_(11)_ -|_<> <>_ -|_Local variable that depends on <> <> only and is computed in the FMU._ -_Cannot be used in another model._ -_After initialization, the value of this <> variable cannot change._ - ->|_(12)_ -|_<> <>_ -|_Local variable that depends on <> <> only and is computed in the FMU._ -_Cannot be used in another model._ -_The value of this <> variable can only change during initialization and at event instants, provided a <> <> was changed._ - ->|_(13)_ -|_<> <>_ -|_<> variable that is computed in the FMU and cannot be used in another model._ - ->|_(14)_ -|_<> <>_ -|_<> variable that is computed in the FMU and cannot be used in another model._ - ->|_(15)_ -|_<> <>_ -|_All variables are a function of the continuous-time variable marked as <>._ -_Usually, this is `time`._ - ->|_(16)_ -|_<> <>_ -|_<> used in <> element._ -_Can be changed in <>._ - ->|_(17)_ -|_<> <>_ -|_<> used in <> element._ -_Can be changed in <> and in <>._ +|Setting +|Example + +>|(1) +|<> <> +|Non-<> <> + +>|(2) +|<> <> +|<> <> (<>). + +>|(3) +|<> <> +|Non-<> <> (variable that depends directly or indirectly on constants or <> <>). + +>|(4) +|<> <> +|<> <> (variable that depends directly or indirectly on constants or <> and <> <>). + +>|(5) +|<> <> +|<> <> variable from the importer. + +>|(6) +|<> <> +|<> <> variable from the importer. + +>|(7) +|<> <> +|Variable where the value never changes and that can be used in another model. + +>|(8) +|<> <> +|<> variable that is computed in the FMU. +Can be used by the importer. + +>|(9) +|<> <> +|<> variable that is computed in the FMU and can be used by the importer. + +>|(10) +|<> <> +|Variable that never changes its value. +Cannot be used in another model. + +>|(11) +|<> <> +|Local variable that depends on <> <> only and is computed in the FMU. +Cannot be used in another model. +After initialization, the value of this <> variable cannot change. + +>|(12) +|<> <> +|Local variable that depends on <> <> only and is computed in the FMU. +Cannot be used in another model. +The value of this <> variable can only change during initialization and at event instants, provided a <> <> was changed. + +>|(13) +|<> <> +|<> variable that is computed in the FMU and cannot be used in another model. + +>|(14) +|<> <> +|<> variable that is computed in the FMU and cannot be used in another model._ + +>|(15) +|<> <> +|All variables are a function of the continuous-time variable marked as <>. +Usually, this is `time`. + +>|(16) +|<> <> +|<> used in <> element. +Can be changed in <>. + +>|(17) +|<> <> +|<> used in <> element. +Can be changed in <> and in <>. |==== [[HowToTreatTunable]] -_How to treat <> variables:_ +How to treat <> variables: -_A <> p is a variable that does not change its value during simulation, in other words, dp/dt = 0._ -_If the <> p is changing, then Dirac impulses are introduced since dp/dt of a discontinuous <> variable `p` is a Dirac impulse._ -_Even if this Dirac impulse would be modeled correctly by the FMU, it would introduce unwanted `vibrations`._ -_Furthermore, in many cases the model equations are derived under the assumption of a <> value (like mass or capacity), and the model equations would be different if `p` would be time varying._ +A <> p is a variable that does not change its value during simulation, in other words, dp/dt = 0. +If the <> p is changing, then Dirac impulses are introduced since dp/dt of a discontinuous <> variable `p` is a Dirac impulse. +Even if this Dirac impulse would be modeled correctly by the FMU, it would introduce unwanted `vibrations`. +Furthermore, in many cases the model equations are derived under the assumption of a <> value (like mass or capacity), and the model equations would be different if `p` would be time varying. -_FMI for Model Exchange:_ + -_Therefore, "tuning a (structural) <>" during simulation does not mean to "change the parameter online" during simulation._ -_Instead, this is a short hand notation for:_ +FMI for Model Exchange: + +Therefore, "tuning a (structural) <>" during simulation does not mean to "change the parameter online" during simulation. +Instead, this is a short hand notation for: -. _Stop the simulation at an event instant (usually, a <>, in other words, after a successful integration step)._ +. Stop the simulation at an event instant (usually, a <>, in other words, after a successful integration step). -. _Change the values of the <> (structural) <>._ -_For <> <>, the <> must be entered before and left afterwards._ +. Change the values of the <> (structural) <>. +For <> <>, the <> must be entered before and left afterwards. -. _Compute all <> (and sizes of variables, <>, <>, event indicators, ...) that depend on the <> (structural) <>._ +. Compute all <> (and sizes of variables, <>, <>, event indicators, ...) that depend on the <> (structural) <>. -. _Newly start the simulation using as initial values previously stored values and the new values of the <>._ +. Newly start the simulation using as initial values previously stored values and the new values of the <>. -_Basically this means that a new simulation run is started from the previous FMU state with changed <> values._ -_With this interpretation, changing <> online is "clean", as long as these changes appear at an event instant._ +Basically this means that a new simulation run is started from the previous FMU state with changed <> values. +With this interpretation, changing <> online is "clean", as long as these changes appear at an event instant. -_FMI for Co-Simulation:_ -_Changing of <> <> is allowed before an <> call (so, whenever an <> can be set with <>) and before <> is called (that is before and during <>)._ -_The FMU internally carries out event handling if necessary._ +FMI for Co-Simulation: +Changing of <> <> is allowed before an <> call (so, whenever an <> can be set with <>) and before <> is called (that is before and during <>). +The FMU internally carries out event handling if necessary. -_FMI for Scheduled Execution:_ -_Changing of <> <> is allowed before an <> call (so, whenever an <> can be set with <>) and before <> is called (that is before and during <>).]_ +FMI for Scheduled Execution:_ +Changing of <> <> is allowed before an <> call (so, whenever an <> can be set with <>) and before <> is called (that is before and during <>). +==== ===== Type-specific properties @@ -1305,27 +1363,27 @@ _Changing of <> <> is allowed before an <> and <>. Type specific attributes are listed in the following table. @@ -1340,7 +1398,9 @@ Type specific attributes are listed in the following table. |`declaredType` |If present, name of type defined with ``. The attributes defined in the corresponding `` (see <>) are used as defaults. -_[For example, if `min` is present both in variable type element of `` and in the specific variable type element of the variable, then the `min` of the variable is actually used.]_ + +NOTE: For example, if `min` is present both in variable type element of `` and in the specific variable type element of the variable, then the `min` of the variable is actually used. + For `` the attribute `declaredType` is required because the `` items are defined in ``. For all other types, this attribute is optional. @@ -1368,7 +1428,8 @@ The importer may set a different initial value using <> starts with the <> value as guess value. -_[The importer may call <> in <> to help the FMU find a solution.]_ + +NOTE: The importer may call <> in <> to help the FMU find a solution. [[calculated,`calculated`]] `= calculated`: The variable is calculated by the FMU from other variables during initialization. @@ -1382,9 +1443,10 @@ For `calculated` variables a <> attribute must not be provided. [[start,`start`]] Initial or guess value of the variable. During instantiation, the FMU initializes its variables with their <> values. -_[Therefore, calling_ <> _to set <> values is only necessary, if a different value as stored in the XML file is desired._ -_It is not allowed to change the start values in the <> file of an FMU, as this would break the consistency with the hard-coded start values within the FMU._ -_This could lead to unpredictable behavior of the FMU in different importers, as it is not mandatory to call <> to set <> values during initialization.]_ + +NOTE: Therefore, calling_ <> _to set <> values is only necessary, if a different value as stored in the XML file is desired. +It is not allowed to change the start values in the <> file of an FMU, as this would break the consistency with the hard-coded start values within the FMU. +This could lead to unpredictable behavior of the FMU in different importers, as it is not mandatory to call <> to set <> values during initialization. The <> attribute is either a single value or a list of values. The serialization of a multi-dimensional array variable is described in <>. @@ -1392,13 +1454,15 @@ If only a single value is given for a multi-dimensional array, all values of the For variables of type `` and ``, the start values are not given as a list in the `start` attribute but as a sequence of `` elements with a `value` attribute. -_[ Example:_ -_Start values of string array variable_ +[NOTE] +==== +Example: Start values of string array variable + [source, xml] ---- include::examples/string_vector_example.xml[tags=string_start_values] ---- -_]_ +==== The interpretation of <> is defined by variable attribute <>. + If <> = <> or <>, a <> attribute must be provided. + @@ -1416,7 +1480,9 @@ Variables with <> = <> or <>, as well as variables | [[derivative,`derivative`]] If present, then the variable with this attribute is the derivative of the variable with value reference given in `derivative`. + -_[For example, if `derivative = 3` for variable 8, then variable 8 is the derivative of variable 3 with respect to the <> variable (usually time).]_ + + +NOTE: For example, if `derivative = 3` for variable 8, then variable 8 is the derivative of variable 3 with respect to the <> variable (usually time). + This information may be used to signal that an <> or an <> is the derivative of another <> or <>, respectively. Furthermore, this attribute defines the continuous <> of the FMU. The derivatives of continuous <> of an FMU are listed as elements <> in <>. @@ -1568,8 +1634,10 @@ arrayIndices = "[" unsignedInteger {"," unsignedInteger} "]" unsignedInteger = digit { digit } ---- -_[This definition is identical to the syntax of an identifier in the <>.]_ +NOTE: This definition is identical to the syntax of an identifier in the <>. +[NOTE] +==== Example: ---- @@ -1590,6 +1658,7 @@ vehicle.transmission.outputSpeed vehicle.engine.inputSpeed vehicle.engine.temperature ---- +==== It might be that not all elements of an array are present. @@ -1605,13 +1674,14 @@ A Model Exchange FMU must also expose all derivatives of continuous states in << The optional part of the model structure defines in which way <>, <>, and initial unknowns depend on <> and/or <>, and continuous-time <>. The listed <> declare the dependencies between whole (multi-dimensional-)variables and not individual elements of the variables. -_[Dependencies of individual array elements can be retrieved during runtime using <>.]_ + +NOTE: Dependencies of individual array elements can be retrieved during runtime using <>. <> shows the definition of <>. .ModelStructure element. [#figure-schema-ModelStructure] -image::images/schema/ModelStructure.png[width=90%] +image::images/schema/ModelStructure.png[width=1000] Note that attribute <> for element <> has less enumeration values as <> in the other lists, as detailed in <>. @@ -1619,7 +1689,7 @@ Note that attribute <> for element <> has less .ModelStructure elements. [#table-model-structure-elements] -[cols="1,5",options="header"] +[cols="1,5a",options="header"] |==== |Element |Description @@ -1636,12 +1706,15 @@ latexmath:[{(\mathbf{y}_c, \mathbf{y}_d) := \mathbf{f}_{\mathit{output}}(\mathbf |[[ContinuousStateDerivative,``]] Ordered list of value references of all derivatives of continuous <>. The order defined by this list defines the order of the elements for <>, <>, and <>. -_[Note that only <> floating point variables are listed here._ -_If a <> or a <> of a <> shall not be exposed from the FMU, or if states are not statically associated with a variable (due to <>), then dummy variables have to be introduced, for example, `x[4]`, or `xDynamicStateSet2[5]`.]_ + +NOTE: Note that only <> floating point variables are listed here. +If a <> or a <> of a <> shall not be exposed from the FMU, or if states are not statically associated with a variable (due to <>), then dummy variables have to be introduced, for example, `x[4]`, or `xDynamicStateSet2[5]`. The corresponding continuous-time <> are defined by attribute <> of the corresponding variable state-derivative element. -_[Note that higher order derivatives must be mapped to first order derivatives but the mapping definition can be preserved due to attribute <>._ -_Example: if_ latexmath:[{\frac{\text{ds}}{\text{dt}} = v,\ \frac{\text{dv}}{\text{dt}} =f(..)}] _,then_ latexmath:[{\left\{ v,\ \frac{\text{dv}}{\text{dt}} \right\}}] _is the vector of state derivatives and attribute <> of_ latexmath:[{v}] _references_ latexmath:[{s}] _, and attribute <> of_ latexmath:[{\frac{\text{dv}}{\text{dt}}}] _references_ latexmath:[{v}] _.]_ + + +NOTE: Note that higher order derivatives must be mapped to first order derivatives but the mapping definition can be preserved due to attribute <>. +Example: if latexmath:[{\frac{\text{ds}}{\text{dt}} = v,\ \frac{\text{dv}}{\text{dt}} =f(..)}],then latexmath:[{\left\{ v,\ \frac{\text{dv}}{\text{dt}} \right\}}] is the vector of state derivatives and attribute <> of latexmath:[{v}] references latexmath:[{s}], and attribute <> of latexmath:[{\frac{\text{dv}}{\text{dt}}}] references latexmath:[{v}]. + For Co-Simulation, elements <> are ignored if capability flag <> has a value of `false`, in other words, it cannot be computed. The functional dependency is defined as: + latexmath:[{\dot{\mathbf{x}}_c := \mathbf{f}_{\mathit{der}}(\mathbf{x}_c, \mathbf{u}_c, \mathbf{u}_d, t, \mathbf{p})}] @@ -1675,14 +1748,17 @@ Since, <>, continuous-time <> and state derivati <> are available during <>, however their dependencies are intended for debugging purposes only (and not for connection with other FMU's), and therefore they must not be listed as <>. -_[Example: Assume an FMU is defined in the following way:_ +[NOTE] +==== +Example: Assume an FMU is defined in the following way: latexmath:[{(\mathbf{y}_{c+d}, \dot{\mathbf{x}}_c) := \mathbf{f}_{\mathit{init}}(\mathbf{x}_c, \mathbf{u}_{c+d}, t_{\mathit{start}}, \mathbf{p})}] + latexmath:[{(\mathbf{y}_{c+d}, \dot{\mathbf{x}}_c) := \mathbf{f}_{\mathit{sim}}(\mathbf{x}_c, \mathbf{u}_{c+d}, t_i, \mathbf{p})}] + -_Therefore, the initial state_ latexmath:[{\mathbf{x}_c(t_{\mathit{start}})}] _has <> = <> and the initial state derivative_ latexmath:[{\dot{\mathbf{x}}_c(t_{\mathit{start}})}] _has <> = <>._ -_The importer can still initialize this FMU in steady-state, by using_ latexmath:[{\mathbf{x}_c(t_{\mathit{start}})}] _as iteration variables and adding the equations_ latexmath:[{\dot{\mathbf{x}}_c(t_{\mathit{start}}) = \mathbf{0}}] _in the importer.]_ +Therefore, the initial state latexmath:[{\mathbf{x}_c(t_{\mathit{start}})}] has <> = <> and the initial state derivative latexmath:[{\dot{\mathbf{x}}_c(t_{\mathit{start}})}] has <> = <>. +The importer can still initialize this FMU in steady-state, by using latexmath:[{\mathbf{x}_c(t_{\mathit{start}})}] as iteration variables and adding the equations latexmath:[{\dot{\mathbf{x}}_c(t_{\mathit{start}}) = \mathbf{0}}] in the importer. +==== |`EventIndicator` | @@ -1694,8 +1770,8 @@ Only <> variables of type `Float32` and `Float64` can be referenced For Co-Simulation and Scheduled Execution, <> elements are ignored. -_[The intention for connecting event indicators to variables via `valueReferences` is to facilitate debugging of the FMU._ -_If an event indicator shall not be exposed, or if event indicators are not statically associated with a variable (due to dynamic event indicator selection), then dummy variables have to be introduced, for example, `eventIndicator[4]`.]_ +NOTE: The intention for connecting event indicators to variables via `valueReferences` is to facilitate debugging of the FMU. +If an event indicator shall not be exposed, or if event indicators are not statically associated with a variable (due to dynamic event indicator selection), then dummy variables have to be introduced, for example, `eventIndicator[4]`. |==== @@ -1718,9 +1794,13 @@ Optional attribute defining the algebraic dependencies as list of value referenc For a real valued unknown and a real valued known, if the known is not listed among the dependencies then the partial derivative of the unknown with respect to that known is identically zero. If dependencies is not present, it must be assumed that the unknown depends on all knowns. If dependencies is present as empty list, the unknown depends on none of the knowns. -_[The importer should not rely on self-dependencies to be explicitly listed, e.g., <>s that are continuous state(s) have an implicit self-dependency.]_ -Otherwise the unknown depends on the knowns defined by the given value references. + -_[This means that all dependencies must be listed, also the dependencies of clocked variables on their clocks.]_ + + +NOTE: The importer should not rely on self-dependencies to be explicitly listed, e.g., <>s that are continuous state(s) have an implicit self-dependency. + +Otherwise the unknown depends on the knowns defined by the given value references. + +NOTE: This means that all dependencies must be listed, also the dependencies of clocked variables on their clocks. + Knowns latexmath:[{\mathbf{v}_{\mathit{known}}}] in <> and <> (ME) and at communication points (CS and SE) for <> and <> elements are: + * inputs (variables with <> = <>), @@ -1735,15 +1815,16 @@ Knowns latexmath:[{\mathbf{v}_{\mathit{known}}}] in <> (for * inputs (variables with <> = <>), -* variables with <> = <>, _[for example, <> or initial <>]_ +* variables with <> = <>, ++ +NOTE: for example, <> or initial <> * <> variable (usually time; <> = <>). -_[The <> variable should be treated as any other variable when it comes to dependencies._ -_As only explicit dependencies are listed it is required that unknowns that depend on the <> variable have a partial derivative w.r.t this variable that is different from identically zero._ -_If the FMU supports <> or <> the <> variable is a valid input to those functions if it is listed, just as any other listed variable._ -_For example, for a mechanical system, if it has the <> variable listed among the dependencies it is called a rheonomous system, otherwise it is called a scleronomous system.]_ - +NOTE: The <> variable should be treated as any other variable when it comes to dependencies. +As only explicit dependencies are listed it is required that unknowns that depend on the <> variable have a partial derivative w.r.t this variable that is different from identically zero. +If the FMU supports <> or <> the <> variable is a valid input to those functions if it is listed, just as any other listed variable. +For example, for a mechanical system, if it has the <> variable listed among the dependencies it is called a rheonomous system, otherwise it is called a scleronomous system. |`dependenciesKind` | @@ -1774,12 +1855,13 @@ This definition adds an additional layer to the interface description of the FMU It does not change the <> of the variables (e.g. inputs will remain inputs, outputs will remain outputs, and parameters will remain parameters) but enables the definition of physical and bus-like connectors and variable groups that require special handling on the system level by the importer (e.g. flow variables and bus frames). Icons define a graphical representation of an FMU and its terminals. -Both features are optional and may be defined in the separate XML file `terminalsAndIcons/terminalsAndIcons.xml`. + -_[The usage of a separate file enables backporting of this feature to previous FMI versions.]_ +Both features are optional and may be defined in the separate XML file `terminalsAndIcons/terminalsAndIcons.xml`. + +NOTE: The usage of a separate file enables backporting of this feature to previous FMI versions. .fmiTerminalsAndIcons element. [[terminals_and_icons_overview]] -image::images/schema/fmiTerminalsAndIcons.png[width=60%, align="center"] +image::images/schema/fmiTerminalsAndIcons.png[width=600] On the top level, the schema consists of the following elements (see <>). @@ -1819,25 +1901,31 @@ There are two optional elements in the ``: .GraphicalRepresentation element. [[figure-schema-GraphicalRepresentation]] -image::images/schema/GraphicalRepresentation.png[width=100%, align="center"] +image::images/schema/GraphicalRepresentation.png[width=1000] ====== CoordinateSystem .CoordinateSytem element. [[figure-schema-CoordinateSystem]] -image::images/schema/CoordinateSystem.png[width=70%, align="center"] +image::images/schema/CoordinateSystem.png[width=650] The `` element and its extent is used as reference for other graphical items. It also provides a scaling factor to millimeter. -The coordinate system is defined by the coordinates of two points, the lower left (`x1`, `y1`) corner and the upper right (`x2`, `y2`) corner, where the coordinates of the first point shall be less than the coordinates of the second point _[a first quadrant coordinate system]_. +The coordinate system is defined by the coordinates of two points, the lower left (`x1`, `y1`) corner and the upper right (`x2`, `y2`) corner, where the coordinates of the first point shall be less than the coordinates of the second point + +NOTE: a first quadrant coordinate system. + The x-axis is directed to the right, the y-axis is directed upwards. -_[The exporting tool should define how the coordinate system unit relates to mm display or printout size._ -_However, an importer might choose to use the factor from the default coordinate system extent to the actual coordinate system extent to calculate a scaling factor, to match the default icon size in the importer._ +[NOTE] +==== +The exporting tool should define how the coordinate system unit relates to mm display or printout size. +However, an importer might choose to use the factor from the default coordinate system extent to the actual coordinate system extent to calculate a scaling factor, to match the default icon size in the importer. -_The area defined by the coordinate system is suggested to be used as "clickable icon size" in importers._ -_A `` might be placed outside of this area, therefore the visible bounding box has to be determined by the importer.]_ +The area defined by the coordinate system is suggested to be used as "clickable icon size" in importers. +A `` might be placed outside of this area, therefore the visible bounding box has to be determined by the importer. +==== The coordinate system default is `x1=-100, y1=-100, x2=100, y2=100`. This extent is used if the `` element is missing. @@ -1852,7 +1940,7 @@ Flipping of the FMU icon or a terminal can be realized by setting its attributes .Icon element. [[figure-schema-Icon]] -image::images/schema/Icon.png[width=40%, align="center"] +image::images/schema/Icon.png[width=400] The extent and position of the FMU icon are defined in the `` element. The optional image file of the FMU icon is placed at the path `terminalsAndIcons/icon.png` in the ZIP archive of the FMU. @@ -1865,18 +1953,20 @@ The point (`x2`, `y2`) maps to the right upper corner of the PNG image or SVG vi ====== Placement, Extent, and Painting Order of Graphical Items -image::images/GraphicalRepresentation.svg[width=70%, pdfwidth=70%, align="center"] +image::images/GraphicalRepresentation.svg[width=600] The clickable icon size is defined by the `` element. The FMU icon itself may exceed this extent (or bounding box). The bounding box of the terminals is given by the extent in the terminals element. Their location is neither limited to the extent of the icon nor the extent of the coordinate system. -_[An importer has to determine the outer bounding box enclosing all graphical items.]_ + +NOTE: An importer has to determine the outer bounding box enclosing all graphical items. Transparent SVG or PNG files are allowed and wanted. The order of the elements in the XML file defines the order of painting. The first element in the `` is painted first and therefore behind the others, the last element is painted on top of the others and because of that in front of them. -_[So the FMU icon should be placed first in the XML file, terminal below.]_ + +NOTE: So the FMU icon should be placed first in the XML file, terminal below. ===== Definition of Terminals [[definitionOfTerminals]] @@ -1894,12 +1984,15 @@ Predefined rules for variable matching in a connection are given in <> of the terminal member variables in connected terminals match._ -_This must be handled by the importer._ +[NOTE] +==== +Algebraic loops in systems of connected FMUs are not addressed or resolved by the terminals. +The FMU standard does not require that the <> of the terminal member variables in connected terminals match. +This must be handled by the importer. -_The https://ssp-standard.org/[System Structure & Parameterization Standard (SSP)] refers to a `connectorKind`._ -_This `connectorKind` is not related to the `terminalKind` or `variableKind` described in <> and <>.]_ +The https://ssp-standard.org/[System Structure & Parameterization Standard (SSP)] refers to a `connectorKind`. +This `connectorKind` is not related to the `terminalKind` or `variableKind` described in <> and <>. +==== [[section-terminals]] ====== Terminals @@ -1908,7 +2001,7 @@ Element `` is defined as: .Terminals element. [[figure-schema-Terminals]] -image::images/schema/Terminals.png[width=80%, align="center"] +image::images/schema/Terminals.png[width=800] The normalized string attribute `name` of the `` element is the <> instance name of the terminal. The terminal name must be unique on each level. @@ -1955,22 +2048,24 @@ Other standards may define terminal kinds. It is strongly recommended to use <> to define a `terminalKind`. It is intended that the `terminalKind` is used to define domain specific member variable sequences, member names and order, or high level restrictions for connections. -_[Externally defined terminal kinds should refer to a predefined `matchingRule`, if possible._ -_Vendor specific terminal kinds should start with `_vendorName` or `_toolName` to avoid namespace clashes._ +[NOTE] +==== +Externally defined terminal kinds should refer to a predefined `matchingRule`, if possible. +Vendor specific terminal kinds should start with `_vendorName` or `_toolName` to avoid namespace clashes. -_Examples for `terminalKind`: `StandardXXX_Mechanical_Translational`, `Modelica.Mechanics.Translational.Interfaces.Flange_a`, `vendorNameA_customTypeA`, `_vendorNameB_customLibrary_customTypeB`._ +Examples for `terminalKind`: `StandardXXX_Mechanical_Translational`, `Modelica.Mechanics.Translational.Interfaces.Flange_a`, `vendorNameA_customTypeA`, `_vendorNameB_customLibrary_customTypeB`. -_The structured naming convention of the <> is independent from the terminal names and member variable names._ +The structured naming convention of the <> is independent from the terminal names and member variable names. -_A tool may choose to connect terminals with a different or unknown `terminalKind`, if the `matchingRule` matches._ +A tool may choose to connect terminals with a different or unknown `terminalKind`, if the `matchingRule` matches. -_A tool may choose to take the structured naming convention of variable names into account when matching terminals._ -_This can for example be used to allow matching between terminals employing arrays mapped to scalar variables using structured naming convention ("naming convention arrays"), and those using native FMI 3.0 arrays, as in the following example:_ +A tool may choose to take the structured naming convention of variable names into account when matching terminals. +This can for example be used to allow matching between terminals employing arrays mapped to scalar variables using structured naming convention ("naming convention arrays"), and those using native FMI 3.0 arrays, as in the following example: -_Assume that an (FMI 3.0) FMU has a one-dimensional array variable `x` of length 3 as member variable of a terminal and is connected to another (FMI 2.0 or FMI 3.0) FMU supporting structured naming convention, which has scalar variables `x[1]`, `x[2]`, `x[3]` as member variables of a terminal._ -_Then `x[1]`, `x[2]`, `x[3]` are interpreted as a "naming convention array" with name `x`, which "matches" the array variable `x` of the first FMU, in name-based matching._ -_Similarly the notional "naming convention array" `x` would participate in sequence-based matching as a single notional variable in the place of the underlying scalar variables._ -_]_ +Assume that an (FMI 3.0) FMU has a one-dimensional array variable `x` of length 3 as member variable of a terminal and is connected to another (FMI 2.0 or FMI 3.0) FMU supporting structured naming convention, which has scalar variables `x[1]`, `x[2]`, `x[3]` as member variables of a terminal. +Then `x[1]`, `x[2]`, `x[3]` are interpreted as a "naming convention array" with name `x`, which "matches" the array variable `x` of the first FMU, in name-based matching. +Similarly the notional "naming convention array" `x` would participate in sequence-based matching as a single notional variable in the place of the underlying scalar variables. +==== [[section-terminalvars]] ====== Terminal Member Variable @@ -1979,7 +2074,7 @@ The `` is defined as: .TerminalMemberVariable element. [[figure-schema-TerminalMemberVariable]] -image::images/schema/TerminalMemberVariable.png[width=70%, pdfwidth=50%, align="center"] +image::images/schema/TerminalMemberVariable.png[width=700] The normalized string `variableName` identifies a variable in <> which is actually connected and for which <> and <> is called. @@ -1995,7 +2090,7 @@ The predefined `variableKind` are: .Predefined kinds of variables. [[table-variable-kinds]] -[cols="1,3",options="header"] +[cols="1,3a",options="header"] |==== |`variableKind` |Description @@ -2004,39 +2099,45 @@ The predefined `variableKind` are: |`signal` |The values in connected terminals are intended to be equal. Restricted to <> and <>, <> and <>. -_[Example: Signal flow, parameter propagation, equality checks]_ + +NOTE: Example: Signal flow, parameter propagation, equality checks [[inoutflow,`inflow/outflow`]] |`inflow` / `outflow` |Variables which fulfill Kirchhoff's current law. Restricted to <> and <>, <> and <>. -_[Example: Electric current]_ + +NOTE: Example: Electric current + |==== -_[The suggested variable naming scheme for the structured naming convention is = .._ +[NOTE] +==== +The suggested variable naming scheme for the structured naming convention is = .. -_Not all <> which have the prefix "." are a member variable, and there may exist member variables which don't have this prefix._ +Not all <> which have the prefix "." are a member variable, and there may exist member variables which don't have this prefix. -_Example 1 (suggested scheme): is `portA.U`, is `portA`, is `U`._ +Example 1 (suggested scheme): is `portA.U`, is `portA`, is `U`. -_Example 2 (suggested scheme): is `hierarchConn.innerConn.U`, is `hierarchConn`, is `innerConn`, is `U`._ +Example 2 (suggested scheme): is `hierarchConn.innerConn.U`, is `hierarchConn`, is `innerConn`, is `U`. -_Example 3 (no prefix): is `u`, is `portA`, is `u`._ +Example 3 (no prefix): is `u`, is `portA`, is `u`. -_Example 4 (prefix but not a member): is `portA.u`, there is a terminal with `portA`, but this variable is not a terminal member._ +Example 4 (prefix but not a member): is `portA.u`, there is a terminal with `portA`, but this variable is not a terminal member. -_The suggested variable naming scheme for the non-structured naming convention is: = _ +The suggested variable naming scheme for the non-structured naming convention is: = -_Matching is not restricted by <>, <> or variable type._ -_Example: A <> variable may be connected to a <> variable, a variable of type `fmi3Float64` may be connected to a variable of type `fmi3Int32`._ -_However, it is recommended that the variable types and variabilities are equal._ +Matching is not restricted by <>, <> or variable type. +Example: A <> variable may be connected to a <> variable, a variable of type `fmi3Float64` may be connected to a variable of type `fmi3Int32`. +However, it is recommended that the variable types and variabilities are equal. -_The `matchingRule` refers to the `` on the same level only._ -_Nested terminals can have different `matchingRules`._ +The `matchingRule` refers to the `` on the same level only. +Nested terminals can have different `matchingRules`. -_There is no special handling of <>._ -_If a <> is a terminal member variable then it is considered as normal member variable._ -_However, if a <> of a terminal member variable is not terminal member, then this <> information may be used by an importer.]_ +There is no special handling of <>. +If a <> is a terminal member variable then it is considered as normal member variable. +However, if a <> of a terminal member variable is not terminal member, then this <> information may be used by an importer. +==== ====== Terminal Stream Member Variable @@ -2044,48 +2145,52 @@ The `` is defined as: .TerminalStreamMemberVariable element. [[figure-schema-TerminalStreamMemberVariable]] -image::images/schema/TerminalStreamMemberVariable.png[width=80%, pdfwidth=60%, align="center"] +image::images/schema/TerminalStreamMemberVariable.png[width=800] This element is used for variables which fulfill the balance equation for transported quantities. It is restricted to <> and <>, <> and <>. The Stream concept is described in the appendix D "Derivations of Stream Equations" of the <>. Only one terminal member variable with the `variableKind` `inflow` or `outflow` per terminal is allowed, if a `` is present. -_[More sophisticated structures can be implemented using hierarchical terminals.]_ + +NOTE: More sophisticated structures can be implemented using hierarchical terminals. The attribute `inStreamVariableName` and `outStreamVariableName` are used to identify the <>. If the referenced model variables are arrays, then the size of the `inStreamVariableName` and `outStreamVariableName` has to be equal. A terminal may have more than one ``. The `inStreamMemberName` and `outStreamMemberName` describe the terminal member name for matching purposes, similar to the `memberName` attribute in the ``. -_[An example of use for an array of stream variables is a gas mixture flow._ -_The gas composition could be implemented as a mass fraction vector._ -_The `outStreamVariableName` refers to_ latexmath:[portA.q_\textit{outStream}\textit{[\]}] _and the `inStreamVariableName` refers to_ latexmath:[portA.q_\textit{inStream}\textit{[\]}] _._ -_The `inStreamMemberName` and `outStreamMemberName` are "_ latexmath:[q_\textit{inStream}\textit{[\]}] _" and "_ latexmath:[q_\textit{outStream}\textit{[\]}] _"._ +[NOTE] +==== +An example of use for an array of stream variables is a gas mixture flow. +The gas composition could be implemented as a mass fraction vector. +The `outStreamVariableName` refers to latexmath:[portA.q_\textit{outStream}\textit{[\]}] and the `inStreamVariableName` refers to latexmath:[portA.q_\textit{inStream}\textit{[\]}]. +The `inStreamMemberName` and `outStreamMemberName` are " latexmath:[q_\textit{inStream}\textit{[\]}] " and " latexmath:[q_\textit{outStream}\textit{[\]}] ". -_Balance equation for transported quantities:_ +Balance equation for transported quantities: -_latexmath:[0 = \sum{q_i\dot{m}_i}]_ +latexmath:[0 = \sum{q_i\dot{m}_i}] -_latexmath:[0 = \sum{\dot{m}_i}\cdot +latexmath:[0 = \sum{\dot{m}_i}\cdot \left\{\begin{array}{ll} q_{i, \mathit{outStream}} &\textit{if $\dot{m}$ is outflowing through terminal $i$}\\ q_{i, \mathit{inStream}} &\textit{if $\dot{m}$ is inflowing through terminal $i$} -\end{array}\right.]_ +\end{array}\right.] -_The_ latexmath:[q_{i,\mathit{outStream}}] _is the convective quantity in case the matter flows out of the FMU._ -latexmath:[q_{i,\mathit{inStream}}] _is the convective quantity in case the matter flows into the FMU._ -_Both variables are present in the terminal._ -_The outStream variable has the <> <> or <> because this information has to be provided by each FMU._ -_The inStream variable has the <> <> or <>._ -_To display the actual value in an importer, this actual value has to be selected depending on the sign of the terminal member variable with `variableKind` `inflow` or `outflow`._ -_However, calculating the actual value is not necessary._ +The latexmath:[q_{i,\mathit{outStream}}] is the convective quantity in case the matter flows out of the FMU. +latexmath:[q_{i,\mathit{inStream}}] is the convective quantity in case the matter flows into the FMU. +Both variables are present in the terminal +The outStream variable has the <> <> or <> because this information has to be provided by each FMU. +The inStream variable has the <> <> or <>. +To display the actual value in an importer, this actual value has to be selected depending on the sign of the terminal member variable with `variableKind` `inflow` or `outflow`. +However, calculating the actual value is not necessary. -_If only two terminals with a variable are connected and their <> matches, then the values of the outStream variables can be forwarded to the corresponding inStream values._ +If only two terminals with a variable are connected and their <> matches, then the values of the outStream variables can be forwarded to the corresponding inStream values. -_In Modelica the inStream variable is not directly visible, the value can only be accessed using "inStream()", therefore an additional model variable has to be added during the export._ -_It is suggested that Modelica tools exporting an FMU derive the member name for the inStream variable according to the scheme "_inStream"._ -_E.g. if the outStream name is "h_outflow" then the inStream name should be "h_outflow_inStream".]_ +In Modelica the inStream variable is not directly visible, the value can only be accessed using "inStream()", therefore an additional model variable has to be added during the export. +It is suggested that Modelica tools exporting an FMU derive the member name for the inStream variable according to the scheme "_inStream". +E.g. if the outStream name is "h_outflow" then the inStream name should be "h_outflow_inStream". +==== ====== Terminal Graphical Representation @@ -2093,7 +2198,7 @@ The `` is defined as: .TerminalGraphicalRepresentation element. [[figure-schema-TerminalGraphicalRepresenation]] -image::images/schema/TerminalGraphicalRepresentation.png[width=75%, pdfwidth=60%, align="center"] +image::images/schema/TerminalGraphicalRepresentation.png[width=800] The `iconBaseName` attribute is mandatory. This attribute defines the base name of the image file as a relative URI according to RFC 3986. @@ -2103,61 +2208,71 @@ Implementations are not required to support any absolute URIs and any specific U The PNG file with the extension '.png' has to be provided. An additional SVG file with extension '.svg' is optional. -_[Note that this specification is functionally equivalent to looking up image sources from the `terminalsAndIcons` folder of the FMU ZIP archive after dot removal from the path as per section 5.2.4 of RFC 3986.]_ +NOTE: Note that this specification is functionally equivalent to looking up image sources from the `terminalsAndIcons` folder of the FMU ZIP archive after dot removal from the path as per section 5.2.4 of RFC 3986. The `defaultConnectionStrokeSize` and `defaultConnectionColor` can be provided to define the intended connection line layout in the importer. The stroke size is given relative to the coordinate system extent. The stroke color is given in RGB values from 0 to 255. E.g.: `255 255 0`. -_[Nested terminals may have a `` element._ -_However, if and how nested terminals are displayed, is up to the importer.]_ +NOTE: Nested terminals may have a `` element. +However, if and how nested terminals are displayed, is up to the importer. -_[The order of painting of the `` of terminals on each level is equal to the order in the `` element._ -_So graphical representations appearing first, are painted first, are behind graphical representations which appear below.]_ +NOTE: The order of painting of the `` of terminals on each level is equal to the order in the `` element. +So graphical representations appearing first, are painted first, are behind graphical representations which appear below. The `Annotations` element can be used by vendors to store additional information for the graphical representation. -_[It is suggested that Modelica tools store the Modelica annotation of the connector under the `type` `org.modelica.Modelica4Annotation` in the annotations of an element `connector`._ -_The attribute `name` of the connector element is equal to the `name` attribute of the referenced `fmi3Terminal`.]_ - -_[If the graphical representation is used for an <> or <> (e.g. a `fmi3Float64` <> `u`), then a `` has to be added to the `` element which has one ``.]_ - -====== General Remark on Signal [[GeneralRemarkOnSignal]] -_[The signal `variableKind` can be applied for different use cases._ -_The first use case is a signal flow from an <> of one FMU to an <> of another FMU._ -_The <> value has to be forwarded to the <>._ +NOTE: It is suggested that Modelica tools store the Modelica annotation of the connector under the `type` `org.modelica.Modelica4Annotation` in the annotations of an element `connector`. +The attribute `name` of the connector element is equal to the `name` attribute of the referenced `fmi3Terminal`. -_The signal flow can cause algebraic loops._ -_If variables in connected terminals have the <> <>, then an importer may iterate an undefined <> of an FMU to ensure that the connected output values are equal._ +NOTE: If the graphical representation is used for an <> or <> (e.g. a `fmi3Float64` <> `u`), then a `` has to be added to the `` element which has one ``. -_Another use case is the parameter propagation._ -_If a variable in both connected terminals has the <> <>, then an importer could ask the user for the value of one of those <> only, and propagate this value to the other FMU._ -_If only one of the variables has <> <>, and the other is a <> <> or <>, then the importer could also propagate the <> value without presenting a parameter to the user._ -_One example of use would be the name of a substance flowing through a pipe._ -_If the fluid flows from one pipe FMU to another, the substance should be the same._ -_This substance name could be propagated over several FMUs._ +====== General Remark on Signal [[GeneralRemarkOnSignal]] -_Finally the `variableKind` `signal` can be applied to implement compatibility checks._ -_If for example the <> of the variables in connected terminals are <>, then the importer can implement an equality assertion._ -_This is also possible with <> <>._ -_One example of use would be the cross sectional flow area in pipes which is calculated from geometry parameters._ -_A change in the cross sectional flow area is relevant for the momentum equation, and therefore the connection has to be deemed incompatible if these variables are present and unequal.]_ +[NOTE] +==== +The signal `variableKind` can be applied for different use cases. +The first use case is a signal flow from an <> of one FMU to an <> of another FMU. +The <> value has to be forwarded to the <>. + +The signal flow can cause algebraic loops. +If variables in connected terminals have the <> <>, then an importer may iterate an undefined <> of an FMU to ensure that the connected output values are equal. + +Another use case is the parameter propagation. +If a variable in both connected terminals has the <> <>, then an importer could ask the user for the value of one of those <> only, and propagate this value to the other FMU. +If only one of the variables has <> <>, and the other is a <> <> or <>, then the importer could also propagate the <> value without presenting a parameter to the user. +One example of use would be the name of a substance flowing through a pipe. +If the fluid flows from one pipe FMU to another, the substance should be the same. +This substance name could be propagated over several FMUs. + +Finally the `variableKind` `signal` can be applied to implement compatibility checks. +If for example the <> of the variables in connected terminals are <>, then the importer can implement an equality assertion. +This is also possible with <> <>. +One example of use would be the cross sectional flow area in pipes which is calculated from geometry parameters. +A change in the cross sectional flow area is relevant for the momentum equation, and therefore the connection has to be deemed incompatible if these variables are present and unequal. +==== ====== General Remark on Inflow and Outflow -_[Flow variables have a direction and must fulfill a zero sum constraint i.e. the sum of all flow variables connected must be zero (Kirchhoff's current law)._ -_In addition because different tools might have different direction definitions both, `inflow` and `outflow` are available as `variableKind`._ -_For variables with `inflow` a positive value means that the flow is inwards, and for `outflow` a positive value means that the flow is outwards._ -_For the sake of simplicity in the following latexmath:[\dot{m}_i] denotes an inflowing quantity:_ +[NOTE] +==== +Flow variables have a direction and must fulfill a zero sum constraint i.e. the sum of all flow variables connected must be zero (Kirchhoff's current law). +In addition because different tools might have different direction definitions both, `inflow` and `outflow` are available as `variableKind`. +For variables with `inflow` a positive value means that the flow is inwards, and for `outflow` a positive value means that the flow is outwards. +For the sake of simplicity in the following latexmath:[\dot{m}_i] denotes an inflowing quantity: -_latexmath:[0 = \sum{\dot{m}_i}]_ +latexmath:[0 = \sum{\dot{m}_i}] +==== -_[Connecting a single <> `outflow` to a single <> `inflow`, or vice versa automatically fulfills the flow constraint, while connecting two variables of the same flow type requires a negation of the variable value._ +[NOTE] +==== +Connecting a single <> `outflow` to a single <> `inflow`, or vice versa automatically fulfills the flow constraint, while connecting two variables of the same flow type requires a negation of the variable value. -`inflow` _and_ `outflow` _is only used as a sign convention for scalar flow quantities which obey Kirchhoff's current law (sum up to zero)._ -_Other, nonscalar, quantities which also sum up to zero, like a mechanical force in 3D space according to D'Alembert's principle, are not covered by this sign convention._ -_This is the case since Kirchhoff's current law only holds for scalars where a sign convention is sufficient._ -_Other definitions are beyond the scope of this terminal specification and need clear definition in other specifications on top of this.]_ +`inflow` _and_ `outflow` _is only used as a sign convention for scalar flow quantities which obey Kirchhoff's current law (sum up to zero). +Other, nonscalar, quantities which also sum up to zero, like a mechanical force in 3D space according to D'Alembert's principle, are not covered by this sign convention. +This is the case since Kirchhoff's current law only holds for scalars where a sign convention is sufficient. +Other definitions are beyond the scope of this terminal specification and need clear definition in other specifications on top of this. +==== ==== Build Configurations [[BuildConfiguration,``]] @@ -2183,7 +2298,8 @@ The element must contain at least one <> provides the necessary information to compile and link the sources of the model into a dynamic library or as part of an executable. An FMU importer may not regard more than one <> when building the FMU for a specific <>. The importer chooses the matching <> based on the <> and <> attributes. -_[On platforms that support shared libraries, executables should not be linked statically against or be compiled directly from the sources of an FMU in order to avoid name conflicts.]_ + +NOTE: On platforms that support shared libraries, executables should not be linked statically against or be compiled directly from the sources of an FMU in order to avoid name conflicts. In order to avoid symbol name conflicts when compiling and linking multiple source code FMUs, source files should keep the exported symbols to a minimum by declaring all symbols not needed for linking as `static`. If only a single <> is provided in the <> all symbols except for the FMI functions should be defined as `static`. @@ -2192,7 +2308,7 @@ It is also recommended to use a descriptive name (e.g. `.c`) f .`fmiBuildDescription` element. [[figure-fmiBuildDescription]] -image::images/schema/fmiBuildDescription.png[width=90%] +image::images/schema/fmiBuildDescription.png[width=900] .BuildConfiguration attribute details. [[table-BuildConfiguration-details]] @@ -2209,8 +2325,9 @@ image::images/schema/fmiBuildDescription.png[width=90%] This attribute is optional. Thus there must not be more than one <> without a <> attribute. If a <> without a <> attribute is provided this is the fallback <> an importer can use if it cannot find any other <> with a matching <> attribute. -_[A BuildDescription may contain multiple BuildConfigurations for the same <> to support e.g. different compilers._ -_In this case the importer has to select the BuildConfiguration based on the other attributes of the BuildConfiguration and the contained SourceFileSets.]_ + +NOTE: A BuildDescription may contain multiple BuildConfigurations for the same <> to support e.g. different compilers. +In this case the importer has to select the BuildConfiguration based on the other attributes of the BuildConfiguration and the contained SourceFileSets. |`description` |Description of the build configuration @@ -2224,7 +2341,7 @@ An importer of the FMU has to process every `` of the matching << .`SourceFileSet` element. [[figure-SourceFileSet]] -image::images/schema/SourceFileSet.png[width=60%] +image::images/schema/SourceFileSet.png[width=600] .SourceFileSet attribute details. [[table-SourceFileSet-details]] @@ -2246,13 +2363,13 @@ image::images/schema/SourceFileSet.png[width=60%] |The compiler flags that have to be used when compiling the sources (e.g. `-fno-rtti`, `/Od`) |==== -_[Please refer to the https://modelica.github.io/fmi-guides/main/fmi-guide/[FMI Implementer's Guide] for lists of commonly agreed upon language and compiler names.]_ +NOTE: Please refer to the https://modelica.github.io/fmi-guides/main/fmi-guide/[FMI Implementer's Guide] for lists of commonly agreed upon language and compiler names. ===== SourceFile [[SourceFile,``]] -.`SourceFileSet` element. +.`SourceFile` element. [[figure-SourceFile]] -image::images/schema/SourceFile.png[width=50%] +image::images/schema/SourceFile.png[width=550] .SourceFile attribute details. [[table-SourceFile-details]] @@ -2272,7 +2389,7 @@ The `` element defines a preprocessor definition that ne .`PreprocessorDefinition` element. [[figure-PreprocessorDefinition]] -image::images/schema/PreprocessorDefinition.png[width=60%] +image::images/schema/PreprocessorDefinition.png[width=650] .ProcessorDefintition attribute details. [[table-ProcessorDefinition-details]] @@ -2319,7 +2436,7 @@ The `` element defines the include directories that need to be .`IncludeDirectory` element. [[figure-IncludeDirectory]] -image::images/schema/IncludeDirectory.png[width=60%] +image::images/schema/IncludeDirectory.png[width=600] .IncludeDirectory attribute details. [[table-IncludeDirectory-details]] @@ -2332,16 +2449,19 @@ image::images/schema/IncludeDirectory.png[width=60%] |Path of the include directory relative to the `sources` directory |==== -_[Note that the header files `fmi3PlatformTypes.h` and `fmi3FunctionTypes.h/fmi3Functions.h` are not included in the FMU because:_ +[NOTE] +==== +Note that the header files `fmi3PlatformTypes.h` and `fmi3FunctionTypes.h/fmi3Functions.h` are not included in the FMU because: -_pass:[]`fmi3PlatformTypes.h` makes no sense in the `sources` directory, because if sources are provided, then the importer defines this header file and not the FMU._ + -_This header file is not included in the `binaries` directory, because it is implicitly defined by the platform directory (for example, `x86-windows` for a 32-bit machine running Windows or `x86_64-linux` for a 64-bit machine running Linux)._ +pass:[]`fmi3PlatformTypes.h` makes no sense in the `sources` directory, because if sources are provided, then the importer defines this header file and not the FMU. + +This header file is not included in the `binaries` directory, because it is implicitly defined by the platform directory (for example, `x86-windows` for a 32-bit machine running Windows or `x86_64-linux` for a 64-bit machine running Linux). -_pass:[]`fmi3FunctionTypes.h` / `fmi3Functions.h` are not needed in the `sources` directory, because they are implicitly defined by attribute `fmiVersion` in file <>._ -_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._ -_The version number of the header file used to construct the FMU can be deduced via attribute `fmiVersion` in file <> or via function call <>.]_ +pass:[]`fmi3FunctionTypes.h` / `fmi3Functions.h` are not needed in the `sources` directory, because they are implicitly defined by attribute `fmiVersion` in file <>. +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. +The version number of the header file used to construct the FMU can be deduced via attribute `fmiVersion` in file <> or via function call <>. +==== ===== Library @@ -2350,7 +2470,7 @@ An importer of the FMU has to link every library of the matching <` (greater-than) and `<` (less-than) must be escaped as `&gt;` and `&lt;`. - _[For example `2.5`, `>=2.0,<3.0` or `>=1.0,!=1.2`]_. + +NOTE: For example `2.5`, `>=2.0,<3.0` or `>=1.0,!=1.2`. |`external` |Boolean attribute that determines whether the library is contained in the `binaries/` directory (`false`) or if it has to be provided by the environment (`true`). diff --git a/docs/2_5_fmu_distribution.adoc b/docs/2_5_fmu_distribution.adoc index a1a41fac7..8b49824ca 100644 --- a/docs/2_5_fmu_distribution.adoc +++ b/docs/2_5_fmu_distribution.adoc @@ -6,20 +6,26 @@ The FMU must be distributed with at least one implementation, in other words, ei It is also possible to provide the sources and binaries for different target machines together in one ZIP file. The FMU must implement all API functions declared in `fmi3Functions.h`, even if they are only needed for interface types or optional capabilities that the FMU does not support. The behavior of those functions is unspecified, so while calling environments can rely on the functions being present, they cannot rely on any particular behavior for functions only needed for capabilities or interface types the FMU does not support. -_[The recommended implementation for such stub functions is to return `fmi3Error` after logging the error reason, as specified in <>. -Calling environments should not rely on the presence of functions that are not required and avoid calling them.]_ + +NOTE: The recommended implementation for such stub functions is to return `fmi3Error` after logging the error reason, as specified in <>. +Calling environments should not rely on the presence of functions that are not required and avoid calling them. + Additional functions may be present in the FMU, as for example required by the OS ABI, for layered standards, or future FMI versions. All symbols starting with the prefix `fmi3` are reserved for use in future minor releases of FMI 3.0. -The extension of the ZIP file must be `.fmu` _[, for example, `HybridVehicle.fmu`]_. +The extension of the ZIP file must be `.fmu` + +NOTE: for example, `HybridVehicle.fmu`. + The compression method for all files stored in the ZIP archive must be either `8` (deflate) or `0` (store). Only files stored using compression method `8` (deflate) may be stored with general purpose bit `3` set. The field `version needed to extract` of the archive must not be higher than `2.0` and encryption must not be employed. The archive must not be a split or spanned ZIP archive. Links must not be used inside the ZIP archive. - _[These restrictions ensure broad compatibility of the archive with common ZIP processing tools and libraries.)]_ -_[Note: especially section 4.4.17 of https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT[the ZIP format specification] states that backslashes "\" are forbidden as path separator, only forward slashes "/" are allowed._ + -_Non-ASCII directory names are not explicitly forbidden, but might pose a problem on different operating systems and are thus discouraged.]_ +NOTE: These restrictions ensure broad compatibility of the archive with common ZIP processing tools and libraries.) + +NOTE: Note: especially section 4.4.17 of https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT[the ZIP format specification] states that backslashes "\" are forbidden as path separator, only forward slashes "/" are allowed. + +Non-ASCII directory names are not explicitly forbidden, but might pose a problem on different operating systems and are thus discouraged. Every FMU is distributed with its own ZIP file. @@ -72,8 +78,8 @@ If the FMU depends on external resources _[e.g. shared libraries, files, or serv This optional subdirectory can be used to bundle all license texts for the code, binaries or other material (documentation, content of resources folder) contained in the FMU. If it is present, it must contain either a https://spdx.dev[license.spdx], `license.txt` or `license.html` file as entry point. -_[It is strongly recommended to include all license and copyright related information in the licenses folder of an FMU (especially but not only for contained open source software) - the `license.{txt|html}` file can serve as an entry point for describing the contained licenses._ -_This will help the users to comply with license conditions when passing source or binary code contained in an FMU to other persons or organizations.]_ +NOTE: It is strongly recommended to include all license and copyright related information in the licenses folder of an FMU (especially but not only for contained open source software) - the `license.{txt|html}` file can serve as an entry point for describing the contained licenses. +This will help the users to comply with license conditions when passing source or binary code contained in an FMU to other persons or organizations. ===== Directory `terminalsAndIcons` [[terminalsAndIcons-directory]] @@ -94,7 +100,10 @@ To use the binaries of a specific platform, all items in that platform-specific The names of the binary directories are standardized by the "platform tuple". Further names can be introduced by vendors. FMUs should contain all resources that are required to load and execute a shared library, link against a static library, or compile from source. -Shared libraries should be statically linked against their dependencies _[e.g. the Visual Studio C Runtime on Windows]_. +Shared libraries should be statically linked against their dependencies + +NOTE: e.g. the Visual Studio C Runtime on Windows. + `RPATH="$ORIGIN"` should be set when building ELF binaries to allow dynamic loading of dependencies on the target machine. All external dependencies must be documented (see <>). @@ -149,8 +158,13 @@ Operating system ``:: |Microsoft Windows |==== -When shipping the implementation as a static library an optional ABI (Application Binary Interface) directory `-{-}` may be added to separate binaries for different toolchains on the same platform and a description must be provided in `documentation/staticLinking.{txt|html}` that contains all necessary information to link against the provided library _[e.g. supported compilers]_. -The ABI directory must only contain lowercase characters `a...z`, digits `0...9`, and underscores `$$_$$` and start with a lowercase character `a...z` _[e.g. `x86_64-windows-msvc140mt` for a static library for 64-bit Windows generated with Visual Studio 2015 with `/MT` flag]_. +When shipping the implementation as a static library an optional ABI (Application Binary Interface) directory `-{-}` may be added to separate binaries for different toolchains on the same platform and a description must be provided in `documentation/staticLinking.{txt|html}` that contains all necessary information to link against the provided library + +NOTE: e.g. supported compilers. + +The ABI directory must only contain lowercase characters `a...z`, digits `0...9`, and underscores `$$_$$` and start with a lowercase character `a...z` + +NOTE: e.g. `x86_64-windows-msvc140mt` for a static library for 64-bit Windows generated with Visual Studio 2015 with `/MT` flag. ====== Platform Tuple Examples [[platform-tuple-examples]] @@ -199,7 +213,7 @@ The following table lists the most common platform tuples for shared libraries a If runtime libraries are needed by the FMU that have to be present on the target machine and cannot be shipped within the FMU (e.g., due to licensing issues), then automatic processing is likely impossible. In such cases special handling is needed, for example, by providing the runtime libraries at appropriate places by the receiver. -The requirements and the expected processing must be documented in the `documentation` directory in the file `externalDependencies.{txt|html}`. + +The requirements and the expected processing must be documented in the `documentation` directory in the file `externalDependencies.{txt|html}`. ===== Directory `resources` [[resources-directory]] @@ -209,17 +223,22 @@ For the FMU to access these resource files - during runtime, after instantiation The resources directory must be available for the lifetime of the FMU instance. The FMU instance must not write to or delete the directory or parts of it. -_[The files contained in the resources folder may be platform dependent files. +NOTE: The files contained in the resources folder may be platform dependent files. In contrast to files in the binaries folder, they can be accessed during runtime by the FMU. -For more information, please consult the https://modelica.github.io/fmi-guides/main/fmi-guide/[FMI Implementer's Guide].]_ +For more information, please consult the https://modelica.github.io/fmi-guides/main/fmi-guide/[FMI Implementer's Guide]. ===== Directory `extra` [[extra-directory]] The ZIP archive may contain additional subdirectories within `extra/` that can be used to store additional data, e.g. for the implementation of <>. -In order to avoid ambiguities and conflicts, the names of these subdirectories should use the <> of a domain that is controlled by the entity defining the semantics and content of the additional entries _[(for example `extra/com.example/SimTool/meta.xml` or `extra/org.example.stdname/data.asd`)]_. +In order to avoid ambiguities and conflicts, the names of these subdirectories should use the <> of a domain that is controlled by the entity defining the semantics and content of the additional entries + +NOTE: (for example `extra/com.example/SimTool/meta.xml` or `extra/org.example.stdname/data.asd`). + It is explicitly allowed for tools and users other than the original creator of an FMU to modify, add or delete entries in the `extra/` directory without affecting the validity of the FMU in all other aspects. -Specifically all validation or digital signature schemes used to protect the content of the FMU should take the variability of extra file content into account _[(for example by having separate checksums or signatures for FMU core content and extra content, or not having signatures at all for extra content)]_. +Specifically all validation or digital signature schemes used to protect the content of the FMU should take the variability of extra file content into account + +NOTE: (for example by having separate checksums or signatures for FMU core content and extra content, or not having signatures at all for extra content). ==== Multiple Interface Types [[multipleInterfaceTypes]] diff --git a/docs/2_6_versioning_layered_standards.adoc b/docs/2_6_versioning_layered_standards.adoc index ea531cf1f..75defbe34 100644 --- a/docs/2_6_versioning_layered_standards.adoc +++ b/docs/2_6_versioning_layered_standards.adoc @@ -1,6 +1,8 @@ === Versioning and Layered Standards [[VersioningLayered]] -The FMI standard uses semantic version numbers, as defined in <>, where the standard version consists of a triple of version numbers, consisting of major version, minor version, and patch version numbers _[e.g. 1.2.3 for major version 1, minor version 2 and patch version 3]_. +The FMI standard uses semantic version numbers, as defined in <>, where the standard version consists of a triple of version numbers, consisting of major version, minor version, and patch version numbers + +NOTE: e.g. 1.2.3 for major version 1, minor version 2 and patch version 3. * Major versions will introduce changes that are neither backward nor forward compatible, including changes to the XML schemas to include new non-ignorable content. * Minor versions will only contain clarifications and include new layered standards, which may add new ignorable XML content, as defined below, into the core standard document, indicating that the standard needs to be supported by all conforming implementations. @@ -78,5 +80,5 @@ include::examples/fmi_ls_manifest_example_schema.xsd[] [[LS-reverse-DNS]]Layered standards use the <> of a domain under the control of the organizations that releases the layered standard to reserve namespaces. All namespaces under both the `org.modelica` and `org.fmi-standard` domains are reserved for use in future layered standards. -_[For example, extensions defined by the Modelica Association might make use of the `org.modelica.fmi` namespace._ -_This could lead to annotations with a `type` attribute of `org.modelica.fmi.something`, and/or extra files under the `extra/org.modelica.ssp.something` sub-directory.]_ +NOTE: For example, extensions defined by the Modelica Association might make use of the `org.modelica.fmi` namespace. +This could lead to annotations with a `type` attribute of `org.modelica.fmi.something`, and/or extra files under the `extra/org.modelica.ssp.something` sub-directory. diff --git a/docs/3_1_model_exchange_math.adoc b/docs/3_1_model_exchange_math.adoc index ea1b549a7..1fbd59925 100644 --- a/docs/3_1_model_exchange_math.adoc +++ b/docs/3_1_model_exchange_math.adoc @@ -12,17 +12,19 @@ For <> event indicators are used. * handle such events in <>. * restart the integration algorithm when leaving <>. -[[state-event,state event]]An <>, and only an event indicator, signals a <> with the domain change from latexmath:[\mathbf{z}_j > 0] to latexmath:[\mathbf{z}_j \leq 0] or from latexmath:[\mathbf{z}_j \leq 0] to latexmath:[\mathbf{z}_j > 0]. + -_[This definition is slightly different from the usual standard definition of state events:_ latexmath:[\mathbf{z}(t) \cdot \mathbf{z}(t_{i-1}) \leq 0] _which has the severe drawback that the value of the event indicator at the previous event instant,_ latexmath:[\mathbf{z}(t_{i-1}) \neq 0], _must be non-zero and this condition cannot be guaranteed._ -_The often used term "zero-crossing function" for latexmath:[\mathbf{z}] is misleading (and is therefore not used in this document), since a state event is defined by a domain change and not by a zero-crossing of a variable.]_ +[[state-event,state event]]An <>, and only an event indicator, signals a <> with the domain change from latexmath:[\mathbf{z}_j > 0] to latexmath:[\mathbf{z}_j \leq 0] or from latexmath:[\mathbf{z}_j \leq 0] to latexmath:[\mathbf{z}_j > 0]. -The FMU must guarantee that after leaving <> latexmath:[\mathbf{z}_j \neq 0], for example, by shifting latexmath:[\mathbf{z}_j] with a small value. + -_[All event indicators should be continuous between events._ -_Furthermore, latexmath:[\mathbf{z}_j] should be scaled in the FMU with its nominal value (so all elements of the returned vector `eventIndicators` should be in the order of 1).]_ +NOTE: This definition is slightly different from the usual standard definition of state events:_ latexmath:[\mathbf{z}(t) \cdot \mathbf{z}(t_{i-1}) \leq 0] _which has the severe drawback that the value of the event indicator at the previous event instant,_ latexmath:[\mathbf{z}(t_{i-1}) \neq 0], _must be non-zero and this condition cannot be guaranteed. +The often used term "zero-crossing function" for latexmath:[\mathbf{z}] is misleading (and is therefore not used in this document), since a state event is defined by a domain change and not by a zero-crossing of a variable. + +The FMU must guarantee that after leaving <> latexmath:[\mathbf{z}_j \neq 0], for example, by shifting latexmath:[\mathbf{z}_j] with a small value. + +NOTE: All event indicators should be continuous between events. +Furthermore, latexmath:[\mathbf{z}_j] should be scaled in the FMU with its nominal value (so all elements of the returned vector `eventIndicators` should be in the order of 1). .An event occurs when the event indicator changes its domain from latexmath:[\mathbf{z}>0] to latexmath:[\mathbf{z} \leq 0] or vice versa. [#figure-events] -image::images/Event.svg[width=60%, align="center"] +image::images/Event.svg[width=500] [[frozen-relations]] During event localization the FMU might be evaluated after the switch of an event indicator. @@ -33,14 +35,15 @@ In <>, vector latexmath:[\mathbf{r}] is used to label all In <> all these relations are "frozen". This is indicated in <> of <> by computing latexmath:[{}^\bullet\mathbf{r}] when leaving <> and using latexmath:[{}^\bullet\mathbf{r}] in the right-hand side of latexmath:[{\mathbf{f}_{\mathit{cont}}}] and latexmath:[{\mathbf{f}_{\mathit{comp}}}] in <> of <>. -_[Example:_ -_An assignment of the form_ +[NOTE] +==== +Example: An assignment of the form ---- y = ((x1 > x2) || (x1 < x3)) ? +1 : -1; ---- -_can be implemented in the FMU as:_ +can be implemented in the FMU as: ---- // event indicator computation: @@ -55,5 +58,6 @@ if Initialization Mode || Event Mode { y = (r1 || r2) ? +1 : -1; ---- -_Therefore, the original if-clause is evaluated in this form only during <> and <>._ -_A hysteresis should be added, in the FMU, for the event indicators to stabilize the event localization.]_ +Therefore, the original if-clause is evaluated in this form only during <> and <>. +A hysteresis should be added, in the FMU, for the event indicators to stabilize the event localization. +==== diff --git a/docs/3_2_model_exchange_api.adoc b/docs/3_2_model_exchange_api.adoc index 980a4496a..cba8bc4c5 100644 --- a/docs/3_2_model_exchange_api.adoc +++ b/docs/3_2_model_exchange_api.adoc @@ -4,7 +4,7 @@ The state machine in <> defines the allowed .Calling sequence of Model Exchange C functions. [#figure-model-exchange-state-machine] -image::images/state-machine-model-exchange.svg[width=80%, align="center"] +image::images/state-machine-model-exchange.svg[width=900] Common states are defined in <>, such as super states <> and <>, states <>, <>, <>, <>, <> and <>. @@ -72,8 +72,11 @@ It refers to the unit of the <> variable. ** the time at the last call to <>. + -_[This allows limited simulation backward in time._ -_As soon as an event occurs (<> was called), going back in time is impossible, because <> / <> can only compute the next discrete state, not the previous one.]_ +[NOTE] +==== +This allows limited simulation backward in time. +As soon as an event occurs (<> was called), going back in time is impossible, because <> / <> can only compute the next discrete state, not the previous one. +==== Function <>:: Only for variables with <> = <> and <> = <>, and <>. @@ -98,7 +101,7 @@ This order is also used in the arguments of the following functions: <> should be returned if the FMU rejects any of the state values because they, for example, violate min/max value restrictions.]_ +NOTE: <> should be returned if the FMU rejects any of the state values because they, for example, violate min/max value restrictions. Function <>:: Returns the current continuous state vector. @@ -117,7 +120,7 @@ Returns the first-order derivatives with respect to the independent variable (us * Argument `nContinuousStates` is the size of the `derivatives` vector. + -_[<> should be returned if the FMU was not able to compute the derivatives according to_ latexmath:[\mathbf{f}_{\mathit{cont}}] _because, for example, a numerical issue, such as division by zero, occurred.]_ +NOTE: <> should be returned if the FMU was not able to compute the derivatives according to latexmath:[\mathbf{f}_{\mathit{cont}}] because, for example, a numerical issue, such as division by zero, occurred. [[fmi3GetEventIndicators,`fmi3GetEventIndicators`]] Function `fmi3GetEventIndicators`:: @@ -134,48 +137,50 @@ Returns the event indicators signaling <> by their sig * Argument `nEventIndicators` is the current size of the `eventIndicators` vector (see <>). + -_[<> should be returned if the FMU was not able to compute the event indicators according to_ latexmath:[\mathbf{f}_{\mathit{cont}}] _because, for example, a numerical issue, such as division by zero, occurred.]_ +NOTE: <> should be returned if the FMU was not able to compute the event indicators according to latexmath:[\mathbf{f}_{\mathit{cont}}] because, for example, a numerical issue, such as division by zero, occurred. [[fmi3CompletedIntegratorStep,`fmi3CompletedIntegratorStep`]] Function `fmi3CompletedIntegratorStep`:: + +-- [source, C] ---- include::../headers/fmi3FunctionTypes.h[tags=CompletedIntegratorStep] ---- -+ + This function is called after every completed step of the integrator provided the capability flag `needsCompletedIntegratorStep = true`. The importer must have set valid values for <