overloaded.tex

\chapter{Overloaded Operators}\label{overloaded-operators}

A Modelica \lstinline!operator record!\indexinline{operator record} can overload the behavior for operations such as constructing, adding, multiplying etc.

The overloading is defined in such a way that ambiguities are not allowed and give an error.
Furthermore, it is sufficient to define overloading for scalars.
Some overloaded array operations are automatically deduced from the overloaded scalar operations (see \cref{overloaded-binary-arrays} and \cref{overloaded-unary-array} in the lists below), and others can be defined independently of the corresponding scalar operations.

\section{Overview of Overloaded Operators}\label{overview-of-overloaded-operators}

In an \lstinline!operator record! the definition of operations are done using the specialized class \lstinline!operator! (a specialized class similar to \lstinline!package!, see \cref{specialized-classes}) followed by the name of the operation.
Each \lstinline!operator! class is comprised of functions implementing different variants of the operation for the \lstinline!operator record! class in which the definition resides.
% This was something weird that could be seen as a table originally,
% that is somewhat awkward - but keeping it.
%
% Changing to use itemize was attempted, but currently fails in LaTeXML
% https://github.com/brucemiller/LaTeXML/issues/1057
% (Note: It's pure coincide that this issue occured for this case.)
\begin{itemize}
\item Overloaded constructors, see \cref{overloaded-constructors}:\\ \lstinline!'constructor'!, \lstinline!'0'!
\item Overloaded string conversions, see \cref{overloaded-string-conversions}:\\ \lstinline!'String'!
\item Overloaded binary operations, see \cref{overloaded-binary-operations}:\\
  \lstinline!'+'!, \lstinline!'-'! (subtraction), \lstinline!'*'!, \lstinline!'/'!, \lstinline!'^'!,
  \lstinline!'=='!, \lstinline!'<='!, \lstinline!'>'!, \lstinline!'<'!,
  \lstinline!'>='!, \lstinline!'<='!, \lstinline!'and'!, \lstinline!'or'!
\item Overloaded unary operations, see \cref{overloaded-unary-operations}:\\
  \lstinline!'-'! (negation), \lstinline!'not'!
\end{itemize}

The functions defined in the operator-class must take at least one component of the record class as input, except for the constructor-functions which instead must return one component of the record class.
All of the functions shall return exactly one output.

The functions can be either called as defined in this section, or they can be called directly using the hierarchical name.
The operator or operator function must be encapsulated; this allows direct calls of the functions and prohibits the functions from using the elements of operator record class.

The \lstinline!operator record! may also contain additional functions, and declarations of components of the record.
It is not legal to extend from an \lstinline!operator record!, except as a short class definition modifying the default attributes for the component elements directly inside the operator record.

If an operator record was derived by a short class definition, the overloaded operators of this operator record are the operators that are defined in its base class, for subtyping see \cref{interface-or-type-relationships}.

The precedence and associativity of the overloaded operators is identical to the one defined in \cref{tab:operator-precedence} in \cref{operator-precedence-and-associativity}.

\begin{nonnormative}
Note, the operator overloading as defined in this section is only a short hand notation for function calls.
\end{nonnormative}

\section{Matching Function}\label{matching-function}

All functions defined inside the \lstinline!operator! class must return one output (based on the restriction above), and may include functions with optional arguments, i.e.\ functions of the form
\begin{lstlisting}[language=modelica]
function f
  input $A_1$ $u_1$;
  $\ldots$
  input $A_{m}$ $u_{m}$ := $a_{m}$;
  $\ldots$
  input $A_{n}$ $u_{n}$;
  output B y;
algorithm
  $\ldots$
end f;
\end{lstlisting}

The vector $P$ indicates whether argument $m$ of \lstinline!f! has a default value (\lstinline!true! for default value, \lstinline!false! otherwise).
A call \lstinline!f($a_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$ = $w_{1}$, $\ldots$, $b_{p}$ = $w_{p}$)! with distinct names $b_{j}$ is a valid match for the function \lstinline!f!, provided (treating \lstinline!Integer! and \lstinline!Real! as the same type)
\begin{itemize}
\item
  $A_{i}$ = typeOf($a_{i}$) for $1 \leq i \leq k$,
\item
  the names $b_{j}$ = $u_{Q_{j}}$, $Q_{j} > k$, $A_{Q_{j}}$ = typeOf($w_{j}$) for $1 \leq j \leq p$, and
\item
  if the union of $\{i: 1 \leq i \leq k \}$, $\{Q_{j}: 1 \leq j \leq p\}$, and $\{m: P_{m} \text{ is \lstinline!true! and } 1 \leq m \leq n \}$ is the set $\{i: 1 \leq i \leq n\}$.
\end{itemize}

\begin{nonnormative}
This corresponds to the normal treatment of function calls with named arguments, requiring that all inputs have some value given by a positional argument, named argument, or a default value (and that positional and named arguments do not overlap).
Note, that this only defines a valid call, but does not explicitly define the set of domains.
\end{nonnormative}

\section{Overloaded Constructors}\label{overloaded-constructors}

Let \lstinline!C! denote an operator record class and consider an expression \lstinline!C($A_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$=$w_{1}$, $\ldots$, $b_{p}$=$w_{p}$)!.

\begin{enumerate}
\item\label{overloaded-constructor-unique}
  If there exists a unique function $f$ in \lstinline!C.'constructor'! such that ($A_1$, $a_{2}$, \ldots{}, $a_{k}$, $b_{1}$=$w_{1}$, \ldots{}, $b_{p}$=$w_{p}$) is a valid match for the function $f$, then
  \lstinline!C($A_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$=$w_{1}$, $\ldots$, $b_{p}$=$w_{p}$)!
  is resolved to
  \lstinline!C.'constructor'.$f$($A_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$=$w_{1}$, $\ldots$, $b_{p}$=$w_{p}$)!.
\item
  If there is no operator \lstinline!C.'constructor'! the automatically generated record constructor is called.
\item
  Otherwise the expression is erroneous.
\end{enumerate}

Restrictions:
\begin{itemize}
\item
  The operator \lstinline!C.'constructor'! shall only contain functions that declare one output component, which shall be of the operator record class \lstinline!C!.
\item
  For an operator recordclass there shall not exist any potential call that lead to multiple matches in \cref{overloaded-constructor-unique} above.
  \begin{nonnormative}
  How to verify this is not specified.
  \end{nonnormative}
\item
  For a pair of operator record classes \lstinline!C! and \lstinline!D! and components \lstinline!c! and \lstinline!d! of these classes both of \lstinline!C.'constructor'(d)! and \lstinline!D.'constructor'(c)! shall not both be legal.
  \begin{nonnormative}
   Hence, one of the two definitions must be removed.
  \end{nonnormative}
\end{itemize}

\begin{nonnormative}
By the last restriction the following problem for binary operators is avoided:

Assume there are two operator record classes \lstinline!C! and \lstinline!D! that both have a constructor from \lstinline!Real!.
If we want to extend \lstinline!c + c! and \lstinline!d + d! to support mixed operations, one variant would be to define \lstinline!c + d! and \lstinline!d + c!; but then \lstinline!c + 2! becomes ambiguous (since it is not clear which instance should be converted to).
Without mixed operations expressions such as \lstinline!c + d! are only ambiguous if both conversion from \lstinline!C! to \lstinline!D! and back from \lstinline!D! to \lstinline!C! are both available, and this possibility is not allowed by the restriction above.
\end{nonnormative}

Additionally there is an operator \lstinline!'0'! defining the zero-value which can also be used to construct an element.
The operator \lstinline!'0'! for an operator record \lstinline!C! can contain only one function, having zero inputs and one output of type \lstinline!C! (the called function is therefore unambiguous).
It should return the identity element of addition, and is used for generating flow-equations for \lstinline!connect!-equations and zero elements for matrix multiplication.

\section{Overloaded String Conversions}\label{overloaded-string-conversions}

Consider an expression \lstinline!String($A_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$=$w_{1}$, $\ldots$, $b_{p}$=$w_{p}$)!, $k \geq 1$ where $A_1$ is an element of class \lstinline!A!.

\begin{enumerate}
\item
  If \lstinline!A! is a predefined type except \lstinline!String! (i.e., \lstinline!Boolean!, \lstinline!Integer!, \lstinline!Real! or an enumeration), or derived from such a type, then the corresponding built-in operation is performed.
\item\label{binary-operator-record-unique-match}
  If \lstinline!A! is an operator record class and there exists a unique function $f$ in \lstinline!A.'String'! such that
  \lstinline!A.'String'.$f$($A_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$=$w_{1}$, $\ldots$, $b_{p}$=$w_{p}$)!
  is a valid match for $f$, then
  \lstinline!String($A_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$=$w_{1}$, $\ldots$, $b_{p}$=$w_{p}$)!
  is evaluated to\\
  \lstinline!A.'String'.$f$($A_1$, $a_{2}$, $\ldots$, $a_{k}$, $b_{1}$=$w_{1}$, $\ldots$, $b_{p}$=$w_{p}$)!.
\item
  Otherwise the expression is erroneous.
\end{enumerate}

Restrictions:
\begin{itemize}
\item
  The operator \lstinline!A.'String'! shall only contain functions that declare one output component, which shall be of the \lstinline!String! type, and the first input argument shall be of the operator record class \lstinline!A!.
\item
  For an operator record class there shall not exist any call that lead to multiple matches in \cref{binary-operator-record-unique-match} above.
  \begin{nonnormative}
  How to verify this is not specified.
  \end{nonnormative}
\end{itemize}

\section{Overloaded Binary Operations}\label{overloaded-binary-operations}

% Can't use \mathit{op} in the \lstinline math due to issue reported here:
%   https://github.com/brucemiller/LaTeXML/issues/1274 (marked as fixed as of commit 80d7940)
%\newcommand{\theop}{\mathit{op}}
\newcommand{\theop}{X}

Let $\theop$ denote a binary operator and consider an expression \lstinline!a $\theop$ b! where \lstinline!a! is an instance or array of instances of class \lstinline!A! and \lstinline!b! is an instance or array of instances of class \lstinline!B!.

\begin{enumerate}
\item\label{overloaded-binary-predefined}
  If \lstinline!A! and \lstinline!B! are predefined types of such, then the corresponding built-in operation is performed.
\item\label{overloaded-binary-unique}
  Otherwise, if there exists \emph{exactly one} function $f$ in the union of \lstinline!A.$\theop$! and \lstinline!B.$\theop$! such that \lstinline!$f$(a, b)! is a valid match for the function $f$, then \lstinline!a $\theop$ b! is evaluated using this function.
  It is an error, if multiple functions match.
  If \lstinline!A! is not an operator record class, \lstinline!A.$\theop$! is seen as the empty set, and similarly for \lstinline!B!.
  \begin{nonnormative}
  Having a union of the operators ensures that if \lstinline!A! and \lstinline!B! are the same, each function only appears once.
  \end{nonnormative}
  Note that if the operations take array arguments, they will in this step only match if the number of dimensions match.
\item
  Otherwise, consider the set given by $f$ in \lstinline!A.$\theop$! and an operator record class \lstinline!C! (different from \lstinline!B!) with a constructor, $g$, such that
  \lstinline!C.'constructor'.$g$(b)!
  is a valid match, and
  \lstinline!f(a, C.'constructor'.$g$(b))!
  is a valid match; and another set given by $f$ in \lstinline!B.$\theop$! and an operator record class \lstinline!D! (different from \lstinline!A!) with a constructor, $h$, such that
  \lstinline!D.'constructor'.$h$(a)!
  is a valid match and
  \lstinline!$f$(D.'constructor'.$h$(a), b)!
  is a valid match.
  If the sum of the sizes of these sets is one this gives the unique match.
  If the sum of the sizes is larger than one it is an error.
  Note that if the operations take array arguments, they will in this step only match if the number of dimensions match.
\begin{nonnormative}
  Informally, this means:
  If there is no direct match of \lstinline!a $\theop$ b!, then it is tried to find a direct match by automatic type casts of \lstinline!a! or \lstinline!b!, by converting either \lstinline!a! or \lstinline!b! to the needed type using an appropriate constructor function from one of the operator record classes used as arguments of the overloaded \lstinline!op! functions.
  Example using the \lstinline!Complex!-definition below:
\begin{lstlisting}[language=modelica]
Real a;
Complex b;
Complex c = a * b; // interpreted as:
// Complex.'*'.multiply(Complex.'constructor'.fromReal(a), b);
\end{lstlisting}
\end{nonnormative}
\item\label{overloaded-binary-arrays}
  Otherwise, if \lstinline!a! or \lstinline!b! is an array expression, then the expression is conceptually evaluated according to the rules of \cref{scalar-vector-matrix-and-array-operator-functions} with the following exceptions concerning \cref{matrix-and-vector-multiplication-of-numeric-arrays}:
  \begin{enumerate}
  \def\labelenumii{\alph{enumii}.}
  \item
    \lstinline!$\mathit{vector}$ * $\mathit{vector}$! is not automatically defined based on the scalar multiplication.
    \begin{nonnormative}
    The scalar product of \cref{tab:product} does not generalize to the expected linear and conjugate linear scalar product of complex numbers.
    It is possible to define a specific product function taking two array arguments handling this case.
    \end{nonnormative}
  \item
    \lstinline!$\mathit{vector}$ * $\mathit{matrix}$! is not automatically defined based on the scalar multiplication.
    \begin{nonnormative}
    The corresponding definition of \cref{tab:product} does not generalize to complex numbers in the expected way.
    It is possible to define a specific product function taking two array arguments handling this case.
    \end{nonnormative}
  \item
    If the inner dimension for \lstinline!$\mathit{matrix}$ * $\mathit{vector}$! or \lstinline!$\mathit{matrix}$ * $\mathit{matrix}$! is zero, this uses the overloaded \lstinline!'0'! operator of the result array element type.
    If the operator \lstinline!'0'! is not defined for that class it is an error if the inner dimension is zero.
  \end{enumerate}

\begin{nonnormative}
For array multiplication it is assumed that the scalar elements form a non-commutative ring that does not necessarily have a multiplicative identity.
\end{nonnormative}

\item\label{overloaded-binary-error}
  Otherwise the expression is erroneous.
\end{enumerate}

For an element-wise operator, \lstinline!a .op b!, \cref{overloaded-binary-predefined,overloaded-binary-arrays,overloaded-binary-error} are used; e.g.\ the operator \lstinline!.+! will always be defined in terms of \lstinline!'+'!.

Restrictions:
\begin{itemize}
\item
  A function is allowed for a binary operator if and only if it has at least two inputs; at least one of which is of the operator record class, and the first two inputs shall not have default values, and all inputs after the first two must have default values.
\item
  For an operator record class there shall not exist any (potential) call that lead to multiple matches in \cref{overloaded-binary-unique} above.
\end{itemize}

\section{Overloaded Unary Operations}\label{overloaded-unary-operations}

Let $\theop$ denote a unary operator and consider an expression \lstinline!$\theop$ a! where \lstinline!a! is an instance or array of instances of class \lstinline!A!.
Then \lstinline!$\theop$ a! is evaluated in the following way.

\begin{enumerate}
\item
  If \lstinline!A! is a predefined type, then the corresponding built-in operation is performed.
\item\label{unary-operator-record-unique-match}
  If \lstinline!A! is an operator record class and there exists a unique function $f$ in \lstinline!A.$\theop$! such that \lstinline!A.$\theop$.$f$(a)! is a valid match, then \lstinline!$\theop$ a! is evaluated to \lstinline!A.$\theop$.$f$(a)!.
  It is an error, if there are multiple valid matches.
  Note that if the operations take array arguments, they will in this step only match if the number of dimensions match.
\item\label{overloaded-unary-array}
  Otherwise, if \lstinline!a! is an array expression, then the expression is conceptually evaluated according to the rules of \cref{scalar-vector-matrix-and-array-operator-functions}.
\item
  Otherwise the expression is erroneous.
\end{enumerate}

Restrictions:
\begin{itemize}
\item
  A function is allowed for a unary operator if and only if it has least one input; and the first input is of the record type (or suitable arrays of such) and does not have a default value, and all inputs after the first one must have default values.
\item
  For an operator record class there shall not exist any (potential) call that lead to multiple matches in \cref{unary-operator-record-unique-match} above.
\item
  A binary and/or unary operator-class may only contain functions that are allowed for this binary and/or unary operator-class; and in case of \lstinline!'-'! it is the union of these sets, since it may define both a unary (negation) and binary (subtraction) operator.
\end{itemize}

\section{Example of Overloading for Complex Numbers}\label{example-of-overloading-for-complex-numbers}

\begin{example}
The rules in the previous subsections are demonstrated at hand of a record class to work conveniently with complex numbers:
\begin{lstlisting}[language=modelica,escapechar=!]
operator record Complex "Record defining a Complex number"
  Real re "Real part of complex number";
  Real im "Imaginary part of complex number";
  encapsulated operator 'constructor'
    import Complex;
    function fromReal
      input Real re;
      input Real im := 0;
      output Complex result(re = re, im = im);
    algorithm
      annotation(Inline = true);
    end fromReal;
  end 'constructor';

  encapsulated operator function '+' // short hand notation, see !\cref{specialized-classes}!
    import Complex;
    input Complex c1;
    input Complex c2;
    output Complex result "= c1 + c2";
  algorithm
    result := Complex(c1.re + c2.re, c1.im + c2.im);
    annotation(Inline = true);
  end '+';

  encapsulated operator '-'
    import Complex;
    function negate
      input Complex c;
      output Complex result "= - c";
    algorithm
      result := Complex(-c.re, -c.im);
      annotation(Inline = true);
    end negate;

    function subtract
      input Complex c1;
      input Complex c2;
      output Complex result "= c1 - c2";
    algorithm
      result := Complex(c1.re - c2.re, c1.im - c2.im);
      annotation(Inline = true);
    end subtract;
  end '-';

  encapsulated operator function '*'
    import Complex;
    input Complex c1;
    input Complex c2;
    output Complex result "= c1 * c2";
  algorithm
    result :=
      Complex(c1.re * c2.re - c1.im * c2.im, c1.re * c2.im + c1.im * c2.re);
    annotation(Inline = true);
  end '*';

  encapsulated operator function '/'
    import Complex; input Complex c1;
    input Complex c2;
    output Complex result "= c1 / c2";
  algorithm
    result :=
      Complex((c1.re*c2.re + c1.im*c2.im) / (c2.re^2 + c2.im^2),
              (-c1.re*c2.im + c1.im*c2.re) / (c2.re^2 + c2.im^2));
    annotation(Inline = true);
  end '/';

  encapsulated operator function '=='
    import Complex;
    input Complex c1;
    input Complex c2;
    output Boolean result "= c1 == c2";
  algorithm
    result := c1.re == c2.re and c1.im == c2.im;
    annotation(Inline = true);
 end '==';

  encapsulated operator function 'String'
    import Complex;
    input Complex c;
    input String name := "j"
      "Name of variable representing sqrt(-1) in the string";
    input Integer significantDigits = 6
      "Number of significant digits to be shown";
    output String s;
  algorithm
    s := String(c.re, significantDigits = significantDigits);
    if c.im <> 0 then
      s := if c.im > 0 then s + " + " else s + " - ";
      s := s + String(abs(c.im), significantDigits = significantDigits) + name;
    end if;
  end 'String';

  encapsulated function j
    import Complex;
    output Complex c;
  algorithm
    c := Complex(0, 1);
    annotation(Inline = true);
  end j;

  encapsulated operator function '0'
    import Complex;
    output Complex c;
  algorithm
    c := Complex(0, 0);
    annotation(Inline = true);
  end '0';
end Complex;

function eigenValues
  input Real A [:,:];
  output Complex ev[size(A, 1)];
  protected
  Integer nx = size(A, 1);
  Real eval[nx, 2];
  Integer i;
algorithm
  eval := Modelica.Math.Matrices.eigenValues(A);
  for i in 1 : nx loop
    ev[i] := Complex(eval[i, 1], eval[i, 2]);
  end for;
end eigenValues;

// Usage of Complex number above:
  Complex j = Complex.j();
  Complex c1 = 2 + 3 * j;
  Complex c2 = 3 + 4 * j;
  Complex c3 = c1 + c2;
  Complex c4[:] = eigenValues([1, 2; -3, 4]);
algorithm
  Modelica.Utilities.Streams.print("c4 = " + String(c4));
  // results in output:
  // c4 = {2.5 + 1.93649j, 2.5 - 1.93649j}
\end{lstlisting}

How overloaded operators can be symbolically processed.
Example:
\begin{lstlisting}[language=modelica]
Real a;
Complex b;
Complex c = a + b;
\end{lstlisting}
Due to inlining of functions, the equation for \lstinline!c! is transformed to:
\begin{lstlisting}[language=modelica]
c = Complex.'+'.add(Complex.'constructor'.fromReal(a), b);
  = Complex.'+'.add(Complex(re = a, im = 0), b)
  = Complex(re = a + b.re, im = b.im);
\end{lstlisting}
or
\begin{lstlisting}[language=modelica]
c.re = a + b.re;
c.im = b.im;
\end{lstlisting}
These equations can be symbolically processed as other equations.

Complex can be used in a connector:
\begin{lstlisting}[language=modelica]
  operator record ComplexVoltage = Complex(re(unit = "V"), im(unit = "V"));
  operator record ComplexCurrent = Complex(re(unit = "A"), im(unit = "A"));

  connector ComplexPin
    ComplexVoltage v;
    flow ComplexCurrent i;
  end ComplexPin;

  ComplexPin p1, p2, p3;
equation
  connect(p1, p2);
  connect(p1, p3);
\end{lstlisting}
The two \lstinline!connect!-equations result in the following connection equations:
\begin{lstlisting}[language=modelica]
p1.v = p2.v;
p1.v = p3.v;
p1.i + p2.i + p3.i = Complex.'0'();
// Complex.'+'(p1.i, Complex.'+'(p2.i, p3.i)) = Complex.'0'();
\end{lstlisting}
The restrictions on extends are intended to avoid combining two variants inheriting from the same operator record, but with possibly different operations; thus \lstinline!ComplexVoltage! and \lstinline!ComplexCurrent! still use the operations from \lstinline!Complex!.
The restriction that it is not legal to extend from any of its enclosing scopes implies that:
\begin{lstlisting}[language=modelica]
package A
  extends Icon; // Ok
  operator record B $\ldots$ end B;
end A;

package A2
  extends A($\ldots$); // Not legal
end A2;

package A3 = A($\ldots$); // Not legal
\end{lstlisting}
\end{example}