Add XML element "Clock", attribute "previous", rename "DiscreteTimeSt… (

#1328)

* Add XML element "Clock", attribute "previous", rename "DiscreteTimeState" to "ClockedState"; regenerate images

* Fix XSD; add attribute description for "clockedVariables"

* Fix language

* Add "variability == discrete" restriction

* Fix XSD formatting

* Exclude Clock from having previous attributes

* Add annotation elements for new model structure elems

* Accept Karl´s change request

* Fix formatting

Co-authored-by: Andreas Junghanns <andreas.junghanns@synopsys.com>
Co-authored-by: Pierre R. Mai <pmai@pmsf.de>

docs/2_4_common_schema.adoc

@@ -940,7 +940,7 @@ The algebraic relationship to the <<input,`inputs`>> can be defined via the <<de
 [[local,`local`]]
 `= local`: Local variables are: +
 
-* continuous <<state,`states`>> and their <<StateDerivative,`StateDerivative`pass:[s]>>, <<DiscreteTimeState,`DiscreteTimeState`pass:[s]>>, <<EventIndicator,`EventIndicator`pass:[s]>> or <<InitialUnknown,`InitialUnknown`pass:[s]>>.
+* continuous <<state,`states`>> and their <<StateDerivative,`StateDerivative`pass:[s]>>, <<ClockedState,`ClockedState`pass:[s]>>, <<EventIndicator,`EventIndicator`pass:[s]>> or <<InitialUnknown,`InitialUnknown`pass:[s]>>.
 These variables are listed in the `<fmiModelDescription><ModelStructure>`. +
 * [[localClock,`local clock`]] internal, intermediate variables or local clocks which can be read for debugging purposes and are not listed in the `<fmiModelDescription><ModelStructure>`.
 
@@ -1071,6 +1071,17 @@ Variables with <<causality>> <<parameter>> must not be marked with <<intermediat
 
 This attribute is ignored in Model Exchange.
 The default value of this attribute is `false`.
+
+|`previous`
+|
+[[previous,`previous`]]
+If present, this variable is a <<ClockedState>> and this attribute is a value reference to the variable with the previous value.
+Only clocked variables (they are listed in at least one of the <<clockedVariables>> lists) may have the <<previous>> attribute.
+Only variables with <<variability,`variability == discrete`>> may have a previous value.
+
+_[For example, if `previous == 3` for variable `8`, then variable `3` is the previous value of variable `8`. See also <<fmi3UpdateDiscreteStates>>._
+_Note: This is reverse compared to the <<derivative>> attribute.]_
+
 |====
 
 If <<initial>> is not present, its value is defined by <<table-definition-initial>> based on the values of <<causality>> and <<variability>> (default [.underline]#underlined#):
@@ -1675,11 +1686,13 @@ Beside the knowns the derivatives also depend on the "frozen" variables (= varia
 The functional dependency is defined as (dependencies of variables that are fixed in Event and <<ContinuousTimeMode>> and at communication points are not shown): +
 latexmath:[{\dot{\mathbf{x}_c} := \mathbf{f}_{\mathit{der}}(\mathbf{x}_c, \mathbf{u}_c, \mathbf{u}_d, t, \mathbf{p}_{\mathit{tune}})}]
 
-|`DiscreteTimeState`
+|`ClockedState`
 |
-[[DiscreteTimeState,`<DiscreteTimeState>`]]
-XXX // TODO: Add description, see #1287 on github. +
-XXX // TODO: This should likely be Locals (ask ZIrina), to allow dependency definitions for modelPartitions (to input clocks) for all local variables
+[[ClockedState,`<ClockedState>`]]
+A <<ClockedState>> is part of the discrete state of a model partition and represented by a <<ClockElement,clocked>> variable.
+To which clock or clocks it belongs is described in <<ClockElement>>.
+Each <<ClockedState>> must have the attribute <<previous>> to represent the previous value of this <<ClockedState>>.
+All <<ClockedState,clocked states>> must have <<variability,`variability == discrete`>>.
 
 |`InitialUnknown`
 |
@@ -1722,11 +1735,19 @@ _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.]_
 
+|`Clock`
+|
+[[ClockElement,`<Clock>`]]
+List of all clocks and their clocked variables.
+All variables referenced by these lists must have <<variability,`variability == discrete`>>.
+A clocked variable my depend on multiple clocks and may therefore be listed in multiple <<ClockElement>> elements.
+_[More rigorous importers requiring a variable to be dependent on a single clock can reject FMUs violating this restriction.]_
+
 |====
 
-Elements <<Output>>, <<StateDerivative>>, <<DiscreteTimeState>> and <<InitialUnknown>> have the following attributes:
+Elements <<Output>>, <<StateDerivative>>, <<ClockedState>>, <<InitialUnknown>>, <<EventIndicator>> and <<ClockElement>> have (partially) the following attributes:
 
-.<<Output>>, <<StateDerivative>>, <<DiscreteTimeState>> and <<InitialUnknown>> attribute details.
+.<<Output>>, <<StateDerivative>>, <<ClockedState>>, <<InitialUnknown>>, <<EventIndicator>> and <<ClockElement>> attribute details.
 [[table-output-der-initialUknown-details]]
 [cols="1,5", options="header"]
 |====
@@ -1787,6 +1808,12 @@ Only for floating point type unknowns latexmath:[{\mathbf{v}_{\mathit{unknown}}}
 `=` <<tunable>>: tunable factor, latexmath:[{p \cdot \mathbf{v}_{\mathit{known},i}}] where latexmath:[{p}] is an expression that is evaluated before <<fmi3ExitInitializationMode>> is called and in <<EventMode>> due to event handling (ME) or at a communication point (CS and SE)
 
 `=` <<discrete>>: discrete factor, latexmath:[{d \cdot \mathbf{v}_{\mathit{known},i}}] where latexmath:[{d}] is an expression that is evaluated before <<fmi3ExitInitializationMode>> is called and in <<EventMode>> due to an external or internal event or at a communication point (CS and SE).
+
+|`clockedVariables`
+|
+[[clockedVariables, `clockedVariables`]]
+This element is only available with the <<ClockElement>> element and is a list of value references indicating clocked variables depending on this clock.
+
 |====
 
 _[Example 1:_

schema/fmi3ModelDescription.xsd

@@ -94,12 +94,28 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 						<xs:sequence>
 							<xs:element name="Output" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
 							<xs:element name="StateDerivative" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
-							<xs:element name="DiscreteTimeState" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
+							<xs:element name="ClockedState" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
 							<xs:element name="InitialUnknown" type="fmi3Unknown" minOccurs="0" maxOccurs="unbounded"/>
 							<xs:element name="EventIndicator" minOccurs="0" maxOccurs="unbounded">
-	                                                        <xs:complexType>
-		                                                        <xs:attribute name="valueReference" type="xs:unsignedInt" use="required"/>
-	                                                        </xs:complexType>
+								<xs:complexType>
+									<xs:sequence>
+										<xs:element ref="Annotations" minOccurs="0"/>
+									</xs:sequence>
+									<xs:attribute name="valueReference" type="xs:unsignedInt" use="required"/>
+								</xs:complexType>
+							</xs:element>
+							<xs:element name="Clock" minOccurs="0" maxOccurs="unbounded">
+								<xs:complexType>
+									<xs:sequence>
+										<xs:element ref="Annotations" minOccurs="0"/>
+									</xs:sequence>
+									<xs:attribute name="valueReference" type="xs:unsignedInt" use="required"/>
+									<xs:attribute name="clockedVariables">
+										<xs:simpleType>
+											<xs:list itemType="xs:unsignedInt"/>
+										</xs:simpleType>
+									</xs:attribute>
+								</xs:complexType>
 							</xs:element>
 						</xs:sequence>
 					</xs:complexType>

schema/fmi3Variable.xsd

@@ -350,6 +350,7 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 		</xs:attribute>
 		<xs:attribute name="canHandleMultipleSetPerTimeInstant" type="xs:boolean"/>
 		<xs:attribute name="intermediateUpdate" type="xs:boolean"/>
+		<xs:attribute name="previous" type="xs:unsignedInt"/>
 	</xs:complexType>
 
 	<xs:group name="fmi3Variable">