diff --git a/docs/index.adoc b/docs/index.adoc index 200853c..667dcde 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -1,4 +1,4 @@ -= Layered Standard for Structured Data += FMI Layered Standard for Structured Data (FMI-LS-STRUCT) :doctype: book :imagesdir: images :sectnums: @@ -36,7 +36,7 @@ The licenses text can be found in the https://raw.githubusercontent.com/modelica 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 variable 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 variables between FMUs. Such a connections 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. +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 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. === How to Read This Document @@ -104,39 +104,45 @@ 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. +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. +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. ==== Definition of `terminalKind` attribute values `org.fmi-standard.fmi-ls-struct.map.rectilinearGrid`:: -for maps defined on the vertices of a rectilinear grid. +for maps sampled on the vertices of a rectilinear grid. `org.fmi-standard.fmi-ls-struct.map.irregular`:: -for maps defined by unstructured tuples of ("point cloud"). +for maps sampled on the vertices of an irregular grid ("point cloud"). ==== `variableKind` attribute values of terminal member variables: -We want to represent a map from a domain set to a codomain by providing points in the domain set and the values they are mapped to. +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 (typically a parameter or a constant) of coordinates (along this dimension) is provided. +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 grid is meant to be changed after the the FMU got created. `org.fmi-standard.fmi-ls-struct.map.domainInput`:: -Optionally, for each `domain` variable at most one variable (typically an input or a local variable) can be referenced that represents the current operating point (along this dimension). -If present, this variable must be listed directly after the corresponding domain. +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`. + +If present, this variable must be listed directly after the corresponding domain variable. + The domain_input isn't required to be a scalar, it could be variable with several dimensions. -However the size of each `domainInput` must be the same for each domain: For nonscalar inputs latexmath:[v=[v_1,\dots,v_n\], w=[w_1, \dots, w_n\], \dots] the function is evaluated element-wise and we get an output vector latexmath:[z=[f(v_1, w_1, \dots), \dots, f(v_n, w_n, \dots)]]. +However the size of each `domainInput` variable must be the same for each domain: For nonscalar inputs latexmath:[v=[v_1,\dots,v_n\], w=[w_1, \dots, w_n\], \dots] the function is evaluated element-wise and we get an output vector latexmath:[z=[f(v_1, w_1, \dots), \dots, f(v_n, w_n, \dots)]]. +Note: The indices latexmath:[1, \dots, n] are the serialization indices of the nonscaler input variable and n 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 represented. _[There can be multiple terminal member variables with `variableKind` `codomain` to represent multiple maps in one terminal.]_ -`org.fmi-standard.fmi-ls-struct.map.domainOutput`:: -Optionally, for each `domain` variable at most one array variable (typically an output or a local variable) can be referenced that represents calculated output value of the map. -If present, a `domainOutput` variable must be listed directly after the corresponding `codomain` variable. +`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`. + +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`. @@ -147,11 +153,11 @@ The matching rule `org.fmi-standard.fmi-ls-struct.map` should be used for termin Requirements for matching: -* The number of domain entries must be the same. -* The terminal member names, its data types and the (effective) size and of all domains (`variableKind=org.fmi-standard.fmi-ls-struct.map.domain`) must match. +* The number of domain variables must be the same. +* The terminal member names, its 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. -* Don't connect any other terminal member variables. +* 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.]_