classes.tex

\chapter{Classes, Predefined Types, and Declarations}\label{class-predefined-types-and-declarations}

The fundamental structuring unit of modeling in Modelica is the class.
Classes provide the structure for objects, also known as instances.
Classes can contain equations which provide the basis for the executable
code that is used for computation in Modelica. Conventional algorithmic
code can also be part of classes. All data objects in Modelica are
instantiated from classes, including the basic data types -- \lstinline!Real!,
\lstinline!Integer!, \lstinline!String!, \lstinline!Boolean! -- and enumeration types, which are built-in
classes or class schemata.

Declarations are the syntactic constructs needed to introduce classes
and objects (i.e., components).

\section{Access Control -- Public and Protected Elements}\label{access-control-public-and-protected-elements}

Members of a Modelica class can have two levels of visibility: \lstinline!public!\indexinline{public} or \lstinline!protected!\indexinline{protected}.
The default is \lstinline!public! if nothing else is specified.

A protected element, \lstinline!P!, in classes and components shall not be accessed via dot notation (e.g., \lstinline!A.P!, \lstinline!a.P!, \lstinline!a[1].P!, \lstinline!a.b.P!, \lstinline!.A.P!; but there is no restriction on using \lstinline!P! or \lstinline!P.x! for a protected element \lstinline!P!).
They shall not be modified or redeclared except for modifiers applied to protected elements in a base class modification (not inside any component or class) and the modifier on the declaration of the protected element.

\begin{example}
\begin{lstlisting}[language=modelica]
package A
  model B
  protected
    parameter Real x;
  end B;
protected
  model C end C;
public
  model D
    C c; // Legal use of protected class C from enclosing scope
    extends A.B(x=2); // Legal modifier for x in derived class
                      // also x.start=2 and x(start=2) are legal.
    Real y=x; // Legal use of x in derived class
  end D;
  model E
    A.B a(x=2);  // Illegal modifier, also x.start=2 and x(start=2) are illegal
    A.C c;       // Illegal use of protected class C
    model F=A.C; // Illegal use of protected class C
  end E;
end A;
\end{lstlisting}
\end{example}

All elements defined under the heading \lstinline!protected! are regarded as protected.  All other elements (i.e., defined
under the heading \lstinline!public!, without headings or in a separate file) are public (i.e.\ not protected).  Regarding
inheritance of protected and public elements, see \cref{inheritance-of-protected-and-public-elements}.


\section{Double Declaration not Allowed}\label{double-declaration-not-allowed}

The name of a declared element shall not have the same name as any other
element in its partially flattened enclosing class. However, the internal
flattening of a class can in some cases be interpreted as having two
elements with the same name; these cases are described in \cref{simultaneous-inner-outer-declarations},
and \cref{redeclaration}.

\begin{example}
\begin{lstlisting}[language=modelica]
record R
  Real x;
end R;
model M // wrong Modelica model
  R R; // not correct, since component name and type specifier are identical
equation
  R.x = 0;
end M;
\end{lstlisting}
\end{example}

\section{Declaration Order and Usage before Declaration}\label{declaration-order-and-usage-before-declaration}

Variables and classes can be used before they are declared.

\begin{nonnormative}
In fact, declaration order is only significant for:
\begin{itemize}
\item
  Functions with more than one input variable called with positional arguments, \cref{positional-or-named-input-arguments-of-functions}.
\item
  Functions with more than one output variable, \cref{output-formal-parameters-of-functions}.
\item
  Records that are used as arguments to external functions, \cref{records}.
\item
  Enumeration literal order within enumeration types, \cref{enumeration-types}.
\end{itemize}
\end{nonnormative}

\section{Component Declarations}\label{component-declarations}

Component declarations are described in this section.

A \firstuse[component!declaration]{component declaration} is an element of a class definition that generates a component.
A component declaration specifies (1) a component name, i.e., an identifier, (2) the class to be flattened in order to generate the component, and (3) an optional \lstinline!Boolean! parameter expression.
Generation of the component is suppressed if this parameter expression evaluates to false.
A component declaration may be overridden by an element-redeclaration.

A \firstuse{component} or \firstuse{variable} is an instance (object) generated by a component declaration.
Special kinds of components are scalar, array, and attribute.

\subsection{Syntax and Examples of Component Declarations}\label{syntax-and-examples-of-component-declarations}

The formal syntax of a component declaration clause is given by the following syntactic rules:
\begin{lstlisting}[language=grammar]
component-clause:
  type-prefix type-specifier [ array-subscripts ] component-list

type-prefix :
  [ flow | stream ]
  [ discrete | parameter | constant ] [ input | output ]

type-specifier :
  name

component-list :
  component-declaration { "," component-declaration }

component-declaration :
  declaration [ condition-attribute ] comment

condition-attribute:
  if expression

declaration :
  IDENT [ array-subscripts ] [ modification ]
\end{lstlisting}

\begin{nonnormative}
The declaration of a component states the type, access, variability, data flow, and other properties of the component.
A \lstinline[language=grammar]!component-clause! i.e., the whole declaration, contains type prefixes followed by a \lstinline[language=grammar]!type-specifier! with optional \lstinline[language=grammar]!array-subscripts! followed by a \lstinline[language=grammar]!component-list!.

There is no semantic difference between variables declared in a single declaration or in multiple declarations.
For example, regard the following single declaration (\lstinline[language=grammar]!component-clause!) of two matrix variables:
\begin{lstlisting}[language=modelica]
Real[2,2] A, B;
\end{lstlisting}
That declaration has the same meaning as the following two
declarations together:
\begin{lstlisting}[language=modelica]
Real[2,2] A;
Real[2,2] B;
\end{lstlisting}
The array dimension descriptors may instead be placed after the
variable name, giving the two declarations below, with the same meaning
as in the previous example:
\begin{lstlisting}[language=modelica]
Real A[2,2];
Real B[2,2];
\end{lstlisting}
The following declaration is different, meaning that the variable
a is a scalar but B is a matrix as above:
\begin{lstlisting}[language=modelica]
Real a, B[2,2];
\end{lstlisting}
\end{nonnormative}

\subsection{Component Declaration Static Semantics}\label{component-declaration-static-semantics}

If the \lstinline[language=grammar]!type-specifier! of the component declaration denotes a built-in type (\lstinline!RealType!, \lstinline!IntegerType!, etc.), the flattened or instantiated component has the same type.

% Seems sufficient to just have \indexinline variant of 'partial' in index.
A class defined with \lstinline!partial!\indexinline{partial} in the \lstinline[language=grammar]!class-prefixes! is called a \firstuse[---]{partial} class.
Such a class is allowed to be incomplete, and cannot be instantiated in a simulation model; useful, e.g., as a base class.

If the \lstinline[language=grammar]!type-specifier! of the component does not denote a built-in type, the name of the type is looked up (\cref{static-name-lookup}).
The found type is flattened with a new environment and the partially flattened enclosing class of the component.
It is an error if the type is partial in a simulation model, or if a simulation model itself is partial.
The new environment is the result of merging
\begin{itemize}
\item
  the modification of enclosing class element-modification with the same name as the component
\item
  the modification of the component declaration
\end{itemize}
in that order.

Array dimensions shall be scalar non-negative parameter expressions of type \lstinline!Integer!, a reference to a type (which must an enumeration type or \lstinline!Boolean!, see \cref{enumeration-types}), or the colon operator denoting that the array dimension is left unspecified (see \cref{array-declarations}).  All variants can also be part of short class definitions.

\begin{example}
Variables with array dimensions:
\begin{lstlisting}[language=modelica]
model ArrayVariants
  type T = Real[:];                       // Unspecified size for type
  parameter T x = ones(4);
  parameter T y[3] = ones(3, 4);
  parameter Real a[2] = ones(2);          // Specified using Integer
  parameter Real b[2, 0] = ones(2, 0);    // Size 0 is allowed
  parameter Real c[:] = ones(0);          // Unspecified size for variable
  parameter Integer n = 0;
  Real z[n*2] = cat(1, ones(n), zeros(n));// Parameter expressions are allowed
  Boolean notV[Boolean] = {true, false};  // Indexing with type
end ArrayVariants;
\end{lstlisting}
\end{example}

The rules for components in functions are described in \cref{function-as-a-specialized-class}.

Conditional declarations of components are described in \cref{conditional-component-declaration}.

\subsubsection{Declaration Equations}\label{declaration-equations}

An environment that defines the value of a component of built-in type is said to define a \firstuse{declaration equation} associated with the declared component.
These are a subset of the binding equations, see \cref{equation-categories}.
% Note: In variability-of-expressions, it's called a "binding equation", not "declaration equation".
The declaration equation is of the form \lstinline!x = expression! defined by a component declaration, where \lstinline!expression! must not have higher variability than the declared component \lstinline!x! (see \cref{variability-of-expressions}).
Unlike other equations, a declaration equation can be overridden (replaced or removed) by an element modification.

For declarations of vectors and matrices, declaration equations are associated with each element.

Only components of the specialized classes \lstinline!type!, \lstinline!record!, \lstinline!operator record!, and \lstinline!connector!, or components of classes inheriting from \lstinline!ExternalObject! may have declaration equations.
See also the corresponding rule for algorithms, \cref{restrictions-on-assigned-variables}.

\subsubsection{Prefix Rules}\label{prefix-rules}

A \firstuse{prefix} is property of an element of a class definition which can be present or not be present, e.g., \lstinline!final!, \lstinline!public!, \lstinline!flow!.

Variables declared with the \lstinline!flow! or the \lstinline!stream! type prefix shall be a subtype of \lstinline!Real!.

Type prefixes (that is, \lstinline!flow!, \lstinline!stream!, \lstinline!discrete!, \lstinline!parameter!, \lstinline!constant!, \lstinline!input!, \lstinline!output!) shall only be applied for type,
record and connector components -- see also record specialized class, \cref{specialized-classes}.

An exception is \lstinline!input! for components whose type is of the special class function type (these can only be used for function formal parameters and has special semantics, see \cref{functional-input-arguments-to-functions}), and the \lstinline!input! prefix is not applied to the elements of the component and is allowed even if the elements have \lstinline!input! or \lstinline!output! prefix.

In addition, instances of classes extending from \lstinline!ExternalObject! may have type prefixes \lstinline!parameter! and \lstinline!constant!, and in functions also type prefixes
\lstinline!input! and \lstinline!output!, see \cref{external-objects}.

The type prefixes \lstinline!flow!, \lstinline!stream!, \lstinline!input! and \lstinline!output! of a structured component (except as described above) are also applied to the elements of the component (this is done after verifying that the type prefixes occurring on elements of the component are correct; e.g.\ the \lstinline!flow! prefix can be used on a record component and all the record elements will generate zero-sum equations, even if elements of a record shall not be declared with the \lstinline!flow! prefix).  When any of the type prefixes \lstinline!flow!, \lstinline!stream!, \lstinline!input! and \lstinline!output! are applied for a structured component, no element of the component may have any of these type prefixes.  The corresponding rules for the type prefixes \lstinline!discrete!, \lstinline!parameter! and \lstinline!constant! are described in \cref{variability-of-structured-entities} for structured components.

\begin{example}
\lstinline!input! can only be used, if none of the elements has a \lstinline!flow!, \lstinline!stream!, \lstinline!input! or \lstinline!output! type prefix.
\end{example}

The prefixes \lstinline!input!\indexinline{input} and \lstinline!output!\indexinline{output} have a slightly different semantic meaning depending on the context where they are used:
\begin{itemize}
\item
  In \emph{functions}, these prefixes define the computational causality
  of the function body, i.e., given the variables declared as \lstinline!input!, the
  variables declared as \lstinline!output! are computed in the function body, see
  \cref{function-call}.
\item
  In \emph{simulation} \emph{models} and \emph{blocks} (i.e., on the top level of a model or block that shall be simulated), these prefixes define the interaction with the environment where the simulation model or block is used.
  Especially, the \lstinline!input! prefix defines that values for such a variable have to be provided from the simulation environment and the \lstinline!output! prefix defines that the values of the corresponding variable can be directly utilized in the simulation environment, see the notion of \emph{globally balanced} in \cref{balanced-models}.
\item
  In component \emph{models} and \emph{blocks}, the \lstinline!input! prefix defines
  that a binding equation has to be provided for the corresponding
  variable when the component is utilized in order to guarantee a
  locally balanced model (i.e., the number of local equations is
  identical to the local number of unknowns), see \cref{balanced-models}.
\begin{example}
\begin{lstlisting}[language=modelica]
block FirstOrder
  input Real u;
  $\ldots$
end FirstOrder;
model UseFirstOrder
  FirstOrder firstOrder(u=time); // binding equation for u
  $\ldots$
end UseFirstOrder;
\end{lstlisting}
\end{example}
  The \lstinline!output! prefix does not have a particular effect in a model or block
  component and is ignored.
\item
  In \emph{connectors}, prefixes \lstinline!input! and \lstinline!output! define that the
  corresponding connectors can only be connected according to block
  diagram semantics, see \cref{connect-equations-and-connectors} (e.g., a connector with an \lstinline!output!
  variable can only be connected to a connector where the corresponding
  variable is declared as \lstinline!input!). There is the restriction that
  connectors which have at least one variable declared as \lstinline!input! must be
  externally connected, see \cref{balanced-models} (in order to get a locally
  balanced model, where the number of local unknowns is identical to the
  number of unknown equations). Together with the block diagram
  semantics rule this means, that such connectors must be connected
  \emph{exactly once externally}.
\item
  In \emph{records}, prefixes \lstinline!input! and \lstinline!output! are not allowed, since
  otherwise a record could not be, e.g., passed as input argument to a
  function.
\end{itemize}

\subsection{Acyclic Bindings of Constants and Parameters}\label{acyclic-bindings-of-constants-and-parameters}

For a constant or parameter \lstinline!v! with declaration equation, the expression of the declaration equation in the flattended model must not depend on \lstinline!v! itself, neither directly nor indirectly via other variables' declaration equations.
To satisfy this condition, dependencies shall be removed as needed by applying simplifications based on values of constants (except with \lstinline!Evaluate = false!) and all other \willintroduce{evaluable parameters} (\cref{component-variability-prefixes-discrete-parameter-constant}) that don't depend on \lstinline!v!.
It is not permitted to expand a non-scalar declaration equation into scalar equations to satisfy the condition.

That the value of an evaluable parameter is used for these simplifications does not mean that it has to be determined during translation, but if \lstinline!v! is found to be an evaluable parameter, then a Modelica tool will be able to break all cycles involving \lstinline!v! by making some (possibly none or all) of the other evaluable parameters determined during translation.
Hence, evaluation of a constant or evaluable parameter can never require solving systems of equations; they can always be sorted so that they can be solved one at a time with the natural causality (i.e., the declaration equation is used to determine the value of the component to which it belongs).

\begin{example}
Direct and indirect cyclic dependency:
\begin{lstlisting}[language=modelica]
/* All of the following are illegal: */
parameter Real r = 2 * sin(r); // Depends directly on r.
parameter Real p = 2 * q;      // Indirect dependency on p via q = sin(p).
parameter Real q = sin(p);     // Indirect dependency on q via p = 2 * q.
\end{lstlisting}
\end{example}

\begin{example}
While declaration equations must not be cyclical, the use of initial equations can still introduce valid cyclic dependencies between parameters:
\begin{lstlisting}[language=modelica]
  parameter Real p = 2 * q; // This is the only declaration equation.
  parameter Real q(fixed = false);
initial equation
  q = sin(p); // OK, not a declaration equation.
\end{lstlisting}
\end{example}

\begin{example}
Breaking cyclic dependency.
\begin{lstlisting}[language=modelica]
model ABCD
  parameter Real A[n, n];
  parameter Integer n = size(A, 1);
end ABCD;

final ABCD a;
// Illegal cyclic dependency between size(a.A, 1) and a.n.

ABCD b(redeclare Real A[2, 2] = [1, 2; 3, 4]);
// Legal since size of A is no longer dependent on n.

ABCD c(n = 2); // Legal since n is no longer dependent on the size of A.

partial model PartialLumpedVolume
  parameter Boolean use_T_start = true "= true, use T_start, otherwise h_start"
    annotation(Dialog(tab = "Initialization"), Evaluate = true);
  parameter Medium.Temperature T_start=if use_T_start then system.T_start else
      Medium.temperature_phX(p_start,h_start,X_start)
    annotation(Dialog(tab = "Initialization", enable = use_T_start));
  parameter Medium.SpecificEnthalpy h_start=if use_T_start then
      Medium.specificEnthalpy_pTX(p_start, T_start, X_start) else Medium.h_default
    annotation(Dialog(tab = "Initialization", enable = not use_T_start));
end PartialLumpedVolume;
// Cycle for T_start and h_start, but still valid since cycle disappears
// when evaluating use_T_start

// The unexpanded bindings have illegal cycles for both x and y
// (even if they would disappear if bindings were expanded).
model HasCycles
  parameter Integer n = 10;
  final constant Real A[3, 3] = [0, 0, 0; 1, 0, 0; 2, 3, 0];
  parameter Real y[3] = A * y + ones(3);
  parameter Real x[n] = cat(1, {3.4}, x[1:(n-1)]);
end HasCycles;
\end{lstlisting}
\end{example}

\subsection{Component Variability Prefixes discrete, parameter, constant}\label{component-variability-prefixes-discrete-parameter-constant}

The prefixes \lstinline!discrete!, \lstinline!parameter!, \lstinline!constant! of a component declaration are called \firstuse[variability!prefix]{variability prefixes}\index{component variability}\index{declared variability}\index{variability!declared|see{declared variability}} and define in which situation the variable values of a component are initialized (see \cref{events-and-synchronization} and \cref{initialization-initial-equation-and-initial-algorithm}) and when they are changed during transient analysis (i.e., solution of initial value problem of the hybrid DAE):
\begin{itemize}
\item
  A variable \lstinline!vc! declared with \lstinline!constant!\indexinline{constant} prefix remains constant during transient analysis, with a value that is unaffected by the initialization problem (i.e., determined during translation).
  This is called a \firstuse[---]{constant}, or \firstuse[constant!variable]{constant variable}\index{component variability!constant}.
\item
  A variable \lstinline!ep! is called a \firstuse[parameter!evaluable]{evaluable parameter variable}\index{component variability!evaluable parameter} if all of the following applies:
  \begin{itemize}
  \item
    It is declared with the \lstinline!parameter!\indexinline{parameter} prefix.
  \item
    It has \lstinline!fixed = true!.
  \item
    It does not have annotation \lstinline!Evaluate = false!.
  \item
    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}
  An evaluable parameter remains constant 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).
  At which of these stages the value is determined is tool dependent.
\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[parameter!normal]{normal parameter}.
  It remains constant during transient analysis, with a value determined by the initialization problem.
\item
  A \firstuse[discrete-time!variable]{discrete-time variable}\index{component variability!discrete-time} \lstinline!vd! is a variable that is discrete-valued (that is, not of \lstinline!Real! type) or assigned in a \lstinline!when!-clause.
  The \lstinline!discrete!\indexinline{discrete} prefix may be used to clarify that a variable is discrete-time.
  It has a vanishing time derivative between events.
  Note that this is not the same as saying that \lstinline!der(vd) = 0! almost everywhere, as the derivative is not even defined at the events.
  It is not allowed to apply \lstinline!der! to discrete-time variables.
  During transient analysis the variable can only change its value at event instants (see \cref{events-and-synchronization}).
\item
  A \firstuse[continuous-time!variable]{continuous-time variable}\index{component variability!continuous-time} is a \lstinline!Real! variable without any prefix that is not assigned in a \lstinline!when!-clause.
  A continuous-time variable \lstinline!vn! may have a non-vanishing time derivative (provided \lstinline!der(vn)! is allowed this can be expressed as \lstinline!der(vn) <> 0!) and may also change its value discontinuously at any time during transient analysis (see \cref{events-and-synchronization}).
  It may also contain a combination of these effects.
  Regarding existence of \lstinline!der(vn)!, see \cref{modelica:der}.
\end{itemize}

Components declared as \lstinline!constant! shall have an associated declaration equation with a constant expression, if the constant is directly in the simulation model, or used in the simulation model.
The value of a constant can be modified after it has been given a value, unless the constant is declared \lstinline!final! or modified with a \lstinline!final! modifier.
A constant without an associated declaration equation can be given one by using a modifier.

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

\begin{nonnormative}
With every normal 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.
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!.

(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.)
\end{nonnormative}

\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.
\end{nonnormative}

By the acyclic binding rule in \cref{acyclic-bindings-of-constants-and-parameters}, it follows that the value of a constant or evaluable parameter to be used in simplifications is possible to obtain by evaluation of an evaluable expression where values are available for all component subexpressions.

\begin{example}
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 */
parameter Integer p = length("Hello")
  annotation(Evaluate = false);                    /* Normal 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:
 */
parameter Real x = if b and n < 3 then 1 - x else 0;

/* Fulfillment of acyclic binding rule cannot cause evaluation of p;
 * to break the cycle, evaluation of b is the only option:
 */
parameter Real y = if b and p < 3 then 1 - y else 0;
\end{lstlisting}
\end{example}

\begin{nonnormative}
Related to evaluable parameters, the term \firstuse{structural parameter} is also used in the Modelica community.
This term has no meaning defined by the specification, and the meaning may vary from one context to another.
One common meaning, however, is that in the context of a given tool, a parameter is called \emph{structural} if the tool has decided to evaluate it because it controls some variation of the equation structure that the tool is unable to leave undecided during translation.
With this interpretation of \emph{structural parameter}, it follows that such a structural parameter must also be an evaluable parameter, while there are typically many evaluable parameters that are not structural.
\end{nonnormative}

If a \lstinline!Real! variable is declared with the prefix \lstinline!discrete!\indexinline{discrete} it must in a simulation model be assigned in a \lstinline!when!-clause, either by an assignment or an equation.
The variable assigned in a \lstinline!when!-clause shall not be defined in a sub-component of \lstinline!model! or \lstinline!block! specialized class.
(This is to keep the property of balanced models.)

A \lstinline!Real! variable assigned in a \lstinline!when!-clause is a discrete-time variable,
even though it was not declared with the prefix \lstinline!discrete!. A \lstinline!Real!
variable not assigned in any \lstinline!when!-clause and without any type prefix is
a continuous-time variable.

The default variability for \lstinline!Integer!, \lstinline!String!,
\lstinline!Boolean!, or \lstinline!enumeration!
variables is discrete-time, and it is not possible to declare
continuous-time \lstinline!Integer!, \lstinline!String!, \lstinline!Boolean!, or
\lstinline!enumeration! variables.

\begin{nonnormative}
The restriction that discrete-valued variables (of type \lstinline!Boolean!, etc) cannot be
declared with continuous-time variability is one of the foundations of the expression variability rules
that will ensure that any discrete-valued expression has at most discrete-time variability, see \cref{variability-of-expressions}.
\end{nonnormative}

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

\begin{nonnormative}
Note that discrete-time \emph{expressions} include parameter expressions, whereas discrete-time \emph{variables} do not include parameter variables.
The reason can intuitively be explained as follows
\begin{itemize}
\item When discussing variables we also want to consider them as left-hand-side variables in assignments, and thus a lower variability would be a problem.
\item When discussing expressions we only consider them as right-hand-side expressions in those assignment, and thus a lower variability can automatically be included; and additionally we have sub-expressions where lower variability is not an issue.
\end{itemize}

For \lstinline!Real! variables we can distinguish two subtly different categories: discrete-time and piecewise constant, where the discrete-time variables are a subset of all piecewise constant variables.
The \lstinline!Real! variables declared with the prefix \lstinline!discrete! is a subset of the discrete-time \lstinline!Real! variables.
For a \lstinline!Real! variable, being discrete-time is equivalent to being assigned in a \lstinline!when!-clause.
A variable used as argument to \lstinline!pre! outside a \lstinline!when!-clause must be discrete-time.

\begin{lstlisting}[language=modelica]
model PiecewiseConstantReals
  discrete Real xd1 "Must be assigned in a when-clause, discrete-time";
  Real xd2 "Assigned in a when-clause (below) and thus discrete-time";
  Real xc3 "Not discrete-time, but piecewise constant";
  Real x4 "Piecewise constant, but changes between events";
equation
  when sample(1, 1) then
    xd1 = pre(xd1) + 1;
    xd2 = pre(xd2) + 1;
  end when;
  // It is legal to use pre for a discrete-time variable outside of when
  xc3 = xd1 + pre(xd2);
  // But pre(xc3) would not be legal
  x4 = if noEvent(cos(time) > 0.5) then 1.0 else -1.0;
end PiecewiseConstantReals;
\end{lstlisting}

Tools may optimize code to only compute and store discrete-time variables at events.
Tools may extend that optimization to piece-wise constant variables that only change at events (in the example above \lstinline!xc3!).
As shown above variables can be piecewise constant, but change at times that are not events (in the example above \lstinline!x4!).
It is not clear how a tool could detect and optimize the latter case.

A \lstinline!parameter! variable is constant during simulation.
This prefix gives the library designer the possibility to express that the physical equations in a library are only valid if some of the used components are constant during simulation.
The same also holds for discrete-time and constant variables.
Additionally, the \lstinline!parameter! prefix allows a convenient graphical user interface in an experiment environment, to support quick changes of the most important constants of a compiled model.
In combination with an \lstinline!if!-equation, a \lstinline!parameter! prefix allows removing parts of a model before the symbolic processing of a model takes place in order to avoid variable causalities in the model (similar to \lstinline!#ifdef! in C).
Class parameters can be sometimes used as an alternative.

Example:
\begin{lstlisting}[language=modelica]
model Inertia
  parameter Boolean state = true;
  $\ldots$
equation
  J*a = t1 - t2;
  if state then // code which is removed during symbolic
    der(v) = a; // processing, if state=false
    der(r) = v;
   end if;
end Inertia;
\end{lstlisting}

A constant variable is similar to a parameter with the difference
that constants cannot be changed after translation and usually not
changed after they have been given a value. It can be used to represent
mathematical constants, e.g.
\begin{lstlisting}[language=modelica]
final constant Real PI=4*atan(1);
\end{lstlisting}

There are no continuous-time \lstinline!Boolean!, \lstinline!Integer! or \lstinline!String!
variables. In the rare cases they are needed they can be
faked by using \lstinline!Real! variables, e.g.:
\begin{lstlisting}[language=modelica]
  Boolean off1, off1a;
  Real off2;
equation
  off1 = s1 < 0;
  off1a = noEvent(s1 < 0); // error, since off1a is discrete
  off2 = if noEvent(s2 < 0) then 1 else 0; // possible
  u1 = if off1 then s1 else 0; // state events
  u2 = if noEvent(off2 > 0.5) then s2 else 0; // no state events
\end{lstlisting}

Since \lstinline!off1! is a discrete-time variable, state events are
generated such that \lstinline!off1! is only changed at event instants.
Variable \lstinline!off2! may change its value during continuous integration.
Therefore, \lstinline!u1! is guaranteed to be continuous during continuous
integration whereas no such guarantee exists for \lstinline!u2!.
\end{nonnormative}

\subsubsection{Variability of Structured Entities}\label{variability-of-structured-entities}

For elements of structured entities with variability prefixes the most
restrictive of the variability prefix and the variability of the
component wins (using the default variability for the component if there
is no variability prefix on the component).

\begin{example}
\begin{lstlisting}[language=modelica]
record A
  constant Real pi=3.14;
  Real y;
  Integer i;
end A;

parameter A a;
  // a.pi is a constant
  // a.y and a.i are parameters

A b;
  // b.pi is a constant
  // b.y is a continuous-time variable
  // b.i is a discrete-time variable
\end{lstlisting}
\end{example}

\subsection{Conditional Component Declaration}\label{conditional-component-declaration}

A component declaration can have a \lstinline!condition-attribute!: \lstinline!if!~\emph{expression}.

\begin{example}
\begin{lstlisting}[language=modelica]
  parameter Integer level(min=1)=1;
  Motor motor;
  Level1 component1(J=J) if level==1 "Conditional component";
  Level2 component2 if level==2 "Conditional component";
  Level3 component3(J=component1.J) if level<2 "Conditional component";
  // Illegal modifier on component3 since component1.J is conditional
  // Even if we can see that component1 always exist if component3 exist
equation
  connect(component1$\ldots$, $\ldots$) "Connection to conditional component 1";
  connect(component2.n, motor.n) "Connection to conditional component 2";
  connect(component3.n, motor.n) "Connection to conditional component 3";
  component1.u=0; // Illegal
\end{lstlisting}
\end{example}

The \emph{expression} must be a \lstinline!Boolean! scalar expression, and must be a parameter expression.

\begin{nonnormative}
A parameter expression is required since it shall be evaluated at compile time.
\end{nonnormative}

A redeclaration of a component shall not include a condition attribute;
and the condition attribute is kept from the original declaration (see
\cref{interface-compatibility-or-subtyping}).

If the \lstinline!Boolean! expression is false the component (including its modifier) is removed from the flattened DAE, and connections to/from the component are removed.
A component declared with a condition-attribute can only be modified and/or used in connections.

\begin{nonnormative}
Adding the component and then removing it ensures that the component is valid.

If a connect equation defines the connection of a non-conditional component \lstinline!c1! with a conditional component \lstinline!c2! and \lstinline!c2! is de-activated, then \lstinline!c1! must still be a declared element.
\end{nonnormative}

If the condition is true for a public connector containing flow
variables the connector must be connected from the outside.

\begin{nonnormative}
The reason for this restriction is that the default flow equation is probably incorrect (since it could otherwise
be an unconditional connector) and the model cannot check that connector is connected.
\end{nonnormative}

\section{Class Declarations}\label{class-declarations}

Essentially everything in Modelica is a \firstuse{class}, from the predefined classes \lstinline!Integer! and \lstinline!Real!, to large packages such as the Modelica standard library.
The description consists of a class definition, a modification environment that modifies the class definition, an optional list of dimension expressions if the class is an array class, and a lexically
enclosing class for all classes.

The object generated by a class is called an \firstuse{instance}.
An instance contains zero or more components (i.e., instances), equations, algorithms, and local classes.
An instance has a type (\cref{interface-or-type}).
% Commenting out parts from old glossary that seem excessive here.
%Basically, two instances have same type, if their important attributes are the same and their public components and classes have pair wise equal identifiers and types.
%More specific type equivalence definitions are given, e.g., for functions.

\begin{example}
A rather typical structure of a Modelica class is
shown below. A class with a name, containing a number of declarations
followed by a number of equations in an equation section.

\begin{lstlisting}[language=modelica]
class ClassName
  Declaration1
  Declaration2
  $\ldots$
equation
  equation1
  equation2
  $\ldots$
end ClassName;
\end{lstlisting}
\end{example}

The following is the formal syntax of class definitions, including the special variants described in later sections.

An \firstuse{element} is part of a class definition, and is one of: class definition, component declaration, or \lstinline!extends!-clause.
Component declarations and class definitions are called \firstuse[named element]{named elements}.
An element is either inherited from a base class or local.

\begin{lstlisting}[language=grammar]
class-definition :
  [ encapsulated ] class-prefixes
  class-specifier

class-prefixes :
  [ partial ]
  ( class | model | [ operator ] record | block | [ expandable ] connector | type |
  package | [ ( pure | impure ) ] [ operator ] function | operator )

class-specifier :
  long-class-specifier | short-class-specifier | der-class-specifier

long-class-specifier :
  IDENT description-string composition end IDENT
  | extends IDENT [ class-modification ] description-string
    composition end IDENT

short-class-specifier :
  IDENT "=" base-prefix name [ array-subscripts ]
  [ class-modification ] comment
  | IDENT "=" enumeration "(" ( [enum-list] | ":" ) ")" comment

der-class-specifier :
  IDENT "=" der "(" name "," IDENT { "," IDENT } ")" comment

base-prefix :
  [ input | output ]

enum-list : enumeration-literal { "," enumeration-literal}

enumeration-literal : IDENT comment

composition :
  element-list
  { public element-list |
    protected element-list |
    equation-section |
    algorithm-section
  }
  [ external [ language-specification ]
  [ external-function-call ] [ annotation ] ";" ]
  [ annotation ";" ]
\end{lstlisting}

\subsection{Short Class Definitions}\label{short-class-definitions}

A class definition of the form
\begin{lstlisting}[language=modelica]
class IDENT1 = IDENT2 class-modification;
\end{lstlisting}

is identical, except that IDENT2 may be replaceable and for the lexical
scope of modifiers, where the short class definition does not introduce
an additional lexical scope for modifiers, to the longer form

\begin{lstlisting}[language=modelica]
class IDENT1
  extends IDENT2 class-modification;
end IDENT1;
\end{lstlisting}

An exception to the above is that if the short class definition is declared as \lstinline!encapsulated!, then the modifiers follow the rules for encapsulated classes and cannot be looked up in the enclosing scope.

\begin{example}
Demonstrating the difference in scopes:
\begin{lstlisting}[language=modelica]
model Resistor
  parameter Real R;
  $\ldots$
end Resistor;
model A
  parameter Real R;
  replaceable model Load=Resistor(R=R) constrainedby TwoPin;
  // Correct, sets the R in Resistor to R from model A.
  replaceable model LoadError
    extends Resistor(R=R);
    // Gives the singular equation R=R, since the right-hand side R
    // is searched for in LoadError and found in its base class Resistor.
  end LoadError constrainedby TwoPin;
  encapsulated model Load2=.Resistor(R=2); // Ok
  encapsulated model LoadR=.Resistor(R=R); // Illegal
  Load a,b,c;
  ConstantSource $\ldots$;
  $\ldots$
end A;
\end{lstlisting}
\end{example}

A short class definition of the form
\begin{lstlisting}[language=modelica]
type TN = T[N] (optional modifier);
\end{lstlisting}

where N represents arbitrary array dimensions, conceptually yields an
array class

\begin{lstlisting}[language=modelica]
'array' TN
  T[n] _ (optional modifiers);
'end' TN;
\end{lstlisting}

Such an array class has exactly one anonymous component (\_); see also \cref{restriction-on-combining-base-classes-and-other-elements}.
When a component of such an array class type is flattened, the resulting flattened component type is an array type with the same dimensions as \_ and with the optional modifier applied.

\begin{example}
The types of \lstinline!f1! and \lstinline!f2! are identical:
\begin{lstlisting}[language=modelica]
type Force = Real[3](unit={"Nm","Nm","Nm"});
Force f1;
Real f2[3](unit={"Nm","Nm","Nm"});
\end{lstlisting}
\end{example}

If a short class definition inherits from a partial class the new class definition will be partial, regardless of whether it is declared with the prefix \lstinline!partial! or not.

\begin{example}
\begin{lstlisting}[language=modelica]
replaceable model Load=TwoPin;
Load R; // Error unless Load is redeclared since TwoPin is a partial class.
\end{lstlisting}
\end{example}

If a short class definition does not specify any specialized class the new class definition will inherit the specialized class (this rule applies iteratively and also for redeclare).

A \lstinline[language=grammar]!base-prefix! applied in the \lstinline[language=grammar]!short-class-definition! does not influence its type, but is applied to components declared of this type or types derived from it; see also \cref{restriction-on-combining-base-classes-and-other-elements}.

\begin{example}
\begin{lstlisting}[language=modelica]
type InArgument = input Real;
type OutArgument = output Real[3];

function foo
  InArgument u; // Same as: input Real u
  OutArgument y; // Same as: output Real[3] y
algorithm
  y:=fill(u,3);
end foo;

Real x[:]=foo(time);
\end{lstlisting}
\end{example}

\subsection{Restriction on combining base classes and other elements}\label{restriction-on-combining-base-classes-and-other-elements}

It is not legal to combine other components or base classes with an extends from an array class, a class with non-empty \lstinline[language=grammar]!base-prefix!, a \firstuse{simple type} (\lstinline!Real!, \lstinline!Boolean!, \lstinline!Integer!, \lstinline!String! and enumeration types), or any class transitively extending from an array class, a class with non-empty \lstinline[language=grammar]!base-prefix!, or a simple type.

\begin{example}
\begin{lstlisting}[language=modelica]
model Integrator
  input Real u;
  output Real y = x;
  Real x;
equation
  der(x) = u;
end Integrator;

model Integrators = Integrator[3]; // Legal

model IllegalModel
  extends Integrators;
  Real x; // Illegal combination of component and array class
end IllegalModel;

connector IllegalConnector
  extends Real;
  Real y; // Illegal combination of component and simple type
end IllegalConnector;
\end{lstlisting}
\end{example}

\subsection{Local Class Definitions -- Nested Classes}\label{local-class-definitions-nested-classes}

The local class should be statically flattenable with the partially flattened enclosing class of the local class apart from local class components that are \lstinline!partial! or \lstinline!outer!.  The environment is the modification of any enclosing class element modification with the same name as the local class, or an empty environment.

The unflattened local class together with its environment becomes an
element of the flattened enclosing class.

\begin{example}
The following example demonstrates parameterization of a local class:
\begin{lstlisting}[language=modelica]
model C1
  type Voltage = Real(nominal=1);
  Voltage v1, v2;
end C1;

model C2
  extends C1(Voltage(nominal=1000));
end C2;
\end{lstlisting}

Flattening of class \lstinline!C2! yields a local class \lstinline!Voltage! with \lstinline!nominal! modifier \lstinline!1000!.
The variables \lstinline!v1! and \lstinline!v2! are instances of this local class and thus have a nominal value of 1000.
\end{example}

\section{Specialized Classes}\label{specialized-classes}

Specialized kinds of classes\index{specialized class} (earlier known as \emph{restricted classes}\index{restricted class|see{specialized class}})
% The difference between the set of specializations given here and those that are defined below need some sort of explanation.
\lstinline!record!, \lstinline!type!, \lstinline!model!, \lstinline!block!, \lstinline!package!, \lstinline!function! and \lstinline!connector!
have the properties of a general class, apart from restrictions.
Moreover, they have additional properties called \firstuse[enhancement!specialized class]{enhancements}.
The definitions of the specialized classes are given below (additional restrictions on inheritance are in \cref{restrictions-on-the-kind-of-base-class}):
\begin{itemize}
\item \lstinline!record!\indexinline{record} --
Only public sections are allowed in the definition or in any of its components (i.e., \lstinline!equation!, \lstinline!algorithm!, \lstinline!initial equation!, \lstinline!initial algorithm! and \lstinline!protected! sections are not allowed).  The elements of a record shall not have prefixes \lstinline!input!, \lstinline!output!, \lstinline!inner!, \lstinline!outer!, \lstinline!stream,! or \lstinline!flow!.  Enhanced with implicitly available record constructor function, see \cref{record-constructor-functions}.  The components directly declared in a record may only be of specialized class record or type.

\item \lstinline!type!\indexinline{type} --
May only be predefined types, enumerations, array of type, or classes extending from type.

\item \lstinline!model!\indexinline{model} --
The normal modeling class in Modelica.

\item \lstinline!block!\indexinline{block} --
Same as \lstinline!model! with the restriction that each connector component of a \lstinline!block! must have prefixes \lstinline!input! and/or \lstinline!output! for all connector variables.

\begin{nonnormative}
The purpose is to model input/output blocks of block diagrams.  Due to the restrictions on \lstinline!input! and \lstinline!output! prefixes,
connections between blocks are only possible according to block diagram semantic.
\end{nonnormative}

\item \lstinline!function!\indexinline{function} --
See \cref{function-as-a-specialized-class} for restrictions and enhancements of functions. Enhanced to allow the function to contain an external function interface.

\begin{nonnormative}
Non-\lstinline!function! specialized classes do not have this property.
\end{nonnormative}

\item \lstinline!connector!\index{connector@\robustinline{connector}|hyperpageit} --
Only public sections are allowed in the definition or in any of its components (i.e., \lstinline!equation!, \lstinline!algorithm!, \lstinline!initial equation!, \lstinline!initial algorithm! and \lstinline!protected! sections are not allowed).

Enhanced to allow \lstinline!connect! to components of connector classes.  The elements of a connector shall not have prefixes \lstinline!inner!, or \lstinline!outer!.  May only contain components of specialized class \lstinline!connector!, \lstinline!record! and \lstinline!type!.

\item \lstinline!package!\indexinline{package} --
May only contain declarations of classes and constants.  Enhanced to allow \lstinline!import! of elements of packages.  (See also \cref{packages} on packages.)

\item \lstinline!operator record!\indexinline{operator record} --
Similar to \lstinline!record!; but operator overloading is possible, and due to this the typing rules are different, see \cref{interface-or-type-relationships}.  It is not legal to extend from an \lstinline!operator record! (or \lstinline!connector! inheriting from \lstinline!operator record!), except if the new class is an \lstinline!operator record! or \lstinline!connector! that is declared as a short class definition, whose modifier is either empty or only modify the default attributes for the component elements directly inside the \lstinline!operator record!.  An \lstinline!operator record! can only extend from an \lstinline!operator record!.  It is not legal to extend from any of its enclosing scopes.  (See \cref{overloaded-operators}).

\item \lstinline!operator!\indexinline{operator} --
Similar to \lstinline!package!; but may only contain declarations of functions.  May only be placed directly in an \lstinline!operator record!.  (See also \cref{overloaded-operators}).

\item \lstinline!operator function!\indexinline{operator function} --
Shorthand for an \lstinline!operator! with exactly one function; same restriction as \lstinline!function! class and in addition may only be placed directly in an \lstinline!operator record!.
\begin{nonnormative}
A function declaration
\begin{lstlisting}[language=modelica]
operator function foo $\ldots$ end foo;
\end{lstlisting}
is conceptually treated as
\begin{lstlisting}[language=modelica]
operator foo function foo1
  $\ldots$
end foo1; end foo;
\end{lstlisting}
\end{nonnormative}

\end{itemize}

Additionally only components which are of specialized classes \lstinline!record!, \lstinline!type!, \lstinline!operator record!, and connector classes based on any of those can be used as component references in normal expressions and in the left hand side of assignments, subject to normal type compatibility rules.
Additionally components of connectors may be arguments of \lstinline!connect!-equations, and any component can be used as argument to the \lstinline!ndims! and \lstinline!size!-functions, or for accessing elements of that component (possibly in combination with array indexing).

\begin{example}
Use of \lstinline!operator!:
\begin{lstlisting}[language=modelica]
operator record Complex
  Real re;
  Real im;
  $\ldots$
  encapsulated operator function '*'
    import Complex;
    input Complex c1;
    input Complex c2;
    output Complex result
  algorithm
     result := Complex(re=c1.re*c2.re - c1.im*c2.im,
                      im=c1.re*c2.im + c1.im*c2.re);
   end '*';
end Complex;
record MyComplex
  extends Complex; // Error; extending from enclosing scope.
  Real k;
end MyComplex;
operator record ComplexVoltage = Complex(re(unit="V"),im(unit="V")); // allowed
\end{lstlisting}
\end{example}

\section{Balanced Models}\label{balanced-models}

\begin{nonnormative}
In this section restrictions for \lstinline!model! and \lstinline!block! classes are present, in order that missing or too many equations can be detected and localized by a Modelica translator before using the respective \lstinline!model! or \lstinline!block! class.  A non-trivial case is demonstrated in the following example:
\begin{lstlisting}[language=modelica]
partial model BaseCorrelation
  input Real x;
  Real y;
end BaseCorrelation;

model SpecialCorrelation // correct in Modelica 2.2 and 3.0
  extends BaseCorrelation(x=2);
equation
  y=2/x;
end SpecialCorrelation;

model UseCorrelation // correct according to Modelica 2.2
  // not valid according to Modelica 3.0
  replaceable model Correlation=BaseCorrelation;
  Correlation correlation;
equation
  correlation.y=time;
end UseCorrelation;

model Broken // after redeclaration, there is 1 equation too much in Modelica 2.2
  UseCorrelation example(redeclare Correlation=SpecialCorrelation);
end Broken;
\end{lstlisting}

In this case one can argue that both \lstinline!UseCorrelation! (adding an acausal equation) and \lstinline!SpecialCorrelation! (adding a default to an input) are correct.  Still, when combined they
lead to a model with too many equations, and it is not possible to determine which model is incorrect without strict rules -- as the ones defined here.

In Modelica 2.2, model \lstinline!Broken! will work with some models.
However, by just redeclaring it to model \lstinline!SpecialCorrelation!, an
error will occur and it will be very difficult in a larger model to
figure out the source of this error.

In Modelica 3.0, model \lstinline!UseCorrelation! is no longer allowed
and the translator will give an error. In fact, it is guaranteed that a
redeclaration cannot lead to an unbalanced model any more.
\end{nonnormative}

The restrictions below apply after flattening -- i.e.\ inherited components are included -- possibly modified.  The corresponding restrictions on connectors and connections are in
\cref{restrictions-of-connections-and-connectors}.

\begin{definition}[Local number of unknowns]\index{local number of unknowns}
The local number of unknowns of a \lstinline!model! or \lstinline!block! class is the sum based on the components:
\begin{itemize}
\item
  For each declared component of specialized class \lstinline!type! (\lstinline!Real!, \lstinline!Integer!, \lstinline!String!, \lstinline!Boolean!, enumeration and arrays of those, etc.) or \lstinline!record!, or \lstinline!operator record! not declared as \lstinline!outer!, it is the number of unknown variables inside it (i.e., excluding parameters and constants and counting the elements after expanding all records, operator record, and arrays to a set of scalars of primitive types).
\item
  Each declared component of specialized class \lstinline!type! or \lstinline!record! declared as \lstinline!outer! is ignored.
  \begin{nonnormative}
  I.e., all variables inside the component are treated as known.
  \end{nonnormative}
\item
  For each declared component of specialized class \lstinline!connector! component,
  it is the number of unknown variables inside it (i.e., excluding
  parameters and constants and counting the elements after expanding all
  records and arrays to a set of scalars of primitive types).
\item
  For each declared component of specialized class \lstinline!block! or \lstinline!model!, it is
  the sum of the number of inputs and flow variables in the (top
  level) public connector components of these components (and counting
  the elements after expanding all records and arrays to a set of
  scalars of primitive types).
\end{itemize}
\end{definition}

\begin{definition}[Local equation size]\index{local equation size}
The local equation size of a \lstinline!model! or \lstinline!block! class is the sum of the following numbers:
\begin{itemize}
\item
  The number of equations defined locally (i.e.\ not in any \lstinline!model! or \lstinline!block! component), including binding equations, and equations generated from \lstinline!connect!-equations.
  \begin{nonnormative}
  This includes the proper count for \lstinline!when!-clauses (see \cref{when-equations}), and algorithms (see \cref{algorithm-sections}), and is also used for
  the flat Hybrid DAE formulation (see \cref{modelica-dae-representation}).
  \end{nonnormative}
\item
  The number of input and flow variables present in each (top-level) public connector component.
  \begin{nonnormative}
  This represents the number of connection equations that will be provided when the class is used.
  \end{nonnormative}
\item
  The number of (top-level) public input variables that neither are connectors nor have binding equations.
  \begin{nonnormative}
  I.e., top-level inputs are treated as known variables.  This represents the number of binding equations that will be provided when the class is used.
  \end{nonnormative}
\end{itemize}
\end{definition}

\begin{nonnormative}
To clarify top-level inputs without binding equation (for
non-inherited inputs binding equation is identical to declaration
equation, but binding equations also include the case where another
model extends \lstinline!M! and has a modifier on \lstinline!u! giving the value):
\begin{lstlisting}[language=modelica]
model M
  input Real u;
  input Real u2=2;
end M;
\end{lstlisting}

Here \lstinline!u! and \lstinline!u2! are top-level inputs and not connectors. The
variable \lstinline!u2! has a binding equation, but \lstinline!u! does not have a binding
equation. In the equation count, it is assumed that an equation for \lstinline!u! is
supplied when using the model.
\end{nonnormative}

\begin{definition}[Locally balanced]\index{locally balanced}\index{balanced!locally}
A \lstinline!model! or \lstinline!block! class is locally balanced if the \emph{local number of unknowns} is identical to the \emph{local equation size} for all legal values of constants and parameters.
\end{definition}

\begin{nonnormative}
Here, \emph{legal values} must respect final bindings and min/max-restrictions.
A tool shall verify the \emph{locally balanced} property for the actual values of parameters and constants in the simulation model.
It is a quality of implementation for a tool to verify this property in general, due to arrays of (locally) undefined sizes, conditional declarations, \lstinline!for!-loops etc.
\end{nonnormative}

\begin{definition}[Globally balanced]\index{globally balanced}\index{balanced!globally}
Similarly as locally balanced, but including all unknowns and equations
from all components. The global number of unknowns is computed by
expanding all unknowns (i.e.\ excluding parameters and constants) into a
set of scalars of primitive types. This should match the global equation
size defined as:
\begin{itemize}
\item
  The number of equations defined (included in any \lstinline!model! or \lstinline!block! component), including equations generated from \lstinline!connect!-equations.
\item
  The number of input and flow variables present in each (top-level) public connector component.
\item
  The number of (top-level) public input variables that neither are connectors nor have binding equations.
  \begin{nonnormative}
  I.e., top-level inputs are treated as known variables.
  \end{nonnormative}
\end{itemize}
\end{definition}

The following restrictions hold:
\begin{itemize}
\item
  In a non-partial \lstinline!model! or \lstinline!block!, all non-connector inputs of \lstinline!model! or \lstinline!block! components must have binding equations.
  \begin{nonnormative}
  E.g.\ if the model contains a component, \lstinline!firstOrder! (of specialized class \lstinline!model!) and \lstinline!firstOrder! has
  \lstinline!input Real u! then there must be a binding equation for \lstinline!firstOrder.u!.
  \end{nonnormative}
\item
  A component declared with the \lstinline!inner! or \lstinline!outer! prefix shall not be of a
  class having top-level public connectors containing inputs.
\item
  In a declaration of a component of a record, connector, or simple type, modifiers can be applied to any element, and these are also considered for the equation count.
\begin{example}
\begin{lstlisting}[language=modelica]
Flange support(phi=phi, tau=torque1+torque2) if use_support;
\end{lstlisting}
  If \lstinline!use_support=true!, there are two additional equations for \lstinline!support.phi! and \lstinline!support.tau! via the modifier.
\end{example}
\item
  In other cases (declaration of a component of a \lstinline!model! or \lstinline!block! class, modifiers on extends, and modifier on short class definitions):  Modifiers for components shall only contain redeclarations of replaceable elements and binding equations.  The binding equations in modifiers for components may in these cases only be for parameters, constants, inputs and variables having a default binding equation.
\item
  All non-partial \lstinline!model! and \lstinline!block! classes must be locally balanced.
  \begin{nonnormative}
  This means that the local number of unknowns equals the local equation size.
  \end{nonnormative}
\end{itemize}

Based on these restrictions, the following strong guarantee can be given:
\begin{itemize}
\item All simulation models and blocks are globally balanced.
\end{itemize}

\begin{nonnormative}
Therefore the number of unknowns equal to the number of equations of a simulation model or block, provided that every used non-partial \lstinline!model! or \lstinline!block! class is locally balanced.
\end{nonnormative}

\begin{example}
\emph{Example 1:}
\begin{lstlisting}[language=modelica]
connector Pin
  Real v;
  flow Real i;
end Pin;

model Capacitor
  parameter Real C;
  Pin p, n;
  Real u;
equation
  0 = p.i + n.i;
  u = p.v - n.v;
  C*der(u) = p.i;
end Capacitor;
\end{lstlisting}

Model \lstinline!Capacitor! is a locally balanced model according to the following analysis:

Locally unknown variables: \lstinline!p.i!, \lstinline!p.v!, \lstinline!n.i!, \lstinline!n.v!, \lstinline!u!

%TODO-FORMAT Should this be verbatim code instead?
Local equations:
\begin{align*}
0 &= p.i + n.i;\\
u &= p.v - n.v;\\
C \cdot \text{der}(u) &= p.i;
\end{align*}
and 2 equations corresponding to the 2 flow variables \lstinline!p.i! and \lstinline!n.i!.

These are 5 equations in 5 unknowns (locally balanced model).  A more detailed analysis would reveal that this is structurally non-singular, i.e.\ that
the hybrid DAE will not contain a singularity independent of actual values.

If the equation \lstinline!u = p.v - n.v! would be missing in the \lstinline!Capacitor! model, there would be 4 equations in 5 unknowns and the model
would be locally unbalanced and thus simulation models in which this model is used would be usually structurally singular and thus not solvable.

If the equation \lstinline!u = p.v - n.v! would be replaced by the equation \lstinline!u = 0! and the equation \lstinline!C*der(u) = p.i! would be
replaced by the equation \lstinline!C*der(u) = 0!, there would be 5 equations in 5 unknowns (locally balanced), but the equations would be singular,
regardless of how the equations corresponding to the flow variables are constructed because the information that \lstinline!u! is constant is given twice
in a slightly different form.
\end{example}

\begin{example}
\emph{Example 2:}
\begin{lstlisting}[language=modelica]
connector Pin
  Real v;
  flow Real i;
end Pin;

partial model TwoPin
  Pin p,n;
end TwoPin;

model Capacitor
  parameter Real C;
  extends TwoPin;
  Real u;
equation
  0 = p.i + n.i;
  u = p.v - n.v;
  C*der(u) = p.i;
end Capacitor;

model Circuit
  extends TwoPin;
  replaceable TwoPin t;
  Capacitor c(C=12);
equation
  connect(p, t.p);
  connect(t.n, c.p);
  connect(c.n, n);
end Circuit;
\end{lstlisting}

Since \lstinline!t! is partial we cannot check whether this is a globally balanced model, but we can check that \lstinline!Circuit! is locally balanced.

Counting on model \lstinline!Circuit! results in the following balance sheet:

Locally unknown variables (8): \lstinline!p.i!, \lstinline!p.v!, \lstinline!n.i!, \lstinline!n.v!, and 2
flow variables for \lstinline!t! (\lstinline!t.p.i!, \lstinline!t.n.i!), and 2 flow variables for \lstinline!c! (\lstinline!c.p.i!, \lstinline!c.n.i!).

Local equations:
\begin{align*} \text{p.v} &= \text{t.p.v};\\
0 &= \text{p.i}-\text{t.p.i};\\
\text{c.p.v} &= \text{t.n.v};\\
0 &= \text{c.p.i}+\text{t.n.i};\\
\text{n.v} &= \text{c.n.v};\\
0 &= \text{n.i}-\text{c.n.i};
\end{align*}
and 2 equation corresponding to the flow variables \lstinline!p.i!, \lstinline!n.i!.

In total we have 8 scalar unknowns and 8 scalar equations, i.e., a locally balanced model (and this feature holds for any models used for the replaceable component \lstinline!t!).

Some more analysis reveals that this local set of equations and
unknowns is structurally non-singular. However, this does not provide
any guarantees for the global set of equations, and specific
combinations of models that are locally non-singular may lead to a
globally singular model.
\end{example}

\begin{example}
\emph{Example 3:}
\begin{lstlisting}[language=modelica]
import Modelica.Units.SI;

partial model BaseProperties
  "Interface of medium model for all type of media"
  parameter Boolean preferredMediumStates=false;
  constant Integer nXi "Number of independent mass fractions";
  InputAbsolutePressure     p;
  InputSpecificEnthalpy     h;
  InputMassFraction         Xi[nXi];
  SI.Temperature            T;
  SI.Density                d;
  SI.SpecificInternalEnergy u;

  connector InputAbsolutePressure = input SI.AbsolutePressure;
  connector InputSpecificEnthalpy = input SI.SpecificEnthalpy;
  connector InputMassFraction = input SI.MassFraction;
end BaseProperties;
\end{lstlisting}

The use of connector here is a special design pattern.
The variables \lstinline!p!, \lstinline!h!, \lstinline!Xi! are marked as input to get correct equation count.
Since they are connectors they should neither be given binding equations in derived classes nor when using the model.
The design pattern is to give textual equations for them (as below); using \lstinline!connect!-equations for these connectors would be possible (and would work) but is not part of the design.

This partial model defines that \lstinline!T!, \lstinline!d!, \lstinline!u! can be computed from
the medium model, provided \lstinline!p!, \lstinline!h!, \lstinline!Xi! are given.  Every medium with
one or multiple substances and one or multiple phases, including
incompressible media, has the property that \lstinline!T!, \lstinline!d!, \lstinline!u! can be computed
from \lstinline!p!, \lstinline!h!, \lstinline!Xi!. A particular medium may have different ``independent
variables'' from which all other intrinsic thermodynamic variables can
be recursively computed. For example, a simple air model could be
defined as:
\begin{lstlisting}[language=modelica]
model SimpleAir "Medium model of simple air. Independent variables: p,T"
  extends BaseProperties(nXi = 0,
     p(stateSelect = if preferredMediumStates then StateSelect.prefer
                       else StateSelect.default),
     T(stateSelect = if preferredMediumStates then StateSelect.prefer
                       else StateSelect.default));
  constant SI.SpecificHeatCapacity R = 287;
  constant SI.SpecificHeatCapacity cp = 1005.45;
  constant SI.Temperature T0 = 298.15
equation
  d = p/(R*T);
  h = cp*(T-T0);
  u = h - p/d;
end SimpleAir;
\end{lstlisting}

The local number of unknowns in model \lstinline!SimpleAir! (after flattening) is:
\begin{itemize}
\item
  $3$ (\lstinline!T!, \lstinline!d!, \lstinline!u!: variables defined in
  \lstinline!BaseProperties! and inherited in \lstinline!SimpleAir!), plus
\item
  $2 + \text{\lstinline!nXi!}$ (\lstinline!p!, \lstinline!h!, \lstinline!Xi!: variables inside
  connectors defined in \lstinline!BaseProperties! and inherited in \lstinline!SimpleAir!)
\end{itemize}
resulting in $5 + \text{\lstinline!nXi!}$ unknowns. The local equation size is:
\begin{itemize}
\item
  $3$ (equations defined in \lstinline!SimpleAir!), plus
\item
  $2 + \text{\lstinline!nXi!}$ (input variables in the connectors inherited from \lstinline!BaseProperties!)
\end{itemize}

Therefore, the model is locally balanced.

The generic medium model \lstinline!BaseProperties! is used as a
\lstinline!replaceable model! in different components, like a dynamic
volume or a fixed boundary condition:
\begin{lstlisting}[language=modelica]
import Modelica.Units.SI;

connector FluidPort
  replaceable model Medium = BaseProperties;
  SI.AbsolutePressure p;
  flow SI.MassFlowRate m_flow;
  SI.SpecificEnthalpy h;
  flow SI.EnthalpyFlowRate H_flow;
  SI.MassFraction Xi [Medium.nXi] "Independent mixture mass fractions";
  flow SI.MassFlowRate mXi_flow[Medium.nXi] "Independent subst. mass flow rates";
end FluidPort;

model DynamicVolume
  parameter SI.Volume V;
  replaceable model Medium = BaseProperties;
  FluidPort port(redeclare model Medium = Medium);
  Medium medium(preferredMediumStates=true); // No modifier for p,h,Xi
  SI.InternalEnergy U;
  SI.Mass M;
  SI.Mass MXi[medium.nXi];
equation
  U = medium.u*M;
  M = medium.d*V;
  MXi = medium.Xi*M;
  der(U) = port.H_flow; // Energy balance
  der(M) = port.m_flow; // Mass balance
  der(MXi) = port.mXi_flow; // Substance mass balance
// Equations binding to medium (inputs)
  medium.p = port.p;
  medium.h = port.h;
  medium.Xi = port.Xi;
end DynamicVolume;
\end{lstlisting}

The local number of unknowns of \lstinline!DynamicVolume! is:
\begin{itemize}
\item
  $4 + 2 \cdot \text{\lstinline!nXi!}$ (inside the \lstinline!port! connector), plus
\item
  $2 + \text{\lstinline!nXi!}$ (variables \lstinline!U!, \lstinline!M! and \lstinline!MXi!), plus
\item
  $2 + \text{\lstinline!nXi!}$ (the input variables in the connectors of the \lstinline!medium! model)
\end{itemize}
resulting in $8 + 4 \cdot \text{\lstinline!nXi!}$ unknowns; the local equation size is
\begin{itemize}
\item
  $6 + 3 \cdot \text{\lstinline!nXi!}$ from the equation section, plus
\item
  $2 + \text{\lstinline!nXi!}$ flow variables in the \lstinline!port! connector.
\end{itemize}

Therefore, \lstinline!DynamicVolume! is a locally balanced model.

Note, when the \lstinline!DynamicVolume! is used and the \lstinline!Medium!
model is redeclared to \lstinline!SimpleAir!, then a tool will try
to select \lstinline!p!, \lstinline!T! as states, since these variables have
\lstinline!StateSelect.prefer! in the \lstinline!SimpleAir! model (this means that
the default states \lstinline!U!, \lstinline!M! are derived quantities). If this state
selection is performed, all intrinsic medium variables are computed
from \lstinline!medium.p! and \lstinline!medium.T!, although
\lstinline!p! and \lstinline!h! are the input arguments to the medium model. This demonstrates
that in Modelica input/output does not define the computational
causality. Instead, it defines that equations have to be provided here
for \lstinline!p!, \lstinline!h!, \lstinline!Xi!, in order that the equation count is correct. The
actual computational causality can be different as it is demonstrated
with the \lstinline!SimpleAir! model.

\begin{lstlisting}[language=modelica]
model FixedBoundary_pTX
  parameter SI.AbsolutePressure p "Predefined boundary pressure";
  parameter SI.Temperature T "Predefined boundary temperature";
  parameter SI.MassFraction Xi[medium.nXi]
    "Predefined boundary mass fraction";
  replaceable model Medium = BaseProperties;
  FluidPort port(redeclare model Medium = Medium);
  Medium medium;
equation
  port.p = p;
  port.H_flow = semiLinear(port.m_flow, port.h , medium.h);
  port.MXi_flow = semiLinear(port.m_flow, port.Xi, medium.Xi);
// Equations binding to medium (note: T is not an input).
  medium.p = p;
  medium.T = T;
  medium.Xi = Xi;
end FixedBoundary_pTX;
\end{lstlisting}

The number of local variables in \lstinline!FixedBoundary_pTX! is:
\begin{itemize}
\item
  $4 + 2 \cdot \text{\lstinline!nXi!}$ (inside the \lstinline!port! connector), plus
\item
  $2 + \text{\lstinline!nXi!}$ (the input variables in the connectors of the \lstinline!medium! model)
\end{itemize}
resulting in $6 + 3 \cdot \text{\lstinline!nXi!}$ unknowns, while the local equation size is
\begin{itemize}
\item
  $4 + 2 \cdot \text{\lstinline!nXi!}$ from the equation section, plus
\item
  $2 + \text{\lstinline!nXi!}$ flow variables in the \lstinline!port! connector.
\end{itemize}

Therefore, \lstinline!FixedBoundary_pTX! is a locally balanced model.  The predefined boundary variables \lstinline!p! and \lstinline!Xi! are
provided via equations to the input arguments \lstinline!medium.p! and \lstinline!medium.Xi!, in addition there is an equation for \lstinline!T!
in the same way -- even though \lstinline!T! is not an input.  Depending on the flow direction, either the specific enthalpy in the port
(\lstinline!port.h!) or \lstinline!h! is used to compute the enthalpy flow rate \lstinline!H_flow!.  \lstinline!h! is provided as binding equation
to the medium.  With the equation \lstinline!medium.T = T!, the specific enthalpy \lstinline!h! of the reservoir is indirectly computed via the
medium equations.  Again, this demonstrates, that an \lstinline!input! just defines the number of equations have to be provided, but that it not
necessarily defines the computational causality.
\end{example}

\section{Predefined Types and Classes}\label{predefined-types-and-classes}

% Not including definition of 'predefined type' from old glossary, since it seems inconsistent with actual use, since, at least
% ExternalObject is also described as a predefined type.
% The definition sounds more like the description of 'simple type'.
%One of the types \lstinline!Real!, \lstinline!Boolean!, \lstinline!Integer!, \lstinline!String! and types defined as \lstinline!enumeration! types.
%The component declarations of the predefined types define attributes such as \lstinline!min!, \lstinline!max!, and \lstinline!unit!.

The \firstuse[attribute]{attributes} of the predefined variable types (\lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean!, \lstinline!String!) and \lstinline!enumeration! types are described below with Modelica syntax although they are predefined.
All attributes are predefined and attribute values can only be defined using a modification, such as in \lstinline!Real x(unit = "kg")!.
Attributes cannot be accessed using dot notation, and are not constrained by equations and algorithm sections.

The $\langle$$\mbox{\emph{value}}$$\rangle$ in the definitions of the predefined types represents the value of an expresion of that type.
Unlike attributes, the $\langle$$\mbox{\emph{value}}$$\rangle$ of a component cannot be referred to by name; both access and modification of the value is made directly on the component.

\begin{example}
Accessing and modifying a variable value, using \lstinline!Real! as example of a predefined type:
\begin{lstlisting}[language=modelica]
model M
  record R
    Real u;
    Real v;
  end R;
  Real x = sin(time);      // Value modification.
  Real y(unit = "kg") = x; // Access value of x, and modify value of y.
  R r(u = y);              // Value modification of r.u.
equation
  r.v + x * x = 0;         // Access values of r.v and x.
end M;
\end{lstlisting}
Note that only the values of \lstinline!x! and \lstinline!y! are declared to be equal, but not their \lstinline!unit! attributes, nor any other attribute of \lstinline!x! and \lstinline!y!
\end{example}

It is not possible to combine extends from the predefined types, enumeration types, or this \lstinline!Clock! type with other components.

The names \lstinline!Real!\index{Real@\robustinline{Real}!reserved name}, \lstinline!Integer!\index{Integer@\robustinline{Integer}!reserved name}, \lstinline!Boolean!\index{Boolean@\robustinline{Boolean}!reserved name} and \lstinline!String!\index{String@\robustinline{String}!reserved name} are reserved such that it is illegal to declare an element with these names.

\begin{nonnormative}
Hence, it is possible to define a normal class called \lstinline!Clock! in a package and extend from it.
\end{nonnormative}

\begin{nonnormative}
It also follows that the only way to declare a subtype of e.g.\ \lstinline!Real! is to use the \lstinline!extends! mechanism.
\end{nonnormative}

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}.

\subsection{Real Type}\label{real-type}

The following is the predefined \lstinline!Real!\indexinline{Real} type:
\begin{lstlisting}[language=modelica]
type Real // Note: Defined with Modelica syntax although predefined
  RealType $\langle$$\mbox{\emph{value}}$$\rangle$; // Not an attribute; only accessed without dot-notation
  parameter StringType quantity    = "";
  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 BooleanType fixed = true,  // default for parameter/constant;
                              = false; // default for other variables
  parameter RealType nominal;            // Nominal value
  parameter BooleanType unbounded = false; // For error control
  parameter StateSelect stateSelect = StateSelect.default;
equation
  assert(min <= $\langle$$\mbox{\emph{value}}$$\rangle$ and $\langle$$\mbox{\emph{value}}$$\rangle$ <= max, "Variable value out of limit");
end Real;
\end{lstlisting}%
\index{quantity@\robustinline{quantity}!attribute of \robustinline{Real}}%
\index{unit@\robustinline{unit}!attribute of \robustinline{Real}}%
\index{displayUnit@\robustinline{displayUnit}!attribute of \robustinline{Real}}%
\index{min@\robustinline{min}!attribute of \robustinline{Real}}%
\index{max@\robustinline{max}!attribute of \robustinline{Real}}%
\index{start@\robustinline{start}!attribute of \robustinline{Real}}%
\index{fixed@\robustinline{fixed}!attribute of \robustinline{Real}}%
\index{nominal@\robustinline{nominal}!attribute of \robustinline{Real}}%
\index{unbounded@\robustinline{unbounded}!attribute of \robustinline{Real}}%
\index{stateSelect@\robustinline{stateSelect}!attribute of \robustinline{Real}}

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}.

\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.
\end{nonnormative}

\subsection{Integer Type}\label{integer-type}

The following is the predefined \lstinline!Integer!\indexinline{Integer} type:
\begin{lstlisting}[language=modelica]
type Integer // Note: Defined with Modelica syntax although predefined
  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 BooleanType fixed = true,  // default for parameter/constant;
                              = false; // default for other variables
equation
  assert(min <= $\langle$$\mbox{\emph{value}}$$\rangle$ and $\langle$$\mbox{\emph{value}}$$\rangle$ <= max, "Variable value out of limit");
end Integer;
\end{lstlisting}%
\index{quantity@\robustinline{quantity}!attribute of \robustinline{Integer}}%
\index{min@\robustinline{min}!attribute of \robustinline{Integer}}%
\index{max@\robustinline{max}!attribute of \robustinline{Integer}}%
\index{start@\robustinline{start}!attribute of \robustinline{Integer}}%
\index{fixed@\robustinline{fixed}!attribute of \robustinline{Integer}}

The minimal recommended number range for \lstinline!IntegerType! is from -2147483648 to +2147483647, corresponding to a two's-complement 32-bit integer implementation.

\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 fixed = true,  // default for parameter/constant;
                              = false, // default for other variables
end Boolean;
\end{lstlisting}%
\index{quantity@\robustinline{quantity}!attribute of \robustinline{Boolean}}%
\index{start@\robustinline{start}!attribute of \robustinline{Boolean}}%
\index{fixed@\robustinline{fixed}!attribute of \robustinline{Boolean}}%

\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 BooleanType fixed = true,  // default for parameter/constant;
                              = false, // default for other variables
end String;
\end{lstlisting}%
\index{quantity@\robustinline{quantity}!attribute of \robustinline{String}}%
\index{start@\robustinline{start}!attribute of \robustinline{String}}%
\index{fixed@\robustinline{fixed}!attribute of \robustinline{String}}

\subsection{Enumeration Types}\label{enumeration-types}

A declaration of the form
\begin{lstlisting}[language=modelica]
type E = enumeration([enum-list]);
\end{lstlisting}%
\indexinline{enumeration}
defines an enumeration type \lstinline!E! and the associated enumeration literals of
the enum-list. The enumeration literals shall be distinct within the
enumeration type. The names of the enumeration literals are defined
inside the scope of \lstinline!E!. Each enumeration literal in the \lstinline!enum-list! has
type \lstinline!E!.

\begin{example}
\begin{lstlisting}[language=modelica]
type Size = enumeration(small, medium, large, xlarge);
Size t_shirt_size = Size.medium;
\end{lstlisting}
\end{example}

An optional comment string can be specified with each enumeration literal.

\begin{example}
\begin{lstlisting}[language=modelica]
type Size2 = enumeration(small "1st", medium "2nd", large "3rd", xlarge "4th");
\end{lstlisting}
\end{example}

An enumeration type is a simple type and the attributes are defined in \cref{attributes-of-enumeration-types}.
The \lstinline!Boolean! type name or an enumeration type name can be used to specify the dimension range for a dimension in an array declaration and to specify the range in a \lstinline!for!-loop range expression; see \cref{types-as-iteration-ranges}.
An element of an enumeration type can be accessed in an expression.

\begin{nonnormative}
Uses of elements of enumeration type in expressions include indexing into an array.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
type DigitalCurrentChoices = enumeration(zero, one);
// Similar to Real, Integer
\end{lstlisting}

Setting attributes:
\begin{lstlisting}[language=modelica]
type DigitalCurrent = DigitalCurrentChoices(quantity="Current",
                               start = DigitalCurrentChoices.one, fixed = true);
DigitalCurrent c(start = DigitalCurrent.one, fixed = true);
DigitalCurrentChoices c(start = DigitalCurrentChoices.one, fixed = true);
\end{lstlisting}

Using enumeration types as expressions:
\begin{lstlisting}[language=modelica]
Real x[DigitalCurrentChoices];

// Example using the type name to represent the range

for e in DigitalCurrentChoices loop
  x[e] := 0.;
end for;

for e loop // Equivalent example using short form
  x[e] := 0.;
end for;

// Equivalent example using the colon range constructor
for e in DigitalCurrentChoices.zero : DigitalCurrentChoices.one loop
  x[e] := 0.;
end for;

model Mixing1 "Mixing of multi-substance flows, alternative 1"
  replaceable type E=enumeration(:)"Substances in Fluid";
  input Real c1[E], c2[E], mdot1, mdot2;
  output Real c3[E], mdot3;
equation
  0 = mdot1 + mdot2 + mdot3;
  for e in E loop
    0 = mdot1*c1[e] + mdot2*c2[e]+ mdot3*c3[e];
  end for;
  /* Array operations on enumerations are NOT (yet) possible:
       zeros(n) = mdot1*c1 + mdot2*c2 + mdot3*c3 // error
  */
end Mixing1;

model Mixing2 "Mixing of multi-substance flows, alternative 2"
  replaceable type E=enumeration(:)"Substances in Fluid";
  input Real c1[E], c2[E], mdot1, mdot2;
  output Real c3[E], mdot3;
protected
  // No efficiency loss, since cc1, cc2, cc3
  // may be removed during translation
  Real cc1[:]=c1, cc2[:]=c2, cc3[:]=c3;
  final parameter Integer n = size(cc1,1);
equation
  0 = mdot1 + mdot2 + mdot3;
  zeros(n) = mdot1*cc1 + mdot2*cc2 + mdot3*cc3
end Mixing2;
\end{lstlisting}
\end{example}

\subsubsection{Attributes of Enumeration Types}\label{attributes-of-enumeration-types}

For each enumeration:
\begin{lstlisting}[language=modelica]
type E = enumeration(e1, e2, $\ldots$, en);
\end{lstlisting}
a new simple type is conceptually defined as
\begin{lstlisting}[language=modelica]
type E // Note: Defined with Modelica syntax although predefined
  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 BooleanType fixed = true,  // default for parameter/constant;
                              = false; // default for other variables
  constant EnumType e1 = $\ldots$;
  $\ldots$
  constant EnumType en = $\ldots$;
equation
  assert(min <= $\langle$$\mbox{\emph{value}}$$\rangle$ and $\langle$$\mbox{\emph{value}}$$\rangle$ <= max, "Variable value out of limit");
end E;
\end{lstlisting}

\begin{nonnormative}
Since the attributes and enumeration literals are on the same
level, it is not possible to use the enumeration attribute names
(\lstinline!quantity!, \lstinline!min!, \lstinline!max!, \lstinline!start!, \lstinline!fixed!) as enumeration literals.
\end{nonnormative}

\subsubsection{Type Conversion of Enumeration Values to String or Integer}\label{type-conversion-of-enumeration-values-to-string-or-integer}

% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
% - https://github.com/brucemiller/LaTeXML/issues/1477
% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
The type conversion function \lstinline!Integer($\langle$$\mbox{\emph{expression of enumeration type}}$$\rangle$)! returns the ordinal number of the enumeration value \lstinline!E.enumvalue!, to which the expression is evaluated, where $\text{\lstinline!Integer(E.e1)!} = 1$, $\text{\lstinline!Integer(E.en)!} = n$, for an enumeration type \lstinline!E = enumeration(e1, $\ldots$, en)!.

\lstinline!String(E.enumvalue)! gives the \lstinline!String! representation of the enumeration value.

\begin{example}
\lstinline!String(E.Small)! gives \lstinline!"Small"!.
\end{example}

See also \cref{numeric-functions-and-conversion-functions}.

\subsubsection{Type Conversion of Integer to Enumeration Values}\label{type-conversion-of-integer-to-enumeration-values}

Whenever an enumeration type is defined, a type conversion function with
the same name and in the same scope as the enumeration type is
implicitly defined. This function can be used in an expression to
convert an integer value to the corresponding (as described in \cref{type-conversion-of-enumeration-values-to-string-or-integer}) enumeration value.

% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
% - https://github.com/brucemiller/LaTeXML/issues/1477
% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
For an enumeration type named \lstinline!EnumTypeName!, the expression \lstinline!EnumTypeName($\langle$$\mbox{\emph{Integer expression}}$$\rangle$)! returns the enumeration value \lstinline!EnumTypeName.e! such that \lstinline!Integer(EnumTypeName.e)! is equal to the original integer expression.

Attempting to convert an integer argument that does not correspond to a
value of the enumeration type is an error.

\begin{example}
\begin{lstlisting}[language=modelica]
type Colors = enumeration ( RED, GREEN, BLUE, CYAN, MAGENTA, YELLOW );
\end{lstlisting}

Converting from \lstinline!Integer! to \lstinline!Colors!:
\begin{lstlisting}[language=modelica]
c = Colors(i);
c = Colors(10); // An error
\end{lstlisting}
\end{example}


\subsubsection{Unspecified enumeration}\label{unspecified-enumeration}

An enumeration type defined using \lstinline!enumeration(:)!\index{enumeration@\robustinline{enumeration}!unspecified} is unspecified and can be used as a replaceable enumeration type that can be freely redeclared to any enumeration type.
There can be no enumeration variables declared using \lstinline!enumeration(:)! in a simulation model.


\subsection{Attributes start, fixed, nominal, and unbounded}\label{attributes-start-fixed-nominal-and-unbounded}

The attributes \lstinline!start! and \lstinline!fixed! define the initial conditions for a variable.  \lstinline!fixed = false! means an initial guess, i.e., value may be changed by static analyzer.  \lstinline!fixed = true! means a required value.  The resulting consistent set of values for \emph{all} model variables is used as initial values for the analysis to be performed.

The attribute \lstinline!nominal! gives the nominal value for the variable.  The user need not set it even though the standard does not define a default value.  The lack of default allows the tool to propagate the nominal attribute based on equations, and if there is no value to propagate the tool should use a non-zero value, it may use additional information (e.g.\ \lstinline!min! attribute) to find a suitable value, and as last resort use 1.  If \lstinline!unbounded = true! it indicates that the state may grow without bound, and the error in absolute terms shall be controlled.

\begin{nonnormative}
The nominal value can be used by an analysis tool to determine appropriate tolerances or epsilons, or may be used for scaling.  For example, the tolerance for an integrator could be computed as \lstinline!tol * (abs(nominal) + (if x.unbounded then 0 else abs(x)))!.  A default value is not provided in order that in cases such as \lstinline!a = b!, where \lstinline!b! has a nominal value but not \lstinline!a!, the nominal value can be propagated to the other variable).
\end{nonnormative}


\subsection{Other Predefined Types}\label{other-predefined-types}

\subsubsection{StateSelect}\label{stateselect}

The predefined \lstinline!StateSelect!\indexinline{StateSelect} enumeration type is the type of the \lstinline!stateSelect! attribute of the \lstinline!Real! type.  It is used to explicitly control state selection.

\begin{lstlisting}[language=modelica]
type StateSelect = enumeration(
 never "Do not use as state at all.",
 avoid "Use as state, if it cannot be avoided (but only if variable appears
         differentiated and no other potential state with attribute
         default, prefer, or always can be selected).",
 default "Use as state if appropriate, but only if variable appears
          differentiated.",
 prefer "Prefer it as state over those having the default value
      (also variables can be selected, which do not appear
      differentiated). ",
always "Do use it as a state."
);
\end{lstlisting}

\subsubsection{ExternalObject}\label{externalobject}

See \cref{external-objects} for information about the predefined type \lstinline!ExternalObject!.

\subsubsection{AssertionLevel}\label{assertionlevel}

The predefined \lstinline!AssertionLevel!\indexinline{AssertionLevel} enumeration type is used together with \lstinline!assert!, \cref{assert}.
\begin{lstlisting}[language=modelica]
type AssertionLevel = enumeration(warning, error);
\end{lstlisting}

\subsubsection{Connections}\label{connections}

The package \lstinline!Connections!\indexinline{Connections} is used for over-constrained connection graphs, \cref{equation-operators-for-overconstrained-connection-based-equation-systems}.

\subsubsection{Graphical Annotation Types}\label{graphical-annotation-types}

A number of ``predefined'' record types and enumeration types for graphical annotations are described in \cref{annotations}.
These types are not predefined in the usual sense since they cannot be referenced in ordinary Modelica code, only within annotations.

\subsubsection{Clock Types}\label{clock-types}

See \cref{clocks-and-clocked-variables} and \cref{clock-constructors}.