Extend variability rules and fix invalid example (modelica#2526)

* Fix and extend example on variability rules
* Clarify the role of rules based on expression variability
* Elaborate a little bit on the 'perfect matching rule'
* A variable declared with 'constant' prefix is unaffected by the initialization problem
Closes modelica#2525

chapters/classes.tex

@@ -376,8 +376,11 @@ \subsection{Component Variability Prefixes discrete, parameter, constant}\double
 
 \begin{itemize}
 \item
-  A variable \lstinline!vc! declared with the parameter or constant prefixes remains
-  constant during transient analysis.
+  A variable \lstinline!vc! declared with \lstinline!constant! prefix remains constant during transient analysis,
+  with a value that is unaffected by the initialization problem.
+\item
+  A variable \lstinline!vc! declared with the \lstinline!parameter! prefix remains constant during transient analysis,
+  with a value determined by the initialization problem.
 \item
   A \emph{discrete-time} variable \lstinline!vd! has a vanishing time derivative between events.
   Note that this is not the same as saying that \lstinline!der(vd)=0! almost everywhere,

chapters/equations.tex

@@ -586,9 +586,10 @@ \section{Synchronous Data-flow Principle and Single Assignment Rule}\doublelabel
 {[}\emph{If computation or communication time has to be simulated, this
 property has to be explicitly modeled}{]}.
 
-\item  There must exist a perfect matching of variables to equations after flattening
-(perfect matching rule - previously called single assignment rule);
-see also globally balanced \autoref{balanced-models}.
+\item There must exist a perfect matching of variables to equations after flattening, where a variable can only
+be matched to equations that can contribute to solving for the variable
+(\emph{perfect matching rule}% TODO: Use \firstuse instead of \emph
+--- previously called \emph{single assignment rule}); see also globally balanced \autoref{balanced-models}.
 \end{enumerate}
 
 \section{Events and Synchronization}\doublelabel{events-and-synchronization}

chapters/operatorsandexpressions.tex

@@ -1221,10 +1221,17 @@ \section{Variability of Expressions}\doublelabel{variability-of-expressions}
   continuous-time variability
 \end{itemize}
 
-For an assignment \lstinline!v:=expr! or binding equation \lstinline!v=expr!, \lstinline!v! must be declared
-to be at least as variable as \lstinline!expr!.
-
+While many invalid models can be rejected based on the declared variabilities of variables alone (without the concept of expression
+variability), the following rules both help enforcing compliance of computed solutions to declared variability, and impose additional
+restrictions that simplify reasoning and reporting of errors:
 \begin{itemize}
+\item
+  For an assignment \lstinline!v:=expr! or binding equation \lstinline!v=expr!, \lstinline!v! must be declared
+  to be at least as variable as \lstinline!expr!.
+\item
+  When determining whether an equation can contribute to solving for a variable \lstinline!v! (for instance,
+  when applying the perfect matching rule, see \autoref{synchronous-data-flow-principle-and-single-assignment-rule}),
+  the equation can only be considered contributing if the resulting solution would be at most as variable as \lstinline!v!.
 \item
   The right-hand side expression in a binding equation {[}\emph{that is,}
   \lstinline!expr!{]} of a parameter component and of the base type attributes
@@ -1351,20 +1358,30 @@ \subsection{Discrete-Time Expressions}\doublelabel{discrete-time-expressions}
 crossing functions do not become active between events.}{]}\\
 
 \begin{example}
+The (underdetermined) model \lstinline!Test! below illustrates two kinds of consequences due to variability constraints.
+First, it contains variability errors for declaration equations and assignments.
+Second, it illustrates the impact of variability on the matching of equations to variables, which can
+lead to violation of the perfect matching rule.
 \begin{lstlisting}[language=modelica]
 model Constants
   parameter Real p1 = 1;
-  constant Real c1 = p1 + 2; // error, no constant expression
+  constant Real c1 = p1 + 2; // error, not a constant expression
   parameter Real p2 = p1 + 2; // fine
 end Constants;
 model Test
   Constants c1(p1=3); // fine
   Constants c2(p2=7); // fine, declaration equation can be modified
-  Boolean b;
   Real x;
+  Boolean b1 = noEvent(x > 1); // error, since b1 is a discrete-time variable
+                               // and noEvent(x > 1) is not discrete-time.
+  Boolean b2;
+  Integer i1;
+  Integer i2;
+algorithm
+  i1 := x; // error, assignment to variable of lesser variability.
 equation
-  b = noEvent(x > 1) // error, since b is a discrete-time expr. and
-                     // noEvent(x > 1) is not a discrete-time expr.
+  b2 = noEvent(x > 1); // no variability error, but equation cannot be matched.
+  i2 = x;              // no variability error, and can be matched to x.
 end Test;
 \end{lstlisting}
 \end{example}