Skip to content

Describe 'delay' as event-generating operator #3730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Describe 'delay' as event-generating operator #3730

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9f25103
Describe 'delay' as event-generating operator
henrikt-ma Sep 5, 2025
2e18686
Remove obsolete table entry
henrikt-ma Sep 5, 2025
b0cd343
Generalize 'delay' to discrete-valued types
henrikt-ma Sep 10, 2025
500743f
Clarify event generation for discontinuities in non-discrete-time input
henrikt-ma Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 54 additions & 34 deletions chapters/operatorsandexpressions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The event generating expression for \lstinline!delay! is the time remaining until the next discontinuity in the operator value.
The event generating expression for \lstinline!delay! is the time remaining until the next significant discontinuous change in the operator value.'
If the delayed expression is non-Real the change is always significant.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would miss the point. When there is a discontinuous change in the operator value, no matter how small, time must have been stopped for an event. Instead, note that the current text is not stressing that even the tiniest discontinuity in expr must be preserved -- this is up to tools to interpret intelligently.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would miss the point. When there is a discontinuous change in the operator value, no matter how small, time must have been stopped for an event. Instead, note that the current text is not stressing that even the tiniest discontinuity in expr must be preserved -- this is up to tools to interpret intelligently.

I don't fully follow this:
Clearly the discontinuous change of the expression to be delayed happened during an event.
However, to me "discontinuous change in the operator value" mean a discontinuous change in the result of delay-operator (after the delay), which requires that an event was triggered.

If "discontinuous change" is intended to be interpreted somewhat loosely, I would say that it isn't clear at the moment.

And I would say that adding "significant" and stating that changes of discrete-valued types clarifies that intent.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have now added a paragraph about event generation, and it includes significant in a statement about quality of implementation. OK?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM


\begin{nonnormative}
If this is not desired, the \lstinline!noEvent! operator can be applied to them.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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} \\
Expand Down Expand Up @@ -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$)
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -1616,10 +1632,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.
Comment on lines +1639 to +1640
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need delay of a parameter expression to be a parameter expression, and especially have an exception so that delay(p, 1+time/2) is a parameter expression despite the time-argument?

As a user or developer I would wonder what the practical applications are of this; and I simply don't see any cases where users want to delay a parameter-expression.

Note that if we add some variant of more advanced initialization as in #3733 (comment) this will no longer hold; even when all of the arguments are parameter-expressions.

A simpler alternative is to add delay to the same exception-list as initial, terminal, etc (since delay has an implicit time-dependency).

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For delay I see two sets of reasons to not add the parameter-rule for variability (but the rest of the PR is good).

  1. When understanding delay it makes sense to view it as having time as implicit argument, and the explanation even that makes that clear by writing that it evaluates to expr(time-timeDelay).

For fixed time-delays we can even compare it to spatialDistribution where we have to use an explicit dependency:

model CC3
  extends Modelica.Mechanics.Rotational.Examples.CoupledClutches;
  Real J1_w_del=delay(J1.w, 0.1);
  Real J1_w_sp1, J1_w_sp2=spatialDistribution(0 , J1.w, -time/0.1, false, {0,1},{10,10});
equation 
  (,J1_w_sp1)=spatialDistribution(J1.w, 0, time/0.1, true, {0,1},{10,10});
  annotation (uses(Modelica(version="4.1.0")));
end CC3;

Here the three delayed signals are basically all the same, and it is just syntactic sugar that has removed time from the delay-call for J1_w_del. If it helps the discussion we could state that delay has time as hidden argument.

  1. It is just confusing and not usable.

Basically I don't see anyone writing: parameter Real p1, p2=delay(p1, 1+time/2); which is the case that we explicitly make an exception for. I don't see any benefit in making an explicit exception for something that will not be used by people making models, and I just expect it to confuse them - and make them wonder why we are spending time on this.

To me even allowing parameter Real p1, p2=delay(p1, 1); is weird (see previous item), but as long as we don't give it as example it just follows from the normal rules, so I don't care.

If we change the rules to state that delay is never a parameter-expression that works as well, and would work even if we add add initialization for the delay.

\end{itemize}
\end{itemize}

Expand All @@ -1646,6 +1664,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
Expand Down