diff --git a/chapters/operatorsandexpressions.tex b/chapters/operatorsandexpressions.tex index 3be828310..f3a699834 100644 --- a/chapters/operatorsandexpressions.tex +++ b/chapters/operatorsandexpressions.tex @@ -594,12 +594,14 @@ \subsection{Event Triggering Mathematical Functions}\label{event-triggering-math {\lstinline!ceil($x$)!} & Smallest integer {\lstinline!Real!} not less than $x$ & \Cref{modelica:ceil} \\ {\lstinline!floor($x$)!} & Largest integer {\lstinline!Real!} not greater than $x$ & \Cref{modelica:floor} \\ {\lstinline!integer($x$)!} & Largest {\lstinline!Integer!} not greater than $x$ & \Cref{modelica:integer} \\ +{\lstinline!delay($\ldots$)!} & Time delay & \Cref{modelica:delay} \\ \hline \end{tabular} \end{center} These expression for \lstinline!div!, \lstinline!ceil!, \lstinline!floor!, and \lstinline!integer! are event generating expression. The event generating expression for \lstinline!mod(x,y)! is \lstinline!floor(x/y)!, and for \lstinline!rem(x,y)! it is \lstinline!div(x,y)! -- i.e., events are not generated when \lstinline!mod! or \lstinline!rem! changes continuously in an interval, but when they change discontinuously from one interval to the next. +The event generating expression for \lstinline!delay! is the time remaining until the next discontinuity in the operator value. \begin{nonnormative} If this is not desired, the \lstinline!noEvent! operator can be applied to them. @@ -690,6 +692,53 @@ \subsection{Event Triggering Mathematical Functions}\label{event-triggering-math \end{semantics} \end{operatordefinition} +\begin{operatordefinition}[delay] +\begin{synopsis}\begin{lstlisting} +delay($\mathit{expr}$, $\mathit{delayTime}$, $\mathit{delayMax}$) +delay($\mathit{expr}$, $\mathit{delayTime}$) +\end{lstlisting}\end{synopsis} +\begin{semantics} +Evaluates to: +\begin{equation*} +\begin{cases} +\mathit{expr}(\text{\lstinline!time.start!}) & \text{\lstinline!time!} - \mathit{delayTime} \leq \text{\lstinline!time.start!}\\ +\mathit{expr}(\text{\lstinline!time!} - \mathit{delayTime}) & \text{otherwise} +\end{cases} +\end{equation*} + +When a \lstinline!delay!-expression is discrete-time (see \cref{discrete-time-expressions}), events will be generated in order to allow the value to change at the correct points in time. +Further, when a \lstinline!delay!-expression is non-discrete-time and event generation is enabled (not appearing inside \lstinline!noEvent!), events may also be generated in order to preserve discontinuities in $expr$. +It is a quality of implementation to avoid excessive generation of events by only preserving significant discontinuities. + +The expression $\mathit{expr}$ shall be a subtype of \lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean!, or an enumeration type. +The time arguments, $\mathit{delayTime}$ and $\mathit{delayMax}$, shall be subtypes of \lstinline!Real!. +The type of the result is the same as the type of $\mathit{expr}$. + +When provided, $\mathit{delayMax}$ shall be a parameter expression, and it shall hold that $0 \leq \mathit{delayTime} \leq \mathit{delayMax}$. +When $\mathit{delayMax}$ is not provided, $\mathit{delayTime} \geq 0$ shall be a parameter expression. +The operator is not allowed inside \lstinline!function! classes. +For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. +For further details, see \cref{delay}. +\end{semantics} +\end{operatordefinition} + + +\subsubsection{delay}\label{delay} + +\begin{nonnormative} +\lstinline!delay! allows a numerical sound implementation by interpolating in the (internal) integrator polynomials, as well as a more simple realization by interpolating linearly in a buffer containing past values of expression $\mathit{expr}$. +Without further information, the complete time history of the delayed signals needs to be stored, because the delay time may change during simulation. +To avoid excessive storage requirements and to enhance efficiency, the maximum allowed delay time has to be given via $\mathit{delayMax}$. +This gives an upper bound on the values of the delayed signals which have to be stored. +For real-time simulation where fixed step size integrators are used, this information is sufficient to allocate the necessary storage for the internal buffer before the simulation starts. +For variable step size integrators, the buffer size is dynamic during integration. + +In principle, \lstinline!delay! could break algebraic loops. +For simplicity, this is not supported because the minimum delay time has to be given as additional argument to be fixed at compile time. +Furthermore, the maximum step size of the integrator is limited by this minimum delay time in order to avoid extrapolation in the delay buffer. +\end{nonnormative} + + \subsection{Elementary Mathematical Functions}\label{built-in-mathematical-functions-and-external-built-in-functions} The functions listed below are elementary mathematical functions. @@ -749,7 +798,6 @@ \subsection{Derivative and Special Purpose Operators with Function Syntax}\label \hline \hline {\lstinline!der($\mathit{expr}$)!} & Time derivative & \Cref{modelica:der} \\ -{\lstinline!delay($\mathit{expr}$, $\ldots$)!} & Time delay & \Cref{modelica:delay} \\ {\lstinline!cardinality($c$)!} & Number of occurrences in {\lstinline!connect!}-equations & \Cref{modelica:cardinality} \\ {\lstinline!homotopy($\mathit{actual}$, $\mathit{simplified}$)!} & Homotopy initialization & \Cref{modelica:homotopy} \\ {\lstinline!semiLinear($x$, $k^{+}$, $k^{-}$)!} & Sign-dependent slope & \Cref{modelica:semiLinear} \\ @@ -816,23 +864,6 @@ \subsection{Derivative and Special Purpose Operators with Function Syntax}\label \end{semantics} \end{operatordefinition} -\begin{operatordefinition}[delay] -\begin{synopsis}\begin{lstlisting} -delay($\mathit{expr}$, $\mathit{delayTime}$, $\mathit{delayMax}$) -delay($\mathit{expr}$, $\mathit{delayTime}$) -\end{lstlisting}\end{synopsis} -\begin{semantics} -Evaluates to \lstinline!$\mathit{expr}$(time - $\mathit{delayTime}$)! for $\text{\lstinline!time!} > \text{\lstinline!time.start!} + \mathit{delayTime}$ and \lstinline!$\mathit{expr}$(time.start)! for $\text{\lstinline!time!} \leq \text{\lstinline!time.start!} + \mathit{delayTime}$. -The arguments, i.e., $\mathit{expr}$, $\mathit{delayTime}$ and $\mathit{delayMax}$, need to be subtypes of \lstinline!Real!. -$\mathit{delayMax}$ needs to be additionally a parameter expression. -The following relation shall hold: $0 \leq \mathit{delayTime} \leq \mathit{delayMax}$, otherwise an error occurs. -If $\mathit{delayMax}$ is not supplied in the argument list, $\mathit{delayTime}$ needs to be a parameter expression. -The operator is not allowed inside \lstinline!function! classes. -For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. -For further details, see \cref{delay}. -\end{semantics} -\end{operatordefinition} - \begin{operatordefinition}[cardinality] \begin{synopsis}\begin{lstlisting} cardinality($c$) @@ -933,21 +964,6 @@ \subsection{Derivative and Special Purpose Operators with Function Syntax}\label A few of these operators are described in more detail in the following. -\subsubsection{delay}\label{delay} - -\begin{nonnormative} -\lstinline!delay! allows a numerical sound implementation by interpolating in the (internal) integrator polynomials, as well as a more simple realization by interpolating linearly in a buffer containing past values of expression $\mathit{expr}$. -Without further information, the complete time history of the delayed signals needs to be stored, because the delay time may change during simulation. -To avoid excessive storage requirements and to enhance efficiency, the maximum allowed delay time has to be given via $\mathit{delayMax}$. -This gives an upper bound on the values of the delayed signals which have to be stored. -For real-time simulation where fixed step size integrators are used, this information is sufficient to allocate the necessary storage for the internal buffer before the simulation starts. -For variable step size integrators, the buffer size is dynamic during integration. - -In principle, \lstinline!delay! could break algebraic loops. -For simplicity, this is not supported because the minimum delay time has to be given as additional argument to be fixed at compile time. -Furthermore, the maximum step size of the integrator is limited by this minimum delay time in order to avoid extrapolation in the delay buffer. -\end{nonnormative} - \subsubsection{spatialDistribution}\label{spatialdistribution} \begin{nonnormative} @@ -1575,6 +1591,12 @@ \subsection{Constant Expressions}\label{constant-expressions} \item \lstinline!ndims(A)! \end{itemize} +\item + Some function calls are constant expressions even if one or more arguments are not: + \begin{itemize} + \item + \lstinline!delay($x$, $\ldots$)! where $x$ is a constant expression. + \end{itemize} \end{itemize} \subsection{Evaluable Expressions}\label{evaluable-expressions} @@ -1592,16 +1614,18 @@ \subsection{Evaluable Expressions}\label{evaluable-expressions} \item The sub-expression \lstinline!end! used in \lstinline!A[$\ldots$ end $\ldots$]! if \lstinline!A! is a variable declared in a non-\lstinline!function! class. \item - Some function calls are evaluable expressions even if the arguments are not: + Some function calls are evaluable expressions even if one or more arguments are not: \begin{itemize} - \item - \lstinline!cardinality(c)!, see restrictions for use in \cref{cardinality-deprecated}. \item \lstinline!size(A)! (including \lstinline!size(A, j)! where \lstinline!j! is an evaluable expression) if \lstinline!A! is variable declared in a non-function class. + \item + \lstinline!delay($x$, $\ldots$)! where $x$ is an evaluable expression. \item \lstinline!Connections.isRoot(A.R)! \item \lstinline!Connections.rooted(A.R)! + \item + \lstinline!cardinality(c)!, see restrictions for use in \cref{cardinality-deprecated}. \end{itemize} \end{itemize} @@ -1616,10 +1640,12 @@ \subsection{Parameter Expressions}\label{parameter-expressions} \item Except for the special built-in operators \lstinline!initial!, \lstinline!terminal!, \lstinline!der!, \lstinline!edge!, \lstinline!change!, \lstinline!sample!, and \lstinline!pre!, a function or operator with parameter subexpressions is a parameter expression. \item - Some function calls are parameter expressions even if the arguments are not: + Some function calls are parameter expressions even if one or more arguments are not: \begin{itemize} \item \lstinline!size(A, j)! where \lstinline!j! is a parameter expression, if \lstinline!A! is variable declared in a non-function class. + \item + \lstinline!delay($x$, $\ldots$)! where $x$ is a parameter expression. \end{itemize} \end{itemize} @@ -1646,6 +1672,8 @@ \subsection{Discrete-Time Expressions}\label{discrete-time-expressions} Note that \lstinline!rem! and \lstinline!mod! generate events but are not discrete-time expressions. In other words, relations inside \lstinline!noEvent!, such as \lstinline!noEvent(x>1)!, are not discrete-time expressions. \end{nonnormative} +\item + Unless inside \lstinline!noEvent!: \lstinline!delay($x$, $\ldots$)!, if $x$ is a discrete-time expression. \item The functions \lstinline!pre!, \lstinline!edge!, and \lstinline!change! result in discrete-time expressions. \item