Skip to content

Improve language and examples #59

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
t-sommer wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Improve language and examples #59

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e7412c3
Improve language
t-sommer Jun 25, 2026
f311ae6
Use full path to terminalsAndIcons.xml
t-sommer Jun 25, 2026
997256f
Use d-dimensional consistently
t-sommer Jun 25, 2026
9baf03e
Clean up example XMLs
t-sommer Jun 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/examples/irregular2d_modelDescription.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@
<ModelVariables>
<Float64 name="time" valueReference="0" causality="independent"/>
<!-- tag::variables[] -->
<Float64 name="x" valueReference="1" causality="parameter" start="2.0 2.0 2.0 3.0 3.0 3.0">
<Float64 name="x" valueReference="1" causality="parameter" start="2 2 2 3 3 3">
<Dimension start="6"/>
</Float64>
<Float64 name="y" valueReference="2" causality="parameter" start="10.0 25.0 30.0 10.0 25.0 30.0">
<Float64 name="y" valueReference="2" causality="parameter" start="10 25 30 10 25 30">
<Dimension start="6"/>
</Float64>
<Float64 name="v" valueReference="3" causality="parameter" start="11.0 12.0 13.0 21.0 22.0 23.0">
<Float64 name="v" valueReference="3" causality="parameter" start="11 12 13 21 22 23">
<Dimension start="6"/>
</Float64>
<Int64 name="InterpolationOrder" valueReference="4" causality="parameter" start="1" />
<Float64 name="in_x" valueReference="5" causality="input" start="2.0"/>
<Float64 name="in_y" valueReference="6" causality="input" start="10.0"/>
<Float64 name="out_v" valueReference="10" causality="local" />
<Int64 name="InterpolationOrder" valueReference="4" causality="parameter" start="1"/>
<Float64 name="in_x" valueReference="5" causality="input" start="2"/>
<Float64 name="in_y" valueReference="6" causality="input" start="10"/>
<Float64 name="out_v" valueReference="10" causality="local"/>
<!-- end::variables[] -->
</ModelVariables>
<ModelStructure>
Expand Down
14 changes: 7 additions & 7 deletions docs/examples/irregular2d_terminalsAndIcons.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
<fmiTerminalsAndIcons fmiVersion="3.0">
<Terminals>
<Terminal name="points" terminalKind="org.fmi-standard.fmi-ls-struct.map.irregular" matchingRule="org.fmi-standard.fmi-ls-struct.map">
<TerminalMemberVariable variableName="x" memberName="x" variableKind="org.fmi-standard.fmi-ls-struct.map.domain" />
<TerminalMemberVariable variableName="in_x" memberName="in_x" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput" />
<TerminalMemberVariable variableName="y" memberName="y" variableKind="org.fmi-standard.fmi-ls-struct.map.domain" />
<TerminalMemberVariable variableName="in_y" memberName="in_y" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput" />
<TerminalMemberVariable variableName="v" memberName="v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain" />
<TerminalMemberVariable variableName="out_v" memberName="out_v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomainOutput" />
<TerminalMemberVariable variableName="x" memberName="x" variableKind="org.fmi-standard.fmi-ls-struct.map.domain"/>
<TerminalMemberVariable variableName="in_x" memberName="in_x" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput"/>
<TerminalMemberVariable variableName="y" memberName="y" variableKind="org.fmi-standard.fmi-ls-struct.map.domain"/>
<TerminalMemberVariable variableName="in_y" memberName="in_y" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput"/>
<TerminalMemberVariable variableName="v" memberName="v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain"/>
<TerminalMemberVariable variableName="out_v" memberName="out_v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomainOutput"/>
<!-- Example of an additional related variable -->
<TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related" />
<TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related"/>
</Terminal>
</Terminals>
</fmiTerminalsAndIcons>
6 changes: 3 additions & 3 deletions docs/examples/irregular3d_modelDescription.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@
<Float64 name="v2" valueReference="5" causality="parameter" start="1 4 3">
<Dimension start="3"/>
</Float64>
<Int64 name="InterpolationOrder" valueReference="6" causality="parameter" start="1" />
<Int64 name="InterpolationOrder" valueReference="6" causality="parameter" start="1"/>
<Float64 name="in_x" valueReference="7" causality="input" start="2"/>
<Float64 name="in_z" valueReference="8" causality="local" />
<Float64 name="out_v2" valueReference="10" causality="local" />
<Float64 name="in_z" valueReference="8" causality="local"/>
<Float64 name="out_v2" valueReference="10" causality="local"/>
<!-- end::variables[] -->
</ModelVariables>
<ModelStructure>
Expand Down
18 changes: 9 additions & 9 deletions docs/examples/irregular3d_terminalsAndIcons.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,18 @@
<fmiTerminalsAndIcons fmiVersion="3.0">
<Terminals>
<Terminal name="points" terminalKind="org.fmi-standard.fmi-ls-struct.map.irregular" matchingRule="org.fmi-standard.fmi-ls-struct.map">
<TerminalMemberVariable variableName="x" memberName="x" variableKind="org.fmi-standard.fmi-ls-struct.map.domain" />
<TerminalMemberVariable variableName="in_x" memberName="OpPoint_x" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput" />
<TerminalMemberVariable variableName="y" memberName="y" variableKind="org.fmi-standard.fmi-ls-struct.map.domain" />
<TerminalMemberVariable variableName="x" memberName="x" variableKind="org.fmi-standard.fmi-ls-struct.map.domain"/>
<TerminalMemberVariable variableName="in_x" memberName="OpPoint_x" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput"/>
<TerminalMemberVariable variableName="y" memberName="y" variableKind="org.fmi-standard.fmi-ls-struct.map.domain"/>
<!-- Optional domainInput for y is omitted intentionally in this example -->
<TerminalMemberVariable variableName="z" memberName="z" variableKind="org.fmi-standard.fmi-ls-struct.map.domain" />
<TerminalMemberVariable variableName="in_z" memberName="OpPoint_z" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput" />
<TerminalMemberVariable variableName="v1" memberName="v1" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain" />
<TerminalMemberVariable variableName="z" memberName="z" variableKind="org.fmi-standard.fmi-ls-struct.map.domain"/>
<TerminalMemberVariable variableName="in_z" memberName="OpPoint_z" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput"/>
<TerminalMemberVariable variableName="v1" memberName="v1" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain"/>
<!-- Optional codomainOutput for v1 is omitted intentionally in this example -->
<TerminalMemberVariable variableName="v2" memberName="v2" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain" />
<TerminalMemberVariable variableName="out_v2" memberName="result_2" variableKind="org.fmi-standard.fmi-ls-struct.map.codomainOutput" />
<TerminalMemberVariable variableName="v2" memberName="v2" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain"/>
<TerminalMemberVariable variableName="out_v2" memberName="result_2" variableKind="org.fmi-standard.fmi-ls-struct.map.codomainOutput"/>
<!-- Example of an additional related variable -->
<TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related" />
<TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related"/>
</Terminal>
</Terminals>
</fmiTerminalsAndIcons>
6 changes: 3 additions & 3 deletions docs/examples/modelDescription.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,10 @@
<Dimension start="2"/>
<Dimension start="3"/>
</Float64>
<Int64 name="InterpolationOrder" valueReference="9" causality="parameter" start="1" />
<Int64 name="InterpolationOrder" valueReference="9" causality="parameter" start="1"/>
<Float64 name="in_x" valueReference="6" causality="input" start="2"/>
<Float64 name="in_y" valueReference="7" causality="local" />
<Float64 name="out_v" valueReference="8" causality="local" />
<Float64 name="in_y" valueReference="7" causality="local"/>
<Float64 name="out_v" valueReference="8" causality="local"/>
<!-- end::variables[] -->
</ModelVariables>
<ModelStructure>
Expand Down
14 changes: 7 additions & 7 deletions docs/examples/terminalsAndIcons.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
<fmiTerminalsAndIcons fmiVersion="3.0">
<Terminals>
<Terminal name="map2d" terminalKind="org.fmi-standard.fmi-ls-struct.map.rectilinearGrid" matchingRule="org.fmi-standard.fmi-ls-struct.map">
<TerminalMemberVariable variableName="x" memberName="x" variableKind="org.fmi-standard.fmi-ls-struct.map.domain" />
<TerminalMemberVariable variableName="in_x" memberName="in_x" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput" />
<TerminalMemberVariable variableName="y" memberName="y" variableKind="org.fmi-standard.fmi-ls-struct.map.domain" />
<TerminalMemberVariable variableName="in_y" memberName="in_y" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput" />
<TerminalMemberVariable variableName="v" memberName="v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain" />
<TerminalMemberVariable variableName="out_v" memberName="out_v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomainOutput" />
<TerminalMemberVariable variableName="x" memberName="x" variableKind="org.fmi-standard.fmi-ls-struct.map.domain"/>
<TerminalMemberVariable variableName="in_x" memberName="in_x" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput"/>
<TerminalMemberVariable variableName="y" memberName="y" variableKind="org.fmi-standard.fmi-ls-struct.map.domain"/>
<TerminalMemberVariable variableName="in_y" memberName="in_y" variableKind="org.fmi-standard.fmi-ls-struct.map.domainInput"/>
<TerminalMemberVariable variableName="v" memberName="v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomain"/>
<TerminalMemberVariable variableName="out_v" memberName="out_v" variableKind="org.fmi-standard.fmi-ls-struct.map.codomainOutput"/>
<!-- Example of an additional related variable -->
<TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related" />
<TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related"/>
</Terminal>
</Terminals>
</fmiTerminalsAndIcons>
29 changes: 15 additions & 14 deletions docs/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ The licenses text can be found in the link:LICENSE.txt[LICENSE.txt] file that ac

=== Motivation

For many use cases, the grouping of variables gives the user a better overview about the usage of variables. For certain groupings the importing tool might be able to provide a more user-friendly interface.
For many use cases, the grouping of variables gives the user a better overview of the usage of variables.
For certain groupings the importing tool might be able to provide a more user-friendly interface.
FMUs might use maps/functions sampled on the vertices of a grid to calculate output values.
The values at these sampling points and even the locations of the sampling points might get exposed as parameter variables of the FMU to allow calibrations.
However, the FMI standard only defines n-dimensional array variables but doesn't define any relation between these variables.
Expand Down Expand Up @@ -60,7 +61,7 @@ NOTE: Especially examples are defined in this style.
The concept of this layered standard can be summarized as follows:

* In `modelDescription.xml`, an FMU defines the variables that represent domain sampling points and codomain values.
* In `TerminalsAndIcons.xml`, these variables are grouped in https://fmi-standard.org/docs/3.0/#fmiTerminalsAndIcons[Terminals] using:
* In `terminalsAndIcons/terminalsAndIcons.xml`, these variables are grouped in https://fmi-standard.org/docs/3.0/#fmiTerminalsAndIcons[Terminals] using:
** `terminalKind` to describe the map type (for example rectilinear grid or irregular grid),
** `variableKind` to label each terminal member (`domain`, `domainInput`, `codomain`, `codomainOutput`), and
** `matchingRule` to describe how map terminals could connected.
Expand All @@ -69,7 +70,7 @@ The concept of this layered standard can be summarized as follows:

== Layered Standard Manifest File

The manifest file signals to the importer that the FMU supports this layered standard and enables the interpretation of the `TerminalsAndIcons.xml` file in the intended way.
The manifest file signals to the importer that the FMU supports this layered standard and enables the interpretation of the `terminalsAndIcons/terminalsAndIcons.xml` file in the intended way.

<<table-schema-fmi-ls-struct-attributes>> shows the content of `fmi-ls-manifest.xml`.

Expand Down Expand Up @@ -113,9 +114,9 @@ The manifest file shall be stored inside the FMU at the following path: `/extra/

=== Definitions

n-d lookup table::
In the context of this layered standard, an n-d lookup table is a sampled representation of an m-valued function of n input variables latexmath:[(y_1, y_2, \dots, y_m) = F(x_1, x_2, x_3, \dots, x_n)], sampled on points of the n-dimensional domain.
Such an n-d lookup table could be also called a map from the n-dimensional domain to an m-dimensional codomain.
n-dimensional lookup table::
In the context of this layered standard, an n-dimensional lookup table is a sampled representation of an m-valued function of n input variables latexmath:[(y_1, y_2, \dots, y_m) = F(x_1, x_2, x_3, \dots, x_n)], sampled on points of the n-dimensional domain.
Such an n-dimensional lookup table could be also called a map from the n-dimensional domain to an m-dimensional codomain.

Each lookup table is represented by a terminal with FMI variables that represent the sampling points of the domain and the sampled values of the codomain.

Expand All @@ -140,7 +141,7 @@ Optionally, for each `domain` variable at most one variable can be referenced th
The `causality` of such a variable can be `input`, `output` or `local` (i.e. the operating point may be provided externally, computed internally, or exposed as an observable). +
If present, this variable must be listed directly after the corresponding domain variable. +
The `domainInput` variable is not required to be a scalar; it may have multiple dimensions.
However the size of each `domainInput` variable must be the same for each domain: For nonscalar inputs latexmath:[v=[v_1,\dots,v_K\], w=[w_1, \dots, w_K\], \dots] the function is evaluated element-wise and we get an output vector latexmath:[z=[f(v_1, w_1, \dots), \dots, f(v_K, w_K, \dots)]].
However the size of each `domainInput` variable must be the same for each domain: for nonscalar inputs latexmath:[v=[v_1,\dots,v_K\], w=[w_1, \dots, w_K\], \dots] the function is evaluated element-wise and we get an output vector latexmath:[z=[f(v_1, w_1, \dots), \dots, f(v_K, w_K, \dots)]].
The indices latexmath:[1, \dots, K] are the serialization indices of the nonscalar input variable and latexmath:[K] is the product of dimension sizes.
These indices are not related to the indices of the domain arrays. +
The data type of a `domainInput` variable shall be identical to the data type of the corresponding `domain` variable.
Expand Down Expand Up @@ -185,14 +186,14 @@ Tools may use them for user interface support or algorithm configuration, but th
=== Structure of the FMU archive

This layered standard uses the "Terminals and Icons" mechanism of FMI 3.0.
All information is stored in the `TerminalsAndIcons.xml` file in the TerminalsAndIcons folder of an FMU.
All information is stored in the `terminalsAndIcons/terminalsAndIcons.xml` file of an FMU.

== Maps sampled on rectilinear grids

=== Definitions

n-d lookup table on a rectilinear grid::
In the context of this layered standard, an n-d lookup table on a rectilinear grid is a sampled representation of a function of n input variables latexmath:[y=F(x_1, x_2, x_3, \dots, x_n)] sampled on the vertices of a rectilinear grid.
n-dimensional lookup table on a rectilinear grid::
In the context of this layered standard, an n-dimensional lookup table on a rectilinear grid is a sampled representation of a function of n input variables latexmath:[y=F(x_1, x_2, x_3, \dots, x_n)] sampled on the vertices of a rectilinear grid.
+
NOTE: In <<ASAM-MCD2>>, such a 1-d lookup table is called a *CURVE*, a 2-d lookup table is called *MAP*, and a 3-d lookup table is called *CUBOID*.
4-d and 5-d lookup tables are called *CUBE_4* and *CUBE_5*, respectively. Higher dimensional lookup tables are not defined in <<ASAM-MCD2>>.
Expand Down Expand Up @@ -227,7 +228,7 @@ include::examples/modelDescription.xml[tags=variables]
<!-- ... -->
----

These variables are grouped in a terminal with the terminalKind `org.fmi-standard.fmi-ls-struct.map.rectilinearGrid` in the `TerminalsAndIcons.xml` file:
These variables are grouped in a terminal with the terminalKind `org.fmi-standard.fmi-ls-struct.map.rectilinearGrid` in the `terminalsAndIcons/terminalsAndIcons.xml` file:

[source, xml]
----
Expand All @@ -242,8 +243,8 @@ Compared to rectilinear maps, irregular maps are more general because they can d

=== Definitions

n-d lookup table on an irregular grid::
In the context of this layered standard, an n-d lookup table on an irregular grid is a sampled representation of a function of n input variables latexmath:[y=F(x_1, x_2, x_3, \dots, x_n)] sampled on arbitrarily chosen points of the domain.
n-dimensional lookup table on an irregular grid::
In the context of this layered standard, an n-dimensional lookup table on an irregular grid is a sampled representation of a function of n input variables latexmath:[y=F(x_1, x_2, x_3, \dots, x_n)] sampled on arbitrarily chosen points of the domain.

terminalKind::
A terminal with `terminalKind="org.fmi-standard.fmi-ls-struct.map.irregular"` defines a map on the vertices of an irregular grid.
Expand All @@ -259,7 +260,7 @@ and codomain arrays latexmath:[u=[u_1, u_2, \dots, u_N\], v=[v_1, v_2, \dots, v_

NOTE: A map on a 1-dimensional domain can be equivalently represented by a terminal of `terminalKind="org.fmi-standard.fmi-ls-struct.map.irregular"` or a terminal with `terminalKind="org.fmi-standard.fmi-ls-struct.map.rectilinearGrid"`.

NOTE: Any n-d lookup table that can be described with `terminalKind="org.fmi-standard.fmi-ls-struct.map.rectilinearGrid"` can also be represented by an n-d lookup table with `terminalKind="org.fmi-standard.fmi-ls-struct.map.irregular"`.
NOTE: Any n-dimensional lookup table that can be described with `terminalKind="org.fmi-standard.fmi-ls-struct.map.rectilinearGrid"` can also be represented by an n-dimensional lookup table with `terminalKind="org.fmi-standard.fmi-ls-struct.map.irregular"`.

NOTE: The reverse is not true in general. An irregular map can only be represented as `terminalKind="org.fmi-standard.fmi-ls-struct.map.rectilinearGrid"` if its sampled domain points form a complete Cartesian product of per-dimension sampling vectors.

Expand Down
Loading