Define event indicators as variables (modelica#587)

The current FMI 3.0 has a well defined variable (including a
valueReference) for all types of values, including states, state
derivatives and the independent variable (time), but not for event
indicators.
This commit fixes this.
Event indicators are listed now in ModelStructure and have therefore a
corresponding variable with a valueReference. Event indicators can be of
causality local and output (as states).
The c-API function for getting event indicators keep the same but
fmi3GetFloat64 can now also be used.

docs/2_1_common_api.adoc

@@ -1179,12 +1179,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 `ModelStrcture`._
+_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.
 
@@ -1203,7 +1201,6 @@ _[All state derivative variables are listed as elements `Derivative` in `ModelSt
 _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)
@@ -1212,7 +1212,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`]]
@@ -1256,7 +1256,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._
@@ -1895,13 +1895,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.]_
 
@@ -1987,6 +1987,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, a 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>