arrays.tex

\chapter{Arrays}\label{arrays}

A non-record array can be regarded as a collection of type compatible values, \cref{type-compatible-expressions}.
An array of records may contain scalar record values whose elements differ in their dimension sizes, but apart from that they must be of the same type.
Such heterogenous arrays may only be used completely, sliced as specified, or indexed.
An array of arrays must have the same dimension sizes for all of the arrays (with the same exception for records).
Modelica arrays can be multidimensional and are ``rectangular'',
which in the case of matrices has the consequence that all rows in a
matrix have equal length, and all columns have equal length.

Each array has a certain dimensionality, i.e., number of dimensions.
The degenerate case of a \firstuse{scalar} variable is not really an array, but can be regarded as an array with zero dimensions.
\firstuse[vector]{Vectors} have one dimension, matrices (sing.\ \firstuse{matrix}) have two dimensions, etc.

So-called row vectors and column vectors do not exist in Modelica and cannot be distinguished since vectors have only one dimension.
If distinguishing these is desired, row matrices and column matrices are available, being the corresponding two-dimensional entities.
However, in practice this is seldom needed since the usual matrix arithmetic and linear algebra operations have been defined to give the expected behavior when operating on Modelica vectors and matrices.

Modelica is a strongly typed language, which also applies to array
types. The number of dimensions of an array is fixed and cannot be
changed at run-time. However, the sizes of array dimensions can
be computed at run-time.

The fixed number of array dimensions permits strong type checking and efficient implementation.  The non-fixed sizes of array
dimensions on the other hand, allow fairly generic array manipulation code to be written as well as interfacing to standard
numeric libraries implemented in other programming languages.

An array is allocated by declaring an array variable or calling an array
constructor. Elements of an array can be indexed by \lstinline!Integer!, \lstinline!Boolean!, or
\lstinline!enumeration! values.

\section{Array Declarations}\label{array-declarations}

The Modelica type system includes scalar number, vector, matrix (number of dimensions, ndim=2), and arrays of more than two dimensions.

\begin{nonnormative}
There is no distinction between a row and column vector.
\end{nonnormative}

The following table shows the two possible forms of declarations and defines the terminology.
% Is the use of "class" here meant to exclude types defined as array aliases (see comment in table below)?
\lstinline!C! is a placeholder for any class, including the built-in type classes \lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean!, \lstinline!String!, and enumeration types.
The type of a dimension upper bound expression, e.g., $n$, $m$, $p$, \ldots in the table below, need to be a subtype of \lstinline!Integer! or \lstinline!EB! for a class \lstinline!EB! that is an enumeration type or subtype of the \lstinline!Boolean! type.

Colon (\lstinline!:!) indicates that the dimension upper bound is unknown and is a subtype of \lstinline!Integer!.
The size of such a variable can be determined from its binding equation, or the size of any of its array attributes, see also \cref{flexible-array-sizes-and-resizing-of-arrays-in-functions}.
The size cannot be determined from other equations or algorithms.

Upper and lower array dimension index bounds are described in \cref{array-dimension-lower-and-upper-index-bounds}.

An array indexed by \lstinline!Boolean! or enumeration type can only be used in the following ways:
\begin{itemize}
\item
  Subscripted using expressions of the appropriate type (i.e., \lstinline!Boolean! or the enumerated type).
\item
  Binding equations of the form \lstinline!x1 = x2! are allowed for arrays independent of whether the index types of dimensions are subtypes of \lstinline!Integer!, \lstinline!Boolean!, or enumeration types.
\end{itemize}

% IMPROVETOP
\begin{table}[H]
% henrikt-ma: Doesn't the "Designation" and "Explanation" here assume that C is of non-array type?
\caption{%
General forms of declaration of arrays.
The notation \lstinline!EB! stands for an enumeration type or \lstinline!Boolean!.
The general array can have one or more dimensions ($k \geq 1$).
}
\begin{center}
\begin{tabular}{l l c l l}
\hline
\tablehead{Modelica form 1} & \tablehead{Modelica form 2} & \tablehead{\# dims} & \tablehead{Designation} & \tablehead{Explanation}\\
\hline
\hline
{\lstinline!C x!};            & {\lstinline!C x!}; & $0$ & Scalar & Scalar\\
{\lstinline!C[$n$] x;!}       & {\lstinline!C x[$n$];!} & $1$ & Vector & $n$-vector\\
{\lstinline!C[EB] x;!}        & {\lstinline!C x[EB]!} & $1$ & Vector & Vector indexed by {\lstinline!EB!}\\
{\lstinline!C[$n$, $m$] x;!}  & {\lstinline!C x[$n$, $m$];!} & $2$ & Matrix & $n \times m$ matrix\\
{\lstinline!C[$n_1$, $n_{2}$, $\ldots$, $n_k$] x;!} &
{\lstinline!C x[$n_{1}$, $n_{2}$, $\ldots$, $n_{k}$];!} & $k$ & Array & General array\\
\hline
\end{tabular}
\end{center}
\end{table}

% henrikt-ma: The following paragraph was only modified slightly when migrated from the old glossary to the index, and seems to be in need of more attention:
A component declared with array dimensions, or where the element type is an array type, is called an \firstuse[array!variable]{array variable}.
It is a component whose components are \willintroduce{array elements} (see below).
For an array variable, the ordering of its components matters:
The $k$th element in the sequence of components of an array variable \lstinline!x! is the array element with index \lstinline!k!, denoted \lstinline!x[k]!.
% henrikt-ma: The following statement seems like an over-simplification; for Flat Modelica, we've spent some time trying to figure out how to deal with the fact that Modelica arrays are not homogenous in general.
All elements of an array have the same type.
An array element may again be an array, i.e., arrays can be nested.
An array element is hence referenced using $n$ indices in general, where $n$ is the number of dimensions of the array.

% henrikt-ma: The following paragraph was only modified slightly when migrated from the old glossary to the index, and seems to be in need of more attention:
A component contained in an array variable is called an \firstuse[array!element]{array element}.
An array element has no identifier.
Instead they are referenced by array access expressions called indices that use enumeration values or positive integer index values.

\begin{example}
The number of dimensions and the dimensions sizes are part of
the type, and shall be checked for example at redeclarations.
Declaration form~1 displays clearly the type of an array, whereas
declaration form~2 is the traditional way of array declarations in
languages such as Fortran, C, C++.

\begin{lstlisting}[language=modelica]
Real[:] v1, v2 // Vectors v1 and v2 have unknown sizes.
               // The actual sizes may be different.
\end{lstlisting}
It is possible to mix the two declaration forms although it might be confusing.
\begin{lstlisting}[language=modelica]
Real[3, 2] x[4, 5]; // x has type Real[4, 5, 3, 2];
\end{lstlisting}
The reason for this order is given by examples such as:
\begin{lstlisting}[language=modelica]
type R3 = Real[3];
R3 a;
R3 b[1] = {a};
Real[3] c[1] = b;
\end{lstlisting}
Using a type for \lstinline!a! and \lstinline!b! in this way is normal, and substituting a type by its definition allows \lstinline!c!.

A vector \lstinline!y! indexed by enumeration values
\begin{lstlisting}[language=modelica]
type TwoEnums = enumeration(one,two);
Real[TwoEnums] y;
\end{lstlisting}
\end{example}

Zero-valued dimensions are allowed, so: \lstinline!C x[0];! declares an empty vector, and: \lstinline!C x[0, 3];! an empty matrix.  Some examples of array dimensions of size one are given in \cref{tab:size-1-dimensions}.

\begin{table}[H]
\caption{Special cases of declaration of arrays as 1-vectors, row-vectors, or column-vectors of arrays.}\label{tab:size-1-dimensions}
\begin{center}
\begin{tabular}{l l c l l}
\hline
\tablehead{Modelica form 1} & \tablehead{Modelica form 2} & \tablehead{\# dims} & \tablehead{Designation} & \tablehead{Explanation}\\
\hline
\hline
{\lstinline!C[1] x;!}      & {\lstinline!C x[1];!}      & $1$ & Vector & 1-vector, representing a scalar\\
{\lstinline!C[1, 1] x;!}   & {\lstinline!C x[1, 1];!}   & $2$ & Matrix & $(1 \times 1)$-matrix, representing a scalar\\
{\lstinline!C[$n$, 1] x;!} & {\lstinline!C x[$n$, 1];!} & $2$ & Matrix & $(n \times 1)$-matrix, representing a column\\
{\lstinline!C[1, $n$] x;!} & {\lstinline!C x[1, $n$];!} & $2$ & Matrix & $(1 \times n)$-matrix, representing a row\\
\hline
\end{tabular}
\end{center}
\end{table}

The type of an array of array is the multidimensional array which is constructed by taking the first dimensions from the component declaration and subsequent dimensions
from the maximally expanded component type.  A type is maximally expanded, if it is either one of the built-in types (\lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean!,
\lstinline!String!, enumeration type) or it is not a type class.  Before operator overloading is applied, a type class of a variable is maximally expanded.

\begin{example}
\begin{lstlisting}[language=modelica]
type Voltage = Real(unit = "V");
type Current = Real(unit = "A");
connector Pin
  Voltage v; // type class of v = Voltage, type of v = Real
  flow Current i; // type class of i = Current, type of i = Real
end Pin;
type MultiPin = Pin[5];
MultiPin[4] p; // type class of p is MultiPin, type of p is Pin[4, 5];
type Point = Real[3];
Point p1[10];
Real p2[10, 3];
\end{lstlisting}
The components \lstinline!p1! and \lstinline!p2! have identical types.
\begin{lstlisting}[language=modelica]
p2[5] = p1[2] + p2[4]; // equivalent to p2[5, :] = p1[2, :] + p2[4, :]
Real r[3] = p1[2]; // equivalent to r[3] = p1[2, :]
\end{lstlisting}
\end{example}

\begin{nonnormative}
Automatic assertions at simulation time:

Let \lstinline!A! be a declared array and \lstinline!i! be the declared maximum dimension size of the \lstinline!di!-dimension, then an \lstinline!assert!-statement \lstinline!assert(i >= 0, $\ldots$)! is generated provided this assertion cannot be checked at compile time.  It is a quality of implementation issue to generate a good error message if the assertion fails.

Let \lstinline!A! be a declared array and \lstinline!i! be an index accessing an index of the \lstinline!di!-dimension.  Then for every such index-access an assert
statement \lstinline!assert(1 <= i and i <= size(A, di), $\ldots$)! is generated, provided this assertion cannot be checked at compile time.

For efficiency reasons, these implicit \lstinline!assert!-statements may be optionally suppressed.
\end{nonnormative}

\subsection{Lower and Upper Index Bounds}\label{array-dimension-lower-and-upper-index-bounds}\label{lower-and-upper-index-bounds}

The lower and upper index bounds for a dimension of an array indexed by \lstinline!Integer!, \lstinline!Boolean!, or \lstinline!enumeration! values are as follows:
\begin{itemize}
\item
  An array dimension indexed by \lstinline!Integer! values has a lower bound of 1 and an upper bound being the size of the dimension.
\item
  An array dimension indexed by \lstinline!Boolean! values has the lower bound \lstinline!false! and the upper bound \lstinline!true!.
\item
  An array dimension indexed by \lstinline!enumeration! values of the type \lstinline!E = enumeration(e1, e2, $\ldots$, en)!
  has the lower bound \lstinline!E.e1! and the upper bound \lstinline!E.en!.
\end{itemize}

\section{Flexible Array Sizes}\label{flexible-array-sizes}

Regarding flexible array sizes and resizing of arrays in functions, see
\cref{flexible-array-sizes-and-resizing-of-arrays-in-functions}.

\section{Built-in Array Functions}\label{built-in-array-functions}

Modelica provides a number of built-in functions that are applicable to arrays.

The \lstinline!promote! function listed below is utilized to define other array operators and functions.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!promote($A$, $n$)!} & Append dimensions of size 1 & \Cref{modelica:promote} \\
\hline
\end{tabular}
\end{center}

\begin{operatordefinition}[promote]\indexinline{promote}
\begin{synopsis}\begin{lstlisting}
promote($A$, $n$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Fills dimensions of size 1 from the right to array $A$ upto dimension $n$, where $n \geq$ \lstinline!ndims($A$)! is required.

Let \lstinline!C = promote(A, $n$)!, with $n_{\mathrm{A}}$ = \lstinline!ndims(A)!, then \lstinline!ndims(C) = $n$!, \lstinline!size(C, $j$) = size(A, $j$)! for $1 \leq j \leq n_{\mathrm{A}}$, \lstinline!size(C, $j$)! = $1$ for $n_{\mathrm{A}} + 1 \leq j \leq n$, \lstinline!C[$i_{1}$, $\ldots$, $i_{n_{\mathrm{A}}}$, 1, $\ldots$, 1]! = \lstinline!A[$i_{1}$, $\ldots$, $i_{n_{\mathrm{A}}}$]!

The argument $n$ must be a constant that can be evaluated during translation, as it determines the number of dimensions of the returned array.
\begin{nonnormative}
An $n$ that is not a constant that can be evaluated during translation for \lstinline!promote! complicates matrix handling as it can change matrix-equations in subtle ways (e.g., changing inner products to matrix multiplication).
\end{nonnormative}
\end{semantics}
\end{operatordefinition}

\begin{nonnormative}
Some examples of using the functions defined in the following
\cref{array-dimension-and-size-functions} to \cref{matrix-and-vector-algebra-functions}:
\begin{lstlisting}[language=modelica]
Real x[4, 1, 6];
size(x, 1) = 4;
size(x); // vector with elements 4, 1, 6
size(2 * x + x) = size(x);
Real[3] v1 = fill(1.0, 3);
Real[3, 1] m = matrix(v1);
Real[3] v2 = vector(m);
Boolean check[3, 4] = fill(true, 3, 4);
\end{lstlisting}
\end{nonnormative}

\subsection{Dimension and Size Functions}\label{array-dimension-and-size-functions}\label{dimension-and-size-functions}

The functions listed below operate on the array dimensions of the type of an expression:
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!ndims($A$)!} & Number of dimensions & \Cref{modelica:ndims} \\
{\lstinline!size($A$, $i$)!} & Size of single array dimension & \Cref{modelica:size-of-dim} \\
{\lstinline!size($A$)!} & Sizes of all array dimensions & \Cref{modelica:size-vector} \\
\hline
\end{tabular}
\end{center}

\begin{operatordefinition}[ndims]
\begin{synopsis}\begin{lstlisting}
ndims($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the number of dimensions $k$ of expression $A$, with $k \geq 0$.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition*}[size]\label{modelica:size-of-dim}\index{size@\robustinline{size}!of single array dimension}
\begin{synopsis}\begin{lstlisting}
size($A$, $i$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the size of dimension $i$ of array expression $A$ where $0 \leq i \leq$ \lstinline!ndims($A$)!.

If $A$ refers to a component of an expandable connector, then the component must be a declared component of the expandable connector, and it must not use colon (\lstinline!:!) to specify the array size of dimension $i$.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[size]\label{modelica:size-vector}\index{size@\robustinline{size}!of all array dimensions}
\begin{synopsis}\begin{lstlisting}
size($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns a vector of length \lstinline!ndims($A$)! containing the dimension sizes of $A$.

If $A$ refers to a component of an expandable connector, then the component must be a declared component of the expandable connector, and it must not use colon (\lstinline!:!) to specify the size of any array dimension.
\end{semantics}
\end{operatordefinition*}

\subsection{Dimensionality Conversion Functions}\label{dimensionality-conversion-functions}

The conversion functions listed below convert scalars, vectors, and arrays to scalars, vectors, or matrices by adding or removing 1-sized dimensions.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!scalar($A$)!} & Extract only element & \Cref{modelica:scalar} \\
{\lstinline!vector($A$)!} & Vector of all elements & \Cref{modelica:vector} \\
{\lstinline!matrix($A$)!} & Two-dimensional array & \Cref{modelica:matrix} \\
\hline
\end{tabular}
\end{center}

\begin{operatordefinition}[scalar]
\begin{synopsis}\begin{lstlisting}
scalar($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the single element of array $A$.  \lstinline!size($A$, i)! $= 1$ is required for $1 \leq i \leq$ \lstinline!ndims($A$)!.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[vector]
\begin{synopsis}\begin{lstlisting}
vector($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
% This definition is lacking detail regarding the order of the elements in the result.
% It's also strange that it isn't defined for an array with just a single element (all sizes equal to 1).
Returns a 1-vector if $A$ is a scalar, and otherwise returns a vector containing all the elements of the array, provided there is at most one dimension size $> 1$.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[matrix]
\begin{synopsis}\begin{lstlisting}
matrix($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns \lstinline!promote($A$, 2)! if $A$ is a scalar or vector, and otherwise returns the elements of the first two dimensions as a matrix.  \lstinline!size($A$, i)! $= 1$ is required for $2 < i \leq$ \lstinline!ndims($A$)!.
\end{semantics}
\end{operatordefinition}

\subsection{Specialized Array Constructor Functions}\label{specialized-array-constructor-functions}

An array constructor function constructs and returns an array computed
from its arguments. Most of the constructor functions listed below
construct an array by filling in values according to a certain pattern,
in several cases just giving all array elements the same value. The
general array constructor with syntax \lstinline!array($\ldots$)! or \lstinline!{$\ldots$}!
is described in \cref{vector-matrix-and-array-constructors}.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!identity($n$)!} & Identity matrix & \Cref{modelica:identity} \\
{\lstinline!diagonal($v$)!} & Diagonal matrix & \Cref{modelica:diagonal} \\
{\lstinline!zeros($n_{1}$, $n_{2}$, $n_{3}$, $\ldots$)!} & Array with all elements being 0 & \Cref{modelica:zeros} \\
{\lstinline!ones($n_{1}$, $n_{2}$, $n_{3}$, $\ldots$)!} & Array with all elements being 1 & \Cref{modelica:ones} \\
{\lstinline!fill($s$, $n_{1}$, $n_{2}$, $n_{3}$, $\ldots$)!} & Array with all elements equal & \Cref{modelica:fill} \\
{\lstinline!linspace($x_{1}$, $x_{2}$, $n$)!} & Vector with equally spaced elements & \Cref{modelica:linspace} \\
\hline
\end{tabular}
\end{center}

\begin{operatordefinition}[identity]
\begin{synopsis}\begin{lstlisting}
identity($n$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the $n \times n$ \lstinline!Integer! identity matrix, with ones on the diagonal and zeros at the other places.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[diagonal]
\begin{synopsis}\begin{lstlisting}
diagonal($v$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns a square matrix with the elements of vector $v$ on the diagonal and all other elements zero.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[zeros]
\begin{synopsis}\begin{lstlisting}
zeros($n_{1}$, $n_{2}$, $n_{3}$, $\ldots$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the $n_{1} \times n_{2} \times n_{3} \times \ldots$ \lstinline!Integer! array with all elements equal to zero ($n_{i} \geq 0$).  The function needs one or more arguments, that is, \lstinline!zeros()! is not legal.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[ones]
\begin{synopsis}\begin{lstlisting}
ones($n_{1}$, $n_{2}$, $n_{3}$, $\ldots$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Return the $n_{1} \times n_{2} \times n_{3} \times \ldots$ \lstinline!Integer! array with all elements equal to one ($n_{i} \geq 0$).  The function needs one or more arguments, that is, \lstinline!ones()! is not legal.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[fill]
\begin{synopsis}\begin{lstlisting}
fill($s$, $n_{1}$, $n_{2}$, $n_{3}$, $\ldots$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the $n_{1} \times n_{2} \times n_{3} \times \ldots$ array with all elements equal to scalar or array expression $s$ ($n_{i} \geq 0$).  The returned array has the same type as $s$.

Recursive definition:
\lstinline!fill($s$, $n_{1}$, $n_{2}$, $n_{3}$, $\ldots$)! =
\lstinline!fill(fill($s$, $n_{2}$, $n_{3}$, $\ldots$), $n_{1}$)!;
\lstinline!fill($s$, $n$)! = \lstinline!{$s$, $s$, $\ldots$, $s$}!.

The function needs two or more arguments; that is, \lstinline!fill($s$)! is not legal.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[linspace]
\begin{synopsis}\begin{lstlisting}
linspace($x_{1}$, $x_{2}$, $n$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns a \lstinline!Real! vector with $n$ equally spaced elements, such that \lstinline!v = linspace($x_{1}$, $x_{2}$, $n$)! results in
\begin{equation*}
\text{\lstinline!v[$i$]!} = x_{1} + (x_{2} - x_{1}) \frac{i - 1}{n - 1} \quad \text{for $1 \leq i \leq n$}
\end{equation*}
It is required that $n \geq 2$.  The arguments $x_{1}$ and $x_{2}$ shall be numeric scalar expressions.
\end{semantics}
\end{operatordefinition}

\subsection{Reduction Functions and Operators}\label{reduction-functions-and-operators}

The reduction functions listed below ``reduce'' an array (or several scalars) to one value (normally a scalar, but the \lstinline!sum! reduction function may give an array as result
and also be applied to an operator record).  Note that none of these operators (particularly \lstinline!min! and \lstinline!max!) generate events themselves (but arguments
could generate events).  The restriction on the type of the input in \cref{reduction-expressions} for reduction expressions also applies to the array elements/scalar
inputs for the reduction operator with the same name.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!min($A$)!} & Least element or array & \Cref{modelica:min-of-array} \\
{\lstinline!min($x$, $y$)!} & Least of two scalars & \Cref{modelica:min-binary} \\
{\lstinline!min($\ldots$ for $\ldots$)!} & Reduction to least value & \Cref{modelica:min-reduction} \\
{\lstinline!max($A$)!} & Greatest element or array & \Cref{modelica:max-of-array} \\
{\lstinline!max($x$, $y$)!} & Greatest of two scalars & \Cref{modelica:max-binary} \\
{\lstinline!max($\ldots$ for $\ldots$)!} & Reduction to greatest value & \Cref{modelica:max-reduction} \\
% Not saying "scalar sum" for symmetry with the product case below:
{\lstinline!sum($A$)!} & Sum of scalar array elements & \Cref{modelica:sum-of-array} \\
{\lstinline!sum($\ldots$ for $\ldots$)!} & Sum reduction & \Cref{modelica:sum-reduction} \\
% Not saying "scalar product" to avoid confusion with inner products:
{\lstinline!product($A$)!} & Product of scalar array elements & \Cref{modelica:product-of-array} \\
{\lstinline!product($\ldots$ for $\ldots$)!} & Product reduction & \Cref{modelica:product-reduction} \\
\hline
\end{tabular}
\end{center}

\begin{operatordefinition*}[min]\label{modelica:min-of-array}\index{min@\robustinline{min}!of array}
\begin{synopsis}\begin{lstlisting}
min($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the least element of array expression $A$; as defined by \lstinline!<!.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[min]\label{modelica:min-binary}\index{min@\robustinline{min}!binary function}
\begin{synopsis}\begin{lstlisting}
min($x$, $y$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the least element of the scalars $x$ and $y$; as defined by \lstinline!<!.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[min]\label{modelica:min-reduction}\index{min@\robustinline{min}!reduction expression}
\begin{synopsis}\begin{lstlisting}
min($e$($i$, $\ldots$, $j$) for $i$ in $u$, $\ldots$, $j$ in $v$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Also described in \cref{reduction-expressions}.  Returns the least value (as defined by \lstinline!<!) of the scalar expression \lstinline!$e$($i$, $\ldots$, $j$)! evaluated for all combinations of $i$ in $u$, \ldots, $j$ in $v$.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[max]\label{modelica:max-of-array}\index{max@\robustinline{max}!of array}
\begin{synopsis}\begin{lstlisting}
max($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the greatest element of array expression $A$; as defined by \lstinline!>!.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[max]\label{modelica:max-binary}\index{max@\robustinline{max}!binary function}
\begin{synopsis}\begin{lstlisting}
max($x$, $y$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the greatest element of the scalars $x$ and $y$; as defined by \lstinline!>!.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[max]\label{modelica:max-reduction}\index{max@\robustinline{max}!reduction expression}
\begin{synopsis}\begin{lstlisting}
max($e$($i$, $\ldots$, $j$) for $i$ in $u$, $\ldots$, $j$ in $v$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Also described in \cref{reduction-expressions}.  Returns the greatest value (as defined by \lstinline!>!) of the scalar expression \lstinline!$e$($i$, $\ldots$, $j$)! evaluated for all combinations of $i$ in $u$, \ldots, $j$ in $v$.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[sum]\label{modelica:sum-of-array}\index{sum@\robustinline{sum}!of array}
\begin{synopsis}\begin{lstlisting}
sum($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the scalar sum of all the elements of array expression \lstinline!A!.  Equivalent to sum reduction (see below, including application to operator records) over all array indices: \lstinline!sum($A$[j, k, $\ldots$] for j, k, $\ldots$)!
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[sum]\label{modelica:sum-reduction}\index{sum@\robustinline{sum}!reduction expression}
\begin{synopsis}\begin{lstlisting}
sum($e$($i$, $\ldots$, $j$) for $i$ in $u$, $\ldots$, $j$ in $v$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Also described in \cref{reduction-expressions}.  Returns the sum of the expression \lstinline!$e$($i$, $\ldots$, $j$)! evaluated for all combinations of $i$ in $u$, \ldots, $j$ in $v$.

The \lstinline!sum! reduction function (both variants) may be applied to an operator record, provided that the operator record defines \lstinline!'0'! and \lstinline!'+'!.
It is then assumed to form an additive group.

For \lstinline!Integer! indexing this is
\begin{lstlisting}[language=modelica]
$e$($u$[1], $\ldots$, $v$[1]) + $e$($u$[2], $\ldots$, $v$[1]) + $\ldots$
 + $e$($u$[end], $\ldots$, $v$[1]) + $\ldots$
 + $e$($u$[end], $\ldots$, $v$[end])
\end{lstlisting}
For non-\lstinline!Integer! indexing this uses all valid indices instead of 1..\lstinline!end!.

The type of \lstinline!sum($e$($i$, $\ldots$, $j$) for $i$ in $u$, $\ldots$, $j$ in $v$)! is the same as the type of \lstinline!$e$($i$, $\ldots$, $j$)!.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[product]\label{modelica:product-of-array}\index{product@\robustinline{product}!of array}
\begin{synopsis}\begin{lstlisting}
product($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
% Dangerous to say "scalar product" when not referring to anything related to inner products.
Returns the scalar product of all the elements of array expression \lstinline!A!.  Equivalent to product reduction (see below) over all array indices: \lstinline!product($A$[j, k, $\ldots$] for j, k, $\ldots$)!
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition*}[product]\label{modelica:product-reduction}\index{product@\robustinline{product}!reduction expression}
\begin{synopsis}\begin{lstlisting}
product($e$($i$, $\ldots$, $j$) for $i$ in $u$, $\ldots$, $j$ in $v$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Also described in \cref{reduction-expressions}.  Returns the product of the expression \lstinline!$e$($i$, $\ldots$, $j$)! evaluated for all combinations of $i$ in $u$, \ldots, $j$ in $v$.

For \lstinline!Integer! indexing this is
\begin{lstlisting}[language=modelica]
$e$($u$[1], $\ldots$, $v$[1]) * $e$($u$[2], $\ldots$, $v$[1]) * $\ldots$
 * $e$($u$[end], $\ldots$, $v$[1]) * $\ldots$
 * $e$($u$[end], $\ldots$, $v$[end])
\end{lstlisting}
For non-\lstinline!Integer! indexing this uses all valid indices instead of 1..\lstinline!end!.

The type of \lstinline!product($e$($i$, $\ldots$, $j$) for $i$ in $u$, $\ldots$, $j$ in $v$)! is the same as the type of \lstinline!$e$($i$, $\ldots$, $j$)!.
\end{semantics}
\end{operatordefinition*}

\subsubsection{Reduction Expressions}\label{reduction-expressions}

An expression:
\begin{lstlisting}[language=grammar]
function-name "(" expression1 for iterators ")"
\end{lstlisting}%
\index{for@\robustinline{for}!reduction expression}
is a \firstuse{reduction expression}.
The expressions in the iterators of a reduction expression shall be vector expressions.
They are evaluated once for each reduction expression, and are evaluated in the scope immediately enclosing the reduction expression.

For an iterator:
\begin{lstlisting}[language=grammar]
IDENT in expression2
\end{lstlisting}%
\index{in@\robustinline{in}!reduction expression}
the loop-variable, \lstinline!IDENT!, is in scope inside \lstinline!expression1!.
The loop-variable may hide other variables, as in \lstinline!for!-loops.
The result depends on the \lstinline!function-name!, and currently the only legal function-names are the built-in operators \lstinline!array!, \lstinline!sum!, \lstinline!product!, \lstinline!min!, and \lstinline!max!.
For array, see \cref{vector-matrix-and-array-constructors}.
If \lstinline!function-name! is \lstinline!sum!, \lstinline!product!, \lstinline!min!, or \lstinline!max! the result is of the same type as \lstinline!expression1! and is constructed by evaluating \lstinline!expression1! for each value of the loop-variable and computing the \lstinline!sum!, \lstinline!product!, \lstinline!min!, or \lstinline!max! of the computed elements.
For deduction of ranges, see \cref{implicit-iteration-ranges}; and for using types as ranges see \cref{types-as-iteration-ranges}.

\begin{table}[H]
\caption{Reduction expressions with iterators.  (The least and greatest values of \lstinline!Real! are available as \lstinline!-Modelica.Constants.inf! and \lstinline!Modelica.Constants.inf!, respectively.)}
\begin{center}
\begin{tabular}{l l l}
\hline
\tablehead{Reduction} & \tablehead{Restriction on \lstinline!expression1!} & \tablehead{Result for empty \lstinline!expression2!}\\
\hline
\hline
{\lstinline!sum!} & {\lstinline!Integer!} or {\lstinline!Real!} & {\lstinline!zeros($\ldots$)!}\\
{\lstinline!product!} & Scalar {\lstinline!Integer!} or {\lstinline!Real!} & 1\\
{\lstinline!min!} & Scalar enumeration, {\lstinline!Boolean!}, {\lstinline!Integer!} or {\lstinline!Real!} & Greatest value of type\\
{\lstinline!max!} & Scalar enumeration, {\lstinline!Boolean!}, {\lstinline!Integer!} or {\lstinline!Real!} & Least value of type\\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{example}
% No frame since the math would break it.
\begin{lstlisting}[language=modelica, frame=none]
sum(i for i in 1:10) // Gives $\sum_{i=1}^{10}i$ = 1 + 2 + $\ldots$ + 10 = 55
// Read it as: compute the sum of i for i in the range 1 to 10.
sum(i^2 for i in {1,3,7,6}) // Gives $\sum_{i\in \{1,\, 3,\, 7,\, 6\}}i^2$ = 1 + 9 + 49 + 36 = 95
{product(j for j in 1:i) for i in 0:4} // Gives {1, 1, 2, 6, 24}
max(i^2 for i in {3,7,6}) // Gives 49
\end{lstlisting}
\end{example}

\subsection{Matrix and Vector Algebra Functions}\label{matrix-and-vector-algebra-functions}

Functions for matrix and vector algebra are listed below.  The function \lstinline!transpose! can be applied to any matrix.  The functions \lstinline!outerProduct!,  \lstinline!symmetric!, \lstinline!cross! and \lstinline!skew! require \lstinline!Real! vector(s) or matrix as input(s) and return a \lstinline!Real! vector or matrix.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!transpose($A$)!} & Matrix transpose & \Cref{modelica:transpose} \\
{\lstinline!outerProduct($x$, $y$)!} & Vector outer product & \Cref{modelica:outerProduct} \\
{\lstinline!symmetric($A$)!} & Symmetric matrix, keeping upper part & \Cref{modelica:symmetric} \\
{\lstinline!cross($x$, $y$)!} & Cross product & \Cref{modelica:cross} \\
{\lstinline!skew($x$)!} & Skew symmetric matrix associated with vector & \Cref{modelica:skew} \\
\hline
\end{tabular}
\end{center}

% Using operatordefinition rather than functiondefinition, since the result types cannot be expressed with a Modelica type signature.
\begin{operatordefinition}[transpose]
\begin{synopsis}\begin{lstlisting}
transpose($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Permutes the first two dimensions of array $A$.  It is an error if array $A$ does not have at least 2 dimensions.
\end{semantics}
\end{operatordefinition}

\begin{functiondefinition}[outerProduct]
\begin{synopsis}\begin{lstlisting}
outerProduct($x$, $y$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the outer product of vectors $x$ and $y$, that is: \lstinline!matrix($x$) * transpose(matrix($y$))!
\end{semantics}
\end{functiondefinition}

\begin{functiondefinition}[symmetric]
\begin{synopsis}\begin{lstlisting}
symmetric($A$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns a symmetric matrix which is identical to the square matrix $A$ on and above the diagonal.

That is, if \lstinline!B := symmetric($A$)!, then \lstinline!B! is given by:
\begin{equation*}
\text{\lstinline!B[$i$, $j$]!} =
\begin{cases}
\text{\lstinline!$A$[$i$, $j$]!} & \text{if $i \leq j$}\\
\text{\lstinline!$A$[$j$, $i$]!} & \text{if $i > j$}
\end{cases}
\end{equation*}
\end{semantics}
\end{functiondefinition}

\begin{functiondefinition}[cross]
\begin{synopsis}\begin{lstlisting}
cross($x$, $y$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the cross product of the 3-vectors $x$ and $y$:
\begin{lstlisting}[frame=none]
vector([ $x$[2] * $y$[3] - $x$[3] * $y$[2] ;
         $x$[3] * $y$[1] - $x$[1] * $y$[3] ;
         $x$[1] * $y$[2] - $x$[2] * $y$[1] ])
\end{lstlisting}
\end{semantics}
\end{functiondefinition}

\begin{functiondefinition}[skew]
\begin{synopsis}\begin{lstlisting}
skew($x$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns the $3 \times 3$ skew symmetric matrix associated with a 3-vector, i.e., \lstinline!cross($x$, $y$) = skew($x$) * $y$!.  Equivalently, \lstinline!skew($x$)! is given by:
\begin{lstlisting}[frame=none]
[ 0,   -$x$[3], $x$[2] ;
  $x$[3], 0,   -$x$[1] ;
 -$x$[2], $x$[1], 0    ]
\end{lstlisting}
\end{semantics}
\end{functiondefinition}

\section{Vector, Matrix and Array Constructors}\label{vector-matrix-and-array-constructors}

The \firstuse[array!constructor]{array constructor} function \lstinline!array(A, B, C, $\ldots$)! constructs an array from its arguments according to the following rules:
\begin{itemize}
\item
  Size matching: All arguments must have the same sizes, i.e.,
  \lstinline!size(A)! = \lstinline!size(B)! = \lstinline!size(C)! = \ldots
\item
  All arguments must be type compatible expressions (\cref{type-compatible-expressions}) giving the type of the elements.  The data type of the result array is the
  maximally expanded type of the arguments. \lstinline!Real! and \lstinline!Integer! subtypes can be mixed resulting in a \lstinline!Real! result array where the
  \lstinline!Integer! numbers have been transformed to \lstinline!Real! numbers.
\item
  Each application of this constructor function adds a one-sized dimension to the left in the result compared to the dimensions of the argument arrays, i.e.,
  \lstinline!ndims(array(A, B, C)) = ndims(A) + 1 = ndims(B) + 1, $\ldots$!
\item
  \lstinline!{A, B, C, $\ldots$}! is a shorthand notation for \lstinline!array(A, B, C, $\ldots$)!.
\item
  There must be at least one argument.
  \begin{nonnormative}
  The reason \lstinline!array()! or \lstinline!{}! is not defined is that at least one argument is needed to determine the type of the resulting array.
  \end{nonnormative}
\end{itemize}

\begin{example}
\begin{lstlisting}[language=modelica, escapechar=!]
{1, 2, 3} !\emph{is a 3-vector of type Integer}.!
{{11, 12, 13}, {21, 22, 23}} !\emph{is a 2 x 3 matrix of type Integer}!
{{{1.0, 2.0, 3.0}}} !\emph{is a 1 x 1 x 3 array of type Real}.!

Real[3] v = array(1, 2, 3.0);
type Angle = Real(unit="rad");
parameter Angle alpha = 2.0; // type of alpha is Real.
// array(alpha, 2, 3.0) or {alpha, 2, 3.0} is a 3-vector of type Real.
Angle[3] a = {1.0, alpha, 4}; // type of a is Real[3].
\end{lstlisting}
\end{example}

\subsection{Constructor with Iterators}\label{array-constructor-with-iterators}\label{constructor-with-iterators}

An expression:
\begin{lstlisting}[language=grammar]
"{" expression for iterators "}"
\end{lstlisting}
or
\begin{lstlisting}[language=grammar]
array "(" expression for iterators ")"
\end{lstlisting}
is an \firstuse[array!constructor!with iterators]{array constructor with iterators}.
The expressions inside the iterators of an array constructor shall be vector expressions.
They are evaluated once for each array constructor, and are evaluated in the scope immediately enclosing the array constructor.

For an iterator:
\begin{lstlisting}[language=modelica]
IDENT in array_expression
\end{lstlisting}
the loop-variable, \lstinline!IDENT!, is in scope inside expression in the array construction.
The loop-variable may hide other variables, as in \lstinline!for!-loops.
The loop-variable has the same type as
the type of the elements of \lstinline!array_expression!; and can be simple type as well as a record type.
The loop-variable will have the same type for the entire loop -- i.e., for an
\lstinline!array_expression! \lstinline!{1, 3.2}! the iterator will have the type of the type-compatible expression (\lstinline!Real!) for all iterations.
For deduction of ranges, see
\cref{implicit-iteration-ranges}; and for using types as range see \cref{types-as-iteration-ranges}.

\subsubsection{Constructor with One Iterator}\label{array-constructor-with-one-iterator}\label{constructor-with-one-iterator}

If only one iterator is used, the result is a vector constructed by
evaluating expression for each value of the loop-variable and forming an
array of the result.

\begin{example}
\begin{lstlisting}[language=modelica]
array(i for i in 1:10)
// Gives the vector 1:10 = {1, 2, 3, $\ldots$, 10}

{r for r in 1.0 : 1.5 : 5.5}
// Gives the vector 1.0:1.5:5.5 = {1.0, 2.5, 4.0, 5.5}

{i^2 for i in {1,3,7,6}}
// Gives the vector {1, 9, 49, 36}
\end{lstlisting}
\end{example}

\subsubsection{Constructor with Several Iterators}\label{array-constructor-with-several-iterators}\label{constructor-with-several-iterators}

The notation with several iterators is a shorthand notation for nested
array constructors. The notation can be expanded into the usual form by
replacing each '\lstinline!,!' by '\lstinline!} for!' and prepending the array constructor with
a '\lstinline!{!'.

\begin{example}
\begin{lstlisting}[language=modelica]
Real toeplitz[:,:] = {i-j for i in 1:n, j in 1:n};
Real toeplitz2[:,:] = {{i-j for i in 1:n} for j in 1:n};
\end{lstlisting}
\end{example}

\subsection{Concatenation}\label{array-concatenation}\label{concatenation}

The function \lstinline!cat($k$, A, B, C, $\ldots$)!\indexinline{cat} concatenates arrays \lstinline!A!, \lstinline!B!, \lstinline!C!, \ldots along dimension $k$ according to the following rules:
\begin{itemize}
\item
  Arrays \lstinline!A!, \lstinline!B!, \lstinline!C!, \ldots must have the same number of dimensions, i.e., \lstinline!ndims(A)! = \lstinline!ndims(B)! = \ldots
\item
  Arrays \lstinline!A!, \lstinline!B!, \lstinline!C!, \ldots must be type compatible expressions (\cref{type-compatible-expressions}) giving the type of the elements of the result.
The maximally expanded types should be equivalent.
  \lstinline!Real! and \lstinline!Integer! subtypes can be mixed resulting in a \lstinline!Real! result array where the \lstinline!Integer! numbers have been transformed to \lstinline!Real! numbers.
\item
  $k$ has to characterize an existing dimension, i.e., $1 \leq k \leq \text{\lstinline!ndims(A)!} = \text{\lstinline!ndims(B)!} = \text{\lstinline!ndims(C)!}$; $k$ shall be a parameter expression of \lstinline!Integer! type.
\item
  Size matching: Arrays \lstinline!A!, \lstinline!B!, \lstinline!C!, \ldots must have identical array sizes with the exception of the size of dimension $k$, i.e., \lstinline!size(A, $j$)! = \lstinline!size(B, $j$)!, for $1 \leq j \leq \text{\lstinline!ndims(A)!}$ and $j \neq k$.
\end{itemize}

\begin{example}
\begin{lstlisting}[language=modelica]
Real[2,3] r1 = cat(1, {{1.0, 2.0, 3}}, {{4, 5, 6}});
Real[2,6] r2 = cat(2, r1, 2*r1);
\end{lstlisting}
\end{example}

Formally, the concatenation \lstinline!R = cat($k$, A, B, C, $\ldots$)! is defined as follows.  Let $n$ = \lstinline!ndims(A)! = \lstinline!ndims(B)! = \lstinline!ndims(C)! = \ldots  Then the size of \lstinline!R! is given by
\begin{lstlisting}[language=modelica,escapechar=!,frame=none,xleftmargin=1em]
size(R,$k$) = size(A,$k$) + size(B,$k$) + size(C,$k$) + $\ldots$
size(R,$j$) = size(A,$j$) = size(B,$j$) = size(C,$j$) = $\ldots$ !for! $1 \leq j \leq n$ !and! $j \neq k$
\end{lstlisting}
and the array elements of \lstinline!R! are given by
\begin{lstlisting}[language=modelica,escapechar=!,frame=none,xleftmargin=1em]
R[$i_{1}$, $\ldots$, $i_{k}$, $\ldots$, $i_{n}$] = A[$i_{1}$, $\ldots$, $i_{k}$, $\ldots$, $i_{n}$]
  !for! $0 < i_{k} \leq$ size(A,$k$)
R[$i_{1}$, $\ldots$, $i_{k}$, $\ldots$, $i_{n}$] = B[$i_{1}$, $\ldots$, $i_{k}$ - size(A,$k$), $\ldots$, $i_{n}$]
  !for! size(A,$k$) $< i_{k} \leq$ size(A,$k$) + size(B,$k$)
R[$i_{1}$, $\ldots$, $i_{k}$, $\ldots$, $i_{n}$] = C[$i_{1}$, $\ldots$, $i_{k}$ - size(A,$k$) - size(B,$k$), $\ldots$, $i_{n}$]
  !for! size(A,$k$) + size(B,$k$) $< i_{k} \leq$ size(A,$k$) + size(B,$k$) + size(C,$k$)
$\ldots$
\end{lstlisting}
where $1 \leq i_{j} \leq$ \lstinline!size(R,$j$)! for $1 \leq j \leq n$.


\subsubsection{Concatenation along First and Second Dimensions}\label{array-concatenation-along-first-and-second-dimensions}\label{concatenation-along-first-and-second-dimensions}

For convenience, a special syntax is supported for the concatenation along the first and second dimensions:
\begin{itemize}
\item
  \emph{Concatenation along first dimension}:\\
  \lstinline![A; B; C; $\ldots$] = cat(1, promote(A, n), promote(B, n), promote(C, n), $\ldots$)! where \lstinline!n = max(2, ndims(A), ndims(B), ndims(C), $\ldots$)!.
  If necessary, 1-sized dimensions are added to the right of \lstinline!A!, \lstinline!B!, \lstinline!C! before the operation is carried out, in order that the operands have the same number of dimensions which will be at least two.
\item
  \emph{Concatenation along second dimension}:\\
  \lstinline![A, B, C, $\ldots$] = cat(2, promote(A, n), promote(B, n), promote(C, n), $\ldots$)! where \lstinline!n = max(2, ndims(A), ndims(B), ndims(C), $\ldots$)!.
  If necessary, 1-sized dimensions are added to the right of \lstinline!A!, \lstinline!B!, \lstinline!C! before the operation is carried out, especially that each operand has at least two dimensions.
\item
  The two forms can be mixed.
  \lstinline![$\ldots$, $\ldots$]! has higher precedence than \lstinline![$\ldots$; $\ldots$]!, e.g., \lstinline![a, b; c, d]! is parsed as \lstinline![[a, b]; [c, d]]!.
\item
  \lstinline![A] = promote(A, max(2, ndims(A)))!, i.e., \lstinline![A] = A!, if \lstinline!A! has 2 or more dimensions, and it is a matrix with the elements of \lstinline!A!, if \lstinline!A! is a scalar or a vector.
\item
  There must be at least one argument (i.e., \lstinline![]! is not defined).
\end{itemize}

\begin{example}
\begin{lstlisting}[language=modelica]
Real s1, s2, v1[n1], v2[n2], M1[m1,n],
M2[m2,n], M3[n,m1], M4[n,m2], K1[m1,n,k],
K2[m2,n,k];
[v1;v2] is a (n1+n2) x 1 matrix
[M1;M2] is a (m1+m2) x n matrix
[M3,M4] is a n x (m1+m2) matrix
[K1;K2] is a (m1+m2) x n x k array
[s1;s2] is a 2 x 1 matrix
[s1,s1] is a 1 x 2 matrix
[s1] is a 1 x 1 matrix
[v1] is a n1 x 1 matrix
Real[3] v1 = array(1, 2, 3);
Real[3] v2 = {4, 5, 6};
Real[3,2] m1 = [v1, v2];
Real[3,2] m2 = [v1, [4;5;6]]; // m1 = m2
Real[2,3] m3 = [1, 2, 3; 4, 5, 6];
Real[1,3] m4 = [1, 2, 3];
Real[3,1] m5 = [1; 2; 3];
\end{lstlisting}
\end{example}

\subsection{Vector Construction}\label{vector-construction}

Vectors can be constructed with the general array constructor, e.g.,
\begin{lstlisting}[language=modelica]
Real[3] v = {1, 2, 3};
\end{lstlisting}
The range vector operator or colon operator of \lstinline[language=grammar]!simple-expression! can be used instead of or in combination with this general constructor to construct \lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean! or enumeration type vectors.
Semantics of the colon operator:
\begin{itemize}
\item
  \lstinline!$j$ : $k$! is the \lstinline!Integer! vector \lstinline!{$j$, $j+1$, $\ldots$, $k$}!, if $j$ and $k$ are of type
  \lstinline!Integer!.
\item
  \lstinline!$j$ : $k$! is the \lstinline!Real! vector \lstinline!{$j$, $j+1.0$, $\ldots$, $j+n$}!, with $n = \text{\lstinline!floor!}(k - j)$, if
  $j$ and/or $k$ are of type \lstinline!Real!.
\item
  \lstinline!$j$ : $k$! is a \lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean!, or \lstinline!enumeration! type vector with zero elements, if $j > k$.
\item
  \lstinline!$j$ : $d$ : $k$! is the \lstinline!Integer! vector \lstinline!{$j$, $j+d$, $\ldots$, $j + n d$}!, with $n = \text{\lstinline!div!}(k - j, d)$, if $j$, $d$, and $k$ are of type \lstinline!Integer!.
\item
  \lstinline!$j$ : $d$ : $k$! is the \lstinline!Real! vector \lstinline!{$j$, $j+d$, $\ldots$, $j + n d$}!, with $n = \text{\lstinline!floor!}((k-j)/d)$,
  if $j$, $d$, or $k$ are of type \lstinline!Real!.  In order to avoid rounding issues for the length it is recommended to use \lstinline!{j + d * i for i in 0 : n}! or
  \lstinline!linspace(j, k, n + 1)! -- if the number of elements are known.
\item
  \lstinline!$j$ : $d$ : $k$! is a \lstinline!Real! or \lstinline!Integer! vector with zero elements, if $d > 0$ and $j > k$ or if $d < 0$ and $j < k$.
\item
  \lstinline!false : true! is the \lstinline!Boolean! vector \lstinline!{false, true}!.
\item
  \lstinline!$j$ : $j$! is \lstinline!{$j$}! if $j$ is \lstinline!Real!, \lstinline!Integer!, \lstinline!Boolean!, or \lstinline!enumeration! type.
\item
  \lstinline!E.ei : E.ej! is the enumeration type vector \lstinline!{E.ei, $\ldots$, E.ej}! where
  $\text{\lstinline!E.ej!} > \text{\lstinline!E.ei!}$, and \lstinline!ei! and \lstinline!ej! belong to some enumeration type
  \lstinline!E = enumeration($\ldots$, ei, $\ldots$, ej, $\ldots$)!.
\end{itemize}

\begin{example}
\begin{lstlisting}[language=modelica]
Real v1[5] = 2.7 : 6.8;
Real v2[5] = {2.7, 3.7, 4.7, 5.7, 6.7}; // = same as v1
Boolean b1[2] = false:true;
Colors = enumeration (red,blue,green);
Colors ec[3] = Colors.red : Colors.green;
\end{lstlisting}
\end{example}

\section{Indexing}\label{array-indexing}\label{indexing}

The array indexing operator \lstinline!$\mathit{name}$[$\ldots$]! is used to access array elements for retrieval of their values or for updating these values.
An indexing operation is subject to upper and lower array dimension index bounds (\cref{array-dimension-lower-and-upper-index-bounds}).
The indexing operator takes two or more operands, where the first operand is the array to be indexed and the rest of the operands are \firstuse{index} (or \firstuse{subscript}) expressions:

\lstinline!$\mathit{arrayname}$[$\mathit{indexexpr}_{1}$, $\mathit{indexexpr}_{2}$, $\ldots$]!

A colon (`\lstinline!:!') is used to denote all indices of one dimension.
A vector expression can be used to pick out selected rows, columns and elements of vectors, matrices, and arrays.
The number of dimensions of the expression is reduced by the number of scalar index arguments.
If the number of index arguments is smaller than the number of dimensions of the array, the trailing indices will use `\lstinline!:!'.

It is also possible to use the array access operator to assign to element/elements of an array in algorithm sections.
This is called an \firstuse[assignment statement!indexed]{indexed assignment statement}.
If the index is an array the assignments take place in the order given by the index array.
For assignments to arrays and elements of arrays, the entire right-hand side and the index on the left-hand side are evaluated before any element is assigned a new value.

\begin{nonnormative}
An indexing operation is assumed to take constant time, i.e., largely independent of the size of the array.
\end{nonnormative}

\begin{example}
Array indexing expressions:
\begin{lstlisting}[language=modelica]
a[:, j]      // Vector of the j'th column of a.
a[j]         // Vector of the j'th row of a. Same as: a[j, :]
a[j : k]     // Same as: {a[j], a[j+1], $\ldots$, a[k]}
a[:, j : k]  // Same as: [a[:, j], a[:, j+1], $\ldots$, a[:, k]]
\end{lstlisting}
The range vector operator is just a special case of a vector expression:
\begin{lstlisting}[language=modelica]
v[2 : 2 : 8] // Same as: v[{2, 4, 6, 8}]
\end{lstlisting}
Array indexing in assignment statements:
\begin{lstlisting}[language=modelica]
v[{j, k}] := {2, 3}; // Same as: v[j] := 2; v[k] := 3;
v[{1, 1}] := {2, 3}; // Same as: v[1] := 3;
\end{lstlisting}
If \lstinline!x! is a vector, \lstinline!x[1]! is a scalar, but the slice \lstinline!x[1:5]! is a vector
(a vector-valued or colon index expression causes a vector to be returned).
\end{example}

\begin{table}[H]
\caption{Examples of scalars vs.\ array slices created with the colon index.  The examples make use of the array variables \lstinline!x[$n$, $m$]!, \lstinline!v[$k$]!, and \lstinline!z[$i$, $j$, $p$]!.}
\begin{center}
\begin{tabular}{l c l}
\hline
\tablehead{Expression} & \tablehead{\# dims} & \tablehead{Description}\\
\hline
\hline
{\lstinline!x[1, 1]!}                     & 0 & Scalar\\
{\lstinline!x[:, 1]!}                     & 1 & $n$-vector\\
{\lstinline!x[1, :]!} or {\lstinline!x[1]!} & 1 & $m$-vector\\
{\lstinline!v[1:$p$]!}                    & 1 & $p$-vector\\
{\lstinline!x[1:$p$, :]!}                 & 2 & $p \times m$ matrix\\
{\lstinline!x[1:1, :]!}                   & 2 & $1 \times m$ ``row'' matrix\\
{\lstinline!x[{1, 3, 5}, :]!}             & 2 & $3 \times m$ matrix\\
{\lstinline!x[:, v]!}                     & 2 & $n \times k$ matrix\\
{\lstinline!z[:, 3, :]!}                  & 2 & $i \times p$ matrix\\
{\lstinline!x[scalar([1]), :]!}           & 1 & $m$-vector\\
{\lstinline!x[vector([1]), :]!}           & 2 & $1 \times m$ ``row'' matrix\\
\hline
\end{tabular}
\end{center}
\end{table}

\subsection{Boolean or Enumeration Indices}\label{boolean-or-enumeration-indices}

Arrays can be indexed using values of enumeration types or the \lstinline!Boolean! type, not only by \lstinline!Integer!.  The type of the index should correspond to
the type used for declaring the dimension of the array.

\begin{example}
\begin{lstlisting}[language=modelica]
  type ShirtSizes = enumeration(small, medium, large, xlarge);
  Real[ShirtSizes] w;
  Real[Boolean] b2;
algorithm
  w[ShirtSizes.large] := 2.28; // Assign a value to an element of w
  b2[true] := 10.0;
  b2[ShirtSizes.medium] := 4; // Error, b2 was declared with Boolean dimension
  w[1] := 3; // Error, w was declared with ShirtSizes dimension
\end{lstlisting}
\end{example}

\subsection{Indexing with end}\label{indexing-with-end}

The expression \lstinline!end!\indexinline{end} may only appear inside array subscripts, and if used in the $i$th subscript of an array expression \lstinline!A! it is equivalent to the upper bound of the $i$th dimension of \lstinline!A!.
If used inside nested array subscripts it refers to the most closely nested array.

\begin{nonnormative}
If indices to \lstinline!A! are a subtype of \lstinline!Integer! it is equivalent to \lstinline!size(A, i)!.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica, escapechar=!]
A[end - 1, end] !is! A[size(A,1) - 1, size(A,2)]
A[v[end], end] !is! A[v[size(v,1)], size(A,2)] // !\emph{First}! end !\emph{is referring to end of v.}!

Real B[Boolean];
B[end] !is! B[true]
\end{lstlisting}
\end{example}

\section{Scalar, Vector, Matrix, and Array Operator Functions}\label{scalar-vector-matrix-and-array-operator-functions}

The mathematical operations defined on scalars, vectors, and matrices are the subject of linear algebra.

The term numeric or numeric class is used below for a subtype of the \lstinline!Real! or \lstinline!Integer! type classes.  The standard type coercion defined
in \cref{standard-type-coercion} applies.

\subsection{Equality and Assignment}\label{equality-and-assignment}

Equality \lstinline!a = b! and assignment \lstinline!a := b! of scalars, vectors, matrices, and arrays is defined element-wise and require both objects to have the same number of dimensions and corresponding dimension sizes.
See \cref{array-indexing} regarding assignments to array variables with vector of subscripts.

The operands need to be type equivalent.
This is legal for the simple types and all types satisfying the requirements for a record, and is in the latter case applied to each component-element of the records.

\begin{table}[H]
\caption{Equality and assignment of arrays and scalars.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!b!} & \tablehead{Size of \lstinline!a = b!} & \tablehead{Operation}\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!a = b!}\\
$n$-vector & $n$-vector & $n$-vector & {\lstinline!a[$j$] = b[$j$]!}\\
$n \times m$ matrix & $n \times m$ matrix & $n \times m$ matrix & {\lstinline!a[$j$, $k$] = b[$j$, $k$]!}\\
$n \times m \times \ldots$ & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!a[$j$, $k$, $\ldots$] = b[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\subsection{Addition, Subtraction, and String Concatenation}\label{array-element-wise-addition-subtraction-and-string-concatenation}\label{addition-subtraction-and-string-concatenation}

Addition \lstinline!a + b! and subtraction \lstinline!a - b! of numeric scalars, vectors, matrices,
and arrays is defined element-wise and require \lstinline!size(a) = size(b)! and a
numeric type for \lstinline!a! and \lstinline!b!. Unary plus and minus are defined element-wise.
Addition \lstinline!a + b! of string scalars, vectors, matrices, and arrays is defined
as element-wise string concatenation of corresponding elements from \lstinline!a!
and \lstinline!b!, and require \lstinline!size(a) = size(b)!.

\begin{table}[H]
\caption{Array addition, subtraction, and string concatenation.  In this table the symbolic operator $\pm$ represents either \lstinline!+! or \lstinline!-!.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!b!} & \tablehead{Size of \lstinline!a! $\pm$ \lstinline!b!} &
% Warning: Spacing inside \lstinline doesn't work properly inside \tablehead.
\tablehead{Operation} \lstinline!c := a $\pm$ b!\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!c := a $\pm$ b!}\\
$n$-vector & $n$-vector & $n$-vector & {\lstinline!c[$j$] := a[$j$] $\pm$ b[$j$]!}\\
$n \times m$ matrix & $n \times m$ matrix & $n \times m$ matrix & {\lstinline!c[$j$, $k$] := a[$j$, $k$] $\pm$ b[$j$, $k$]!}\\
$n \times m \times \ldots$ & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] $\pm$ b[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

Element-wise addition \lstinline!a .+ b! and subtraction \lstinline!a .- b! of numeric scalars, vectors, matrices or arrays \lstinline!a! and \lstinline!b! requires a
numeric type class for \lstinline!a! and \lstinline!b! and either \lstinline!size(a) = size(b)! or scalar \lstinline!a! or scalar \lstinline!b!.  Element-wise addition
\lstinline!a .+ b! of string scalars, vectors, matrices, and arrays is defined as element-wise string concatenation of corresponding elements from \lstinline!a! and
\lstinline!b!, and require either \lstinline!size(a) = size(b)! or scalar \lstinline!a! or scalar \lstinline!b!.

\begin{table}[H]
\caption{Array element-wise addition, subtraction, and string concatenation.  In this table the symbolic operator $\pm$ represents either \lstinline!+! or \lstinline!-!, and when preceded by a dot (\lstinline!.$\pm$!), either \lstinline!.+! or \lstinline!.-!.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!b!} & \tablehead{Size of \lstinline!a .$\pm$ b!}
& \tablehead{Operation \lstinline!c := a .$\pm$ b!}\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!c := a $\pm$ b!}\\
Scalar & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a $\pm$ b[$j$, $k$, $\ldots$]!}\\
$n \times m \times \ldots$ & Scalar & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] $\pm$ b!}\\
$n \times m \times \ldots$ & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] $\pm$ b[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{table}[H]
\caption{Unary operators.  In this table the symbolic operator $\pm$ represents either unary \lstinline!+! or unary \lstinline!-!.  The element-wise (\lstinline!.+!, \lstinline!.-!) and normal (\lstinline!+!, \lstinline!-!) operators give the same results.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!$\pm$ a!} &
% Warning: Spacing inside \lstinline doesn't work properly inside \tablehead.
\tablehead{Operation} \lstinline!c := $\pm$ a!\\
\hline
\hline
Scalar & Scalar & {\lstinline!c := $\pm$ a!}\\
$n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := $\pm$ a[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\subsection{Element-wise Multiplication}\label{array-element-wise-multiplication}\label{element-wise-multiplication}

Scalar multiplication \lstinline!s * a! or \lstinline!a * s! with numeric scalar s and numeric
scalar, vector, matrix or array \lstinline!a! is defined element-wise:
\begin{table}[H]
\caption{Scalar and scalar to array multiplication of numeric elements.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!s!} & \tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!s * a! and \lstinline!a * s!} &
\tablehead{Operation \lstinline!c := s * a! or \lstinline!c := a * s!}\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!c := s * a!}\\
Scalar & $n$-vector & $n$-vector & {\lstinline!c[$j$] := s * a[$j$]!}\\
Scalar & $n \times m$ matrix & $n \times m$ matrix & {\lstinline!c[$j$, $k$] := s * a[$j$, $k$]!}\\
Scalar & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := s * a[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

Element-wise multiplication \lstinline!a .* b! of numeric scalars, vectors, matrices or arrays \lstinline!a! and \lstinline!b! requires a numeric type class
for \lstinline!a! and \lstinline!b! and either \lstinline!size(a) = size(b)! or scalar \lstinline!a! or scalar \lstinline!b!.

\begin{table}[H]
\caption{Array element-wise multiplication.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}\label{tab:product}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!b!} & \tablehead{Size of \lstinline!a .* b!} &
\tablehead{Operation} \lstinline!c := a .* b!\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!c := a * b!}\\
Scalar & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a * b[$j$, $k$, $\ldots$]!}\\
$n \times m \times \ldots$ & Scalar & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] * b!}\\
$n \times m \times \ldots$ & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] * b[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\subsection{Multiplication of Matrices and Vectors}\label{matrix-and-vector-multiplication-of-numeric-arrays}\label{multiplication-of-matrices-and-vectors}

Multiplication \lstinline!a * b! of numeric vectors and matrices is defined only for the following combinations:
\begin{table}[H]
\caption{Matrix and vector multiplication of arrays with numeric elements.  The scalar \tablehead{Operation} applies for all $i$ in $1,\, \ldots,\, l$ and $j$ in $1,\, \ldots,\, n$, and the summation over $k$ goes from 1 to $m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!b!} & \tablehead{Size of \lstinline!a * b!} &
\tablehead{Operation \lstinline!c := a * b!}\\
\hline
\hline
$m$-vector & $m$-vector & Scalar & {\lstinline!c := $\sum_{k}$ a[$k$] * b[$k$]!}\\
$m$-vector & $m \times n$ matrix & $n$-vector & {\lstinline!c[$j$] := $\sum_{k}$ a[$k$] * b[$k$, $j$]!}\\
$l \times m$ matrix & $m$-vector & $l$-vector & {\lstinline!c[$i$] := $\sum_{k}$ a[$i$, $k$] * b[$k$]!}\\
$l \times m$ matrix & $m \times n$ matrix & $l \times n$ matrix & {\lstinline!c[$i$, $j$] := $\sum_{k}$ a[$i$, $k$] * b[$k$, $j$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{example}
\begin{lstlisting}[language=modelica]
Real A[3, 3], x[3], b[3], v[3];
A * x = b;
x * A = b; // same as transpose([x])*A*b
[v] * transpose([v]) // outer product
v * A * v // scalar
tranpose([v]) * A * v // vector with one element
\end{lstlisting}
\end{example}

\subsection{Division by Numeric Scalars}\label{division-by-numeric-scalars}

Division \lstinline!a / s! of numeric scalars, vectors, matrices, or arrays \lstinline!a! and numeric scalars \lstinline!s! is defined element-wise.
The result is always of \lstinline!Real! type.  In order to get integer division with truncation, use the function \lstinline!div!.

\begin{table}[H]
\caption{Division of scalars and arrays by numeric elements.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!s!} & \tablehead{Size of \lstinline!a / s!} &
\tablehead{Operation \lstinline!c := a / s!}\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!c := a / s!}\\
$n$-vector & Scalar & $n$-vector & {\lstinline!c[$k$] := a[$k$] / s!}\\
$n \times m$ matrix & Scalar & $n \times m$ matrix & {\lstinline!c[$j$, $k$] := a[$j$, $k$] / s!}\\
$n \times m \times \ldots$ & Scalar & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] / s!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\subsection{Element-wise Division}\label{array-element-wise-division}\label{element-wise-division}

Element-wise division \lstinline!a ./ b! of numeric scalars, vectors, matrices or arrays \lstinline!a! and \lstinline!b! requires a numeric type class for \lstinline!a! and \lstinline!b!
and either \lstinline!size(a) = size(b)! or scalar \lstinline!a! or scalar \lstinline!b!.  The result is always of \lstinline!Real! type.  In order to get integer division with truncation,
use the function \lstinline!div!.

\begin{table}[H]
\caption{Element-wise division of arrays.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!b!} & \tablehead{Size of \lstinline!a ./ b!} &
\tablehead{Operation} \lstinline!c := a ./ b!\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!c := a / b!}\\
Scalar & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a / b[$j$, $k$, $\ldots$]!}\\
$n \times m \times \ldots$ & Scalar & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] / b!}\\
$n \times m \times \ldots$ & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] / b[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{example}
Element-wise division by scalar (\lstinline!./!) and division by scalar (\lstinline!/!) are identical: \lstinline!a ./ s = a / s!:
\begin{lstlisting}[language=modelica]
2./[1, 2; 3, 4]  // error; same as  2.0 / [1, 2; 3, 4]
2 ./[1, 2; 3, 4] // fine; element-wise division
\end{lstlisting}
This is a consequence of the parsing rules, since `\lstinline!2.!' is a lexical unit.  Using a space after the literal solves the problem.
\end{example}

\subsection{Element-wise Exponentiation}\label{element-wise-exponentiation}

Exponentiation \lstinline!a ^ b! always returns a \lstinline!Real! scalar value, and it is required that \lstinline!a! and \lstinline!b! are scalar \lstinline!Real! or \lstinline!Integer! expressions.
The result should correspond to mathematical exponentiation with the following special cases:
\begin{itemize}
\item For any value of \lstinline!a! (including $0.0$) and an \lstinline!Integer! $\text{\lstinline!b!} = 0$, the result is $1.0$.
\item If $\text{\lstinline!a!} < 0$ and \lstinline!b! is an \lstinline!Integer!, the result is defined as $\pm |a|^b$, with sign depending on whether \lstinline!b! is even (positive) or odd (negative).
\item A deprecated semantics is to treat $\text{\lstinline!a!} < 0$ and a \lstinline!Real! \lstinline!b! having a non-zero integer value as if \lstinline!b! were an \lstinline!Integer!.
\item For $\text{\lstinline!a!} = 0$ and $\text{\lstinline!b!} > 0$, the result is $0.0$.
\item
  Other exceptional situations are illegal.
  For example: $\text{\lstinline!a!} = 0.0$ and $\text{\lstinline!b!} = 0.0$ for a \lstinline!Real b!, $\text{\lstinline!a!} = 0.0$ and $\text{\lstinline!b!} < 0$, or $\text{\lstinline!a!} < 0$ and \lstinline!b! does not have an integer value.
\end{itemize}

\begin{nonnormative}
Except for defining the special case of $0.0^0$ it corresponds to \lstinline[language=C]!pow(double a, double b)! in the ANSI~C library.
The result is always \lstinline!Real! as negative exponents can give non-integer results also when both operands are \lstinline!Integer!.
The special treatment of \lstinline!Integer! exponents makes it possible to use $x^n$ in a power series.
\end{nonnormative}

Element-wise exponentiation \lstinline!a .^ b! of numeric scalars, vectors, matrices, or arrays \lstinline!a! and \lstinline!b! requires a numeric type class for
\lstinline!a! and \lstinline!b! and either \lstinline!size(a) = size(b)! or scalar \lstinline!a! or scalar \lstinline!b!.

\begin{table}[H]
\caption{Element-wise exponentiation of arrays.  The scalar \tablehead{Operation} applies for all $j$ in $1,\, \ldots,\, n$ and $k$ in $1,\, \ldots,\, m$.}
\begin{center}
\begin{tabular}{l l|l l}
\hline
\tablehead{Size of \lstinline!a!} & \tablehead{Size of \lstinline!b!} & \tablehead{Size of \lstinline!a .^ b!} &
\tablehead{Operation} \lstinline!c := a .^ b!\\
\hline
\hline
Scalar & Scalar & Scalar & {\lstinline!c := a ^ b!}\\
Scalar & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a ^ b[$j$, $k$, $\ldots$]!}\\
$n \times m \times \ldots$ & Scalar & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] ^ b!}\\
$n \times m \times \ldots$ & $n \times m \times \ldots$ & $n \times m \times \ldots$ & {\lstinline!c[$j$, $k$, $\ldots$] := a[$j$, $k$, $\ldots$] ^ b[$j$, $k$, $\ldots$]!}\\
\hline
\end{tabular}
\end{center}
\end{table}

\begin{example}
\begin{lstlisting}[language=modelica]
2.^[1, 2; 3, 4]  // error; same as 2.0 ^ [1, 2; 3, 4]
2 .^[1, 2; 3, 4] // fine; element-wise exponentiation
\end{lstlisting}
This is a consequence of the parsing rules, i.e., since \lstinline!2.! could be a lexical unit it seen as a lexical unit; using a space after
literals solves the problem.
\end{example}

\subsection{Scalar Exponentiation of Matrices}\label{scalar-exponentiation-of-square-matrices-of-numeric-elements}\label{scalar-exponentiation-of-matrices}

Exponentiation \lstinline!a ^ s! is defined if \lstinline!a! is a square numeric matrix and \lstinline!s! is a scalar as a subtype of \lstinline!Integer!
with $\text{\lstinline!s!} \geq 0$.  The exponentiation is done by repeated multiplication, e.g.:
\begin{lstlisting}[language=modelica]
a^3 = a * a * a;
a^0 = identity(size(a, 1));
assert(size(a, 1) == size(a, 2), "Matrix must be square");
a^1 = a;
\end{lstlisting}

\begin{nonnormative}
Non-\lstinline!Integer! exponents are forbidden, because this would require
computing the eigenvalues and eigenvectors of \lstinline!a! and this is no
longer an elementary operation.
\end{nonnormative}

\subsection{Slice Operation}\label{slice-operation}

The following holds for slice operations:
\begin{itemize}
\item
  If \lstinline!a! is an array containing scalar components and \lstinline!m! is a component of those components, the expression \lstinline!a.m! is interpreted as a
  slice operation.  It returns the array of components \lstinline!{a[1].m, $\ldots$}!.
\item
  If \lstinline!m! is also an array component, the slice operation is valid only if \lstinline!size(a[1].m)! = \lstinline!size(a[2].m)! = \ldots
\item
  The slicing operation can be combined with indexing, e.g., \lstinline!a.m[1]!.  It returns the array of components \lstinline!{a[1].m[1], a[2].m[1], $\ldots$}!,
  and does not require that \lstinline!size(a[1].m) = size(a[2].m)!.  The number of subscripts on \lstinline!m! must not be greater than the number of array dimension
  for \lstinline!m! (the number can be smaller, in which case the missing trailing indices are assumed to be `\lstinline!:!'), and is only valid if
  \lstinline!size(a[1].m[$\ldots$]) = size(a[2].m[$\ldots$])!.
\end{itemize}

\begin{example}
The size-restriction on the operand is only applicable if the indexing on the second operand uses vectors or colon as in the example:
\begin{lstlisting}[language=modelica]
  constant Integer m=3;
  Modelica.Blocks.Continuous.LowpassButterworth tf[m](n=2:(m+1));
  Real y[m];
  Real y2,y3;
equation
  // Extract the x1 slice even though different x1's have different lengths
  y = tf.x1[1] ; // Legal, = {tf[1].x1[1], tf[2].x1[1], $\ldots$ tf[m].x1[1]};
  y2 = sum(tf.x1[:]); // Illegal to extract all elements since they have
    // different lengths. Does not satisfy:
    // size(tf[1].x1[:]) = size(tf[2].x1[:]) = $\ldots$ = size(tf[m].x1[:])
  y3 = sum(tf.x1[1:2]); // Legal.
    // Since x1 has at least 2 elements in all tf, and
    // size(tf[1].x1[1:2]) = $\ldots$ = size(tf[m].x1[1:2]) = {2}
\end{lstlisting}
In this example the different \lstinline!x1! vectors have different lengths,
but it is still possible to perform some operations on them.
\end{example}

\subsection{Relational Operators}\label{relational-operators}

Relational operators \lstinline!<!, \lstinline!<=!, \lstinline!>!,
\lstinline!>=!, \lstinline!==!, \lstinline!<>!, are only defined for
scalar operands of simple types, not for arrays, see \cref{equality-relational-and-logical-operators}

\subsection{Boolean Operators}\label{boolean-operators}

The operators \lstinline!and! and \lstinline!or! take expressions of \lstinline!Boolean! type, which are either scalars or arrays of matching dimensions.  The operator \lstinline!not!
takes an expression of \lstinline!Boolean! type, which is either scalar or an array.  The result is the element-wise logical operation.  For short-circuit evaluation of \lstinline!and!
and \lstinline!or!, see \cref{evaluation-order}.

\subsection{Vectorized Calls of Functions}\label{vectorized-calls-of-functions}

See \cref{scalar-functions-applied-to-array-arguments}.

\subsection{Standard Type Coercion}\label{standard-type-coercion}

In all contexts that require an expression which is a subtype of \lstinline!Real!, an expression which is a subtype of \lstinline!Integer! can also be used;
the \lstinline!Integer! expression is automatically converted to \lstinline!Real!.

This also applies to arrays of \lstinline!Real!, and for fields of record expressions.  There is no similar rule for sub-typing.

\begin{example}
\begin{lstlisting}[language=modelica]
record RealR
  Real x,y;
end RealR;
record IntegerR
  Integer x,y;
end IntegerR;
parameter Integer a = 1;
Real y(start=a);           // Ok, a is automatically coerced to Real
RealR r1 = IntegerR(a, a); // Ok, record is automatically coerced
RealR r2 = RealR(a, a);    // Ok, a is automatically coerced to Real
\end{lstlisting}
\end{example}

\section{Empty Arrays}\label{empty-arrays}

Arrays may have dimension sizes of 0.  For example:
\begin{lstlisting}[language=modelica]
Real x[0]; // an empty vector
Real A[0, 3], B[5, 0], C[0, 0]; // empty matrices
\end{lstlisting}

Empty matrices can be constructed using the \lstinline!fill! function.
For example:
\begin{lstlisting}[language=modelica]
Real A[:,:] = fill(0.0, 0, 1); // a Real 0 x 1 matrix
Boolean B[:, :, :] = fill(false, 0, 1, 0); // a Boolean 0 x 1 x 0 matrix
\end{lstlisting}

\begin{example}
Whereas scalar indexing into an empty dimension of an array is an error, not all applications of indices to empty arrays are invalid:
\begin{lstlisting}
Real[1, 0] a = fill(0.0, 1, 0); // a Real 1 x 0 matrix
Real[0] a1a = a[1]; // empty vector
Real[0] a1b = a[1, :]; // same as above
Real[0] a1c = a[1, 1 : end]; // same as above, as 1 : end is empty
\end{lstlisting}
\end{example}

Size-requirements of operations, such as \lstinline!+!, \lstinline!-!, must also be fulfilled if a dimension is zero.  For example:
\begin{lstlisting}[language=modelica]
Real[3, 0] A, B;
Real[0, 0] C;
A + B // fine, result is an empty matrix
A + C // error, sizes do not agree
\end{lstlisting}

Multiplication of two empty matrices results in a zero matrix of corresponding numeric type if the result matrix has no zero dimension sizes, i.e.,
\begin{lstlisting}[language=modelica]
Real[0, m] * Real[m, n] = Real[0, n] // empty matrix
Real[m, n] * Real[n, 0] = Real[m, 0] // empty matrix
Real[m, 0] * Real[0, n] = fill(0.0, m, n) // non-empty matrix of zeros
\end{lstlisting}

\begin{example}
\begin{lstlisting}[language=modelica]
Real u[p], x[n], y[q], A[n, n], B[n, p], C[q, n], D[q, p];
der(x) = A * x + B * u
y = C * x + D * u
\end{lstlisting}
Assume $\text{\lstinline!n!} = 0$, $\text{\lstinline!p!} > 0$, $\text{\lstinline!q!} > 0$: Results in \lstinline!y = D * u!.
\end{example}