Merge pull request #3532 from HansOlsson/DetailedWhen

Detailed when

chapters/equations.tex

@@ -325,6 +325,7 @@ \subsubsection{Equations within When-Equations}\label{restrictions-on-equations-
   end when;
 \end{lstlisting}
 Here, variable \lstinline!y! is held constant when the \lstinline!when!-equation is deactivated and \lstinline!x! is computed from the first equation using the value of \lstinline!y! from the previous event instant.
+Note that during event iterations \lstinline!y! will be solved from a system of two equations.
 \end{nonnormative}
 
 \begin{example}
@@ -793,6 +794,12 @@ \section{Initialization, initial equation, and initial algorithm}\label{initiali
 
 Before the start of the integration, it must be guaranteed that for all variables \lstinline!v!, \lstinline!v = pre(v)!.
 If this is not the case for some variables \lstinline!vi!, \lstinline!pre(vi) := vi! must be set and an event iteration at the initial time must follow, so the model is re-evaluated, until this condition is fulfilled.
+In detail this means that during initialization initial equations and normal equations are solved with \lstinline!v! and \lstinline!pre(v)! as unknowns without any event iterations.
+Then only the normal equations are solved repeatedly (each time after \lstinline!v! is copied to \lstinline!pre(v)!) until \lstinline!v = pre(v)!.
+
+\begin{nonnormative}
+Tools may optimize initialization by not computing unnecessary \lstinline!pre(v)!, and only performing the event iteration if necessary.
+\end{nonnormative}
 
 A Modelica translator may first transform the continuous equations of a model, at least conceptually, to state space form.
 This may require to differentiate equations for index reduction, i.e., additional equations and, in some cases, additional unknown variables are introduced.

chapters/functions.tex

@@ -280,9 +280,9 @@ \section{Pure Modelica Functions}\label{pure-modelica-functions}
   Binding equations for external objects.
 \end{itemize}
 
-For initial equations, initial algorithms, and bindings it is an error
-if the function calls are part of systems of equations and thus have to
-be called multiple times.
+It is an error if an impure function call is part of a systems of equations (including linear systems), even if called in agreement with the restrictions above.
+The reason is that solving systems of equations generally requires expressions to be evaluated an unknown number of times.
+This includes the special handling of \lstinline!when initial()! during initialization.
 
 \begin{nonnormative}
 A tool is not allowed to perform any optimizations on function