Working through Chapter 2 issues

When removing todo items I either fix them or at least add them as issues in GitHub.

Author: mtiller

text/source/behavior/discrete/bouncing.rst

@@ -78,15 +78,12 @@ following behavior from this model:
 .. plot:: ../plots/BB1.py
    :class: interactive
 
-In this plot, we see that at around 0.48 seconds, the first impact with the
-surface occurs.  This occurs because the condition ``h<0`` first becomes
-true at that moment.  Note that what makes this a state event (unlike
-our example in :ref:`previous cooling examples <cooling-revisited>`) is the
-fact that this conditional expression references continuous variables
-other than ``time``.
-
-.. todo:: link to previous cooling examples not showing up correctly
-          do the referenced variables have to be continuous to make a state event?
+In this plot, we see that at around 0.48 seconds, the first impact
+with the surface occurs.  This occurs because the condition ``h<0``
+first becomes true at that moment.  Note that what makes this a state
+event (unlike our example in :ref:`previous cooling examples
+<cooling-revisited>`) is the fact that this conditional expression
+references variables other than ``time``.
 
 As such, the simulation proceeds assuming the ball is in free fall
 until it identifies a solution trajectory where the value of the

text/source/behavior/discrete/decay.rst

@@ -22,7 +22,6 @@ If we attempt to simulate this model for 5 seconds, we find that the
 simulation terminates after about 2 seconds with the following trajectory:
 
 .. plot:: ../plots/Decay1.py
-   :class: interactive
 
 Again, numerical issues creep in.  Even though mathematically it
 should not be possible for the value of ``x`` to drop below zero,
@@ -44,7 +43,6 @@ against evaluating the square root of a negative number, like this:
 Simulating this model we get the following trajectory [#tol]_:
 
 .. plot:: ../plots/Decay2.py
-   :class: interactive
 
 Again, the simulation fails.  But why?  It fails for the same reason,
 a numerical exception that results from taking the square root of a
@@ -269,8 +267,6 @@ performance:
 .. plot:: ../plots/Decay5.py
    :class: interactive
 
-.. todo:: Smooth operator?
-
 .. [#tol] This model will not always fail.  The failure depends on how
 	  much integration error is introduced and this, in turn,
 	  depends on the numerical tolerances used.

text/source/behavior/discrete/events.rst

@@ -52,19 +52,11 @@ should also be noted that even a simple variable assignment, *e.g.,*
 
 can trigger an event to be generated.
 
-.. todo::
-
-   Discuss smooth (and smoothOrder?)
-
 Events and Functions
 ^^^^^^^^^^^^^^^^^^^^
 
 .. index:: ! sample
 
-.. todo::
-
-   I Need to fill in this table more
-
 In addition to being generated by conditional expressions, events can
 also be generated by certain functions in Modelica.  The
 following is a list of functions and how they generate events:

text/source/behavior/discrete/hysteresis.rst

@@ -31,21 +31,21 @@ simulation:
 .. plot:: ../plots/CC1_Q.py
    :class: interactive
 
-.. todo:: the plot isn't showing this - it is just a solid blue background
-
 What you see is that after around 0.2 seconds, the heater is
-constantly turning on and off.  This is actually a real problem in
-control systems.  If you look carefully at the way the furnace works
-in your own home, you will see that it does not turn on and off
-constantly as the temperature goes above and below the desired room
-temperature you have specified.  Instead, it waits until the
-temperature gets some specified amount above or below the desired
-temperature before acting.
-
-.. todo:: there seems to be a formatting problem around code{ChatteringControl}
+constantly turning on and off.  This happens so frequently, in fact,
+that you would have to zoom in quite a bit on the plot to see the
+transitions.  With normal scaling, there are so many transitions that
+the results resemble a filled rectangle.
+
+This is actually a real problem in control systems.  If you look
+carefully at the way the furnace works in your own home, you will see
+that it does not turn on and off constantly as the temperature goes
+above and below the desired room temperature you have specified.
+Instead, it waits until the temperature gets some specified amount
+above or below the desired temperature before acting.
 
 This "band" that is introduced around the desired temperature is
-called hysteresis.  The problem with the \code{ChatteringControl}
+called hysteresis.  The problem with the ``ChatteringControl``
 model is that it doesn't have any hysteresis.  Instead, it is
 constantly turning the heater off and on in response to miniscule
 changes in temperature.

text/source/behavior/discrete/measuring.rst

@@ -263,16 +263,15 @@ In this way, an ``algorithm`` section is very much like the way most
 programming languages work.  The statements in the algorithm section
 are executed in order and each statement isn't interpreted as an
 equation, but rather as an assignment of an expression to a variable.
-The familiarity of assignment statements may make using ``algorithm`` sections attractive to people with a programming background who find the otherwise
-equation oriented aspects of Modelica disorienting and unfamiliar.
-But be aware that one big reason to avoid ``algorithm`` sections is because they interfere with the symbolic manipulation
+The familiarity of assignment statements may make using ``algorithm``
+sections attractive to people with a programming background who find
+the otherwise equation oriented aspects of Modelica disorienting and
+unfamiliar.  But be aware that one big reason to avoid ``algorithm``
+sections is because they interfere with the symbolic manipulation
 performed by the Modelica compiler.  This can result in both poor
 simulation performance and a loss of flexibility in how you compose
-your models.
-
-.. todo:: what would be the alternative?
-	  note, reworded this because it sounded like it was saying familiarity with
-	  assignment statements is the reason to avoid them
+your models.  So it is best to use an ``equation`` section whenever
+possible
 
 In our case, there are no significant consequences to using the
 ``algorithm`` section.  Here is an example of how the previous

text/source/behavior/discrete/sampling.rst

@@ -88,15 +88,66 @@ these lines one by one and discuss them.  First we have:
    :language: modelica
    :lines: 5
 
-.. todo::
+Note that we have done away with the ``0.1``.  We no longer see any
+mention of the clock interval as a real number.  Instead, we use the
+``Clock`` operator to the define clock interval for ``x`` as a
+rational number.  This is important because it allows us to do exact
+comparisons between clocks.  This brings us to the next line:
 
-  Finish this explanation after checking on the semantics of Clock
+.. literalinclude:: /ModelicaByExample/DiscreteBehavior/SynchronousSystems/SamplingWithClocks.mo
+   :language: modelica
+   :lines: 6
+
+Again, we see the rational representation of the clock.  What this
+means, in practice, is that the Modelica compiler can know for certain
+that these two clocks, ``x`` and ``y``, are identical because they are
+defined in terms of integer quantities which allow exact comparison.
+This means that when executing a simulation, we can know for certain
+that these two clocks will trigger simultaneously.
+
+If we wanted to create a clock that was exactly two times slower than
+``x``, we can use the ``subSample`` operator to accomplish this.  We
+see this in the definition of ``z``:
+
+.. literalinclude:: /ModelicaByExample/DiscreteBehavior/SynchronousSystems/SamplingWithClocks.mo
+   :language: modelica
+   :lines: 7
+
+Behind the scenes, the Modelica compiler can reason about these
+clocks.  It knows that the ``x`` clock triggers every
+:math:`\frac{1}{10}` of a second.  Using the information provided by
+the ``subSample`` operator the Modelica compiler can therefore deduce
+that ``z`` triggers every :math:`\frac{2}{10}` of a second.
+Conceptually, this means that ``z`` could also have been defined as:
+
+.. code-block:: modelica
+
+  z = sample(time, Clock(2,10));
+
+But by defining ``z`` using the ``subSample`` operator and defining it
+with respect to ``x`` we ensure that ``z`` is always triggering at
+half the frequency of ``x`` regardless of how ``x`` is defined.
+
+In a similar way, we can define another clock, ``w`` that triggers 3 times more
+frequently than ``x`` by using the ``superSample`` operator:
+
+.. literalinclude:: /ModelicaByExample/DiscreteBehavior/SynchronousSystems/SamplingWithClocks.mo
+   :language: modelica
+   :lines: 8
+
+Again, we could have defined ``w`` directly using ``sample`` with:
+
+.. code-block:: modelica
 
+  w = sample(time, Clock(1,30));
 
-.. todo::
+But by using ``superSample``, we can ensure that ``w`` is always
+sampling three times faster than ``x`` and six times faster than ``z``
+(since ``z`` is also defined with respect to ``x``).
 
-  Cite Hilding's paper for detailed discussion of synchronous
-  features.
+The synchronous clock features in Modelica are relatively new.  To
+learn more about these synchronous features and their applications see
+[Elmqvist]_ and/or the Modelica Specification, version 3.3 or later.
 
 .. [Elmqvist] "Fundamentals of Synchronous Control in Modelica",
 	      Hilding Elmqvist, Martin Otter and Sven-Erik Mattsson