From ca5f9d6f5885f471e2b68088b91d9719d3ae039f Mon Sep 17 00:00:00 2001 From: Torsten Sommer Date: Tue, 10 Mar 2020 21:04:35 -0700 Subject: [PATCH] Add element to model variables (#834) solves #807 --- .circleci/validate_xml.py | 1 + docs/2_1_common_api.adoc | 2 -- docs/2_2_common_schema.adoc | 51 +++++++++--------------------- docs/examples/alias_example.xml | 19 +++++++++++ schema/fmi3Variable.xsd | 56 ++++++++++++++++++++++++++++++++- 5 files changed, 90 insertions(+), 39 deletions(-) create mode 100644 docs/examples/alias_example.xml diff --git a/.circleci/validate_xml.py b/.circleci/validate_xml.py index a82848a93..28fdde4c7 100644 --- a/.circleci/validate_xml.py +++ b/.circleci/validate_xml.py @@ -7,6 +7,7 @@ parser = etree.XMLParser(schema=schema) xml_files = [ + 'alias_example.xml', 'build_configuration.xml', 'co_simulation.xml', 'model_structure_example1.xml', diff --git a/docs/2_1_common_api.adoc b/docs/2_1_common_api.adoc index 65de86334..850b30a80 100644 --- a/docs/2_1_common_api.adoc +++ b/docs/2_1_common_api.adoc @@ -347,8 +347,6 @@ Variables can be referenced in a message with `pass:[#]pass:[#]` If the character `pass:[#]` shall be included in the message, it has to be prefixed with `pass:[#]`, so `pass:[#]` is an escape character. + _[Example: The message `\#1365# must be larger than zero (used in IO channel ##4)` might be changed by the <> function to `body.m must be larger than zero (used in IO channel #4)` if `body.m` is the name of the variable with value reference 1365.]_ -+ -In case `pass:[#]pass:[#]` points to an alias set of variables, the environment is free to pick any, or all, of the variable names in the alias set to replace the <>. [[allocateMemory,`allocateMemory`]] Function `allocateMemory`:: diff --git a/docs/2_2_common_schema.adoc b/docs/2_2_common_schema.adoc index ae151ec85..807efcb83 100644 --- a/docs/2_2_common_schema.adoc +++ b/docs/2_2_common_schema.adoc @@ -608,7 +608,7 @@ _[For example, `N.m`: in this case a `Unit.name = `N.m` must be present under `U _[Note that for variables that are without a unit, the element should not have a `unit` attribute.]_ _[Giving an empty string as a `unit` attribute specifies a valid unit that needs to be defined among the unit definitions.]_ -|`displayUnit` +|[[displayUnit,`displayUnit`]] displayUnit |Default display unit. The conversion to the `unit` is defined with the element ``. If the corresponding `displayUnit` is not defined under ` `, then `displayUnit` is ignored. It is an error if `displayUnit` is defined as variable type element, but `unit` is not, or unit is not defined under ``. @@ -642,7 +642,7 @@ _where `tolerance` is, for example, the relative tolerance defined in `> variable.]_ +_This information can, for example, be used to increase numerical stability and accuracy by setting the corresponding bound for the relative error to zero (relative tolerance = 0.0), if the corresponding variable is a continuous <> variable.]_ |Item |Items of an enumeration has a sequence of `name` and `value` pairs. @@ -906,7 +906,7 @@ The normalized string `variableName` is used to identify the terminal member var _[The `name` attribute of the model variable is equal to the `variableName` of the `TerminalMemberVariable`._ _An importing tool may use the `variableName` attribute to identify a specific alias to get additional information, such as minimum, maximum, and nominal values.]_ -One variable can be part of several terminals, which is considered aliasing according to the rules of <>. +One variable can be part of several terminals. _[Tools which apply sequence based matching should also provide unique member names, so that all importing tools which use name based matching use the same member names._ @@ -1163,6 +1163,17 @@ It should be noted that changing a < It is not possible to use a variable of type `Clock` in arrays, since array elements do not have individual <> and the access to <> requires a unique <> information. +A variable can have any number of `` elements that define a variable alias. +Each variable alias has a required attribute `name` whose value must be unique among all variables and variable aliases and an optional attribute `description`. +Variable aliases of floating point variables may additionally have a <> that follows the same rules as for variables. + +Example: + +[source, xml] +---- +include::examples/alias_example.xml[tags=VariableAliases] +---- + The attributes of variables are: image::images/ScalarVariable_schema.png[width=90%, align="center"] @@ -1181,7 +1192,7 @@ Every variable is uniquely identified within an FMU instance by this name. [[valueReference,`valueReference`]] A handle of the variable to efficiently identify the variable value in the model interface and for references within the `modelDescription.xml`. This handle is a secret of the tool that generated the C functions. -It is required to be unique for an FMU with exception of variables that have identical values (such variables are also called alias variables). `Clock` type variables do not have alias variables and are therefore unique. +It is required to be unique for an FMU. This attribute is `required`. |`description` @@ -1766,38 +1777,6 @@ _FMI for Co-Simulation:_ _Changing of <> <> is allowed before an <> call (so, whenever an <> can be set with `fmi3Set{VariableType}`) and before <> is called (that is before and during *Initialization Mode*)._ _The FMU internally carries out event handling if necessary.]_ -===== Aliasing of Variables [[aliasing-of-variables]] - -Variables with the same <> are called "alias variables". -The variables that share the same <> are called "alias set". -The main purpose of alias variables is to enhance efficiency. -If two variables `a` and `b` are alias variables, then this is only allowed if the behavior of the FMU would be exactly the same if `a` and `b` were not treated as alias variables (that is, had different <>pass:[s]). -This requirement leads naturally to the following restrictions: - -. Variables `a` and `b` that can both be set with `fmi3Set{VariableType}`, or variable `a` that can be set with `fmi3Set{VariableType}` and variable `b` that is defined with <> = <>, cannot be alias variables _[since these variables are <> variables and alias means that there is a constraint equation between variables (= the values are the same), these variables are no longer <>._ + -_For example, if variables `a` and `b` have <> = <>, then the value references of `a` and `b` must be different._ -_However, if variable a has <> = <> and `b` has <> = <> and `b := a`, then `a` and `b` can have the same value reference.]_ - -. At most one variable of the same alias set of variables with <> latexmath:[\neq] <> can have a <> attribute _[since <> variables are independent initial values.]_ - -. A variable with <> = <> can only be aliased to another variable with <> = <>. -It is then required that the <> values of all aliased (constant) variables are identical. - -. All variables of the same alias set must all have either no `` element defined, or all of them must have the same `` and the same `` definitions. - -. All variables of the same alias set must have the same dimensions. - -The aliasing of variables only means that the `value` of the variables is always identical. -However, aliased variables may have different attributes, such as `min/max/nominal` values or description texts. -_[For example, if `v1`, `v2` are two alias variables with `v1 = v2` and `v1.max = 10` and `v2.max = 5`, then the FMU will trigger an error if either `v1` or `v2` becomes larger than 5.]_ - -_[The dependency definition in `fmiModelDescription.ModelStructure` is completely unrelated to the alias definition._ -_In particular, the "direct dependency" definition can be a superset of the "real" direct dependency definition, even if the alias information shows that this is too conservative._ -_For example, if it is stated that the <> `y1` depends on <> `u1` and the <> `y2` depends on <> `u2`, and `y1` is an alias to `y2`, then this definition is fine, although it can be deduced that in reality neither `y1` nor `y2` depend on any <>.]._ - -_[In case of different variability among the set of alias variables, and if that set of aliases does not contain an input or parameter, the variability should be the highest of the variables in the set, e.g. continuous > discrete > tunable > fixed._ -_If the set includes a parameter or input the aliases will have the stated variability of that parameter or input.]_ - Type specific properties are defined in the required choice element, where exactly one of the numeric types or an Enumeration must be present in the XML file: image::images/Real_Schema_large.png[width=50%, align="center"] diff --git a/docs/examples/alias_example.xml b/docs/examples/alias_example.xml new file mode 100644 index 000000000..772a734b0 --- /dev/null +++ b/docs/examples/alias_example.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + diff --git a/schema/fmi3Variable.xsd b/schema/fmi3Variable.xsd index 685662df3..4ae59ade5 100644 --- a/schema/fmi3Variable.xsd +++ b/schema/fmi3Variable.xsd @@ -39,6 +39,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -56,6 +59,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -73,6 +79,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -89,6 +98,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -105,6 +117,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -121,6 +136,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -137,6 +155,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -153,6 +174,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -169,6 +193,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -185,6 +212,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -201,6 +231,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -223,6 +256,7 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + @@ -230,6 +264,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -252,6 +289,9 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + @@ -272,11 +312,25 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + + - + + + + + + + + + + + +