expand and clarify Clocks chapter of Clocked User Guide

Modelica/Clocked/UsersGuide/Clocks.mo

@@ -10,7 +10,22 @@ Chapter 16 (for Modelica Language Version ≥ 3.3).
 </p>
 
 <p>
-A <strong>Clock</strong> type is a base data type (introduced in Modelica 3.3, additionally to Real, Integer, Boolean, String) that defines when a particular partition consisting of a set of equations is active. Starting with Modelica Language Version 3.3, every variable and every equation is either continuous-time or is associated exactly to one clock. This feature is visualized in the figure below where c(ti) is a clock that is active at particular time instants ti and r(ti) is a variable that is associated to this clock. A clocked variable has only a value when the corresponding clock is active:
+The <strong>Clock</strong> type is a base data type introduced in Modelica 3.3 (additionally to Real, Boolean&hellip;)
+which can be understood as a <em>specialized Boolean</em> type:
+Clock variables are either true (also called "active") or false ("inactive").
+It is specialized in the sense that each Clock variable generates a <strong>partition</strong>
+consisting of a set of equations which gets activated when the clock is active.
+In fact, every variable and every equation of a Modelica model (starting with Modelica Language Version 3.3)
+is assigned to a partition:
+</p>
+<ul>
+    <li>either the global continuous-time partition (no associated clock)
+    <li>or a <strong>clocked partition</strong>, associated to <em>exactly one</em> clock (see more details below).
+</ul>
+<p>
+This feature is visualized in the figure below where c(ti) is a clock that is active
+at particular time instants ti and r(ti) is a variable that is associated to this clock.
+Notice that a clocked variable has <em>only a value when the corresponding clock is active</em>:
 </p>
 
 <div>
@@ -49,44 +64,61 @@ is generated:
 </div>
 
 <p>
-As usual in synchronous languages, a clock is represented by a <strong>true</strong> value
-when the clock is active. The relationship between such derived
+The relationship between such derived
 clocks is <strong>exact</strong>, so it is guaranteed that at every 3rd tick of clock
 \"periodicRealClock.y\", the clock \"subSample.y\" is active.
 </p>
 
+<h3>The two types of clocked partitions</h3>
+<p>
+A clocked partition is a set of equations that depend
+on each other and where the boundary variables are marked
+with sample and hold operators (boundary with other clocked partitions
+or with the global continuous-time partition).
+</p>
+<p>
+There are two types of clocked partitions:
+</p>
+<ul>
+    <li>A <strong>clocked discrete-time</strong> partition shall contain
+    <em>no operator relating to continuous time</em>:
+    <strong>der</strong>, <strong>delay</strong>, <strong>spatialDistribution</strong>,
+    no event-related operators (with exception of <strong>noEvent</strong>(&hellip;)),
+    and no <strong>when</strong>-clause with a Boolean condition.
+    A clocked discrete-time partition is thus a standard sampled data system described by difference equations
+    (it can typically contain the <strong>previous</strong> operator).</li>
+    <li>A <strong>clocked discretized continuous-time</strong> partition shall contain
+    neither operator <strong>previous</strong> nor operator <strong>interval</strong> (i.e. discrete-time operators).
+    It can contain continuous time operators (<strong>der</strong>&hellip;) and it has to be solved with a <strong>solver</strong> (see below).
+    </li>
+</ul>
+<p>
+Notice that it is an error if a partition doesn't fall into one of these two categories, e.g., if operators
+<strong>previous</strong> and <strong>der</strong> are both used in the same partition.
+This means it is <em>not allowed to mix continuous time and discrete-time operators</em> in a clocked partition
+(unlike in the global continuous time partition).
+</p>
+</p>
+Also notice that in a clocked discrete-time partition all event generating mechanisms
+do no longer apply. Especially neither relations, nor one of the built-in event
+triggering operators will trigger an event.
+</p>
+
+<h3>Solver for clocked discretized continuous-time partitions</h3>
 <p>
 If a clock is associated to a clocked continuous-time partition, then an <strong>integrator</strong>
 has to be defined that is used to integrate the partition from the previous
-to the current clock tick. This is performed by setting parameter <strong>useSolver</strong>
-= <strong>true</strong> and defining the integration method as String with
-parameter <strong>solver</strong>. Both parameters are in tab <strong>Advanced</strong>
-of one of the clock signal generating blocks.
+to the current clock tick.
+This is performed by setting, for the corresponding clock signal generating block,
+parameter <strong>useSolver</strong> = <strong>true</strong>
+and defining the integration method as String with parameter <strong>solver</strong>.
+Both parameters are to be found in tab <strong>Advanced</strong>
+of clock signal generating blocks.
 The possible integration methods are tool dependent. It is expected that
 at least the solvers \"External\" (= use the integrator selected in the
 simulation environment) and \"ExplicitEuler\" (= explicit Euler method)
 are supported by every tool. For an example, see
 <a href=\"modelica://Modelica.Clocked.Examples.Systems.ControlledMixingUnit\">Examples.Systems.ControlledMixingUnit</a>.
 </p>
-
-<p>
-A clocked partition is a set of equations that depend
-on each other and where the boundary variables are marked
-with sample and hold operators.
-If a clocked partition contains no operator <strong>der</strong>, <strong>delay</strong>,
-<strong>spatialDistribution</strong>, no event related operators (with exception of <strong>noEvent</strong>(&hellip;)),
-and no <strong>when</strong>-clause with a Boolean condition, it is a <strong>clocked discrete-time</strong>
-partition, that is, it is a standard sampled data system that is described by difference equations.
-If a clocked partition is <strong>not</strong> a <strong>clocked discrete-time</strong> partition and
-it contains neither operator <strong>previous</strong> nor operator
-<strong>interval</strong>, it is a
-<strong>clocked discretized continuous-time</strong> partition.
-Such a partition has to be solved with a <strong>solver</strong> method.
-It is an error, if none of the two properties hold, e.g., if operators
-<strong>previous</strong> and <strong>der</strong> are both used in the same partition.
-In a clocked discrete-time partition all event generating mechanisms
-do no longer apply. Especially neither relations, nor one of the built-in event
-triggering operators will trigger an event.
-</p>
 </html>"));
 end Clocks;