Clarify variability of functions.

chapters/functions.tex

@@ -116,6 +116,29 @@ \subsection{Inheritance of Functions}\label{inheritance-of-functions}
 For example, it is possible to modify and extend a \lstinline!function! class to add default values for input variables.
 \end{nonnormative}
 
+A special case is defining a \lstinline!function! as a short-class definition with modifiers for inputs inside a model.
+These default values, unless overridden in the function call, will then be considered for variability similarly as if they were given in the function call, see \cref{function-variability}.
+
+\begin{example}
+Demonstrating the variability implications.
+Note that functions cannot directly use non-constants in enclosing scopes, so we cannot write \lstinline!input Real x1 = x;! directly in \lstinline!foo!.
+\begin{lstlisting}[language=modelica]
+model M
+  function foo
+    input Real x1;
+    input Real x2 = 2;
+    output Real y;
+  algorithm
+    y := x1 + x2;
+  end foo;
+  Real x = time;
+  function f1 = foo(x1 = x);
+  constant Real z = f1(x2 = 1); // Illegal since 'x' is seen as argument
+  constant Real z2 = f1(x1 = 2); // Legal, since 'x1' has a new value.
+end M;
+\end{lstlisting}
+\end{example}
+
 \section{Function as a Specialized Class}\label{function-as-a-specialized-class}
 
 The function concept in Modelica is a specialized class (\cref{specialized-classes}).

chapters/interface.tex

@@ -537,6 +537,9 @@ \section{Function-Compatibility or Function-Subtyping for Functions}\label{funct
   constraining interface of the function being redeclared.
 \end{itemize}
 
+Note that variability of function calls, see \cref{function-variability}, cannot be determined using just the interface of a function, as the variabilities of default argument expressions are not expressed by the interface.
+Hence a function redeclaration being function-compatible does not ensure that function calls will fulfill variability requirements, and tools must therefore check variability requirements separately.
+
 \begin{example}
 Demonstrating a redeclaration using a function-compatible function
 \begin{lstlisting}[language=modelica]
@@ -559,14 +562,16 @@ \section{Function-Compatibility or Function-Subtyping for Functions}\label{funct
   end UseDriveLine;
   Modelica.Mechanics.MultiBody.Interface.Frame_a frame_a;
   replaceable function gravity = GravityInterface;
+  constant Real failed[:] = gravity({1, 0, 0}); // May fail
 equation
   frame_a.f = gravity(frame_a.r0);
   // or gravity(position=frame_a.r0);
   frame_a.t = zeros(3);
 end Body;
 
 model PlanetSimulation
-  function sunGravity = PointMassGravity (m=2e30);
+  parameter Modelica.Units.SI.Mass mSun = 2e30;
+  function sunGravity = PointMassGravity (m = mSun);
   Body planet1(redeclare function gravity = sunGravity);
   Body planet2(redeclare function gravity = PointMassGravity (m=2e30));
   $\ldots$
@@ -577,6 +582,9 @@ \section{Function-Compatibility or Function-Subtyping for Functions}\label{funct
 \lstinline!GravityInterface! (no default for \lstinline!m!), but \lstinline!sunGravity!
 inside \lstinline!PlanetSimulation! is function-compatible with
 \lstinline!GravityInterface!.
+
+The constant \lstinline!failed! in \lstinline!planet1!, will violate variability constraints, whereas it will work in \lstinline!planet2!.
+The call \lstinline!gravity(frame_a.r0)! will work in both of them.
 \end{example}
 
 \section{Type Compatible Expressions}\label{type-compatible-expressions}

chapters/operatorsandexpressions.tex

@@ -1415,6 +1415,20 @@ \section{Variability of Expressions}\label{variability-of-expressions}
 \end{lstlisting}
 \end{example}
 
+\subsection{Function Variability}\label{function-variability}
+
+The variability of function calls needs to consider both the variability of arguments directly given in the function and the variability of the used default arguments, if any.
+This is especially a concern for functions given as a short class, see \cref{inheritance-of-functions}.
+This has additional implications for redeclarations, see \cref{function-compatibility}.
+The purity of the function, see \cref{pure-modelica-functions}, does not influence the variability of the function call.
+
+\begin{nonnormative}
+The reason the variability ignores if functions is declared as \lstinline!impure! is that even in this case variability does not depend on the function.
+Consider a function reading an external file and returning some value from that file.
+Different uses can have the file updated before the simulation (as a parameter-expression), or during the simulation (as a discrete-time expression).
+Thus it depends on the use case and the specific file, not the function itself, and it would even be possible to update the file in continuous time (as part of an algorithm) and still use the same function.
+\end{nonnormative}
+
 \subsection{Constant Expressions}\label{constant-expressions}
 
 Constant expressions\index{constant expression}\index{expression variability!constant} are: