Merge pull request modelica#3226 from HansOlsson/RemoveStart

Remove zero start value and explain alternative.

chapters/classes.tex

@@ -1397,6 +1397,12 @@ \section{Predefined Types and Classes}\label{predefined-types-and-classes}
 The definitions use \lstinline!RealType!\indexinline{RealType}, \lstinline!IntegerType!\indexinline{IntegerType}, \lstinline!BooleanType!\indexinline{BooleanType}, \lstinline!StringType!\indexinline{StringType}, \lstinline!EnumType!\indexinline{EnumType} as mnemonics corresponding to machine representations.
 These are called the \firstuse[primitive type]{primitive types}.
 
+\begin{definition}[Fallback value]\label{def:fallback-value}\index{fallback value}
+In situations where the \lstinline!start!-attribute would apply if provided, but the attribute is not provided, the \emph{fallback value} shall be used instead.
+Tools are recommended to give diagnostics when the fallback value is used.
+The fallback values for variables of the different predefined types are defined below.
+\end{definition}
+
 \subsection{Real Type}\label{real-type}
 
 The following is the predefined \lstinline!Real!\indexinline{Real} type:
@@ -1407,7 +1413,7 @@ \subsection{Real Type}\label{real-type}
   parameter StringType unit        = "" "Unit used in equations";
   parameter StringType displayUnit = "" "Default display unit";
   parameter RealType min = -Inf, max = +Inf; // Inf denotes a large value
-  parameter RealType start    = 0; // Initial value
+  parameter RealType start;            // Initial value
   parameter BooleanType fixed = true,  // default for parameter/constant;
                               = false; // default for other variables
   parameter RealType nominal;            // Nominal value
@@ -1431,6 +1437,8 @@ \subsection{Real Type}\label{real-type}
 The \lstinline!nominal! attribute is meant to be used for scaling purposes and to
 define tolerances in relative terms, see \cref{attributes-start-fixed-nominal-and-unbounded}.
 
+The fallback value is the closest value to $0.0$ consistent with the \lstinline!min! and \lstinline!max! bounds.
+
 \begin{nonnormative}
 For external functions in C89, \lstinline!RealType! maps to \lstinline[language=C]!double!.  In the mapping proposed in Annex~F of the C99 standard,
 \lstinline!RealType!/\lstinline[language=C]!double! matches the IEC~60559:1989 (ANSI/IEEE~754-1985) \lstinline[language=C]!double! format.
@@ -1444,7 +1452,7 @@ \subsection{Integer Type}\label{integer-type}
   IntegerType $\langle$$\mbox{\emph{value}}$$\rangle$; // Not an attribute; only accessed without dot-notation
   parameter StringType quantity = "";
   parameter IntegerType min = -Inf, max = +Inf;
-  parameter IntegerType start = 0; // Initial value
+  parameter IntegerType start;         // Initial value
   parameter BooleanType fixed = true,  // default for parameter/constant;
                               = false; // default for other variables
 equation
@@ -1459,14 +1467,16 @@ \subsection{Integer Type}\label{integer-type}
 
 The minimal recommended number range for \lstinline!IntegerType! is from -2147483648 to +2147483647, corresponding to a two's-complement 32-bit integer implementation.
 
+The fallback value is the closest value to $0$ consistent with the \lstinline!min! and \lstinline!max! bounds.
+
 \subsection{Boolean Type}\label{boolean-type}
 
 The following is the predefined \lstinline!Boolean!\indexinline{Boolean} type:
 \begin{lstlisting}[language=modelica]
 type Boolean // Note: Defined with Modelica syntax although predefined
   BooleanType $\langle$$\mbox{\emph{value}}$$\rangle$; // Not an attribute; only accessed without dot-notation
   parameter StringType quantity = "";
-  parameter BooleanType start = false; // Initial value
+  parameter BooleanType start;         // Initial value
   parameter BooleanType fixed = true,  // default for parameter/constant;
                               = false, // default for other variables
 end Boolean;
@@ -1475,14 +1485,16 @@ \subsection{Boolean Type}\label{boolean-type}
 \index{start@\robustinline{start}!attribute of \robustinline{Boolean}}%
 \index{fixed@\robustinline{fixed}!attribute of \robustinline{Boolean}}%
 
+The fallback value is \lstinline!false!.
+
 \subsection{String Type}\label{string-type}
 
 The following is the predefined \lstinline!String!\indexinline{String} type:
 \begin{lstlisting}[language=modelica]
 type String // Note: Defined with Modelica syntax although predefined
   StringType $\langle$$\mbox{\emph{value}}$$\rangle$; // Not an attribute; only accessed without dot-notation
   parameter StringType quantity = "";
-  parameter StringType start = "";     // Initial value
+  parameter StringType start;          // Initial value
   parameter BooleanType fixed = true,  // default for parameter/constant;
                               = false, // default for other variables
 end String;
@@ -1493,6 +1505,8 @@ \subsection{String Type}\label{string-type}
 
 A \lstinline!StringType! value (such as $\langle\mathit{value}\rangle$ or other textual attributes of built-in types) may contain any Unicode data (and nothing else).
 
+The fallback value is \lstinline!""!.
+
 \subsection{Enumeration Types}\label{enumeration-types}
 
 A declaration of the form
@@ -1604,7 +1618,7 @@ \subsubsection{Attributes of Enumeration Types}\label{attributes-of-enumeration-
   EnumType $\langle$$\mbox{\emph{value}}$$\rangle$; // Not an attribute; only accessed without dot-notation
   parameter StringType quantity = "";
   parameter EnumType min = e1, max = en;
-  parameter EnumType start = e1;       // Initial value
+  parameter EnumType start;             // Initial value
   parameter BooleanType fixed = true,  // default for parameter/constant;
                               = false; // default for other variables
   constant EnumType e1 = $\ldots$;
@@ -1615,6 +1629,8 @@ \subsubsection{Attributes of Enumeration Types}\label{attributes-of-enumeration-
 end E;
 \end{lstlisting}
 
+The fallback value is the \lstinline!min! bound.
+
 \begin{nonnormative}
 Since the attributes and enumeration literals are on the same
 level, it is not possible to use the enumeration attribute names

chapters/equations.tex

@@ -773,14 +773,14 @@ \section{Initialization, initial equation, and initial algorithm}\label{initiali
 \lstinline!start!-values of variables having \lstinline!fixed = false! can be used as initial guesses, in case iterative solvers are used in the initialization phase.
 
 \begin{nonnormative}
-In case of iterative solver failure, it is recommended to specially report those variables for which the solver needs an initial guess, but which only have the default value of the \lstinline!start!-attribute as defined in \cref{predefined-types-and-classes}, since the lack of appropriate initial guesses is a likely cause of the solver failure.
+In case of iterative solver failure, it is recommended to specially report those variables for which the solver needs an initial guess, but where the fallback value (see \cref{predefined-types-and-classes}) has been applied, since the lack of appropriate initial guesses is a likely cause of the solver failure.
 \end{nonnormative}
 
-If a parameter has a modifier for the \lstinline!start!-attribute, does not have \lstinline!fixed = false!, and neither has a binding equation nor is part of a record having a binding equation, the modifier for the \lstinline!start!-attribute can be used to add a parameter binding equation assigning the parameter to that \lstinline!start! value.
+If a parameter has a value for the \lstinline!start!-attribute, does not have \lstinline!fixed = false!, and neither has a binding equation nor is part of a record having a binding equation, the value for the \lstinline!start!-attribute can be used to add a parameter binding equation assigning the parameter to that \lstinline!start! value.
 In this case a diagnostic message is recommended in a simulation model.
 
 \begin{nonnormative}
-This is used in libraries to give non-zero defaults so that users can quickly combine models and simulate without setting parameters; but still easily find the parameters that need to be set.
+This is used in libraries to give rudimentary defaults so that users can quickly combine models and simulate without setting parameters; but still easily find the parameters that should be set properly.
 \end{nonnormative}
 
 All variables declared as \lstinline!parameter! having \lstinline!fixed = false! are treated as unknowns during the initialization phase, i.e.\ there must be additional equations for them -- and the \lstinline!start!-value can be used as a guess-value during initialization.