FMI Layered Standard for Structured Data (FMI-LS-STRUCT)

Based on FMI 3.0, this layered standard defines how variables (especially parameters) of an FMU can be structured and grouped in a more flexible way than with the "structured naming convention" of the FMI Standard. The first version of this layered standard is focused on the definition of sampled maps.

This document is licensed under the Attribution-ShareAlike 4.0 International license. The code is released under the 2-Clause BSD License. The licenses text can be found in the LICENSE.txt file that accompanies this distribution.

1. Introduction

1.1. 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. 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. This layered standard defines how to group variables to represent maps.

This layered standard uses terminals of the FMI 3.0 standard to represent structures like maps by grouping variables in terminals. Terminals are used to group variables and already define means to connect its member variables between FMUs. Such a connection could ensure that the same map values are used by different FMUs or allow one FMU to provide the map values to be used by other FMUs.

1.2. How to Read This Document

The standard document is in HTML allowing use of in-document links. By pressing "t", the table of contents can be displayed on the left side or hidden.

In key parts of this document, non-normative examples are used to help understand the standard.

Conventions used in this document:

Non-normative text is given like this:

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 RFC 2119 (regardless of formatting and capitalization).

1.3. Rough Outline of the Approach

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 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.
Importing tools read the manifest and terminal metadata to provide map-aware handling (for example map-oriented grouping/visualization of variables and ).

2. 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.

Table 1 shows the content of fmi-ls-manifest.xml.

Table 1. `fmiLayeredStandardManifest` attribute details.
Attribute	Namespace	Value	Description
`fmi-ls-name`	`http://fmi-standard.org/fmi-ls-manifest`	`org.fmi-standard.fmi-ls-struct`	Name of the layered standard in reverse domain name notation.
`fmi-ls-version`	`http://fmi-standard.org/fmi-ls-manifest`	`1.0.0-beta.1`	Version of the layered standard. This layered standard uses semantic versioning, as defined in [PW13].
`fmi-ls-description`	`http://fmi-standard.org/fmi-ls-manifest`	`Layered standard for structuring of variables`	String with a brief description of the layered standard that is suitable for display to users.

An example of a manifest file for this layered standard is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<fmiLayeredStandardManifest
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/modelica/fmi-ls-struct/v1.0.0-beta.1/schema/fmi3LayeredStandardStructManifest.xsd"

	xmlns:fmi-ls="http://fmi-standard.org/fmi-ls-manifest"
	fmi-ls:fmi-ls-name="org.fmi-standard.fmi-ls-struct"
	fmi-ls:fmi-ls-version="1.0.0-beta.1"
	fmi-ls:fmi-ls-description="Layered standard for structuring of variables"/>

The manifest file shall be stored inside the FMU at the following path: /extra/org.fmi-standard.fmi-ls-struct/fmi-ls-manifest.xml.

3. Common concepts for the representation of maps

3.1. 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 \((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.

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.

3.1.1. `terminalKind` attribute values

org.fmi-standard.fmi-ls-struct.map.rectilinearGrid: for maps sampled on the vertices of a rectilinear grid.
org.fmi-standard.fmi-ls-struct.map.irregular: for maps sampled on the vertices of an irregular grid ("point cloud").

3.1.2. `variableKind` attribute values of terminal member variables

We want to represent a sampled map from a domain set to a codomain by providing sampled points in the domain set and the values they are mapped to.

org.fmi-standard.fmi-ls-struct.map.domain

For each of the n dimensions of the domain set, a 1-dimensional array variable containing the coordinates (along this dimension) is provided.
The causality of such a variable is parameter if the sampling points are meant to be changed after the FMU is created, and constant otherwise.

org.fmi-standard.fmi-ls-struct.map.domainInput

Optionally, for each domain variable at most one variable can be referenced that represents the current operating point (along this dimension). 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 \(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 \(z=[f(v_1, w_1, \dots), \dots, f(v_K, w_K, \dots)\)]. The indices \(1, \dots, K\) are the serialization indices of the nonscalar input variable and \(K\) is the product of dimension sizes. These indices are not related to the indices of the domain arrays.

org.fmi-standard.fmi-ls-struct.map.codomain

For each of the represented points in the domain set, the values to which they are mapped are provided. The shape of this variable is grid-type-specific: for a rectilinear grid it is an n-dimensional array (one dimension per domain axis), while for an irregular grid it is a 1-dimensional array (one entry per sample point).

There can be multiple terminal member variables with variableKind codomain to represent multiple maps in one terminal.

org.fmi-standard.fmi-ls-struct.map.codomainOutput

Optionally, for each codomain variable at most one array variable can be referenced that represents the calculated output value of the map.
The causality of such a variable can be output or local, since it represents a value computed from the map and cannot be driven from outside the FMU.
If present, a codomainOutput variable must be listed directly after the corresponding codomain variable.

Additional terminal member variables can be added to the terminal as related variables but if they do not fit into one of the above categories, they shall not have a variableKind starting with org.fmi-standard.fmi-ls-struct.

3.1.3. Map-specific `matchingRule`

The matching rule org.fmi-standard.fmi-ls-struct.map should be used for terminals that represent maps.

Requirements for matching:

The number of domain variables must be the same.
The terminal member names, their data types and the (effective) sizes of all domains (variableKind=org.fmi-standard.fmi-ls-struct.map.domain) must match.
If all domains match, connect all these domains.
Connect all codomains (variableKind=org.fmi-standard.fmi-ls-struct.map.codomain) that match.
Do not connect any other terminal member variables.

This indicates that the variableKind of the member must be considered for the connection of the individual members of the terminal.

Related variables are not considered by the map matching rule. Tools may use them for user interface support or algorithm configuration, but they should not be required for map compatibility.

3.2. Structure of the FMU archive

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

4. Maps sampled on rectilinear grids

4.1. 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 \(y=F(x_1, x_2, x_3, \dots, x_n)\) sampled on the vertices of a rectilinear grid.

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].

terminalKind

A terminal with terminalKind="org.fmi-standard.fmi-ls-struct.map.rectilinearGrid" defines a map on the vertices of a rectilinear grid.

domain

For each of the n dimensions of the lookup table, a 1-dimensional array variable (typically a parameter or a constant) containing the sampling points (along this dimension) of the lookup table must be referenced with variableKind="org.fmi-standard.fmi-ls-struct.map.domain".

codomain

For each of the m dimensions of the codomain, the sampled function values (along this dimension of the codomain) are stored in this n-dimensional array variable and referenced with variableKind="org.fmi-standard.fmi-ls-struct.map.codomain".

The length of the i-th domain vector must be equal to length of the i-th codomain dimension.

This layered standard doesn’t define how maps have to be represented in a GUI. In particular, the standard doesn’t define if the first dimension is displayed as columns or rows. However, for the example lookup tables of this document, the sampling points of the first dimension of the domain are shown as a column vector, and the values of the second dimension are shown as a row vector.

4.2. 2-d example of a lookup table on a rectilinear grid

v		y
v		10.0	25.0	30.0
x	2.0	11.0	12.0	13.0
x	3.0	21.0	22.0	23.0

The individual variables of the example 2-dimensional map on a rectilinear grid are given in the modelDescription.xml.

...
<Float64 name="x" valueReference="1" causality="parameter" start="2.0 3.0">
  <Dimension start="2"/>
</Float64>
<Float64 name="y" valueReference="2" causality="parameter" start="10.0 25.0 30.0">
  <Dimension start="3"/>
</Float64>
<Float64 name="v" valueReference="3" causality="parameter" start="11.0 12.0 13.0 21.0 22.0 23.0">
  <Dimension start="2"/>
  <Dimension start="3"/>
</Float64>
<Int64 name="InterpolationOrder" valueReference="9" causality="parameter" start="1" />
<Float64 name="in_x" valueReference="6" causality="input" start="2.0"/>
<Float64 name="in_y" valueReference="7" causality="local" />
<Float64 name="out_v" valueReference="8" causality="local" />
...

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

<?xml version="1.0" encoding="UTF-8"?>
<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" />
      <!-- Example of an additional related variable -->
      <TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related" />
    </Terminal>
  </Terminals>
</fmiTerminalsAndIcons>

5. Maps sampled on irregular grids ("Point Cloud")

Irregular maps represent sampled functions at explicitly listed domain points. This representation is intended for data sets that do not lie on a complete rectilinear grid, for example measurements whose sample points do not form a complete Cartesian product of per-dimension sampling vectors, or sparse calibration points. Compared to rectilinear maps, irregular maps are more general because they can describe arbitrary point clouds; however, they do not implicitly provide per-dimension grid structure.

5.1. 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 \(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.
domain: For each of the n dimensions of the lookup table, a 1-dimensional array variable (typically a parameter or a constant) containing the sampling points (along this dimension) of the lookup table must be referenced with variableKind="org.fmi-standard.fmi-ls-struct.map.domain".
codomain: For each of the m dimensions of the codomain of the lookup table, a 1-dimensional array variable containing the sampling values of the lookup table must be referenced with variableKind="org.fmi-standard.fmi-ls-struct.map.codomain".

For domain arrays \(x=[x_1, x_2, \dots, x_N], y=[y_1, y_2, \dots, y_N], z=[z_1, z_2, \dots, z_N], \dots\) and codomain arrays \(u=[u_1, u_2, \dots, u_N], v=[v_1, v_2, \dots, v_N], \dots\), each sample index \(i \in \{1, \dots, N\}\) maps the tuple \((x_i, y_i, z_i, \dots)\) to the values \((u_i, v_i, \dots)\).

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".

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".

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.

5.2. 3-d example of a lookup table on an irregular grid

The lookup table is sampled at 3 different points of the domain (2, 10, 10), (3, 25, 28) and (10, 30, 30) with the values (11, 1), (1, 4) and (13, 3) on the 2-dimensional codomain.

x	y	z	v1	v2
2.0	10.0	10.0	11.0	1.0
3.0	25.0	28.0	1.0	4.0
10.0	30.0	30.0	13.0	3.0

<?xml version="1.0" encoding="UTF-8"?>
<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" />
      <!-- 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" />
      <!-- 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" />
      <!-- Example of an additional related variable -->
      <TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related" />
    </Terminal>
  </Terminals>
</fmiTerminalsAndIcons>

...
<Float64 name="x" valueReference="1" causality="parameter" start="2.0 3.0 10.0">
  <Dimension start="3"/>
</Float64>
<Float64 name="y" valueReference="2" causality="parameter" start="10.0 25.0 30.0">
  <Dimension start="3"/>
</Float64>
<Float64 name="z" valueReference="3" causality="parameter" start="10.0 28.0 30.0">
  <Dimension start="3"/>
</Float64>
<Float64 name="v1" valueReference="4" causality="parameter" start="11.0 1.0 13.0">
  <Dimension start="3"/>
</Float64>
<Float64 name="v2" valueReference="5" causality="parameter" start="1.0 4.0 3.0">
  <Dimension start="3"/>
</Float64>
<Int64 name="InterpolationOrder" valueReference="6" causality="parameter" start="1" />
<Float64 name="in_x" valueReference="7" causality="input" start="2.0"/>
<Float64 name="in_z" valueReference="8" causality="local" />
<Float64 name="out_v2" valueReference="10" causality="local" />
...

5.3. 2-d example of a lookup table on an irregular grid which could be represented with a rectilinear grid

The previous 2-d rectilinear grid example with 2 sampling points in the x dimension and 3 sampling points in the y dimension

v		y
v		10.0	25.0	30.0
x	2.0	11.0	12.0	13.0
x	3.0	21.0	22.0	23.0

can be represented as a lookup table on an irregular grid with the same 6 sampling points:

x	y	v
2.0	10.0	11.0
2.0	25.0	12.0
2.0	30.0	13.0
3.0	10.0	21.0
3.0	25.0	22.0
3.0	30.0	23.0

<?xml version="1.0" encoding="UTF-8"?>
<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" />
      <!-- Example of an additional related variable -->
      <TerminalMemberVariable variableName="InterpolationOrder" memberName="InterpolationOrder" variableKind="com.example.related" />
    </Terminal>
  </Terminals>
</fmiTerminalsAndIcons>

...
<Float64 name="x" valueReference="1" causality="parameter" start="2.0 2.0 2.0 3.0 3.0 3.0">
  <Dimension start="6"/>
</Float64>
<Float64 name="y" valueReference="2" causality="parameter" start="10.0 25.0 30.0 10.0 25.0 30.0">
  <Dimension start="6"/>
</Float64>
<Float64 name="v" valueReference="3" causality="parameter" start="11.0 12.0 13.0 21.0 22.0 23.0">
  <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" />
...

6. Known Limitations of This Standard

General limitations:

todo

References

[PW13] Preston-Werner, T. (2013): Semantic Versioning 2.0.0. https://semver.org/spec/v2.0.0.html
[ASAM-MCD2] ASAM e.V. (2018) ASAM MCD-2 MC (aka ASAP2) v1.7.1. https://www.asam.net/standards/detail/mcd-2-mc/