Discrete-time variability based on GenerateEvents (#3610)

* Add variability change for these functions.
* After some thinking I believe this is how we handle multiple outputs.
So, an Integer output will be discrete-time, but a Real output still non-discrete time (assuming the inputs are non-discrete time).
* To handle the other case for GenerateEvents-functions.
* Forgot variability for inputs previously.
* State that variables in functions being discrete-time is a bit more complicated, with link.
* Add examples.
* Apply suggestions from code review
Co-authored-by: Henrik Tidefelt <henrikt@wolfram.com>

Author: HansOlsson

chapters/functions.tex

@@ -173,7 +173,7 @@ \section{Function as a Specialized Class}\label{function-as-a-specialized-class}
 \item
   For initialization of local variables of a function see \cref{initialization-and-binding-equations-of-components-in-functions}).
 \item
-  Components of a function will inside the function behave as though they had discrete-time variability.
+  Components of a function follow special variability rules where the \lstinline!GenerateEvents! annotation plays a central role, see \cref{discrete-time-expressions} for details.
 \end{itemize}
 
 Modelica functions have the following enhancements compared to a general Modelica \lstinline!class!:
@@ -1771,6 +1771,86 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve
 
 If the function is called in a context where events will not be generated (e.g., inside another function without {\lstinline!GenerateEvents = true!}) no special action is needed.
 \end{nonnormative}
+\begin{example}
+\lstinline!GenerateEvents! impacts variability according to \cref{variability-of-expressions}.
+The benefit of treating functions with \lstinline!GenerateEvents = true! in this way is that it makes it possible to construct functions behaving like the built-in event generating operators.
+E.g., it allows constructing a variant of \lstinline!integer()! that rounds towards closest \lstinline!Integer! instead of towards $-\inf$ that is usable in the same way as \lstinline!integer()!.
+\begin{lstlisting}[language=modelica]
+function nearestInteger
+  input Real r;
+  output Integer i;
+algorithm
+  i :=if (r > 0) then integer(floor(r + 0.5)) else integer(ceil(r - 0.5));
+end nearestInteger;
+\end{lstlisting}
+
+The following is an illustration of some trivial cases.
+\begin{lstlisting}[language=modelica]
+function greaterEqual
+  input Real x1;
+  input Real x2;
+  output Boolean b;
+algorithm
+  b := x1 >= x2;
+  annotation(GenerateEvents=true, LateInline=true);
+end greaterEqual;
+
+function greaterEqualWO
+  input Real x1;
+  input Real x2;
+  output Boolean b;
+algorithm
+  b := x1 >= x2;
+  annotation(LateInline=true);
+end greaterEqualWO;
+
+model M
+  Boolean b1 = greaterEqual(time, 1);
+  Boolean b2 = greaterEqualWO(time, 1) "Illegal";
+  Boolean b3 = noEvent(greaterEqual(time, 1)) "Illegal";
+  Boolean b4 = greaterEqualWO(if b1 then 2 else 0, 1);
+  Real z = if greaterEqualWO(time, 1) then 2 else 1;
+end M;
+
+function bad
+  input Real x1;
+  output Integer i;
+algorithm
+  i := greaterEqualWO(x1, 1) then 2 else 1;
+  annotation(GenerateEvents=true, LateInline=true);
+end bad;
+\end{lstlisting}
+
+In \lstinline!M!, there will be an event when \lstinline!time! becomes greater or equal to \lstinline!1!, and thus the discrete-time variable \lstinline!b1! can be bound to this function call even though it involves the non-discrete time variable \lstinline!time!.
+Both \lstinline!b2! and \lstinline!b3! are illegal, since the right hand sides have non-discrete-time variability.
+The variable \lstinline!z! is legal, since a \lstinline!Real! variable can have non-discrete time variability.
+The variable \lstinline!b4! is legal, since the function inputs have discrete-time variability.
+The function \lstinline!bad! demonstrates that similar restrictions (as for \lstinline!b2! and \lstinline!b3!) apply inside functions with {\lstinline!GenerateEvents = true!}.
+\begin{lstlisting}[language=modelica]
+function saturatedSquare
+  input Real x2;
+  output Real y;
+algorithm
+  if x2 > 1 then
+    y := 1;
+  else
+    y := x2^2;
+  end if;
+end saturatedSquare;
+
+function isBelowSat
+  input Real x1, x2;
+  output Boolean b;
+algorithm
+  b : = x1 < saturatedSquare(x2);
+  annotation (GenerateEvents=true, LateInline=true);
+end isBelowSat;
+\end{lstlisting}
+The function \lstinline!isBelowSat! demonstrates that it is possible to call functions that do not generate events (like \lstinline!saturatedSquare!) inside functions with {\lstinline!GenerateEvents = true!}.
+Combined, the last two examples demonstrate that {\lstinline!GenerateEvents = true!} does not propagate to called functions.
+
+The annotation \lstinline!LateInline=true! is not needed, but makes the issue more obvious in tools that normally inline function before checking variability.
+\end{example}
 \end{semantics}
 \end{annotationdefinition}
 

chapters/operatorsandexpressions.tex

@@ -1586,7 +1586,7 @@ \subsection{Evaluable Expressions}\label{evaluable-expressions}
 \item
   Evaluable parameter variables, see \cref{component-variability}.
 \item
-  Input variables in functions behave as though they were evaluable expressions.
+  Input variables in functions not having annotation \lstinline!GenerateEvents = true! (\cref{modelica:GenerateEvents}) behave as though they were evaluable 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 evaluable subexpressions is an evaluable expression.
 \item
@@ -1597,7 +1597,7 @@ \subsection{Evaluable Expressions}\label{evaluable-expressions}
   \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.
+    \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!Connections.isRoot(A.R)!
   \item
@@ -1646,10 +1646,13 @@ \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!: Function calls where the function has annotation \lstinline!GenerateEvents = true! (\cref{modelica:GenerateEvents}), the output does not contain a subtype of \lstinline!Real!, and any non-\lstinline!Real! inputs have discrete-time variability.
+  For a function call returning multiple return values (see \cref{output-formal-parameters-of-functions}) the variability is decided separately for each output.
 \item
   The functions \lstinline!pre!, \lstinline!edge!, and \lstinline!change! result in discrete-time expressions.
 \item
-  Expressions in functions behave as though they were discrete-time expressions.
+  Expressions in functions not having annotation \lstinline!GenerateEvents = true! (\cref{modelica:GenerateEvents}), behave as though they were discrete-time expressions.
 \end{itemize}
 
 Inside an \lstinline!if!-expression, \lstinline!if!-clause, \lstinline!while!-statement or \lstinline!for!-clause, that is controlled by a non-discrete-time (that is continuous-time, but not discrete-time) switching expression and not in the body of a \lstinline!when!-clause, it is not legal to have assignments to discrete-time variables, equations between discrete-time expressions, or real elementary relations/functions that should generate events.