Skip to content

Commit

Permalink
Clean up table of Clock constructors
Browse files Browse the repository at this point in the history
  • Loading branch information
@henrikt-ma
henrikt-ma committed Sep 18, 2020
1 parent 41aff8e commit 728fc86
Showing 1 changed file with 107 additions and 144 deletions.
251 changes: 107 additions & 144 deletions chapters/synchronous.tex
View file
Expand Up @@ -321,71 +321,64 @@ \subsection{Argument Restrictions (Component Expression)}\label{argument-restric

\section{Clock Constructors}\label{clock-constructors}

The following overloaded constructors are available to generate clocks, and
it is possible to call them with the specified named arguments, or with positional arguments (according to the order below):
\begin{longtable}[]{|p{3cm}|p{12cm}|}
\hline \endhead
\lstinline!Clock()!
&
\begin{tabular}{@{}p{119mm}@{}}
\firstuse{Inferred Clock}\\
The operator returns a clock that is inferred.
\par
\begin{example*}
The following overloaded constructors are available to generate clocks, and it is possible to call them with the specified named arguments, or with positional arguments (according to the order shown in the details after the table):
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
\lstinline!Clock()! & Inferred clock & \Cref{modelica:clock-inferred}\\
\lstinline!Clock(intervalCounter, resolution)! & Rational interval clock & \Cref{modelica:clock-rational}\\
\lstinline!Clock(interval)! & Real interval clock & \Cref{modelica:clock-interval}\\
\lstinline!Clock(condition, startInterval)! & Event clock & \Cref{modelica:clock-event}\\
\lstinline!Clock(c, solverMethod)! & Solver clock & \Cref{modelica:clock-solver}\\
\hline
\end{tabular}
\end{center}

\begin{operatordefinition*}[Clock]\label{modelica:clock-inferred}
\begin{synopsis}\begin{lstlisting}
Clock()
\end{lstlisting}\end{synopsis}
\begin{semantics}
\firstuse{Inferred clock}. The operator returns a clock that is inferred.

\begin{example}
\begin{lstlisting}[language=modelica]
when Clock() then // equations are on the same clock
x = A*previous(x) + B*u;
when Clock() then // equations are on the same clock
x = A * previous(x) + B * u;
Modelica.Utilities.Streams.print
("clock ticks at = " + String(sample(time)));
end when;
\end{lstlisting}
Note, in most cases, the operator is not needed and equations
could be written without a when-clause (but not in the example above,
since the \lstinline!print! statement is otherwise not associated to a clock).
This style is useful if a modeler would clearly like to mark the
equations that must belong to one clock (although a tool could figure
this out as well, if the when-clause is not present).
\end{example*}
\end{tabular}\\ \hline
\begin{tabular}{@{}p{29mm}@{}}
\lstinline!Clock!(\newline
intervalCounter,\newline
resolution)
\end{tabular}
&
\begin{tabular}{@{}p{119mm}@{}}
\firstuse{Clock with Rational Interval}\\
The first input argument, \lstinline!intervalCounter!, is a clocked Component
Expression (see \cref{argument-restrictions-component-expression}) or a parameter expression of type
\lstinline!Integer! with \lstinline!min=0!. The optional second argument \lstinline!resolution!
(default=1) is a parameter expression of type Integer with \lstinline!min=1! and
\lstinline!unit="Hz"!. If \lstinline!intervalCounter! is a parameter expression with value
zero, the period of the clock is derived by clock inference, see
\cref{sub-clock-inferencing}. The output argument is of base type Clock that ticks when time
becomes t\textsubscript{start}, t\textsubscript{start}+interval1,
t\textsubscript{start}+interval1+interval2, ... The clock starts at the
start of the simulation t\textsubscript{start} or when the controller is
switched on. At the start of the simulation, previous(intervalCounter) =
intervalCounter.start and the clocks ticks the first time. At the first
clock tick intervalCounter must be computed and the second clock tick is
then triggered at interval1=intervalCounter/resolution. At the second
clock tick at time tstart+interval1, a new value for intervalCounter
must be computed and the next clock tick is scheduled at interval2 =
intervalCounter/resolution, and so on. If interval is a parameter
expression, the clock defines a periodic clock.
Note, in most cases, the operator is not needed and equations could be written without a when-clause (but not in the example above, since the \lstinline!print! statement is otherwise not associated to a clock). This style is useful if a modeler would clearly like to mark the equations that must belong to one clock (although a tool could figure this out as well, if the when-clause is not present).
\end{example}
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[Clock]\label{modelica:clock-rational}
\begin{synopsis}\begin{lstlisting}
Clock(intervalCounter=$\mathit{intervalCounter}$, resolution=$\mathit{resolution}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
\firstuse{Rational interval clock}. The first input argument, $\mathit{intervalCounter}$, is a clocked Component Expression (see \cref{argument-restrictions-component-expression}) or a parameter expression of type \lstinline!Integer! with \lstinline!min = 0!. The optional second argument $\mathit{resolution}$ (defaults to 1) is a parameter expression of type \lstinline!Integer! with \lstinline!min = 1! and \lstinline!unit = "Hz"!. If $\mathit{intervalCounter}$ is a parameter expression with value zero, the period of the clock is derived by clock inference, see \cref{sub-clock-inferencing}. The result is of base type \lstinline!Clock! that ticks when \lstinline!time! becomes $t_{\mathrm{start}}$, $t_{\mathrm{start}} + \mathit{interval}_{1}$, $t_{\mathrm{start}} + \mathit{interval}_{1} + \mathit{interval}_{2}$, \ldots The clock starts at the start of the simulation $t_{\mathrm{start}}$ or when the controller is switched on. At the start of the simulation, \lstinline!previous($\mathit{intervalCounter}$)! = \lstinline!$\mathit{intervalCounter}$.start! and the clocks ticks the first time. At the first clock tick $\mathit{intervalCounter}$ must be computed and the second clock tick is then triggered at $\mathit{interval}_{1} = \mathit{intervalCounter}/\mathit{resolution}$. At the second clock tick at time $t_{\mathrm{start}} + \mathit{interval}_{1}$, a new value for $\mathit{intervalCounter}$ must be computed and the next clock tick is scheduled at $\mathit{interval}_{2} = \mathit{intervalCounter}/\mathit{resolution}$, and so on. If
interval % This should be "intervalCounter", right?
is a parameter expression, the clock defines a periodic clock.

\begin{nonnormative}
The given interval and time shift can be modified by using the subSample, superSample, shiftSample and backSample operators on the returned clock, see \cref{sub-clock-conversion-operators}.
The given interval and time shift % What given "interval" and "time shift"?
can be modified by using the \lstinline!subSample!, \lstinline!superSample!, \lstinline!shiftSample! and \lstinline!backSample! operators on the returned clock, see \cref{sub-clock-conversion-operators}.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
// first clock tick: previous(nextInterval)=2
Integer nextInterval(start=2);
Real y1(start=0);
Real y2(start=0);
// first clock tick: previous(nextInterval) = 2
Integer nextInterval(start = 2);
Real y1(start = 0);
Real y2(start = 0);
equation
when Clock(2,1000) then
when Clock(2, 1000) then
// periodic clock that ticks at 0, 0.002, 0.004, ...
y1 = previous(y1) + 1;
end when;
Expand All @@ -398,111 +391,81 @@ \section{Clock Constructors}\label{clock-constructors}
\end{lstlisting}
\end{example}

Note that operator \lstinline!interval(c)! of \lstinline!Clock c = Clock(nextInterval, resolution)! returns:\newline
\lstinline!previous(intervalCounter) / resolution; // in seconds!
\end{tabular}\\ \hline
\lstinline!Clock(interval)!
&
\begin{tabular}{@{}p{119mm}@{}}
\firstuse{Clock with Real Interval}\\
The input argument, \lstinline!interval!, is a clocked Component Expression (see
\cref{argument-restrictions-component-expression}) or a parameter expression.
The \lstinline!interval! must be strictly positive (\lstinline!interval>0.0!) of type \lstinline!Real! with \lstinline!unit="s"!.
The output argument is of base type Clock that
ticks when time becomes t\textsubscript{start},
t\textsubscript{start}+interval1,
t\textsubscript{start}+interval1+interval2, ... The clock starts at the
start of the simulation t\textsubscript{start} or when the controller is
switched on. Here the next clock tick is scheduled at interval1 =
\lstinline!previous(interval) = interval.start!. At the second clock tick
at time t\textsubscript{start}+interval1, the next clock tick is
scheduled at \lstinline!interval2 = previous(interval)!, and so on. If
interval is a parameter expression, the clock defines a periodic clock.
\par
\begin{nonnormative*}
Note, the clock is defined with \lstinline!previous(interval)!. Therefore, for sorting the input argument is treated as known. The given interval and time shift can be modified
by using the subSample, superSample, shiftSample and backSample operators on the returned clock, see \cref{sub-clock-conversion-operators}. There are restrictions where this
operator can be used, see Clock expressions below.
\end{nonnormative*}
\end{tabular}\\ \hline
\begin{tabular}{@{}p{29mm}@{}}
\lstinline!Clock!(\newline
\lstinline!condition!,\newline
\lstinline!startInterval!)
\end{tabular}
&
\begin{tabular}{@{}p{119mm}@{}}
\firstuse{Event Clock}\\
The input argument, \lstinline!condition!, is a continuous-time expression of type
Boolean. The optional \lstinline!startInterval! argument (default = 0.0) is the
value returned by \lstinline!interval()! at the first tick of
the clock, see \cref{initialization-of-clocked-partitions}. The output argument is of base type Clock
that ticks when \lstinline!edge(condition)! becomes true.
Note that operator \lstinline!interval(c)! of \lstinline!Clock c = Clock(nextInterval, $\mathit{resolution}$)! returns:\newline
\lstinline!previous($\mathit{intervalCounter}$) / $\mathit{resolution}$! (in seconds)
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[Clock]\label{modelica:clock-interval}
\begin{synopsis}\begin{lstlisting}
Clock(interval=$\mathit{interval}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
\firstuse{Real interval clock}. The input argument, $\mathit{interval}$, is a clocked Component Expression (see \cref{argument-restrictions-component-expression}) or a parameter expression. The $\mathit{interval}$ must be strictly positive ($\mathit{interval} > 0$) of type \lstinline!Real! with \lstinline!unit = "s"!. The result is of base type \lstinline!Clock! that ticks when \lstinline!time! becomes $t_{\mathrm{start}}$, $t_{\mathrm{start}} + \mathit{interval}_{1}$, $t_{\mathit{start}} + \mathit{interval}_{1} + \mathit{interval}_{2}$, \ldots The clock starts at the start of the simulation $t_{\mathrm{start}}$ or when the controller is switched on. Here the next clock tick is scheduled at $\mathit{interval}_{1}$ = \lstinline!previous($\mathit{interval}$)! = \lstinline!$\mathit{interval}$.start!. At the second clock tick at time $t_{\mathrm{start}} + \mathit{interval}_{1}$, the next clock tick is scheduled at $\mathit{interval}_{2}$ = \lstinline!previous($\mathit{interval}$)!, and so on. If $\mathit{interval}$ is a parameter expression, the clock defines a periodic clock.

\begin{nonnormative}
This clock is used to trigger a clocked partition due to a state event, that is a zero-crossing of a Real variable, in a continuous-time partition or due to a hardware interrupt
that is modeled as Boolean in the simulation model.
Note, the clock is defined with \lstinline!previous($\mathit{interval}$)!. Therefore, for sorting the input argument is treated as known. The given interval and time shift can be modified by using the \lstinline!subSample!, \lstinline!superSample!, \lstinline!shiftSample! and \lstinline!backSample! operators on the returned clock, see \cref{sub-clock-conversion-operators}. There are restrictions where this operator can be used, see \lstinline!Clock! expressions below.
\end{nonnormative}
\par
\begin{example*}
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[Clock]\label{modelica:clock-event}
\begin{synopsis}\begin{lstlisting}
Clock(condition=$\mathit{condition}$, startInterval=$\mathit{startInterval}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
\firstuse{Event clock}. The first input argument, $\mathit{condition}$, is a continuous-time expression of type \lstinline!Boolean!. The optional $\mathit{startInterval}$ argument (defaults to 0) is the value returned by \lstinline!interval()! at the first tick of the clock, see \cref{initialization-of-clocked-partitions}. The result is of base type \lstinline!Clock! that ticks when \lstinline!edge($\mathit{condition}$)! becomes \lstinline!true!.
\begin{nonnormative}
This clock is used to trigger a clocked partition due to a state event, that is a zero-crossing of a \lstinline!Real! variable, in a continuous-time partition or due to a hardware interrupt that is modeled as \lstinline!Boolean! in the simulation model.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
Clock c = Clock(angle > 0, 0.1) // before first tick of c:
// interval(c) = 0.1
\end{lstlisting}
\end{example}

The implicitly given interval and time shift can be modified by
using the subsample, superSample, shiftSample and backSample operators
on the returned clock, see \cref{sub-clock-conversion-operators}, provided the base
interval is not smaller than the implicitly given interval.
\end{example*}
\end{tabular}\\ \hline
\begin{tabular}{@{}p{29mm}@{}}
\lstinline!Clock!(\newline
\lstinline!c!,\newline
\lstinline!solverMethod!)\newline
\end{tabular}
&
\begin{tabular}{@{}p{119mm}@{}}
\firstuse{Solver Clock}\\
The first input argument \lstinline!c! is a clock and the operator returns this
clock. The returned clock is associated with the second input argument
of type String \lstinline!solverMethod!. The meaning of solverMethod is defined
in \cref{solver-methods}. If the second input argument solverMethod is an empty
String, then this Clock-construct does not associate an integrator with the returned clock.
\par
\begin{example*}
\begin{nonnormative}
The implicitly given interval and time shift can be modified by using the \lstinline!subsample!, \lstinline!superSample!, \lstinline!shiftSample! and \lstinline!backSample! operators on the returned clock, see \cref{sub-clock-conversion-operators}, provided the base interval is not smaller than the implicitly given interval.
\end{nonnormative}
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[Clock]\label{modelica:clock-solver}
\begin{synopsis}\begin{lstlisting}
Clock(c=$c$, solverMethod=$\mathit{solverMethod}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
\firstuse{Solver clock}. The first input argument, $c$, is a clock and the operator returns this clock. The returned clock is associated with the second input argument $\mathit{solverMethod}$ of type \lstinline!String!. The meaning of $\mathit{solverMethod}$ is defined in \cref{solver-methods}. If $\mathit{solverMethod}$ is the empty \lstinline!String!, then this \lstinline!Clock! construct does not associate an integrator with the returned clock.

\begin{example}
\begin{lstlisting}[language=modelica]
Clock c1 = Clock(1,10) // 100 ms, no solver
Clock c2 = Clock(c1, "ImplicitTrapezoid");
// 100 ms, ImplicitTrapezoid solver
Clock c1 = Clock(1, 10) // 100 ms, no solver
Clock c2 = Clock(c1, "ImplicitTrapezoid"); // 100 ms, ImplicitTrapezoid solver
Clock c3 = Clock(c2, ""); // 100 ms, no solver
\end{lstlisting}
\end{example*}
\end{tabular}
\\ \hline
\end{longtable}
\end{example}
\end{semantics}
\end{operatordefinition*}

Besides inferred clocks and solver clocks, one of the following mutually
exclusive associations of clocks are possible in one base partition:
\begin{enumerate}
\item
One or more Rational interval clocks, provided they are consistent
with each other, see \cref{sub-clock-inferencing}.
\begin{nonnormative}
For example, assume \lstinline!y = subSample(u)!, and \lstinline!Clock(1, 10)! is associated with \lstinline!u! and \lstinline!Clock(2, 10)! is associated with \lstinline!y!,
then this is correct, but it would be an error if \lstinline!y! is associated with a \lstinline!Clock(1, 3)!.
\end{nonnormative}
One or more rational interval clocks, provided they are consistent with each other, see \cref{sub-clock-inferencing}.
\begin{example}
Assume \lstinline!y = subSample(u)!, and \lstinline!Clock(1, 10)! is associated with \lstinline!u! and \lstinline!Clock(2, 10)! is associated with \lstinline!y!, then this is correct, but it would be an error if \lstinline!y! is associated with a \lstinline!Clock(1, 3)!.
\end{example}
\item
Exactly one Real interval clock.
\begin{nonnormative}
Assume \lstinline!Clock c = Clock(2.5)!, then variables in the same base partition can be associated multiple times with \lstinline!c! but not multiple times
with \lstinline!Clock(2.5)!.
\end{nonnormative}
Exactly one real interval clock.
\begin{example}
Assume \lstinline!Clock c = Clock(2.5)!, then variables in the same base partition can be associated multiple times with \lstinline!c! but not multiple times with \lstinline!Clock(2.5)!.
\end{example}
\item
Exactly one Event clock.
Exactly one event clock.
\item
A default clock, if neither a Real interval, nor a Rational interval
nor an Event clock is associated with a base partition. In this case
the default clock is associated with the fastest sub-clock partition.
A default clock, if neither a real interval, nor a rational interval nor an event clock is associated with a base partition. In this case the default clock is associated with the fastest sub-clock partition.
\begin{nonnormative}
Typically, a tool will use Clock(1.0) as a default clock and will raise a warning, that it selected a default clock.
\end{nonnormative}
Expand Down Expand Up @@ -703,7 +666,7 @@ \subsection{Sub-clock conversion operators}\label{sub-clock-conversion-operators
Thus \lstinline!subSample(superSample(u, factor), factor)=u!
\end{nonnormative}
If argument factor is not provided or is equal to zero, it
is inferred, see \cref{sub-clock-inferencing}. If an Event clock is associated to a
is inferred, see \cref{sub-clock-inferencing}. If an event clock is associated to a
base-clock partition, all its sub-clock partitions must have resulting
clocks that are sub-sampled with an Integer factor with respect to this
base clock.
Expand Down Expand Up @@ -732,7 +695,7 @@ \subsection{Sub-clock conversion operators}\label{sub-clock-conversion-operators
\end{lstlisting}
\par
\begin{nonnormative*}
Note, due to the restriction of superSample on Event clocks, shiftSample can only shift the number of ticks of the Event clock, but cannot introduce new ticks. Example:
Note, due to the restriction of \lstinline!superSample! on event clocks, \lstinline!shiftSample! can only shift the number of ticks of the event clock, but cannot introduce new ticks. Example:
\begin{lstlisting}[language=modelica]
// Rational interval clock
Clock u = Clock(3, 10); // ticks: 0, 3/10, 6/10, ..
Expand Down Expand Up @@ -1412,8 +1375,8 @@ \section{Other Operators}\label{other-operators}
At the first tick of the clock the following is returned: a) if the
specified clock interval is parametric, this value is returned; b)
otherwise the start value of the variable specifying the interval is
returned; c) for an Event clock the additional startInterval argument to
the Event clock constructor is returned. The return value of the
returned; c) for an event clock the additional startInterval argument to
the event clock constructor is returned. The return value of the
interval operator is a scalar Real number.
\\ \hline
\end{longtable}
Expand Down

0 comments on commit 728fc86

Please sign in to comment.