Skip to content

Improve irregular grid (point cloud) section #32

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

Merged
klausschuch merged 9 commits into from
May 26, 2025
Merged

Improve irregular grid (point cloud) section #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
61ee614
Add line feeds and write n-d(imensional) consistently
klausschuch Apr 22, 2025
3a4d709
Fix CUBE_5
klausschuch Apr 22, 2025
1e4b232
Improve point cloud text
klausschuch Apr 22, 2025
f85d503
Rename example caption
klausschuch May 6, 2025
4638950
Improve 3d irregular example
klausschuch May 6, 2025
3b5c22c
Add 2d irregular grid example (representable on a rectilinear grid)
klausschuch May 6, 2025
8b76d28
Fix codomain typo
klausschuch May 6, 2025
6a72666
Minor fixes
chrbertsch May 20, 2025
f275a00
Add closing ----
klausschuch May 26, 2025
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
15 changes: 15 additions & 0 deletions docs/examples/irregular2d_modelDescription.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
...
<Float64 name="x" valueReference="1" causality="parameter" start="2.0 2.0 2.0 3.0 3.0 3.0">
<Dimension start="3"/>
</Float64>
<Float64 name="y" valueReference="2" causality="parameter" start="10.0 25.0 30.0 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="3"/>
</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" />
...
14 changes: 14 additions & 0 deletions docs/examples/irregular2d_terminalsAndIcons.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
<?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.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="interpolationOrder" memberName="interpolationOrder" variableKind="com.example.related" />
</Terminal>
</Terminals>
</fmiTerminalsAndIcons>
0 docs/examples/irregular_modelDescription.xml → ...examples/irregular3d_modelDescription.xml
View file
Open in desktop
File renamed without changes.
0 .../examples/irregular_terminalsAndIcons.xml → ...xamples/irregular3d_terminalsAndIcons.xml
View file
Open in desktop
File renamed without changes.
109 changes: 97 additions & 12 deletions docs/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,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 a 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-d lookup table::
In the context of this layered standard, an n-d lookup table is a sampled representation of a 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.


==== Definition of `terminalKind` attribute values
Expand Down Expand Up @@ -155,17 +157,19 @@ _[This indicates that the variableKind of the member must be considered for the

=== Structure of the FMU archive

This layered standard uses and extends the "Terminals and Icons Concept" of FMI 3.0. All information is stored in the TerminalsAndIcons.xml file in the TerminalsAndIcons folder of an FMU.
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.


== Maps sampled on rectilinear grids

=== Definitions

n-d lookup table on rectilinear grid:: In the context of this layered standard, an n-D lookup table 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-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.

_[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>>.]_
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.
Expand All @@ -183,7 +187,7 @@ In particular, the standard doesn't define if the first dimension is displayed a
However, for the example lookup tables of this document, the sampling points of first dimension of the domain are shown as a column vector, and the values of second dimension are shown as a row vector.]_


=== Example
=== 2-d example of a lookup table on a rectilinear grid


[[rectilinear_example]]
Expand Down Expand Up @@ -230,18 +234,30 @@ include::examples/terminalsAndIcons.xml[]

=== Definitions

Definition of domains and codomains as above.
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.

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 domains latexmath:[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 codomains latexmath:[u=[u_1, u_2, \dots, u_n\], v=[v_1, v_2, \dots, v_n\], \dots], the tuple latexmath:[(x_i, y_i, z_i, \dots)] gets mapped to the values latexmath:[(u_i, v_i, ...)].

All domains and codomains must have the same length.
All domain arrays and codomain arrays must have the same length.

_[Note: A map on a 1 dimensional domain can be equivalently represented with 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: 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"`.]_

ToDo add picture
_[Note: Any n-d lookup table that can be described with `terminalKind="org.fmi-standard.fmi-ls-struct.map.rectilinearGrid"` could be also represented by an n-d lookup table with `terminalKind="org.fmi-standard.fmi-ls-struct.map.irregular"`.]_

=== Example
=== 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.

[[irregular_example]]
[cols="1,1,1,1,1"]
Expand Down Expand Up @@ -275,15 +291,84 @@ ToDo add picture

[source, xml]
----
include::examples/irregular_terminalsAndIcons.xml[]
include::examples/irregular3d_terminalsAndIcons.xml[]
----

[source, xml]
----
include::examples/irregular_modelDescription.xml[]
include::examples/irregular3d_modelDescription.xml[]
----


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

The previous <<rectilinear_example, 2-d rectilinear grid example>> with 2 sampling points in the x dimension and 3 sampling points points in the y dimension
[[irregular_rectilinear_example]]
[cols="1,1,1,1,1"]
|====
2.2+|v
3+|y
|10.0
|25.0
|30.0

.2+|x
|2.0
|11.0
|12.0
|13.0

|3.0
|21.0
|22.0
|23.0
|====

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

[[irregular_irregular_rectilinear_example]]
[cols="1,1,1"]

|====
|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

|====

[source, xml]
----
include::examples/irregular2d_terminalsAndIcons.xml[]
----

[source, xml]
----
include::examples/irregular2d_modelDescription.xml[]
----

Copy link
Member

@otronarp otronarp May 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing a closing ---- ?

Copy link
Collaborator Author

@klausschuch klausschuch May 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks, fixed

== Known Limitations of This Standard

Expand Down