Define event indicators in <ModelStructure> (#587)

and remove "numberOfEventIndicators" attribute

solves #842

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 <<structuralParameter,`structural parameters`>> must be specified in the `ModelStructure` in the element `NumberOfEventIndicators`.
-This element is optional but necessary if the number of event indicators depends on <<structuralParameter,`structural parameters`>>.
-The attribute `dependencies` of this element holds a list of `valueReferences` of <<structuralParameter,`structural parameters`>> having an influence on the number of event indicators.
-If the `NumberOfEventIndicators` element is not present or its <<dependencies>> list is empty, the number of event indicators does not depend on <<structuralParameter,`structural parameters`>>, i.e. it is constant.
-
-The `numberOfEventIndicators` attribute of the `fmiModelDescription` element holds the number of event indicators if all <<structuralParameter,`structural parameters`>> are unchanged, i.e. set to their <<start>> value.
+The dependency of the number of event indicators on <<structuralParameter,`structural parameters`>> 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 <<structuralParameter,`structural parameters`>> 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 <<state,`states`>>.
 The dependency of the number of states on <<structuralParameter,`structural parameters`>> 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 <<structuralParameter,`structural parameters`>> 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 <<state,`states`>>.
 

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 <<output,`outputs`>>, continuous-time <<state,`states`>> and initial unknowns (the unknowns during *Initialization Mode*) are defined here.
+Especially, the ordered lists of <<output,`outputs`>>, continuous-time <<state,`states`>>, initial unknowns (the unknowns during *Initialization Mode*) and the event indicators are defined here.
 For more details on ModelStructure, see <<ModelStructure>>.
-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 <<output,`outputs`>>, continuous-time <<state,`states`>> and initial unknowns.
 _[This information can be, for example, used to compute efficiently a sparse Jacobian for simulation, or to utilize the <<input>> / <<output>> 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 <<variableNamingConvention>>. 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 <<initial>>.
 The algebraic relationship to the <<input,`inputs`>> is defined via the <<dependencies>> attribute of `<fmiModelDescription><ModelStructure><Outputs><Unknown>`.
 
 [[local,`local`]]
-- `local`: Local variable that is calculated from other variables or is a continuous-time <<state>> (see <<ModelStructure>>).
+- `local`: Local variable that is calculated from other variables or is a continuous-time <<state>> or an event indicator (see <<ModelStructure>>).
 It is not allowed to use the variable value in another model or slave.
 
 [[independent,`independent`]]
@@ -1267,7 +1267,7 @@ Variability must be <<clock>>.
 Only a variable of type `Clock` can have this <<causality>>.
 
 The default of <<causality>> is <<local>>. +
-A continuous-time <<state>> must have <<causality>> = <<local>> or <<output>>, see also <<ModelStructure>>.
+A continuous-time <<state>> or a event indicator must have <<causality>> = <<local>> or <<output>>, see also <<ModelStructure>>.
 
 _[<<causality>> = <<calculatedParameter>> and <<causality>> = <<local>> with <<variability>> = <<fixed>> or <<tunable>> are similar._
 _The difference is that a <<calculatedParameter>> can be used in another model or slave, whereas a <<local>> 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 <<state,`states`>>._
 _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 <<output,`outputs`>> and of the (exposed) <<derivative,`derivatives`>>, and defines the unknowns that are available during Initialization _[Therefore, when linearizing an FMU, every tool will use the same ordering for the <<output,`outputs`>>, <<state,`states`>>, and <<derivative,`derivatives`>> for the linearized model.
+The required part defines an ordering of the <<output,`outputs`>>, the (exposed) <<derivative,`derivatives`>>, 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 <<output,`outputs`>>, <<state,`states`>>, and <<derivative,`derivatives`>> for the linearized model.
 The ordering of the <<input,`inputs`>> should be performed in this case according to the ordering in `ModelVariables`.]_
-A Model Exchange FMU must expose all <<derivative,`derivatives`>> of its continuous-time <<state,`states`>> in element `Derivatives`.
-A Co- Simulation FMU does not need to expose these state derivatives.
+A Model Exchange FMU must expose all <<derivative,`derivatives`>> of its continuous-time <<state,`states`>> 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 <<derivative,`derivatives`>> and <<output,`outputs`>> depend on <<input,`inputs`>>, and continuous-time <<state,`states`>> at the current super-dense time instant (Model Exchange) or at the current communication point (Co-Simulation).
+The optional part defines in which way <<derivative,`derivatives`>>, <<output,`outputs`>> and unitial unknowns depend on <<input,`inputs`>>, and continuous-time <<state,`states`>> at the current super-dense time instant (Model Exchange) or at the current communication point (Co-Simulation).
 _[The listed <<dependencies>> 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 <<derivative,`derivatives`>> with respect to the <<state,`states`>> 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 <<initial>> = <<exact>> and the initial state derivative latexmath:[\color{blue}{\dot{\mathbf{x}}_c(t_0)}] has <<initial>> = <<calculated>>._
 _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 <<continuous>> 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`]]

docs/3_1_model_exchange_math.adoc

@@ -163,7 +163,9 @@ Whether the <<output>> is a discrete-time or continuous-time variable is defined
 Variables of this type are defined with attribute <<causality>> = <<local>>, see <<definition-of-model-variables>>.
 
 ^|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 <<output>> or a <<local>> variable for the mathematical description below.
+In reality, event indicator is however part of the <<output,`outputs`>> latexmath:[\mathbf{y}] or the <<local>> variables latexmath:[\mathbf{w}] of an FMU.
 
 ^|latexmath:[\mathbf{x}_c(t)]
 |A vector of floating point continuous-time variables representing the continuous-time <<state,`states`>>.

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 <<state,`states`>>.
+Note that `fmi3Status = fmi3Discard` is possible for both functions.
+
 The <<derivative,`derivatives`>> 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 <<derivative>> 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 <<derivative>> 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 <<variability>> latexmath:[\neq] <<constant>> that has <<initial>> =
 <<exact>> or <<approx>> +
-*2* for a variable with <<causality>> = <<output>>, or continuous-time states or state derivatives +
+*2* for a variable with <<causality>> = <<output>>, or continuous-time states, state derivatives or event indicators,
 *3* for a variable with <<variability>> latexmath:[\neq] <<constant>> that has <<initial>> = <<exact>>,
 or <<causality>> = <<input>>  +
 *4* for a variable with <<causality>> = <<input>>,

docs/examples/c-code/VanDerPol/modelDescription.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
-<fmiModelDescription fmiVersion="3.0-alpha.2" modelName="van der Pol oscillator" instantiationToken="{8c4e810f-3da3-4a00-8276-176fa3c9f000}" numberOfEventIndicators="0">
+<fmiModelDescription fmiVersion="3.0-alpha.2" modelName="van der Pol oscillator" instantiationToken="{8c4e810f-3da3-4a00-8276-176fa3c9f000}">
 
   <ModelExchange modelIdentifier="VanDerPol">
     <BuildConfiguration>

schema/fmi3ModelDescription.xsd

@@ -195,14 +195,10 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 							<xs:element name="Output" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
 							<xs:element name="Derivative" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
 							<xs:element name="InitialUnknown" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
-							<xs:element name="NumberOfEventIndicators" minOccurs="0">
-								<xs:complexType>
-									<xs:attribute name="dependencies" use="required">
-										<xs:simpleType>
-											<xs:list itemType="xs:unsignedInt"/>
-										</xs:simpleType>
-									</xs:attribute>
-								</xs:complexType>
+							<xs:element name="EventIndicator" minOccurs="0" maxOccurs="unbounded">
+	                                                        <xs:complexType>
+		                                                        <xs:attribute name="valueReference" type="xs:unsignedInt" use="required"/>
+	                                                        </xs:complexType>
 							</xs:element>
 						</xs:sequence>
 					</xs:complexType>
@@ -232,7 +228,6 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 					</xs:restriction>
 				</xs:simpleType>
 			</xs:attribute>
-			<xs:attribute name="numberOfEventIndicators" type="xs:unsignedInt"/>
 		</xs:complexType>
 	</xs:element>
 </xs:schema>