From e7412c3aa6e418fdfbc81b54dffe6618bedd5a6d Mon Sep 17 00:00:00 2001 From: Torsten Sommer Date: Thu, 25 Jun 2026 10:23:06 +0200 Subject: [PATCH 1/4] Improve language --- docs/index.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/index.adoc b/docs/index.adoc index 773031c..978f634 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -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. @@ -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. From f311ae644dcae23dc1469a58d0bc125953df185b Mon Sep 17 00:00:00 2001 From: Torsten Sommer Date: Thu, 25 Jun 2026 10:24:13 +0200 Subject: [PATCH 2/4] Use full path to terminalsAndIcons.xml --- docs/index.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/index.adoc b/docs/index.adoc index 978f634..dc50e0b 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -61,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. @@ -70,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. <> shows the content of `fmi-ls-manifest.xml`. @@ -186,7 +186,7 @@ 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 @@ -228,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] ---- From 997256fdf48c2847dbc070152f19730e867be96c Mon Sep 17 00:00:00 2001 From: Torsten Sommer Date: Thu, 25 Jun 2026 10:32:54 +0200 Subject: [PATCH 3/4] Use d-dimensional consistently --- docs/index.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/index.adoc b/docs/index.adoc index dc50e0b..30dedd3 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -114,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. @@ -192,8 +192,8 @@ All information is stored in the `terminalsAndIcons/terminalsAndIcons.xml` file === 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 <>, 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 <>. @@ -243,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. @@ -260,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. From 9baf03e04b6c47afdebd63b004f8cdb8044569aa Mon Sep 17 00:00:00 2001 From: Torsten Sommer Date: Thu, 25 Jun 2026 10:50:37 +0200 Subject: [PATCH 4/4] Clean up example XMLs --- docs/examples/irregular2d_modelDescription.xml | 14 +++++++------- .../examples/irregular2d_terminalsAndIcons.xml | 14 +++++++------- docs/examples/irregular3d_modelDescription.xml | 6 +++--- .../examples/irregular3d_terminalsAndIcons.xml | 18 +++++++++--------- docs/examples/modelDescription.xml | 6 +++--- docs/examples/terminalsAndIcons.xml | 14 +++++++------- 6 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/examples/irregular2d_modelDescription.xml b/docs/examples/irregular2d_modelDescription.xml index 3863aef..06f8b9b 100644 --- a/docs/examples/irregular2d_modelDescription.xml +++ b/docs/examples/irregular2d_modelDescription.xml @@ -4,19 +4,19 @@ - + - + - + - - - - + + + + diff --git a/docs/examples/irregular2d_terminalsAndIcons.xml b/docs/examples/irregular2d_terminalsAndIcons.xml index 50d3ea7..acc04f1 100644 --- a/docs/examples/irregular2d_terminalsAndIcons.xml +++ b/docs/examples/irregular2d_terminalsAndIcons.xml @@ -2,14 +2,14 @@ - - - - - - + + + + + + - + diff --git a/docs/examples/irregular3d_modelDescription.xml b/docs/examples/irregular3d_modelDescription.xml index af7aa61..a28f124 100644 --- a/docs/examples/irregular3d_modelDescription.xml +++ b/docs/examples/irregular3d_modelDescription.xml @@ -19,10 +19,10 @@ - + - - + + diff --git a/docs/examples/irregular3d_terminalsAndIcons.xml b/docs/examples/irregular3d_terminalsAndIcons.xml index 660b5b8..e1de073 100644 --- a/docs/examples/irregular3d_terminalsAndIcons.xml +++ b/docs/examples/irregular3d_terminalsAndIcons.xml @@ -2,18 +2,18 @@ - - - + + + - - - + + + - - + + - + diff --git a/docs/examples/modelDescription.xml b/docs/examples/modelDescription.xml index 0120bb7..2829503 100644 --- a/docs/examples/modelDescription.xml +++ b/docs/examples/modelDescription.xml @@ -14,10 +14,10 @@ - + - - + + diff --git a/docs/examples/terminalsAndIcons.xml b/docs/examples/terminalsAndIcons.xml index f8dd649..4495041 100644 --- a/docs/examples/terminalsAndIcons.xml +++ b/docs/examples/terminalsAndIcons.xml @@ -2,14 +2,14 @@ - - - - - - + + + + + + - +