Skip to content

Commit

Permalink
Change terminology 'normal parameter' -> 'non-evaluable parameter'
Browse files Browse the repository at this point in the history
  • Loading branch information
henrikt-ma committed Mar 14, 2023
1 parent 13f0d00 commit 3b05128
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 25 deletions.
15 changes: 8 additions & 7 deletions chapters/annotations.tex
Original file line number Diff line number Diff line change
Expand Up @@ -368,12 +368,12 @@ \section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{s
The annotation \lstinline!Evaluate! is only allowed for parameters and constants.

Setting \lstinline!Evaluate = true! for an evaluable parameter, means that it must be an evaluated parameter (i.e., its value must be determined during translation, similar to a constant).
For a normal parameter, it has no impact and it is recommended to issue a warning in most cases.
The exception for recommending this warning is when the parameter is normal due to dependency on a parameter with \lstinline!Evaluate = false!, as this could be a sign of intentional overriding of \lstinline!Evaluate = true!, see example below.
For a non-evaluable parameter, it has no impact and it is recommended to issue a warning in most cases.
The exception for recommending this warning is when the parameter is non-evaluable due to dependency on a parameter with \lstinline!Evaluate = false!, as this could be a sign of intentional overriding of \lstinline!Evaluate = true!, see example below.
For both evaluable parameters and constants, the model developer further proposes to utilize the value for symbolic processing.
A constant can never be changed after translation, and it is normal for its value to be used for symbolic processing even without \lstinline!Evaluate = true!.

For a parameter, \lstinline!Evaluate = false! ensures that the parameter is a normal parameter according to \cref{component-variability} (meaning it is not allowed to be used where an evaluable expression (\cref{evaluable-expressions}) is expected).
For a parameter, \lstinline!Evaluate = false! ensures that the parameter is a non-evaluable parameter according to \cref{component-variability} (meaning it is not allowed to be used where an evaluable expression (\cref{evaluable-expressions}) is expected).
For both parameters and constants -- even when the value can be determined during translation -- the model developer further proposes to not utilize the value for symbolic processing.

\begin{nonnormative}
Expand All @@ -397,13 +397,14 @@ \section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{s
end if;
end M_evaluable;

model M_normal
/* Here, 'bn' is normal, which in turn will cause 'b' to be normal,
* thereby preventing it from being determined during translation.
model M_non_evaluable
/* Here, 'bn' is non-evaluable, which in turn will cause 'b' to be
* non-evaluable, thereby preventing it from being determined during
* translation.
*/
extends M_evaluable(b = bn);
parameter Boolean bn = false annotation(Evaluate = false);
end M_normal;
end M_non_evaluable;
\end{lstlisting}
\end{example}
\end{semantics}
Expand Down
35 changes: 18 additions & 17 deletions chapters/classes.tex
Original file line number Diff line number Diff line change
Expand Up @@ -438,12 +438,12 @@ \section{Component Variability}\label{component-variability}
The declaration equation -- or \lstinline!start!-attribute if no declaration equation is given (see \cref{initialization-initial-equation-and-initial-algorithm}) -- is given by an evaluable expression (\cref{evaluable-expressions}).
\end{itemize}
It is also simply called an \firstuse[---]{evaluable parameter}.
An evaluable parameter does not change during transient analysis, with a value either determined during translation (similar to having prefix \lstinline!constant!, and is then called an \firstuse[parameter!evaluated]{evaluated parameter}) or by the initialization problem (similar to a \willintroduce{normal parameter}, see item below).
An evaluable parameter does not change during transient analysis, with a value either determined during translation (similar to having prefix \lstinline!constant!, and is then called an \firstuse[parameter!evaluated]{evaluated parameter}) or by the initialization problem (similar to a \willintroduce{non-evaluable parameter}, see item below).
At which of these stages the value is determined is tool dependent.
For further details, see \ref{parameters}.
\item
A variable \lstinline!np! declared with the \lstinline!parameter!\indexinline{parameter} prefix, is called a \firstuse[parameter!normal]{normal parameter variable}\index{component variability!normal parameter} unless it is an evaluable parameter.
It is also simply called a \firstuse[---]{normal parameter}.
A variable \lstinline!np! declared with the \lstinline!parameter!\indexinline{parameter} prefix, is called a \firstuse[parameter!non-evaluable]{non-evaluable parameter variable}\index{component variability!non-evaluable parameter} unless it is an evaluable parameter.
It is also simply called a \firstuse[---]{non-evaluable parameter}.
It does not change during transient analysis, with a value determined by the initialization problem.
For further details, see \ref{parameters}.
\item
Expand All @@ -457,7 +457,7 @@ \section{Component Variability}\label{component-variability}
For further details, see \ref{continuous-time-variables}.
\end{itemize}

The term \firstuse[---]{parameter variable} or just \firstuse[---]{parameter} refers to a variable that is either a normal or evaluable parameter variable.
The term \firstuse[---]{parameter variable} or just \firstuse[---]{parameter} refers to a variable that is either an evaluable or non-evaluable parameter variable.

The variability of expressions and restrictions on variability for declaration equations is given in \cref{variability-of-expressions}.

Expand Down Expand Up @@ -554,7 +554,7 @@ \subsection{Constants}\label{constants}

\subsection{Parameters}\label{parameters}

Parameter variables are divided into evaluable parameter variables and normal parameter variables, both defined in \cref{component-variability}.
Parameter variables are divided into evaluable parameter variables and non-evaluable parameter variables, both defined in \cref{component-variability}.

By the acyclic binding rule in \cref{acyclic-bindings-of-constants-and-parameters}, it follows that a value for an evaluable parameter is possible to obtain during translation, compare \cref{constants}.
Making use of that value during translation turns the evaluable parameter into an evaluated parameter, and it must be ensured that the parameter cannot be assigned a different value after translation, as this would invalidate the use of the original value during translation.
Expand All @@ -563,11 +563,11 @@ \subsection{Parameters}\label{parameters}
A particularly demanding aspect of this evaluation is the potential presence of external functions.
Hence, if it is known that a parameter won't be used by an evaluable expression, a user can make it clear that the external function is not meant to be evaluated during translation by using \lstinline!Evaluate = false!:
\begin{lstlisting}[language=modelica]
import length = Modelica.Utilities.Strings.length; /* Pure external function */
parameter Integer n = length("Hello"); /* Evaluable parameter */
import length = Modelica.Utilities.Strings.length; // Pure external function
parameter Integer n = length("Hello"); // Evaluable parameter
parameter Integer p = length("Hello")
annotation(Evaluate = false); /* Normal parameter */
parameter Boolean b = false; /* Evaluable parameter */
annotation(Evaluate = false); // Non-evaluable parameter
parameter Boolean b = false; // Evaluable parameter

/* Fulfillment of acyclic binding rule might cause evaluation of n;
* to break the cycle, a tool might evaluate either b, n, or both:
Expand All @@ -582,25 +582,26 @@ \subsection{Parameters}\label{parameters}
\end{example}

\begin{nonnormative}
For a parameter in a valid model, presence of \lstinline!Evaluate! (\cref{modelica:Evaluate}) makes it possible to tell immediately whether it is an evaluable or normal parameter, at least as long as the warning described in \cref{modelica:Evaluate} isn't triggered.
To see this, note that \lstinline!Evaluate = false! makes it a normal parameter by definition, and that \lstinline!Evaluate = true! would trigger the warning if the parameter is normal.
For a parameter in a valid model, presence of \lstinline!Evaluate! (\cref{modelica:Evaluate}) makes it possible to tell immediately whether it is an evaluable or non-evaluable parameter, at least as long as the warning described in \cref{modelica:Evaluate} isn't triggered.
To see this, note that \lstinline!Evaluate = false! makes it a non-evaluable parameter by definition, and that \lstinline!Evaluate = true! would trigger the warning if the parameter is non-evaluable.
\end{nonnormative}

\begin{nonnormative}
With every normal parameter, there is at least one reason why it isn't an evaluable parameter.
With every non-evaluable parameter, there is at least one reason why it isn't an evaluable parameter.
This information is useful to maintain in tools, as it allows generation of informative error messages when a violation of evaluable expression variability is detected.
For example:
\begin{lstlisting}[language=modelica]
parameter Integer n =
if b then 1 else 2; // Normal parameter due to variability of b.
parameter Boolean b(fixed = false); // Normal parameter due to fixed = false.
Real[n] x; // Variability error: n must be evaluable.
if b then 1 else 2; // Non-evaluable parameter due to variability of b.
parameter Boolean b(fixed = false);
// Non-evaluable parameter due to fixed = false.
Real[n] x; // Variability error: n must be evaluable.
initial equation
b = n > 3;
\end{lstlisting}
Here, a good error message for the variability error can include the information that the reason for \lstinline!n! being a normal parameter is that it has a dependency on the normal parameter \lstinline!b!.
Here, a good error message for the variability error can include the information that the reason for \lstinline!n! being a non-evaluable parameter is that it has a dependency on the non-evaluable parameter \lstinline!b!.

(Would evaluable and normal parameters have had different variability prefixes in their component declarations, it would have been possible to detect and report errors directly at the evaluable component declarations instead.)
(Would evaluable and non-evaluable parameters have had different variability prefixes in their component declarations, it would have been possible to detect and report errors directly at the evaluable component declarations instead.)
\end{nonnormative}

\begin{nonnormative}
Expand Down
2 changes: 1 addition & 1 deletion chapters/operatorsandexpressions.tex
Original file line number Diff line number Diff line change
Expand Up @@ -1530,7 +1530,7 @@ \subsection{Parameter Expressions}\label{parameter-expressions}
\item
Evaluable expressions.
\item
Normal parameter variables, see \cref{component-variability}.
Non-evaluable parameter variables, see \cref{component-variability}.
\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
Expand Down

0 comments on commit 3b05128

Please sign in to comment.