diff --git a/docs/2_1_common_api.adoc b/docs/2_1_common_api.adoc index 850b30a80..6e6d0cd6a 100644 --- a/docs/2_1_common_api.adoc +++ b/docs/2_1_common_api.adoc @@ -1177,12 +1177,10 @@ include::../headers/fmi3FunctionTypes.h[tags=GetNumberOfEventIndicators] ---- This function returns the number of event indicators. -The dependency of the number of event indicators on <> must be specified in the `ModelStructure` in the element `NumberOfEventIndicators`. -This element is optional but necessary if the number of event indicators depends on <>. -The attribute `dependencies` of this element holds a list of `valueReferences` of <> having an influence on the number of event indicators. -If the `NumberOfEventIndicators` element is not present or its <> list is empty, the number of event indicators does not depend on <>, i.e. it is constant. - -The `numberOfEventIndicators` attribute of the `fmiModelDescription` element holds the number of event indicators if all <> are unchanged, i.e. set to their <> value. +The dependency of the number of event indicators on <> is implicitly given in the `modelDescription.xml` file. +_[All event indicator variables are listed as elements `EventIndicator` in `ModelStructure`._ +_If the event indicator variable is an array variable and the `Dimension` element maps to a dependent variable than this dependent variable is a dependency for the number of event indicators.]_ +If all <> are unchanged then this dependency information can be used to calculate the initial number of states just using information given in the XML file without the need to call this C-API function. - Argument `nz` points to the `size_t` variable that will receive the number of event indicators. @@ -1197,11 +1195,10 @@ include::../headers/fmi3FunctionTypes.h[tags=GetNumberOfContinuousStates] This function returns the number of <>. The dependency of the number of states on <> is implicitly given in the `modelDescription.xml` file. -_[All state derivative variables are listed as elements `Derivative` in `ModelStrcture`._ +_[All state derivative variables are listed as elements `Derivative` in `ModelStructure`._ _Each state derivative variable maps to the corresponding state variable by the `derivative` attribute._ _If the state variable is an array variable and the `Dimension` element maps to a dependent variable than this dependent variable is a dependency for the number of states.]_ If all <> are unchanged then this dependency information can be used to calculate the initial number of states just using information given in the XML file without the need to call this C-API function. -_[Therefore their is no `numberOfStates` attribute as it is for `numberOfEventIndicators`.]_ - Argument `nz` points to the `size_t` variable that will receive the number of <>. diff --git a/docs/2_2_common_schema.adoc b/docs/2_2_common_schema.adoc index 807efcb83..8ce5e23d2 100644 --- a/docs/2_2_common_schema.adoc +++ b/docs/2_2_common_schema.adoc @@ -153,10 +153,12 @@ These definitions are used in the XML element `ModelVariables`. |`ModelStructure` |Defines the structure of the model. -Especially, the ordered lists of <>, continuous-time <> and initial unknowns (the unknowns during *Initialization Mode*) are defined here. +Especially, the ordered lists of <>, continuous-time <>, initial unknowns (the unknowns during *Initialization Mode*) and the event indicators are defined here. For more details on ModelStructure, see <>. -Furthermore, the dependency of the unkowns from the knowns can be optionally defined. +Furthermore, the dependency of the unknowns from the knowns can be optionally defined for <>, continuous-time <> and initial unknowns. _[This information can be, for example, used to compute efficiently a sparse Jacobian for simulation, or to utilize the <> / <> dependency in order to detect that in some cases there are actually no algebraic loops when connecting FMUs together]_. +Dependencies for event indicators are not provided. +_[The calculation of derivatives of event indicators is not provided.]_. |==== At least one element of `ModelExchange` or `CoSimulation` must be present to identify the type of the FMU. @@ -218,8 +220,6 @@ For the details, see <>. Currently standardized are: - `structured`: Hierarchical names with `.` as hierarchy separator, and with array elements and derivative characterization. -|`numberOfEventIndicators` -|The (fixed) number of event indicators for an FMU based on FMI for Model Exchange. For Co-Simulation, this value is ignored. |==== ==== Definition of Source Code (BuildConfiguration) @@ -1223,7 +1223,7 @@ It is not allowed to define <>. The algebraic relationship to the <> is defined via the <> attribute of ``. [[local,`local`]] -- `local`: Local variable that is calculated from other variables or is a continuous-time <> (see <>). +- `local`: Local variable that is calculated from other variables or is a continuous-time <> or an event indicator (see <>). It is not allowed to use the variable value in another model or slave. [[independent,`independent`]] @@ -1267,7 +1267,7 @@ Variability must be <>. Only a variable of type `Clock` can have this <>. The default of <> is <>. + -A continuous-time <> must have <> = <> or <>, see also <>. +A continuous-time <> or a event indicator must have <> = <> or <>, see also <>. _[<> = <> and <> = <> with <> = <> or <> are similar._ _The difference is that a <> can be used in another model or slave, whereas a <> variable cannot._ @@ -1874,13 +1874,13 @@ _The Co-Simulation FMU has either an integrator included that solves the model e _In both cases the model has the same continuous-time <>._ _In the second case the internal implementation is a discrete-time system, but from the outside this is still a continuous-time model that is solved with an integration method.]_ -The required part defines an ordering of the <> and of the (exposed) <>, and defines the unknowns that are available during Initialization _[Therefore, when linearizing an FMU, every tool will use the same ordering for the <>, <>, and <> for the linearized model. +The required part defines an ordering of the <>, the (exposed) <>, the event indicators and defines the unknowns that are available during Initialization _[Therefore, when linearizing an FMU, every tool will use the same ordering for the <>, <>, and <> for the linearized model. The ordering of the <> should be performed in this case according to the ordering in `ModelVariables`.]_ -A Model Exchange FMU must expose all <> of its continuous-time <> in element `Derivatives`. -A Co- Simulation FMU does not need to expose these state derivatives. +A Model Exchange FMU must expose all <> of its continuous-time <> in element `Derivatives` and must expose all event indicators in elements `EventIndicator`. +A Co- Simulation FMU does not need to expose these state derivatives and event indicators. _[If a Co-Simulation FMU exposes its state derivatives, they are usually not utilized for the co-simulation, but, for example, to linearize the FMU at a communication point.]_ -The optional part defines in which way <> and <> depend on <>, and continuous-time <> at the current super-dense time instant (Model Exchange) or at the current communication point (Co-Simulation). +The optional part defines in which way <>, <> and unitial unknowns depend on <>, and continuous-time <> at the current super-dense time instant (Model Exchange) or at the current communication point (Co-Simulation). _[The listed <> declare the dependencies between whole (multi-dimensional-)variables and not individual elements of the variables.]_ _[A simulation environment can utilize this information to improve the efficiency, for example, when connecting FMUs together, or when computing the partial derivative of the <> with respect to the <> in the simulation engine.]_ @@ -1966,6 +1966,17 @@ latexmath:[\color{blue}{(\mathbf{y}_{c+d}, \dot{\mathbf{x}}_c) := \mathbf{f}_{si _Therefore, the initial state latexmath:[\color{blue}{\mathbf{x}_c(t_0)}] has <> = <> and the initial state derivative latexmath:[\color{blue}{\dot{\mathbf{x}}_c(t_0)}] has <> = <>._ _The environment can still initialize this FMU in steady-state, by using latexmath:[\color{blue}{\mathbf{x}_c(t_0)}] as iteration variables and adding the equations latexmath:[\color{blue}{\mathbf{x}_c(t_0) = \mathbf{0}}] in the environment.]_ +|`EventIndicator` +| +[[EventIndicator,`EventIndicator`]] +|Ordered list of all event indicators, in other words, a list of value references where every corresponding variable must be a event indicator. +_[Note that only <> floating point variables are listed here._ +_If an event indicator shall not be exposed from the FMU, or if event indicators are not statically associated with a variable (due to dynamic event indicator selection), then dummy variables have to be introduced, for example, `eventIndocator[4]`._ +_The ordering of the variables in this list is defined by the exporting tool.]_ + +For Co-Simulation, elements `EventIndicator` are ignored. +_[If an FMU supports both Model Exchange and Co-Simulation, then the `EventIndicator` elements might be present, since it is needed for Model Exchange.]_ + |`Unknown` | [[Unknown,`Unknown`]] diff --git a/docs/3_1_model_exchange_math.adoc b/docs/3_1_model_exchange_math.adoc index aa10913c7..110f8f50c 100644 --- a/docs/3_1_model_exchange_math.adoc +++ b/docs/3_1_model_exchange_math.adoc @@ -163,7 +163,9 @@ Whether the <> is a discrete-time or continuous-time variable is defined Variables of this type are defined with attribute <> = <>, see <>. ^|latexmath:[\mathbf{z}(t)] -|A vector of floating point continuous-time variables utilized to define state events, see below. +|A vector of floating point continuous-time variables representing the event indicators utilized to define state events, see below. +For notational convenience, an event indicator is conceptually treated as a different type of variable as an <> or a <> variable for the mathematical description below. +In reality, event indicator is however part of the <> latexmath:[\mathbf{y}] or the <> variables latexmath:[\mathbf{w}] of an FMU. ^|latexmath:[\mathbf{x}_c(t)] |A vector of floating point continuous-time variables representing the continuous-time <>. diff --git a/docs/3_2_model_exchange_api.adoc b/docs/3_2_model_exchange_api.adoc index c204127cd..562fecf69 100644 --- a/docs/3_2_model_exchange_api.adoc +++ b/docs/3_2_model_exchange_api.adoc @@ -165,14 +165,19 @@ include::../headers/fmi3FunctionTypes.h[tags=GetEventIndicators] ---- Compute state derivatives and event indicators at the current time instant and for the current <>. +Note that `fmi3Status = fmi3Discard` is possible for both functions. + The <> are returned as a vector with `nx` elements. +The ordering of the elements of the `derivatives` vector is identical to the ordering of the state vector (for example, `derivatives[2]` is the <> of `x[2]`). +The order of the states and derivatives is also the same as the ordered list of `Derivative` elements in `ModelStructure`. +_[Array variables are serialized in "row major" order, as usual.]_ + +The event indicators are returned as a vector with `ni` elements. +The order of event indicators in `eventIndicators` vector is the same as the ordered list of `EventIndicator` elements in `ModelStructure`. +_[Array variables are serialized in "row major" order, as usual.]_ A state event is triggered when the domain of an event indicator changes from latexmath:[z_j > 0] to latexmath:[z_j \leq 0] or vice versa. The FMU must guarantee that at an event restart latexmath:[z_j \neq 0], for example, by shifting latexmath:[z_j] with a small value. Furthermore, latexmath:[z_j] should be scaled in the FMU with its nominal value (so all elements of the returned vector `eventIndicators` should be in the order of "one"). -The event indicators are returned as a vector with `ni` elements. + -The ordering of the elements of the derivatives vector is identical to the ordering of the state vector (for example, `derivatives[2]` is the <> of `x[2]`). -Event indicators are not necessarily related to variables on the Model Description File. + -Note that `fmi3Status = fmi3Discard` is possible for both functions. [[fmi3GetContinuousStates,`fmi3GetContinuousStates`]] [source, C] @@ -308,7 +313,7 @@ The allowed function calls in the respective states are summarized in the follow *number* means: call is allowed if the indicated condition holds: + *1* for a variable with <> latexmath:[\neq] <> that has <> = <> or <> + -*2* for a variable with <> = <>, or continuous-time states or state derivatives + +*2* for a variable with <> = <>, or continuous-time states, state derivatives or event indicators, *3* for a variable with <> latexmath:[\neq] <> that has <> = <>, or <> = <> + *4* for a variable with <> = <>, diff --git a/docs/examples/c-code/VanDerPol/modelDescription.xml b/docs/examples/c-code/VanDerPol/modelDescription.xml index 9d997a850..231d0a497 100644 --- a/docs/examples/c-code/VanDerPol/modelDescription.xml +++ b/docs/examples/c-code/VanDerPol/modelDescription.xml @@ -1,5 +1,5 @@ - + diff --git a/schema/fmi3ModelDescription.xsd b/schema/fmi3ModelDescription.xsd index b097533f8..d0712c63e 100644 --- a/schema/fmi3ModelDescription.xsd +++ b/schema/fmi3ModelDescription.xsd @@ -195,14 +195,10 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - - - - - - - + + + + @@ -232,7 +228,6 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -