functions.tex

\chapter{Functions}\label{functions}

This chapter describes the Modelica function construct.

\section{Function Declaration}\label{function-declaration}

A Modelica function is a specialized class (\cref{function-as-a-specialized-class}) using the
keyword \lstinline!function!. The body of a Modelica function is an algorithm
section that contains procedural algorithmic code to be executed when
the function is called, or alternatively an external function specifier
(\cref{external-function-interface}). Formal parameters are specified using the \lstinline!input! keyword,
whereas results are denoted using the \lstinline!output! keyword. This makes the
syntax of function definitions quite close to Modelica class
definitions, but using the keyword \lstinline!function! instead of \lstinline!class!.

\begin{nonnormative}
The structure of a typical function declaration is sketched by
the following schematic function example:
\begin{lstlisting}[language=modelica,escapechar=!]
function  !\emph{functionname}!
  input  TypeI1 in1;
  input  TypeI2 in2;
  input  TypeI3 in3 = !\emph{default\_expr1}! "Comment" annotation($\ldots$);
  ...
  output TypeO1 out1;
  output TypeO2 out2 =  !\emph{default\_expr2}!;
  ...
protected
  !\emph{\textless{}local variables\textgreater{}}!
  ...
algorithm
  ...
    !\emph{\textless{}statements\textgreater{}}!
  ...
end !\emph{functionname}!;
\end{lstlisting}
\end{nonnormative}

Optional explicit default values can be associated with any input or output formal parameter through binding equations.  Comment strings
and annotations can be given for any formal parameter declaration, as usual in Modelica declarations.

\begin{nonnormative}
Explicit default values are shown for the third input parameter and the second output parameter in the example above.
\end{nonnormative}

\begin{nonnormative}
All internal parts of a function are optional; i.e., the following is also a legal function:
\begin{lstlisting}[language=modelica,escapechar=!]
function !\emph{functionname}!
end !\emph{functionname}!;
\end{lstlisting}
\end{nonnormative}

\subsection{Ordering of Formal Parameters}\label{ordering-of-formal-parameters}

The relative ordering between input formal parameter declarations is
significant since that determines the matching between actual arguments
and formal parameters at function calls with positional parameter
passing. Likewise, the relative ordering between the declarations of the
outputs is significant since that determines the matching with receiving
variables at function calls of functions with multiple results. However,
the declarations of the inputs and outputs can be intermixed as long as
these internal orderings are preserved.

\begin{nonnormative}
Mixing declarations in this way is not recommended, however, since it makes the code hard to read.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica,escapechar=!]
function !\emph{\textless{}functionname\textgreater{}}!
  output TypeO1 out1; // Intermixed declarations of inputs and outputs
  input TypeI1 in1; // not recommended since code becomes hard to read
  input TypeI2 in2;
  ...
  output TypeO2 out2;
  input TypeI3 in3;
  ...
end !\emph{\textless{}functionname\textgreater{}}!;
\end{lstlisting}
\end{example}

\subsection{Function return-statements}\label{function-return-statements}

The return-statement terminates the current function call, see \cref{function-call}.  It can only be used in an algorithm section of a function.  It has the following form:
\begin{lstlisting}[language=modelica]
return;
\end{lstlisting}

\begin{example}
(Note that this could alternatively use \lstinline!break!:)
\begin{lstlisting}[language=modelica]
function findValue "Returns position of val or 0 if not found"
  input Integer x[:];
  input Integer val;
  output Integer index;
algorithm
  for i in 1:size(x,1) loop
    if x[i] == val then
      index := i;
      return;
    end if;
  end for;
  index := 0;
  return;
end findValue;
\end{lstlisting}
\end{example}

\subsection{Inheritance of Functions}\label{inheritance-of-functions}

It is allowed for a function to inherit and/or modify another function
following the usual rules for inheritance of classes (\cref{inheritance-modification-and-redeclaration}).

\begin{nonnormative}
For example, it is possible to modify and extend a \lstinline!function! class to add default values for input variables.
\end{nonnormative}

\section{Function as a Specialized Class}\label{function-as-a-specialized-class}

The function concept in Modelica is a specialized class (\cref{specialized-classes}).

\begin{nonnormative}
The syntax and semantics of a function have many similarities to those of the \lstinline!block! specialized class. A function has many of the properties
of a general class, e.g.\ being able to inherit other functions, or to redeclare or modify elements of a function declaration.
\end{nonnormative}

Modelica functions have the following restrictions compared to a general
Modelica \lstinline!class!:
\begin{itemize}
\item
  Each input formal parameter of the function must be prefixed by the
  keyword input, and each result formal parameter by the keyword output.
  All public variables are formal parameters.
\item
  Input formal parameters are read-only after being bound to the actual
  arguments or default values, i.e., they shall not be assigned values in
  the body of the function.
\item
  A function shall \emph{not be used in connections}, shall not have
  \emph{equations}, shall not have \emph{initial algorithms}.
\item
  A function can have at most \emph{one algorithm} section or \emph{one
  external function interface} (not both), which, if present, is the
  body of the function.
\item
  A function may only contain components of the restricted classes
  \lstinline!type!, \lstinline!record!, \lstinline!operator record!, and \lstinline!function!;
  and it must not contain e.g.
  \lstinline!model!, \lstinline!block!, \lstinline!operator! or \lstinline!connector!
  components.
\item
  The elements of a function shall not have prefixes \lstinline!inner!, or \lstinline!outer!.
\item
  A function may have zero or one external function interface, which, if
  present, is the external definition of the function.
\item
  For a function to be called in a simulation model, the function shall
  not be partial, and the output variables must be assigned inside the
  function either in binding equations or in an algorithm section,
  or have an external function interface as its body, or be defined as a
  function partial derivative. The output variables of a function should
  be computed.
  \begin{nonnormative}
  It is a quality of implementation how much analysis a tool performs in order to determine if the output variables are computed.
  \end{nonnormative}
  A function \emph{cannot contain} calls to the Modelica \emph{built-in operators} \lstinline!der!, \lstinline!initial!, \lstinline!terminal!, \lstinline!sample!, \lstinline!pre!, \lstinline!edge!, \lstinline!change!, \lstinline!reinit!, \lstinline!delay!, \lstinline!cardinality!, \lstinline!inStream!, \lstinline!actualStream!, to the operators of the built-in package \lstinline!Connections!, to the operators defined in \cref{synchronous-language-elements} and \cref{state-machines}, and is not allowed to contain when-statements.
\item
  The dimension \emph{sizes} not declared with (:) of each array result
  or array local variable (i.e., a non-input components) of a
  function must be either given by the input formal parameters, or given
  by constant or parameter expressions, or by expressions containing
  combinations of those (\cref{initialization-and-binding-equations-of-components-in-functions}).
\item
  For initialization of local variables of a function see \cref{initialization-and-binding-equations-of-components-in-functions}).
\item
  Components of a function will inside the function behave as though
  they had discrete-time variability.
\end{itemize}

Modelica functions have the following enhancements compared to a general
Modelica \lstinline!class!:
\begin{itemize}
\item
  Functions can be called, \cref{function-call}.

  \begin{itemize}
  \item
    The calls can use a mix of positional and named arguments, see
    \cref{positional-or-named-input-arguments-of-functions}.
  \item
    Instances of functions have a special meaning, see \cref{functional-input-arguments-to-functions}.
  \item
    The lookup of the \lstinline!function! class to be called is extended, see \cref{composite-name-lookup}.
  \end{itemize}
\item
  A function can be \emph{recursive}.
\item
  A formal parameter or local variable may be initialized through a
  \emph{binding} (=) of a default value in its declaration,
  see \cref{initialization-and-binding-equations-of-components-in-functions}.
  Using assignment (:=) is deprecated. If a non-input component in the
  function uses a record class that contain one or more binding
  equations they are viewed as initialization of those component of the
  record component.
\item
  A function is dynamically instantiated when it is called rather than
  being statically instantiated by an instance declaration, which is the
  case for other kinds of classes.
\item
  A function may have an external function interface specifier as its
  body.
\item
  A function may have a \lstinline!return! statement in its algorithm section body.
\item
  A function allows dimension sizes declared with (:) to be resized for
  non-input array variables, see \cref{flexible-array-sizes-and-resizing-of-arrays-in-functions}.
\item
  A function may be defined in a short function definition to be a
  function partial derivative.
\end{itemize}

\section{Pure Modelica Functions}\label{pure-modelica-functions}

Modelica functions are normally \emph{pure} which makes it easy for
humans to reason about the code since they behave as mathematical
functions, and possible for compilers to optimize.

\begin{itemize}
\item
  \emph{Pure} Modelica functions always give the same output values or
  errors for the same input values and only the output values influence
  the simulation result, i.e.\ is seen as equivalent to a mathematical
  map from input values to output values. Some input values may map to
  errors. Pure functions are thus allowed to fail by calling \lstinline!assert!, or
  \lstinline[language=C]!ModelicaError! in C code, or dividing by zero. Such errors will only be
  reported when and if the function is called.  \emph{Pure} Modelica
  functions are not assumed to be thread-safe.
\item
  A Modelica function which does not have the \emph{pure} function
  properties is \emph{impure}.
\end{itemize}

The declaration of functions follow these rules:
\begin{itemize}
\item
  Functions defined in Modelica (non-external) are \emph{normally} assumed to be pure (the exception is the deprecated case below), if they are impure they shall be marked with the \lstinline!impure! keyword.  They can be explicitly marked as \lstinline!pure!.
  \begin{nonnormative}
  However, since functions as default are pure it is not recommended to explicitly declare them as \lstinline!pure!.
  \end{nonnormative}
\item
  External functions must be explicitly declared with \lstinline!pure! or \lstinline!impure!.
\item
  A deprecated semantics is that external functions (and functions defined in Modelica directly or indirectly calling them) without \lstinline!pure! or \lstinline!impure! keyword are assumed to be
  impure, but without any restriction on calling them.  Except for the function \lstinline!Modelica.Utilities.Streams.print!, diagnostics must be given if called in a simulation model.
\end{itemize}

Calls of pure functions used inside expression may be skipped if the
resulting expression will not depend on the possible returned value;
ignoring the possibility of the function generating an error.

A call to a function with no declared outputs is assumed to have desired
side-effects or assertion checks.

\begin{nonnormative}
A tool shall thus not remove such function calls, with exception of non-triggered assert calls.  A pure function, used in an expression or used with
a non-empty left hand side, need not be called if the output from the function call do not mathematically influence the simulation result, even if
errors would be generated if it were called.
\end{nonnormative}

\begin{nonnormative}
Comment 1: This property enables writing declarative
specifications using Modelica. It also makes it possible for Modelica
compilers to freely perform algebraic manipulation of expressions
containing function calls while still preserving their semantics. For
example, a tool may use common subexpression elimination to call a pure
function just once, if it is called several times with identical input
arguments. However, since functions may fail we can e.g.\ only move a
common function call from inside a loop to outside the loop if the loop
is run at least once.
\end{nonnormative}

\begin{nonnormative}
Comment 2: The Modelica translator is responsible for
maintaining this property for pure non-external functions. Regarding
external functions, the external function implementor is responsible.
Note that external functions can have side-effects as long as they do
not influence the internal Modelica simulation state, e.g.\ caching
variables for performance or printing trace output to a log file.
\end{nonnormative}

With the prefix keyword \lstinline!impure! it is stated that a Modelica
function is \emph{impure} and it is only allowed to call such a function
from within:
\begin{itemize}
\item
  Another function marked with the prefix \lstinline!impure!.
\item
  A when-equation.
\item
  A when-statement.
\item
  \lstinline!pure(impureFunctionCall($\ldots$))! -- which allows calling impure functions in any pure context.
\item
  Initial equations and initial algorithms.
\item
  Binding equations for components declared as parameter -- which is seen as syntactic sugar for having a parameter with \lstinline!fixed=false! and the binding as an initial equation.
  \begin{nonnormative}
  Thus, evaluation of the same function call at a later time during simulation is not guaranteed to result in the same value as when the parameter
  was initialized, seemingly breaking the declaration equation.
  \end{nonnormative}
\item
  Binding equations for external objects.
\end{itemize}

For initial equations, initial algorithms, and bindings it is an error
if the function calls are part of systems of equations and thus have to
be called multiple times.

\begin{nonnormative}
A tool is not allowed to perform any optimizations on function
calls to an impure function, e.g., reordering calls from different
statements in an algorithm or common subexpression elimination is not
allowed.
\end{nonnormative}

It is possible to mark a function formal parameter as \lstinline!impure!. Only if
the function formal parameter is marked \lstinline!impure!, it is allowed to pass an
\lstinline!impure! function to it. A function having a formal function parameter
marked \lstinline!impure! must be marked \lstinline!pure! or \lstinline!impure!.

\begin{nonnormative}
Comment: The semantics are undefined if the function call of an
impure function is part of an algebraic loop.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
function evaluateLinear // pure function
  input Real a0;
  input Real a1;
  input Real x;
  output Real y;
algorithm
  y := a0 + a1*x;
end evaluateLinear;

impure function receiveRealSignal // impure function
  input HardwareDriverID id;
  output Real y;
  external "C" y = receiveSignal(id);
end receiveRealSignal;
\end{lstlisting}
Examples of allowed optimizations of pure functions:
\begin{lstlisting}[language=modelica]
model M // Assume sin, cos, asin are pure functions with normal derivatives.
  input Real x[2];
  input Real w;
  Real y[2] = [cos(w), sin(w); -sin(w), cos(w)] * x;
  Real z[2] = der(y);
  Real a = 0 * asin(w);
end M;
\end{lstlisting}
A tool only needs to generate one call of the pure function \lstinline!cos(w)! in the model \lstinline!M! -- a single call used for both the two elements of the matrix, as well as for the derivative
of that matrix.  A tool may also skip the possible error for \lstinline!asin(w)! and assume that \lstinline!a! is zero.

Examples of restrictions on optimizing pure functions:
\begin{lstlisting}[language=modelica]
  Real x =
    if noEvent(abs(x)) < 1 then
      asin(x) // Cannot move asin(x) out of if-branch.
    else
      0;
algorithm
  assertCheck(p, T); // Must call function
algorithm
  if b then
    y := 2 * someOtherFunction(x);
  end if;
  y := y + asin(x);
  y := y + someOtherFunction(x);
  // Cannot evaluate someOtherFunction(x) before asin(x) - unless b is true
  // The reason is that asin(x) may fail and someOtherFunction may hang,
  // and it might be possible to recover from this error.
\end{lstlisting}
\end{example}

\section{Function Call}\label{function-call}

Function classes and record constructors (\cref{record-constructor-functions}) and enumeration type
conversions (\cref{type-conversion-of-integer-to-enumeration-values}) can be called as described in this section.

\subsection{Positional or Named Input Arguments of Functions}\label{positional-or-named-input-arguments-of-functions}

A function call has optional positional arguments followed by zero, one
or more named arguments, such as

\begin{lstlisting}[language=modelica]
f(3.5, 5.76, arg3=5, arg6=8.3);
\end{lstlisting}

The formal syntax of a function call (simplified by removing reduction
expression, \cref{reduction-expressions}):
\begin{lstlisting}[language=grammar]
primary :
   component-reference function-call-args

function-call-args :
   "(" [ function-arguments ] ")"

function-arguments :
   function-argument [ "," function-arguments]
   | named-arguments

named-arguments: named-argument [ "," named-arguments ]

named-argument: IDENT "=" function-argument

function-argument : function-partial-application | expression
\end{lstlisting}

The interpretation of a function call is as follows: First, a list of unfilled slots is created for all formal input parameters.  If there are $N$ positional arguments, they are placed in the first
$N$ slots, where the order of the parameters is given by the order of the component declarations in the function definition.  Next, for each named argument \lstinline!identifier = expression!, the
\lstinline!identifier! is used to determine the corresponding slot.  The value of the argument is placed in the slot, filling it (it is an error if this slot is already filled).  When all arguments
have been processed, the slots that are still unfilled are filled with the corresponding default value of the function definition.  The default values may depend on other inputs (these dependencies
must be acyclical in the function) -- the values for those other inputs will then be substituted into the default values (this process may be repeated if the default value for that input depend on another input).  The default values for inputs shall not depend on non-input variables in the function.  The list of filled slots is used as the argument list for the call (it is an error if any
unfilled slots still remain).

Special purpose operators with function syntax defined in the
specification shall not be called with named arguments, unless otherwise
noted.

The type of each argument must agree with the type of the corresponding
parameter, except where the standard type coercion, \cref{standard-type-coercion}, can be used to make
the types agree. (See also \cref{scalar-functions-applied-to-array-arguments} on applying scalar functions
to arrays.)

\begin{example}
Assume a function \lstinline!RealToString! is defined as follows to
convert a \lstinline!Real! number to a \lstinline!String!:
\begin{lstlisting}[language=modelica]
function RealToString
  input Real number;
  input Real precision = 6 "number of significantdigits";
  input Real length = 0 "minimum length of field";
  output String string "number as string";
  ...
end RealToString;
\end{lstlisting}
Then the following applications are equivalent:
\begin{lstlisting}[language=modelica]
RealToString(2.0);
RealToString(2.0, 6, 0);
RealToString(2.0, 6);
RealToString(2.0, precision=6);
RealToString(2.0, length=0);
RealToString(2.0, 6, precision=6); // error: slot is used twice
\end{lstlisting}
\end{example}

\subsection{Functional Input Arguments to Functions}\label{functional-input-arguments-to-functions}

A functional input argument to a function is an argument of function
type. The declared type of such an input formal parameter in a function
can be the type-specifier of a partial function that has no replaceable
elements. It cannot be the type-specifier of a record or enumeration
(i.e., record constructor functions and enumeration type
conversions are not allowed in this context). Such an input formal
parameter of function type can also have an optional functional default
value.

\begin{example}
\begin{lstlisting}[language=modelica]
function quadrature "Integrate function y=integrand(x) from x1 to x2"
  input Real x1;
  input Real x2;
  input Integrand integrand; // Integrand is a partial function,
  see below
  // With default: input Integrand integrand =
  Modelica.Math.sin;
  output Real integral;
algorithm
  integral :=(x2-x1)*(integrand(x1) + integrand(x2))/2;
end quadrature;

partial function Integrand
  input Real u;
  output Real y;
end Integrand;
\end{lstlisting}
\end{example}

A functional argument can be provided in one of the following forms to
be passed to a scalar formal parameter of function type in a function
call:
\begin{enumerate}
\def\labelenumi{\alph{enumi})}
\item
  as a function type-specifier (\lstinline!Parabola! example below),
\item
  as a function partial application (\cref{function-partial-application} below),
\item
  as a function that is a component (i.e., a formal parameter of function type of the enclosing function),
\item
  as a function partial application of a function that is a component
  (example in \cref{function-partial-application} below).
\end{enumerate}

In all cases the provided function must be \firstuse{function type compatible}
(\cref{function-compatibility-or-function-subtyping-for-functions}) to the corresponding formal parameter of function type.

\begin{example}
A function as a positional input argument according to case (a):
\begin{lstlisting}[language=modelica]
function Parabola
  extends Integrand;
algorithm
  y := x*x;
end Parabola;
area = quadrature(0, 1, Parabola);
\end{lstlisting}
The \lstinline!quadrature2! example below uses a function \lstinline!integrand! that is a
component as input argument according to case (c):
\begin{lstlisting}[language=modelica]
function quadrature2 "Integrate function y=integrand(x) from x1 to x2"
  input Real x1;
  input Real x2;
  input Integrand integrand; // Integrand is a partial function type
  output Real integral;
algorithm
  integral := quadrature(x1, (x1+x2)/2, integrand)+  quadrature((x1+x2)/2, x2, integrand);
end quadrature2;
\end{lstlisting}
\end{example}

\subsubsection{Function Partial Application}\label{function-partial-application}

A function partial application is similar to a function call with
certain formal parameters bound to expressions, the specific rules are
specified in this section and are not identical to the ones for function
call in \cref{positional-or-named-input-arguments-of-functions}. A function partial application returns a partially
evaluated function that is also a function, with the remaining not bound
formal parameters still present in the same order as in the original
function declaration. A function partial application is specified by the
\lstinline!function! keyword followed by a function call to \lstinline!func_name!
giving named formal parameter associations for the formal parameters to
be bound, e.g.:
\begin{lstlisting}[language=modelica]
function func_name(..., formal_parameter_name = expr, ...)
\end{lstlisting}

\begin{nonnormative}
Note that the keyword \lstinline!function! in a function partial
application differentiates the syntax from a normal function call
where some parameters have been left out, and instead supplied via
default values.
\end{nonnormative}

The function created by the function partial application acts as the
original function but with the bound formal input parameters(s) removed,
i.e., they cannot be supplied arguments at function call. The binding
occurs when the partially evaluated function is created. A partially
evaluated function is \firstuse{function compatible} (see \cref{function-compatibility-or-function-subtyping-for-functions}) to the
same function where all bound arguments are removed.

\begin{nonnormative}
Thus, for checking function type compatibility, bound formal parameters are ignored.
\end{nonnormative}

\begin{example}
Function partial application as argument, positional argument passing, according to case (b) above:
\begin{lstlisting}[language=modelica]
model Test
  parameter Integer N;
  Real area;
algorithm
  area := 0;
  for i in 1:N loop
    area := area + quadrature(0, 1, function  Sine(A=2, w=i*time));
  end for;
end Test;

function Sine "y = Sine(x,A,w)"
  extends Integrand;
  input Real A;
  input Real w;
algorithm
  y:=A*Modelica.Math.sin(w*x);
end Sine;
\end{lstlisting}
Call with function partial application as named input argument:
\begin{lstlisting}[language=modelica]
area := area + quadrature(0, 1, integrand = function Sine(A=2, w=i*time));
\end{lstlisting}
\end{example}

\begin{example}
Function types are matching after removing the bound arguments \lstinline!A! and \lstinline!w! in a function partial
application:
\begin{lstlisting}[language=modelica]
function Sine2 "y = Sine2(A,w,x)"
  input Real A;
  input Real w;
  input Real x; // Note: x is now last in argument list.
  output Real y;
algorithm
  y:=A*Modelica.Math.sin(w*x);
end Sine2;
area = quadrature(0, 1, integrand = function  Sine2(A=2, w=3));
\end{lstlisting}
The partially evaluated \lstinline!Sine2! has only one argument: \lstinline!x! -- and is thus type compatible with \lstinline!Integrand!.
\end{example}

\begin{example}
Function partial application of a function that is a component, according to case (d) above:
\begin{lstlisting}[language=modelica]
partial function SurfaceIntegrand
  input Real x;
  input Real y;
  output Real z;
end SurfaceIntegrand;

function quadratureOnce
  input Real x;
  input Real y1;
  input Real y2;
  input SurfaceIntegrand integrand;
  output Real z;
algorithm
  z := quadrature(y1, y2, function  integrand(y=x));
  // This is according to case (d) and needs to bind the 2nd argument
end quadratureOnce;

function surfaceQuadrature
  input Real x1;
  input Real x2;
  input Real y1;
  input Real y2;
  input SurfaceIntegrand integrand;
  output Real integral;
algorithm
  integral := quadrature(x1, x2,
  function quadratureOnce(y1=y1, y2=y2, integrand=integrand));
  // Case (b) and (c)
end surfaceQuadrature;
\end{lstlisting}
\end{example}

\subsection{Output Formal Parameters of Functions}\label{output-formal-parameters-of-functions}

A function may have more than one output component, corresponding to
multiple return values. The only way to use more than the first return
value of such a function is to make the function call the right hand
side of an equation or assignment. In this case, the left hand side of
the equation or assignment shall contain a list of component references
within parentheses:

\lstinline!(out1, out2, out3) = f($\ldots$);!

The component references are associated with the output components
according to their position in the list. Thus output component i is set
equal to, or assigned to, component reference i in the list, where the
order of the output components is given by the order of the component
declarations in the function definition. The type of each component
reference in the list must agree with the type of the corresponding
output component.

A function application may be used as expression whose value and type is
given by the value and type of the first output component, if at least
one return result is provided.

It is possible to omit left hand side component references and/or
truncate the left hand side list in order to discard outputs from a
function call.

\begin{nonnormative}
Optimizations to avoid computation of unused output results can
be automatically deduced by an optimizing compiler.
\end{nonnormative}

\begin{example}
Function \lstinline!eigen! to compute eigenvalues and optionally
eigenvectors may be called in the following ways:
\begin{lstlisting}[language=modelica]
ev = eigen(A); // calculate eigenvalues
x = isStable(eigen(A)); // used in an expression
(ev, vr) = eigen(A) // calculate eigenvectors
(ev,vr,vl) = eigen(A) // and also left eigenvectors
(ev,,vl) = eigen(A) // no right eigenvectors
\end{lstlisting}
The function may be defined as:
\begin{lstlisting}[language=modelica]
function eigen "calculate eigenvalues and optionally eigenvectors"
  input Real A[:, size(A,1)];
  output Real eigenValues[size(A,1),2];
  output Real rightEigenVectors[size(A,1),size(A,1)];
  output Real leftEigenVectors [size(A,1),size(A,1)];
algorithm
  // The output variables are computed separately (and not, e.g., by one
  // call of a Fortran function) in order that an optimizing compiler can remove
  // unnecessary computations, if one or more output arguments are missing
  //   compute eigenvalues
  //   compute right eigenvectors using the computed eigenvalues
  //   compute left eigenvectors using the computed eigenvalues
end eigen;
\end{lstlisting}
\end{example}

The only permissible use of an expression in the form of a list of
expressions in parentheses, is when it is used as the left hand side of
an equation or assignment where the right hand side is an application of
a function.

\begin{example}
The following are illegal:
\begin{lstlisting}[language=modelica]
(x+1, 3.0, z/y) = f(1.0, 2.0); // Not a list of component references.
(x, y, z) + (u, v, w) // Not LHS of suitable eqn/assignment.
\end{lstlisting}
\end{example}

\subsection{Initialization and Binding Equations of Components in Functions}
\label{initialization-and-binding-equations-of-components-in-functions}
\label{initialization-and-declaration-assignments-of-components-in-functions}

Components in a function can be divided into three groups:
\begin{itemize}
\item
  Public components which are input formal parameters.
\item
  Public components which are output formal parameters.
\item
  Protected components which are local variables, parameters, or
  constants.
\end{itemize}

When a function is called components of a function do not have
start-attributes. However, a binding equation (\lstinline!= expression!) with
an expression may be present for a component.
\begin{nonnormative}
Declaration assignments of the form \lstinline!:= expression! are deprecated, but otherwise identical to binding equations.
\end{nonnormative}

A binding equation for a non-input component initializes the
component to this \lstinline!expression! at the start of every function invocation
(before executing the algorithm section or calling the external
function). These bindings must be executed in an order where a variable
is not used before its binding equations has been executed; it is
an error if no such order exists (i.e.\ the binding must be acyclic).

Binding equations can only be used for components of a function.
If no binding equation is given for a non-input component the
variable is uninitialized (except for record components where modifiers
may also initialize that component). It is an error to use (or return)
an uninitialized variable in a function.  Binding equations for input
formal parameters are interpreted as default arguments, as described in
\cref{positional-or-named-input-arguments-of-functions}.

\begin{nonnormative}
It is recommended to check for use of uninitialized variables statically -- if this is not possible a warning is recommended
combined with a run-time check.
\end{nonnormative}

\begin{nonnormative}
The properties of components in functions described in this
section are also briefly described in \cref{function-as-a-specialized-class}.
\end{nonnormative}

\subsection{Flexible Array Sizes and Resizing of Arrays in Functions}\label{flexible-array-sizes-and-resizing-of-arrays-in-functions}

\begin{nonnormative}
Flexible setting of array dimension sizes of arrays in
functions is also briefly described in \cref{function-as-a-specialized-class}.
\end{nonnormative}

A dimension size not specified with colon(\lstinline!:!) for a non-input array
component of a function must be given by the inputs or be constant.

\begin{example}
\begin{lstlisting}[language=modelica]
function joinThreeVectors
  input Real v1[:],v2[:],v3[:];
  output Real vres[size(v1,1)+size(v2,1)+size(v3,1)];
algorithm
  vres := cat (1,v1,v2,v3);
end joinThreeVectors;
\end{lstlisting}
\end{example}

\begin{itemize}
\item
  A non-input array component declared in a function with a dimension
  size specified by colon(:) and no binding equation, can change
  size according to these special rules:Prior to execution of the
  function algorithm the dimension size is zero.
\item
  The entire array (without any subscripts) may be assigned with a
  corresponding array with arbitrary dimension size (the array variable
  is re-sized).
\end{itemize}

These rules also apply if the array component is an element of a record
component in a function.

\begin{example}
A function to collect the positive elements in a vector:
\begin{lstlisting}[language=modelica]
function collectPositive
  input Real x[:];
  output Real xpos[:];
algorithm
  for i in 1:size(x,1) loop
    if x[i]>0 then
      xpos:=cat(1,xpos,x[i:i]);
    end if;
  end for;
end collectPositive;
\end{lstlisting}
\end{example}

\subsection{Scalar Functions Applied to Array Arguments}\label{scalar-functions-applied-to-array-arguments}

Functions with one scalar return value can be applied to arrays element-wise, e.g.\ if \lstinline!A! is a vector of reals, then \lstinline!sin(A)! is a vector where each element is the result of applying the function \lstinline!sin! to the corresponding element in \lstinline!A!.  Only \lstinline!function! classes that are transitively non-replaceable (\cref{transitively-non-replaceable} and \cref{restrictions-on-base-classes-and-constraining-types-to-be-transitively-non-replaceable}) may be called vectorized.

Consider the expression \lstinline!f(arg1, $\ldots$, argn)!, an application of the function \lstinline!f! to the arguments \lstinline!arg1!, \ldots, \lstinline!argn!.
Potential vectorization of this call is defined as follows.
For each passed argument, the type of the argument is checked against the type of the corresponding formal parameter of the function:
\begin{enumerate}
\item\label{argument-type-check-match}
  If the types match, nothing is done.
\item
  If the types do not match, and a type conversion can be applied, it is
  applied. Continue with step~\ref{argument-type-check-match}.
\item
  If the types do not match, and no type conversion is applicable, the passed argument type is checked to see if it is an $n$-dimensional array of the formal parameter type.  If it is not, the function call is invalid.  If it is, we call this a \emph{foreach argument}.
\item
  For all foreach arguments, the number and sizes of dimensions must
  match. If they do not match, the function call is invalid.
\item
  If no foreach argument exists, the function is applied in the normal
  fashion, and the result has the type specified by the function
  definition.
\item
  The result of the function call expression is an $n$-dimensional array \lstinline!e! with the same dimension sizes as the foreach arguments.
  Each element \lstinline!e[$i$, $\ldots$, $j$]! is the result of applying \lstinline!f! to arguments constructed from the original arguments in the following way:
\begin{itemize}
\item
  If the argument is not a foreach argument, it is used as-is.
\item
  If the argument is a foreach argument, the element at index \lstinline![$i$, $\ldots$, $j$]! is used.
\end{itemize}
\end{enumerate}

If more than one argument is an array, all of them have to be the same
size, and they are traversed in parallel.

\begin{example}
\begin{lstlisting}[language=modelica]
sin({a, b, c}) = {sin(a), sin(b), sin(c)} // argument is a vector
sin([a, b, c]) = [sin(a), sin(b), sin(c)] // argument may be a matrix
atan({a, b, c}, {d, e, f}) = {atan(a, d), atan(b, e), atan(c, f)}
\end{lstlisting}
This works even if the function is declared to take an array as
one of its arguments. If \lstinline!pval! is defined as a function that takes
one argument that is a \lstinline!Real! vector and returns a \lstinline!Real!, then it can
be used with an actual argument which is a two-dimensional array (a
vector of vectors). The result type in this case will be a vector of
\lstinline!Real!.
\begin{lstlisting}[language=modelica]
pval([1,2;3,4]) = [pval([1,2]); pval([3,4])]
sin([1,2;3,4]) = [sin({1,2}); sin({3,4})]
  = [sin(1), sin(2); sin(3), sin(4)]
\end{lstlisting}
\begin{lstlisting}[language=modelica]
function Add
  input Real e1, e2;
  output Real sum1;
algorithm
  sum1 := e1 + e2;
end Add;
\end{lstlisting}
\lstinline!Add(1, [1,2,3])! adds one to each of the elements of the second
argument giving the result \lstinline![2,3,4]!. However, it is illegal to
write \lstinline!1 + [1,2,3]!, because the rules for the built-in
operators are more restrictive.
\end{example}

\subsection{Empty Function Calls}\label{empty-function-calls}

An \emph{empty} function call is a call that does not return any results.

\begin{nonnormative}
An empty call is of limited use in Modelica since a function call without results does not contribute to the simulation,
but it is useful to check assertions and in certain cases for desired side-effects, see \cref{pure-modelica-functions}.
\end{nonnormative}

An empty call can occur either as a kind of ``null equation'' or ``null statement''.

\begin{example}
The empty calls to \lstinline!eigen()! are examples of a ``null equation'' and a ``null statement'':
\begin{lstlisting}[language=modelica]
equation
  Modelica.Math.Matrices.eigen(A); // Empty function call as an equation
algorithm
  Modelica.Math.Matrices.eigen(A); // Empty function call as a statement
\end{lstlisting}
\end{example}

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

There are basically four groups of built-in functions in Modelica:
\begin{itemize}
\item
  Intrinsic mathematical and conversion functions, see \cref{numeric-functions-and-conversion-functions}.
\item
  Derivative and special operators with function syntax,
  see \cref{derivative-and-special-purpose-operators-with-function-syntax}.
\item
  Event-related operators with function syntax, see \cref{event-related-operators-with-function-syntax}.
\item
  Built-in array functions, see \cref{built-in-array-functions}.

  Note that when the specification references a function having the name
  of a built-in function it references the built-in function, not a
  user-defined function having the same name.
\end{itemize}

\section{Record Constructor Functions}\label{record-constructor-functions}

Whenever a record is defined, a record constructor function with the
same name and in the same scope as the record class is implicitly
defined according to the following rules:

The declaration of the record is partially flattened including
inheritance, modifications, redeclarations, and expansion of all names
referring to declarations outside of the scope of the record to their
fully qualified names.

\begin{nonnormative}
The partial flattening is performed in order to remove potentially conflicting import-clauses in the record constructor function due to flattening the inheritance tree.
\end{nonnormative}

All record elements (i.e., components and local class
definitions) of the partially flattened record declaration are used
as declarations in the record constructor function with the following
exceptions:
\begin{itemize}
\item
  Component declarations which do not allow a modification (such
  as \lstinline!final parameter Real!) are declared
  as protected components in the record constructor function.
\item
  Prefixes (\lstinline!constant!, \lstinline!parameter!, \lstinline!final!, \lstinline!discrete!, \ldots) of the remaining
  record components are removed.
\item
  The prefix \lstinline!input! is added to the public components of the record
  constructor function.
\end{itemize}

An instance of the record is declared as output parameter using
a name not appearing in the record, together with a modification. In
the modification, all input parameters are used to set the corresponding
record variables.

A record constructor can only be called if the referenced record class
is found in the global scope, and thus cannot be modified.

\begin{nonnormative}
This allows constructing an instance of a record, with an
optional modification, at all places where a function call is allowed.

Examples:
\begin{lstlisting}[language=modelica]
  record Complex "Complex number"
    Real re "real part";
    Real im "imaginary part";
  end Complex;

  function add
    input Complex u, v;
    output Complex w(re=u.re + v.re, im=u.im+v.re);
  end add;

  Complex c1, c2;
equation
  c2 = add(c1, Complex(sin(time), cos(time));
\end{lstlisting}

In the following example, a convenient data sheet library of
components is built up:
\begin{lstlisting}[language=modelica]
package Motors
  record MotorData "Data sheet of a motor"
    parameter Real inertia;
    parameter Real nominalTorque;
    parameter Real maxTorque;
    parameter Real maxSpeed;
  end MotorData;

  model Motor "Motor model" // using the generic MotorData
    MotorData data;
    ...
  equation
    ...
  end Motor;

  record MotorI123 = MotorData( // data of a specific motor
    inertia = 0.001,
    nominalTorque = 10,
    maxTorque = 20,
    maxSpeed = 3600) "Data sheet of motor I123";
  record MotorI145 = MotorData( // data of another specific motor
    inertia = 0.0015,
    nominalTorque = 15,
    maxTorque = 22,
    maxSpeed = 3600) "Data sheet of motor I145";
end Motors

model Robot
  import Motors.*;
  Motor motor1(data = MotorI123()); // just refer to data sheet
  Motor motor2(data = MotorI123(inertia=0.0012));
  // data can still be modified (if no final declaration in record)
  Motor motor3(data = MotorI145());
  ...
end Robot;
\end{lstlisting}

Example showing most of the situations, which may occur for the
implicit record constructor function creation. With the following record
definitions:
\begin{lstlisting}[language=modelica]
package Demo;
  record Record1;
    parameter Real r0 = 0;
  end Record1;

  record Record2
    import Modelica.Math.*;
    extends Record1;
    final constant Real c1 = 2.0;
    constant Real c2;
    parameter Integer n1 = 5;
    parameter Integer n2;
    parameter Real r1 "comment";
    parameter Real r2 = sin(c1);
    final parameter Real r3 = cos(r2);
    Real r4;
    Real r5 = 5.0;
    Real r6[n1];
    Real r7[n2];
  end Record2;
end Demo;
\end{lstlisting}

The following record constructor functions are implicitly defined
(the name of the output, given in italic below, is not defined; it
should be chosen to not cause any conflict):
\begin{lstlisting}[language=modelica,escapechar=!]
package Demo;
  function Record1
    input Real r0 = 0;
    output Record1 !\emph{result}!(r0 = r0);
  end Record1;

  function Record2
    input Real r0 = 0;
    input Real c2;
    input Integer n1 = 5;
    input Integer n2;
    input Real r1 "comment"; // the comment also copied from record
    input Real r2 = Modelica.Math.sin(c1);
    input Real r4;
    input Real r5 = 5.0;
    input Real r6[n1];
    input Real r7[n2];
    output Record2 !\emph{result}!(r0=r0,c2=c2,n1=n1,n2=n2,r1=r1,r2=r2,r4=r4,r5=r5,r6=r6,r7=r7);
  protected
    final constant Real c1 = 2.0; // referenced from r2
    final parameter Real r3 = Modelica.Math.cos(r2);
  end Record2;
end Demo;
\end{lstlisting}
and can be applied in the following way
\begin{lstlisting}[language=modelica]
Demo.Record2 r1 = Demo.Record2(r0=1, c2=2, n1=2, n2=3, r1=1, r2=2,r4=5, r5=5, r6={1,2}, r7={1,2,3});
Demo.Record2 r2 = Demo.Record2(1,2,2,3,1,2,5,5,{1,2},{1,2,3});
parameter Demo.Record2 r3 = Demo.Record2(c2=2, n2=1, r1=1,r4=4, r6=1:5, r7={1});
\end{lstlisting}

The above example is only used to show the different variants
appearing with prefixes, but it is not very meaningful, because it is
simpler to just use a direct modifier.
\end{nonnormative}

\subsection{Casting to Record}\label{casting-to-record}

A constructor of a record \lstinline!R! can be used to cast an instance m of a
\lstinline!model!, \lstinline!block!, \lstinline!connector! class \lstinline!M! to a value of type \lstinline!R!, provided that for
each component defined in \lstinline!R! (that do not have a default value) there is
also a public component defined in \lstinline!M! with identical name and type. A
nested record component of \lstinline!R! is handled as follows, if the corresponding
component of \lstinline!M! is a \lstinline!model!/\lstinline!block!/\lstinline!connector! a nested record constructor is
called -- otherwise the component is used directly; and the resulting
call/component is used as argument to the record constructor \lstinline!R!. If the
corresponding component of \lstinline!R! in \lstinline!M! is a conditional component, it is an
error. The instance \lstinline!m! is given as single (un-named)
argument to the record constructor of \lstinline!R!. The interpretation is that \lstinline!R(m)!
is replaced by a record constructor of type \lstinline!R! where all public
components of \lstinline!M! that are present in \lstinline!R! are assigned to the corresponding
components of \lstinline!R!. The record cast can be used in vectorized form
according to \cref{scalar-functions-applied-to-array-arguments}.

\begin{nonnormative}
The problem if \lstinline!R! would be a conditional component is that the corresponding binding would be illegal since it is not a
connect-statement.
\end{nonnormative}

\begin{nonnormative}
The record cast operation is uniquely distinguished from a record constructor call, because an argument of the record constructor cannot
be a \lstinline!model!, \lstinline!block! or \lstinline!connector! instance.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
connector Flange
  Real phi;
  flow Real tau;
end Flange;

model Model1
  Real m1;
  Boolean b1;
  Flange flange;
end Model1;

model Model2
  Real r1;
  Real r2;
  Integer i2
  Pin p1, p2;
  Model1 sub1;
  protected
  Integer i1;
  ...
end Model2;

record MyFlange
  Real tau;
end MyFlange;

record MyRecord1
  Boolean b1;
  MyFlange flange;
end MyRecord1;

record MyRecord2
  Real r1;
  Integer i2;
  MyRecord1 sub1;
end MyRecord2;

model Model
  Model2 s1;
  Model2 s2[2];
  MyRecord2 rec1 = MyRecord2(s1);
  MyRecord2 rec2[2] = MyRecord2(s2);
  ...
end Model;
// Model is conceptually mapped to
model ModelExpanded
  Model2 s1;
  Model2 s2[2];
  MyRecord2 rec1 = MyRecord2(r1=s1.r1, i2=s1.i2,
  sub1 = MyRecord1(b1=s1.sub1.b1,
  flange = MyFlange(tau=s1.sub1.flange.tau));
  MyRecord2 rec2[2] = {MyRecord2(r1=s2[1].r1, i2=s2[1].i2,
  sub1 = MyRecord1(b1=s2[1].sub1.b1,
  flange = MyFlange(tau=s1[1].sub1.flange.tau)),
  MyRecord2(r1=s2[2].r1, i2=s2[2].i2,
  sub1 = MyRecord1(b1=s2[2].sub1.b1,
  flange = MyFlange(tau=s2[2].sub1.flange.tau)};
  ...
end ModelExpanded;
\end{lstlisting}
\end{example}

\section{Declaring Derivatives of Functions}\label{declaring-derivatives-of-functions}

Derivatives of functions can be declared explicitly using the \lstinline!derivative!
annotation, see \cref{using-the-derivative-annotation}, whereas a function can be defined as a
partial derivative of another function using the \lstinline!der!-operator in a short
function definition, see \cref{partial-derivatives-of-functions}.

\subsection{Using the Derivative Annotation}\label{using-the-derivative-annotation}

A function declaration can have an annotation \lstinline!derivative! specifying the derivative function or preferably, for a function written in Modelica, use the \lstinline!smoothOrder! annotation to indicate that the tool can construct the derivative function automatically, \cref{annotations-for-code-generation}.  The \lstinline!derivative! annotation can influence simulation time and accuracy and can be applied to both functions written in Modelica and to external functions.  A \lstinline!derivative! annotation can state that it is only valid under certain restrictions on the input arguments.  These restrictions are defined using the following optional attributes: \lstinline!order! (only a restriction if \lstinline!order>1!, the default for \lstinline!order! is 1), \lstinline!noDerivative!, and \lstinline!zeroDerivative!.  The given derivative-function can only be used to compute the derivative of a function call if these restrictions are satisfied.  There may be multiple restrictions on the derivative, in which case they must all be satisfied. The restrictions also imply that some derivatives of some inputs are excluded from the call of the derivative (since they are not necessary).  A function may supply multiple derivative functions subject to different restrictions, the first one that can be used (i.e.\ satisfying the restrictions) will be used for each call.

\begin{nonnormative}
This means that the most restrictive derivatives should be written first.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
function foo0 annotation(derivative=foo1);
end foo0;

function foo1 annotation(derivative(order=2)=foo2);
end foo1;

function foo2 end foo2;
\end{lstlisting}
\end{example}

The inputs to the derivative function of \lstinline!order! 1 are constructed as
follows:
\begin{itemize}
\item
  First are all inputs to the original function, and after all them we
  will in order append one derivative for each input containing reals.
  These common inputs must have the same name, type, and declaration
  order for the function and its derivative.
\item
  The outputs are constructed by starting with an empty list and then in
  order appending one derivative for each output containing reals. The
  outputs must have the same type and declaration order for the function
  and its derivative.
\end{itemize}

If the Modelica function call is a nth derivative (n\textgreater{}=1),
i.e.\ this function call has been derived from an (n-1)th derivative by
differentiation inside the tool, an \lstinline!annotation(order=n+1)=...!,
specifies the (n+1)th derivative, and the (n+1)th derivative call is
constructed as follows:
\begin{itemize}
\item
  The input arguments are appended with the (n+1)th derivative, which
  are constructed in order from the nth \lstinline!order! derivatives.
\item
  The output arguments are similar to the output argument for the nth
  derivative, but each output is one higher in derivative order. The
  outputs must have the same type and declaration order for the function
  and its derivative.
\end{itemize}

\begin{nonnormative}
The restriction that only the result of differentiation can use
higher-order derivatives ensures that the derivatives \lstinline!x!, \lstinline!der_x!,
\ldots{} are in fact derivatives of each other. Without that restriction
we would have both \lstinline!der(x)! and \lstinline!x_der! as inputs (or perform advanced
tests to verify that they are the same).
\end{nonnormative}

\begin{example}
Given the declarations
\begin{lstlisting}[language=modelica]
function foo0
  ...
  input Real x;
  input Boolean linear;
  input ...;
  output Real y;
  ...
  annotation(derivative=foo1);
end foo0;

function foo1
  ...
  input Real x;
  input Boolean linear;
  input ...;
  input Real der_x;
  ...
  output Real der_y;
  ...
  annotation(derivative(order=2)=foo2);
end foo1;

function foo2
  ...
  input Real x;
  input Boolean linear;
  input ...;
  input Real der_x;
  ...;
  input Real der_2_x;
  ...
  output Real der_2_y;
  ...
\end{lstlisting}
the equation
\begin{align*}
(\ldots,\, y(t),\, \ldots) &= \text{\lstinline!foo0!}(\ldots,\, x(t),\, b,\ldots)
\intertext{implies that:}
(\ldots,\, \pdfrac{y(t)}{t},\, \ldots) &=
\text{\lstinline!foo1!}(\ldots,\, x(t),\, b,\, \ldots,\,  \ldots,\, \pdfrac{x(t)}{t},\, \ldots)
\\
(\ldots,\, \pdfrac[2]{y(t)}{t},\, \ldots) &=
\text{\lstinline!foo2!}(\ldots,\, x(t),\, b,\, \ldots,\, \pdfrac{x(t)}{t},\, \ldots,\, \ldots,\, \pdfrac[2]{x(t)}{t},\, \ldots)
\end{align*}
\end{example}

An input or output to the function may be any simple type (\lstinline!Real!, \lstinline!Boolean!, \lstinline!Integer!, \lstinline!String! and enumeration types) or a record.  For a record containing Reals the corresponding derivative uses a derivative record, that only contain the real-predefined types and sub-records containing reals (handled recursively) from the original record.  When using \lstinline!smoothOrder!, then the derivative record is automatically constructed.  The function must have at least one input containing reals.  The output list of the derivative function shall not be empty.

\begin{example}
Here is one example use case with records mixing \lstinline!Real! and
non-\lstinline!Real! as inputs and outputs:
\begin{lstlisting}[language=modelica]
record ThermodynamicState "Thermodynamic state"
  SpecificEnthalpy h "Specific enthalpy";
  AbsolutePressure p "Pressure";
  Integer phase(min=1, max=2, start=1);
end ThermodynamicState;

record ThermoDynamicState_der "Derivative"
  SpecificEnthalpyDerivative h "Specific enthalphy derivative";
  PressureDerivative p "Pressure derivative";
  // Integer input is skipped
end ThermodynamicState_der;

function density
  input ThermodynamicState state "Thermodynamic state";
  output Density d "Density";
algorithm
  ...
  annotation(derivative=density_der);
end density;

function density_der
  input ThermodynamicState state "Thermodynamic state";
  input ThermodynamicState_der state_der;
  output DensityDerivative d "Density derivative";
algorithm
  ...
end density_der;

function setState_ph
  input Pressure p;
  input SpecificEnthalpy h;
  input Integer phase = 0;
  output ThermodynamicState state;
algorithm
  ...
  annotation(derivative = setState_ph_der);
end setState_ph;

function setState_ph_der
  input Pressure p;
  input SpecificEnthalpy h;
  input Integer phase;
  input PressureDerivative p_der;
  input SpecificEnthalpyDerivative h_der;
  output ThermodynamicState_der state_der;
algorithm
  ...
end setState_ph_der;

ThermodynamicState state1 = setState_ph(p=..., h=..., phase=...);
Density rho1=density(state1);
DensityDerivative d_rho1=der (rho1);
Density rho2=density(setState_ph(p=..., h=..., phase=...));
DensityDerivative d_rho2=der (rho2);
\end{lstlisting}
\end{example}

\begin{itemize}
\item
  \lstinline[language=grammar]!zeroDerivative = inputVar1 { , zeroDerivative = inputVar2 }!
\end{itemize}

The derivative function is only valid if \lstinline!inputVar1! (and \lstinline!inputVar2! etc.)
are independent of the variables the function call is differentiated
with respect to (i.e.\ that the derivative of \lstinline!inputVar1! is zero). The
derivative of \lstinline!inputVar1! (and \lstinline!inputVar2! etc.) are excluded from the
argument list of the derivative-function. If the derivative-function
also specifies a derivative the common variables should have consistent
\lstinline!zeroDerivative!.

\begin{nonnormative}
Assume that function \lstinline!f! takes a matrix and a scalar.
Since the matrix argument is usually a parameter expression it is then
useful to define the function as follows (the additional derivative =
\lstinline!f_general_der! is optional and can be used when the derivative of
the matrix or offset is non-zero). Note that \lstinline!f_der! must have
\lstinline!zeroDerivative! for both \lstinline!y! and \lstinline!offset!, but \lstinline!f_general_der! shall not have
\lstinline!zeroDerivative! for either of them (it may \lstinline!zeroDerivative! for \lstinline!x_der!,
\lstinline!y_der!, or \lstinline!offset_der!).

\begin{lstlisting}[language=modelica]
function f "Simple table lookup"
  input Real x;
  input Real y[:, 2];
  input Real offset;
  output Real z;
algorithm
  ...
  annotation(derivative(zeroDerivative=y, zeroDerivative=offset)= f_der,
             derivative=f_general_der);
end f;

function f_der "Derivative of simple table lookup"
  input Real x;
  input Real y[:, 2];
  input Real offset;
  input Real x_der;
  output Real z_der;
algorithm
  ...
  annotation(derivative(zeroDerivative=y, zeroDerivative=offset, order=2) = f_der2);
end f_der;

function f_der2 "Second derivative of simple table lookup"
  input Real x;
  input Real y[:, 2];
  input Real offset;
  input Real x_der;
  input Real x_der2;
  output Real z_der2;
algorithm
  ...
end f_der2;

function f_general_der "Derivative of table lookup taking
into account varying tables"
  input Real x;
  input Real y[:, 2];
  input Real offset;
  input Real x_der;
  input Real y_der[:, 2];
  input Real offset_der;
  output Real z_der;
algorithm
  ...
  //annotation(derivative(order=2) = f_general_der2);
end f_general_der;
\end{lstlisting}
\end{nonnormative}

\begin{itemize}
\item
  \lstinline!noDerivative = inputVar1!
\end{itemize}

The derivative of inputVar1 is excluded from the argument list of the
derivative-function. This relies on assumptions on the arguments to the
function; and the function should document these assumptions (it is not
always straightforward to verify them). In many cases even the
undifferentiated function will only behave correctly under these
assumptions.

The inputs excluded using \lstinline!zeroDerivative! or \lstinline!noDerivative! may be of any type (including types not containing reals).

\begin{nonnormative}
Assume that function \lstinline!fg! is defined as a composition \lstinline!f(x, g(x))!.
When differentiating \lstinline!f! it is useful to give the derivative under the
assumption that the second argument is defined in this way:
\begin{lstlisting}[language=modelica]
function fg
  input Real x;
  output Real z;
algorithm
  z := f(x, g(x));
end fg;

function f
  input Real x;
  input Real y;
  output Real z;
algorithm
  ...
  annotation(derivative(noDerivative = y) = f_der);
end f;

function f_der
  input Real x;
  input Real y;
  input Real x_der;
  output Real z_der;
algorithm
  ...
end f_der;
\end{lstlisting}
This is useful if \lstinline!g! represents the major computational
effort of \lstinline!fg!.
\end{nonnormative}

\subsection{Partial Derivatives of Functions}\label{partial-derivatives-of-functions}

A class defined as:
\begin{lstlisting}[language=grammar]
IDENT "=" der "(" name "," IDENT { "," IDENT } ")" comment
\end{lstlisting}
is the partial derivative of a function, and may only be used as declarations of functions.

The semantics is that a function (and only a function) can be specified in this form, defining that it is the partial derivative of the function to the right of the equal sign (looked up in the same way as a short class definition, and the looked up name must be a function), and partially differentiated with respect to each \lstinline!IDENT! in order (starting from the first one).  The \lstinline!IDENT! must be \lstinline!Real! inputs to the function.

The comment allows a user to comment the function (in the info-layer and as one-line description, and as icon).

\begin{example}
The specific enthalpy can be computed from a Gibbs-function as follows:
\begin{lstlisting}[language=modelica]
function Gibbs
  input Real p, T;
  output Real g;
algorithm
  ...
end Gibbs;
function Gibbs_T = der(Gibbs, T);
function specificEnthalpy
  input Real p, T;
  output Real h;
algorithm
  h := Gibbs(p, T) - T * Gibbs_T(p, T);
end specificEnthalpy;
\end{lstlisting}
\end{example}

\section{Declaring Inverses of Functions}\label{declaring-inverses-of-functions}

Every function with one output formal parameter may have one or more
\lstinline!inverse! annotations to define inverses of this function:
\begin{lstlisting}[language=modelica]
function $f_1$
  input $A_1$ $u_1$;
  ...
  input $T_1$ $u_k$;
  ...
  input $A_m$ $u_m$ = $a_m$;
  ...
  input $A_n$ $u_n$;
  output $T_2$ y;
algorithm
  ...
  annotation(inverse($u_k$ =$f_2$(..., y, ....), $u_i$ =$f_3$(..., y, ...), ...));
end $f_1$;
\end{lstlisting}

The meaning is that function $f_2$ is one inverse to function $f_1$ where the previous output \lstinline!y! is now an input and the previous input $u_k$ is now an output.  More than one inverse can be defined within the same \lstinline!inverse! annotation.  Several inverses are separated by commas.

\begin{nonnormative}
The inverse requires that for all valid values of the input arguments of \lstinline!$f_2$(..., y, ...)! and $u_k$ being calculated as \lstinline!$u_k$ := $f_2$(..., y, ...)! implies
the equality \lstinline!y = $f_1$(..., $u_k$, ...,)! up to a certain precision.
\end{nonnormative}

Function $f_1$ can have any number and types of formal
Function $f_1$ can have any number and types of formal
parameters with and without default value. The restriction is that the
\emph{number of unknown variables} (see \cref{balanced-models}) in the output formal
parameter of both $f_1$ and $f_2$ must be
the same and that $f_2$ should have a union of output and formal
parameters that is the same or a sub-set of that union for $f_1$, but the order of the formal
parameters may be permuted.


\begin{example}
Same union of variables:
\begin{lstlisting}[language=modelica]
function h_pTX
  input Real p "pressure";
  input Real T "temperature";
  input Real X[:] "mass fractions";
  output Real h "specific enthalpy";
algorithm
  ...
  annotation(inverse(T = T_phX(p,h,X)));
end h_pTX;

function T_phX
  input Real p "pressure";
  input Real h "specific enthalpy";
  input Real X[:] "mass fractions";
  output Real T "temperature";
algorithm
  ...
end T_phX;
\end{lstlisting}
\end{example}

The sub-set case is useful if $f_1$ computes the inverse of $f_2$ within a region, or up to a certain tolerance.
Then, $f_1$ may specify $f_2$ as inverse with fewer arguments, skipping the arguments for tolerance and/or the region.

\begin{example}

\begin{lstlisting}[language=modelica]
function inv_sine
  input Real x;
  input Real angleOrig;
  output Real angle;
  // Finds sine(angle) = x with angle closest to angleOrig.
algorithm
  ...
  annotation(inverse(x = sine(angle)));
end inv_sine;

function sine
  input Real angle;
  output Real x;
algorithm
  x := sin(angle);
  // Note: No inverse.
end sine;
\end{lstlisting}
\end{example}
\section{External Function Interface}\label{external-function-interface}

Here, the word function is used to refer to an arbitrary external
routine, whether or not the routine has a return value or returns its
result via output parameters (or both). The Modelica external function
call interface provides the following:
\begin{itemize}
\item
  Support for external functions written in C (specifically C89) and
  FORTRAN~77. Other languages, e.g.\ C++ and Fortran 90, may be supported
  in the future, and provided the function is link-compatible with C89
  or FORTRAN~77 it can be written in any language.
\item
  Mapping of argument types from Modelica to the target language and
  back.
\item
  Natural type conversion rules in the sense that there is a mapping
  from Modelica to standard libraries of the target language.
\item
  Handling arbitrary parameter order for the external function.
\item
  Passing arrays to and from external functions where the dimension
  sizes are passed as explicit integer parameters.
\item
  Handling of external function parameters which are used both for input
  and output, by passing an output that has a binding equation to
  the external function.
  \begin{nonnormative}
  Binding equations are executed prior to calling the external function.
  \end{nonnormative}
\end{itemize}

The format of an external function declaration is as follows.
\begin{lstlisting}[language=grammar]
function IDENT description-string
  { component-clause ";" }
  [ protected { component-clause ";" } ]
  external [ language-specification ] [
  external-function-call ] [annotation ] ";"
  [ annotation ";" ]
end IDENT;
\end{lstlisting}

Components in the public part of an external function declaration shall be declared either as \lstinline!input! or \lstinline!output!.

\begin{nonnormative}
This is just as for any other function.  The components in the protected part allow local variables for temporary storage to be declared.
\end{nonnormative}

The \lstinline[language=grammar]!language-specification! must currently be one of \lstinline!"builtin"!, \lstinline!"C"!, \lstinline!"C..."! (for one of the specific C standards like C89, C99, and C11 -- specifying
that it relies on the C standard library of that version) or \lstinline!"FORTRAN 77"!.  Unless the external language is specified, it is assumed to be \lstinline!"C"!.

\begin{nonnormative}
The intended use of e.g.\ C99 is to detect if the user tries to link with a C99-function using a C89 compiler.
\end{nonnormative}

The \lstinline!"builtin"! specification is only used for functions that are defined to be built-in in Modelica.  The external function call mechanism for \lstinline!"builtin"! functions is implementation-defined.

\begin{nonnormative}
Typically, for functions from the standard C library, the prototype of the function is provided but no \lstinline!Library! annotation.  Currently, there are no other builtin functions defined in Modelica.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
package Modelica
  package Math
    function sin
      input Real x;
      output Real y;
      external "builtin" y=sin(x);
    end sin;
  end Math;
end Modelica;

model UserModel
  parameter Real p=Modelica.Math.sin(2);
end UserModel;
\end{lstlisting}
\end{example}

The \lstinline[language=grammar]!external-function-call! specification allows functions whose prototypes do not match the default assumptions as defined below to be called.  It also gives the name used to call the external function.  If the external call is not given explicitly, this name is assumed to be the same as the Modelica name.

The only permissible kinds of expressions in the argument list are
component references, scalar constants, and the function size applied to
an array and a constant dimension number. The annotations are used to
pass additional information to the compiler when necessary.

A component reference to a component that is part of an input or output
is treated the same way as a top-level input or output in the external
call.

If the function has \lstinline!annotation(Include="includeDirective")!, \cref{annotations-for-external-libraries-and-include-files} it is assumed that it contains an actual prototype and no prototype shall be automatically generated.  In that case the input argument pointers shall be const pointers (indicating that they do not modify the inputs), and non-const pointers are deprecated.  The optional \lstinline[language=grammar]!external-function-call! is still used for determining the name of the function, and order of arguments, as described below.

\subsection{Argument type Mapping}\label{argument-type-mapping}

The arguments of the external function are declared in the same order as
in the Modelica declaration, unless specified otherwise in an explicit
external function call. Protected variables (i.e.\ temporaries) are
passed in the same way as outputs, whereas constants and size-expression
are passed as inputs.

\subsubsection{Simple Types}\label{simple-types}

Arguments of \emph{simple} types are by default mapped as follows for C:
\begin{center}
\begin{tabular}{l|l|l}
\hline
\multicolumn{1}{c|}{\tablehead{Modelica}} & \multicolumn{2}{c}{\tablehead{C}}\\
                                         & \multicolumn{1}{c}{\tablehead{Input}} & \multicolumn{1}{c}{\tablehead{Output}}\\
\hline
\hline
\lstinline!Real! & \lstinline[language=C]!double! & \lstinline[language=C]!double *!\\
\lstinline!Integer! & \lstinline[language=C]!int! & \lstinline[language=C]!int *!\\
\lstinline!Boolean! & \lstinline[language=C]!int! & \lstinline[language=C]!int *!\\
\lstinline!String! & \lstinline[language=C]!const char *! & \lstinline[language=C]!const char **!\\
Enumeration type & \lstinline[language=C]!int! & \lstinline[language=C]!int *!\\
\hline
\end{tabular}
\end{center}

An exception is made when the argument is of the form \lstinline!size($\ldots$, $\ldots$)!. In this case the corresponding C type is \lstinline!size_t!.

Strings are \textsc{nul}-terminated (i.e., terminated by \lstinline[language=C]!'\0'!) to
facilitate calling of C functions. When returning a non-literal string,
see \cref{utility-functions-for-allocating-strings} for details on memory allocation.

\lstinline!Boolean! values are mapped to C such that \lstinline!false! in Modelica is 0 in C and \lstinline!true! in Modelica is 1 in C.  If the returned value from C is 0 it is treated as \lstinline!false! in Modelica; otherwise as \lstinline!true!.

\begin{nonnormative}
It is recommended that the C function should interpret any non-zero value as true.
\end{nonnormative}

Arguments of simple types are by default mapped as follows for FORTRAN~77:
\begin{center}
\begin{tabular}{l|l|l}
\hline
\multicolumn{1}{c|}{\tablehead{Modelica}} & \multicolumn{2}{c}{\tablehead{FORTRAN~77}}\\
                                         & \multicolumn{1}{c}{\tablehead{Input}} & \multicolumn{1}{c}{\tablehead{Output}}\\
\hline
\hline
\lstinline!Real! & \lstinline[language=FORTRAN77]!DOUBLE PRECISION! & \lstinline[language=FORTRAN77]!DOUBLE PRECISION!\\
\lstinline!Integer! & \lstinline[language=FORTRAN77]!INTEGER! & \lstinline[language=FORTRAN77]!INTEGER!\\
\lstinline!Boolean! & \lstinline[language=FORTRAN77]!LOGICAL! & \lstinline[language=FORTRAN77]!LOGICAL!\\
\lstinline!String! & \emph{Special} & \emph{Not available}\\
Enumeration type & \lstinline[language=FORTRAN77]!INTEGER! & \lstinline[language=FORTRAN77]!INTEGER!\\
\hline
\end{tabular}
\end{center}

Sending string literals to FORTRAN~77 subroutines/functions is supported
for Lapack/Blas-routines, and the strings are \textsc{nul}-terminated for
compatibility with C. Returning strings from FORTRAN~77
subroutines/functions is currently not supported.

Enumeration types used as arguments are mapped to type int when calling
an external C function, and to type \lstinline!INTEGER! when calling an external
FORTRAN function. The $i$:th enumeration literal is mapped to integer
value $i$, starting at 1.

Return values are mapped to enumeration types analogously: integer value
1 is mapped to the first enumeration literal, 2 to the second, etc.
Returning a value which does not map to an existing enumeration literal
for the specified enumeration type is an error.

\subsubsection{Arrays}\label{arrays-1}

Unless an explicit function call is present in the external-clause, an array is passed by its address followed by $n$ arguments of type \lstinline!size_t! with the corresponding array dimension sizes, where $n$ is the number of dimensions.

\begin{nonnormative}
The type \lstinline!size_t! is a C unsigned integer type.
\end{nonnormative}

Arrays are by default stored in row-major order when calling C functions and in column-major order when calling FORTRAN~77 functions.  These defaults can be overridden by the \lstinline!arrayLayout! annotation.  See the example below.

The table below shows the mapping of an array argument in the absence of
an explicit external function call when calling a C function. The type \lstinline!T!
is allowed to be any of the simple types which can be passed to C as
defined in \cref{simple-types} or a record type as defined in
\cref{records} and it is mapped to the type \lstinline!T'! as defined in these sections
for input arguments.

\begin{center}
\begin{tabular}{l|l}
\hline
\multicolumn{1}{c|}{\tablehead{Modelica}} & \multicolumn{1}{c}{\tablehead{C}}\\
                                          & \multicolumn{1}{c}{\tablehead{Input and output}}\\
\hline
\hline
\lstinline!T[$\mathit{dim}_{1}$]! &
\lstinline[language=C]!T' *, size_t $\mathit{dim}_{1}$!
\\
\lstinline!T[$\mathit{dim}_{1}$, $\mathit{dim}_{2}$]! &
\lstinline[language=C]!T' *, size_t $\mathit{dim}_{1}$, size_t $\mathit{dim}_{2}$!
\\
\lstinline!T[$\mathit{dim}_{1}$, $\ldots$, $\mathit{dim}_{n}$]! &
\lstinline[language=C]!T' *, size_t $\mathit{dim}_{1}$, $\ldots$, size_t $\mathit{dim}_{n}$!
\\
\hline
\end{tabular}
\end{center}

The method used to pass array arguments to FORTRAN~77 functions in the
absence of an explicit external function call is similar to the one
defined above for C: first the address of the array, then the dimension
sizes as integers. See the table below. The type T is allowed to be any
of the simple types which can be passed to FORTRAN~77 as defined in
\cref{simple-types} and it is mapped to the type T' as defined in that
section.

\begin{center}
\begin{tabular}{l|l}
\hline
\multicolumn{1}{c|}{\tablehead{Modelica}} & \multicolumn{1}{c}{\tablehead{FORTRAN~77}}\\
                                          & \multicolumn{1}{c}{\tablehead{Input and output}}\\
\hline
\hline
\lstinline!T[$\mathit{dim}_{1}$]! &
\lstinline[language=FORTRAN77]!T', INTEGER $\mathit{dim}_{1}$!
\\
\lstinline!T[$\mathit{dim}_{1}$, $\mathit{dim}_{2}$]! &
\lstinline[language=FORTRAN77]!T', INTEGER $\mathit{dim}_{1}$, INTEGER $\mathit{dim}_{2}$!
\\
\lstinline!T[$\mathit{dim}_{1}$, $\ldots$, $\mathit{dim}_{n}$]! &
\lstinline[language=FORTRAN77]!T', INTEGER $\mathit{dim}_{1}$, $\ldots$, INTEGER $\mathit{dim}_{n}$!
\\
\hline
\end{tabular}
\end{center}

\begin{example}
The following two examples illustrate the default mapping of
array arguments to external C and FORTRAN~77 functions.

\begin{lstlisting}[language=modelica]
function foo
  input Real a[:,:,:];
  output Real x;
  external;
end foo;
\end{lstlisting}
The corresponding C prototype is as follows:
\begin{lstlisting}[language=C]
double foo(double *, size_t, size_t, size_t);
\end{lstlisting}

If the external function is written in FORTRAN~77, i.e.:
\begin{lstlisting}[language=modelica]
function foo
  input Real a[:,:,:];
  output Real x;
  external "FORTRAN 77";
end foo;
\end{lstlisting}
the default assumptions correspond to a FORTRAN~77 function
defined as follows:
\begin{lstlisting}[language=fortran77]
FUNCTION foo(a, d1, d2, d3)
  DOUBLE PRECISION(d1, d2, d3) a
  INTEGER                      d1
  INTEGER                      d2
  INTEGER                      d3
  DOUBLE PRECISION             foo
  ...
END
\end{lstlisting}
\end{example}

When an explicit call to the external function is present, the array and
the sizes of its dimensions must be passed explicitly.

\begin{example}
This example shows how arrays can be passed explicitly to an
external FORTRAN~77 function when the default assumptions are
unsuitable.

\begin{lstlisting}[language=modelica]
function foo
  input Real x[:];
  input Real y[size(x,1),:];
  input Integer i;
  output Real u1[size(y,1)];
  output Integer u2[size(y,2)];
  external "FORTRAN 77" myfoo(x, y, size(x,1), size(y,2), u1, i, u2);
end foo;
\end{lstlisting}
The corresponding FORTRAN~77 subroutine would be declared as follows:
\begin{lstlisting}[language=fortran77]
SUBROUTINE myfoo(x, y, n, m, u1, i, u2)
  DOUBLE PRECISION(n) x
  DOUBLE PRECISION(n,m) y
  INTEGER n
  INTEGER m
  DOUBLE PRECISION(n) u1
  INTEGER i
  DOUBLE PRECISION(m) u2
  ...
END
\end{lstlisting}

This example shows how to pass an array in column major order to a C function.

\begin{lstlisting}[language=modelica]
function fie
  input Real[:,:] a;
  output Real b;
  external;
  annotation(arrayLayout = "columnMajor");
end fie;
\end{lstlisting}
This corresponds to the following C prototype:
\begin{lstlisting}[language=C]
double fie(double *, size\_t, size\_t);
\end{lstlisting}
\end{example}

\subsubsection{Records}\label{records}

Mapping of record types is only supported for C. A Modelica record class
that contains simple types, other record elements, is mapped as follows:
\begin{itemize}
\item
  The record class is represented by a struct in C.
\item
  Each element of the Modelica record is mapped to its corresponding C
  representation.
\item
  The elements of the Modelica record class are declared in the same
  order in the C struct.
\item
  Arrays cannot be mapped.
\end{itemize}

Records are passed by reference (i.e.\ a pointer to the record is being
passed).

\begin{example}
\begin{lstlisting}[language=modelica]
record R
  Real x;
  Real z;
end R;
\end{lstlisting}
is mapped to:
\begin{lstlisting}[language=C]
struct R {
  double x;
  double z;
};
\end{lstlisting}
\end{example}

\subsection{Return Type Mapping}\label{return-type-mapping}

If there is a single output parameter and no explicit call of the
external function, or if there is an explicit external call in the form
of an equation, in which case the LHS must be one of the output
parameters, the external routine is assumed to be a value-returning
function. Mapping of the return type of functions is performed as
indicated in the table below. Storage for arrays as return values is
allocated by the calling routine, so the dimensions of the returned
array are fixed at call time. Otherwise the external function is assumed
not to return anything; i.e., it is really a procedure or, in C, a
void-function.

\begin{nonnormative}
In the case of an external function not returning anything, argument type mapping according to \cref{simple-types} is performed in the absence
of any explicit external function call.
\end{nonnormative}

Return types are by default mapped as follows for C and FORTRAN~77:
\begin{center}
\begin{tabular}{l|l|l}
\hline
\multicolumn{1}{c|}{\tablehead{Modelica}} & \multicolumn{1}{c|}{\tablehead{C}} & \multicolumn{1}{c}{\tablehead{FORTRAN~77}}\\
\hline
\hline
\lstinline!Real!    & \lstinline[language=C]!double!      & \lstinline[language=FORTRAN77]!DOUBLE PRECISION!\\
\lstinline!Integer! & \lstinline[language=C]!int!         & \lstinline[language=FORTRAN77]!INTEGER!\\
\lstinline!Boolean! & \lstinline[language=C]!int!         & \lstinline[language=FORTRAN77]!LOGICAL!\\
\lstinline!String!  & \lstinline[language=C]!const char*! & \emph{Not allowed}\\
\lstinline!T[$\mathit{dim}_{1}$, $\ldots$, $\mathit{dim}_{n}$]! & \emph{Not allowed} & \emph{Not allowed} \\
Enumeration type    & \lstinline[language=C]!int!         & \lstinline[language=FORTRAN77]!INTEGER!\\
Record              & See \cref{records}                  & \emph{Not allowed}\\
\hline
\end{tabular}
\end{center}

The element type \lstinline!T! of an array can be any simple type as defined in
\cref{simple-types} or, for C, a record type is returned as a value of the
record type defined in \cref{records}.

\subsection{Aliasing}\label{aliasing}

Any potential aliasing in the external function is the responsibility of
the tool and not the user. An external function is not allowed to
internally change the inputs (even if they are restored before the end
of the function).

\begin{example}
\begin{lstlisting}[language=modelica]
function foo
  input Real x;
  input Real y;
  output Real z=x;
  external "FORTRAN 77" myfoo(x,y,z);
end foo;
\end{lstlisting}
The following Modelica function:
\begin{lstlisting}[language=modelica]
function f
  input Real a;
  output Real b;
algorithm
  b:=foo(a,a);
  b:=foo(b,2*b);
end f;
\end{lstlisting}
can on most systems be transformed into the following C function:
\begin{lstlisting}[language=C]
double f(double a) {
  extern void myfoo_(double*,double*,double*);
  double b,temp1,temp2;

  myfoo_(&a,&a,&b);
  temp1=2*b;
  temp2=b;
  myfoo_(&b,&temp1,&temp2);

  return temp2;
}
\end{lstlisting}

The reason for not allowing the external function to change the
inputs is to ensure that inputs can be stored in static memory and to
avoid superfluous copying (especially of matrices). If the routine does
not satisfy the requirements the interface must copy the input argument
to a temporary. This is rare but occurs e.g.\ in \lstinline!dormlq! in some
Lapack implementations. In those special cases the writer of the
external interface have to copy the input to a temporary. If the first
input was changed internally in myfoo the designer of the interface
would have to change the interface function \lstinline!foo! to:
\begin{lstlisting}[language=modelica]
function foo
  input Real x;
  protected Real xtemp=x; // Temporary used because myfoo changes its input
  public input Real y;
  output Real z;
  external "FORTRAN 77" myfoo(xtemp,y,z);
end foo;
\end{lstlisting}

Note that we discuss input arguments for Fortran-routines even
though FORTRAN~77 does not formally have input arguments and forbid
aliasing between any pair of arguments to a function (Section 15.9.3.6
of X3J3/90.4). For the few (if any) FORTRAN~77 compilers that strictly
follow the standard and are unable to handle aliasing between input
variables the tool must transform the first call of \lstinline!foo! into:
\begin{lstlisting}[language=C]
temp1=a; /* Temporary to avoid aliasing */
myfoo_(&a,&temp1,&b);
\end{lstlisting}

The use of the function \lstinline!foo! in Modelica is uninfluenced by these considerations.
\end{example}

\subsection{Annotations for External Libraries and Include Files}\label{annotations-for-external-libraries-and-include-files}

The following annotations are useful in the context of calling external functions from Modelica, and they should occur on the external-clause and no other standard annotations should occur on the external-clause.  They can all specify either a scalar value or an array of values as indicated below for annotation (Library=\ldots{}):
\begin{itemize}
\item
  The \lstinline!annotation(Library="libraryName")!, used by the linker to include
  the library file where the compiled external function is available.
\item
  The \lstinline!annotation(Library=("libraryName1","libraryName2"))!, used by the
  linker to include the library files where the compiled external
  function is available and additional libraries used to implement it.
  For shared libraries it is recommended to include all non-system
  libraries in this list.
\item
  The \lstinline!annotation(Include="includeDirective")!, used to include source files needed for calling the external function in the code
  generated by the Modelica compiler. The included code should be valid C89 code.
  \begin{nonnormative}
  Examples of files that can be included are header files or source files that contain the
  functions referenced in the external function declaration.
  \end{nonnormative}
\item
  The
  \lstinline!annotation(IncludeDirectory="modelica://ModelicaLibraryName/Resources/Include")!,
  used to specify a location for header files. The preceding one is the
  default and need not be specified; but another location could be
  specified by using an URI name for the include directory, see \cref{external-resources}.
\item
  The
  \lstinline!annotation(LibraryDirectory="modelica://ModelicaLibraryName/Resources/Library")!,
  used to specify a location for library files. The preceding one is the
  default and need not be specified; but another location could be
  specified by using an URI name for the library directory, see \cref{external-resources}.
  Different versions of one object library can be provided
  (e.g.\ for Windows and for Linux) by providing a
  \emph{platform} directory below the \lstinline!LibraryDirectory!. If no
  platform directory is present, the object library must be present
  in the \lstinline!LibraryDirectory!. The following \emph{platform} names are
  standardized:
  \begin{itemize}
  \item
    \lstinline!"win32"! (Microsoft Windows 32 bit)
  \item
    \lstinline!"win64"! (Microsoft Windows 64 bit)
  \item
    \lstinline!"linux32"! (Linux Intel 32 bit)
  \item
    \lstinline!"linux64"! (Linux Intel 64 bit)
  \end{itemize}
\end{itemize}

The \filename{win32} or \filename{win64} directories may contain \filename{gcc47}, \filename{vs2010}, \filename{vs2012}
for specific versions of these compilers and these are used instead of
the general \filename{win32} or \filename{win64} directories, and similarly for other
platforms.

The library on Windows may refer to a lib-file (static library), both a lib- and dll-file (in this case the lib-file is an import-library),
or just a dll-file. It shall not refer to an obj-file.

If the directory for the specific compiler version is missing the
platform specific directory is used.

\begin{nonnormative}
A tool may give diagnostics if the directory corresponding to the selected compiler version is missing.  The directories may use symbolic links or use
a text-file as described below: e.g.\ a text-file \filename{vs2008} containing the text \emph{../win32/vs2005} (or \emph{vs2005}) suggesting that it is
compatible with vs2005.
\end{nonnormative}

The \lstinline!ModelicaLibraryName! used for \lstinline!IncludeDirectory! and \lstinline!LibraryDirectory! indicates the top-level class where the annotation is found in the Modelica source code.

\begin{example}
Use of external functions and of object libraries:
\begin{lstlisting}[language=modelica]
package ExternalFunctions
  model Example
    Real x(start=1.0),y(start=2.0);
  equation
    der(x)=-ExternalFunc1(x);
    der(y)=-ExternalFunc2(y);
  end Example;

  model OtherExample
    Real x(start=1.0);
  equation
    der(x)=-ExternalFunc3(x);
  end OtherExample;

  function ExternalFunc1
    input Real x;
    output Real y;
    external "C"
    y=ExternalFunc1_ext(x) annotation(Library="ExternalLib1",
      Include="#include \"ExternalFunc1.h\"");
  end ExternalFunc1;

  function ExternalFunc2
    input Real x;
    output Real y;
    external "C" annotation(Library="ExternalLib2",
      Include="#include \"ExternalFunc2.h\"");
  end ExternalFunc2;

  function ExternalFunc3
    input Real x;
    output Real y;
    external "C" annotation(Include="#include \"ExternalFunc3.c\"");
  end ExternalFunc3;
end ExternalFunctions;

package MyExternalFunctions
  extends ExternalFunctions;
end MyExternalFunctions;
\end{lstlisting}
Directory structure:
\begin{lstlisting}[language=modelica]
ExternalFunctions
  package.mo  // contains the Modelica code from above
  Resources
    Include        // contains the include files
      ExternalFunc1.h // C header file
      ExternalFunc2.h // C header file
      ExternalFunc3.c // C source file
    Library       // contains the object libraries for different
     platforms
       win32
         ExternalLib1.lib // static link library for VisualStudio
         ExternalLib2.lib // statically linking the dynamic link library
         ExternalLib2.dll // dynamic link library (with manifest)
       linux32
         libExternalLib1.a   // static link library
         libExternalLib2.so // shared library
MyExternalFunctions
   package.mo
\end{lstlisting}
Note that calling \lstinline!MyExternalFunctions.ExternalFunc1! will use
header and library files from \lstinline!ExternalFunction!, the \lstinline!ExternalFunctions.Example! will not use \filename{ExternalFunc3.c},
and one library file may contain multiple functions.

Header file for the function in the dynamic link / shared library
\filename{ExternalLib2} so that the desired functions are defined to be exported
for Microsoft VisualStudio and for GNU C compiler (note, for Linux it is
recommended to use the compiler option \lstinline!-fPIC! to build shared
libraries or object libraries that are later transformed to a shared
library):
\begin{lstlisting}[language=C]
// File ExternalFunc2.h
#ifdef __cplusplus
extern "C" {
#endif
#ifdef _MSC_VER
#ifdef EXTERNAL_FUNCTION_EXPORT
#  define EXTLIB2_EXPORT __declspec( dllexport )
#else
#  define EXTLIB2_EXPORT __declspec( dllimport )
#endif
#elif  __GNUC__ >= 4
  /* In gnuc, all symbols are by default exported. It is still often useful,
  to not export all symbols but only the needed ones */
#  define EXTLIB2_EXPORT __attribute__ ((visibility("default")))
#else
#  define EXTLIB2_EXPORT
#endif

EXTLIB2_EXPORT void ExternalFunc2(<function arguments>);

#ifdef __cplusplus
}
#endif
\end{lstlisting}
\end{example}

The \lstinline!Library! name and the \lstinline!LibraryDirectory! name in the function annotation are mapped to a linkage directive in a compiler-dependent way thereby selecting the object library suited for the respective computer platform.

\subsection{Examples}\label{examples1}

\subsubsection{Input Parameters, Function Value}\label{input-parameters-function-value}

\begin{example}
Here all parameters to the external function are input
parameters. One function value is returned. If the external language is
not specified, the default is \lstinline!"C"!, as below.
\begin{lstlisting}[language=modelica]
function foo
  input Real x;
  input Integer y;
  output Real w;
  external;
end foo;
\end{lstlisting}
This corresponds to the following C prototype:
\begin{lstlisting}[language=C]
double foo(double, int);
\end{lstlisting}

Example call in Modelica:
\begin{lstlisting}[language=modelica]
z = foo(2.4, 3);
\end{lstlisting}
Translated call in C:
\begin{lstlisting}[language=C]
z = foo(2.4, 3);
\end{lstlisting}
\end{example}

\subsubsection{Arbitrary Placement of Output Parameters, No External Function Value}\label{arbitrary-placement-of-output-parameters-no-external-function-value}

\begin{example}
In the following example, the external function call is given
explicitly which allows passing the arguments in a different order than
in the Modelica version.
\begin{lstlisting}[language=modelica]
function foo
  input Real x;
  input Integer y;
  output Real u1;
  output Integer u2;
  external "C" myfoo(x, u1, y, u2);
end foo;
\end{lstlisting}
This corresponds to the following C prototype:
\begin{lstlisting}[language=C]
void myfoo(double, double *, int, int *);
\end{lstlisting}
Example call in Modelica:
\begin{lstlisting}[language=modelica]
(z1,i2) = foo(2.4, 3);
\end{lstlisting}
Translated call in C:
\begin{lstlisting}[language=C]
myfoo(2.4, \&z1, 3, \&i2);
\end{lstlisting}
\end{example}

\subsubsection{External Function with Both Function Value and Output Variable}\label{external-function-with-both-function-value-and-output-variable}

\begin{example}
The following external function returns two results: one
function value and one output parameter value. Both are mapped to
Modelica output parameters.
\begin{lstlisting}[language=modelica]
function foo
  input Real x;
  input Integer y;
  output Real funcvalue;
  output Integer out1;
  external "C" funcvalue = myfoo(x, y, out1);
end foo;
\end{lstlisting}
This corresponds to the following C prototype:
\begin{lstlisting}[language=C]
double myfoo(double, int, int *);
\end{lstlisting}
Example call in Modelica:
\begin{lstlisting}[language=modelica]
(z1,i2) = foo(2.4, 3);
\end{lstlisting}
Translated call in C:
\begin{lstlisting}[language=C]
z1 = myfoo(2.4, 3, \&i2);
\end{lstlisting}
\end{example}

\subsection{Utility Functions}\label{utility-functions}

This section describes the utility functions declared in \filename{ModelicaUtilities.h}, which can be called in external Modelica functions written in C.

\subsubsection{Utility Functions for Reporting Errors}\label{utility-functions-for-reporting-errors}

The functions listed below produce a message in different ways.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
\lstinline[language=C]!ModelicaMessage($\mathit{string}$)! & Message with fixed string & \multirow{3}{*}{\Cref{modelica:ModelicaMessage-et-al}} \\
\lstinline[language=C]!ModelicaWarning($\mathit{string}$)! & Warning with fixed string & \\
\lstinline[language=C]!ModelicaError($\mathit{string}$)! & Error with fixed string & \\
\hline
\lstinline[language=C]!ModelicaFormatMessage($\mathit{format}$, $\ldots$)! & Message with \lstinline[language=C]!printf! style formatting & \multirow{3}{*}{\Cref{modelica:ModelicaFormatMessage-et-al}} \\
\lstinline[language=C]!ModelicaFormatWarning($\mathit{format}$, $\ldots$)! & Warning with \lstinline[language=C]!printf! style formatting & \\
\lstinline[language=C]!ModelicaFormatError($\mathit{format}$, $\ldots$)! & Error with \lstinline[language=C]!printf! style formatting & \\
\hline
\lstinline[language=C]!ModelicaVFormatMessage($\mathit{format}$, $\mathit{ap}$)! & Message with \lstinline[language=C]!vprintf! style formatting & \multirow{3}{*}{\Cref{modelica:ModelicaVFormatMessage-et-al}} \\
\lstinline[language=C]!ModelicaVFormatWarning($\mathit{format}$, $\mathit{ap}$)! & Warning with \lstinline[language=C]!vprintf! style formatting & \\
\lstinline[language=C]!ModelicaVFormatError($\mathit{format}$, $\mathit{ap}$)! & Error with \lstinline[language=C]!vprintf! style formatting & \\
\hline
\end{tabular}
\end{center}

The \emph{Message}-functions only produce the message, but the \emph{Warning}- and \emph{Error}-functions combine this with error handling as follows.

The \emph{Warning}-functions view the message as a warning and can skip
duplicated messages similarly as an \lstinline!assert! with
\lstinline!level = AssertionLevel.Warning! in the Modelica code.

The \emph{Error}-functions never return to the calling function, but handle the
error similarly to an \lstinline!assert! with \lstinline!level = AssertionLevel.Error! in the
Modelica code.

\begin{functiondefinition*}[ModelicaMessage, ModelicaWarning, ModelicaError]\label{modelica:ModelicaMessage-et-al}
\begin{synopsis}[C]\begin{lstlisting}
void ModelicaMessage(const char* $\mathit{string}$)
void ModelicaWarning(const char* $\mathit{string}$)
void ModelicaError(const char* $\mathit{string}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Output the fixed message string (no format control).
\end{semantics}
\end{functiondefinition*}

\begin{functiondefinition*}[ModelicaFormatMessage, ModelicaFormatWarning, ModelicaFormatError]\label{modelica:ModelicaFormatMessage-et-al}
\begin{synopsis}[C]
% Note that the "..." below are actual C code, and shouldn't be typeset as \ldots.
\begin{lstlisting}
void ModelicaFormatMessage(const char* $\mathit{format}$, ...)
void ModelicaFormatWarning(const char* $\mathit{format}$, ...)
void ModelicaFormatError(const char* $\mathit{format}$, ...)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Output the message under the same format control as the C function \lstinline[language=C]!printf!.
\end{semantics}
\end{functiondefinition*}

\begin{functiondefinition*}[ModelicaVFormatMessage, ModelicaVFormatWarning, ModelicaVFormatError]\label{modelica:ModelicaVFormatMessage-et-al}
\begin{synopsis}[C]\begin{lstlisting}
void ModelicaVFormatMessage(const char* $\mathit{format}$, va_list $\mathit{ap}$)
void ModelicaVFormatWarning(const char* $\mathit{format}$, va_list $\mathit{ap}$)
void ModelicaVFormatError(const char* $\mathit{format}$, va_list $\mathit{ap}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Output the message under the same format control as the C function \lstinline[language=C]!vprintf!.
\end{semantics}
\end{functiondefinition*}

\subsubsection{Utility Functions for Allocating Strings}\label{utility-functions-for-allocating-strings}

The functions listed below are related to string allocation.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
\lstinline[language=C]!ModelicaAllocateString($\mathit{len}$)! & Allocate or error & \Cref{modelica:ModelicaAllocateString} \\
\lstinline[language=C]!ModelicaAllocateStringWithErrorReturn($\mathit{len}$)! & Allocate or null& \Cref{modelica:ModelicaAllocateStringWithErrorReturn} \\
\lstinline[language=C]!ModelicaDuplicateString($\mathit{str}$)! & Duplicate or error & \Cref{modelica:ModelicaDuplicateString} \\
\lstinline[language=C]!ModelicaDuplicateStringWithErrorReturn($\mathit{str}$)! & Duplicate or null& \Cref{modelica:ModelicaDuplicateStringWithErrorReturn} \\
\hline
\end{tabular}
\end{center}

\begin{functiondefinition}[ModelicaAllocateString]
\begin{synopsis}[C]\begin{lstlisting}
char* ModelicaAllocateString(size_t $\mathit{len}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Allocate memory for a writeable non-literal string which is used as a return argument of an external Modelica function.  It allocates $\mathit{len}+1$ characters and the last one is set to \textsc{nul}.  If an error occurs, this function does not return, but calls \lstinline[language=C]!ModelicaError!.
\end{semantics}
\end{functiondefinition}

\begin{functiondefinition}[ModelicaAllocateStringWithErrorReturn]
\begin{synopsis}[C]\begin{lstlisting}
char* ModelicaAllocateStringWithErrorReturn(size_t $\mathit{len}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Same as \lstinline[language=C]!ModelicaAllocateString!, except that in case of error, the function returns 0.  This allows the external function to close files and free other open resources in case of error.  After cleaning up resources, use \lstinline[language=C]!ModelicaError! or \lstinline[language=C]!ModelicaFormatError! to signal the error.
\end{semantics}
\end{functiondefinition}

\begin{functiondefinition}[ModelicaDuplicateString]
\begin{synopsis}[C]\begin{lstlisting}
char* ModelicaDuplicateString(const char* $\mathit{str}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns a writeable duplicate of the \textsc{nul}-terminated string $\mathit{str}$.  If an error occurs, this function does not return, but calls \lstinline[language=C]!ModelicaError!.
\end{semantics}
\end{functiondefinition}

\begin{functiondefinition}[ModelicaDuplicateStringWithErrorReturn]
\begin{synopsis}[C]\begin{lstlisting}
char* ModelicaDuplicateStringWithErrorReturn(const char* $\mathit{str}$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Same as \lstinline[language=C]!ModelicaDuplicateString!, except that in case of error, the function returns 0.  This allows the external function to close files and free other open resources in case of error. After cleaning up resources, use \lstinline[language=C]!ModelicaError! or \lstinline[language=C]!ModelicaFormatError! to signal the error.
\end{semantics}
\end{functiondefinition}

The valid return values for an external function returning a \lstinline!String! are:
\begin{itemize}
\item A literal \lstinline!String!.
\item A string given as \lstinline!String! input to the external function.
\item A string pointer returned by one the functions in the table above.
\end{itemize}

Thus if an external function wants to create a non-literal string it must be allocated with one of the functions in this section, e.g., \lstinline[language=C]!ModelicaAllocateString!.  After return of the external function, the Modelica environment is responsible for the memory allocated with \lstinline[language=C]!ModelicaAllocateString! (e.g., to free this memory, when appropriate).  It is not allowed to access memory that was allocated with \lstinline[language=C]!ModelicaAllocateString! in a previous call of this external function.

\begin{nonnormative}
Memory that is not passed to the Modelica simulation environment, such as memory that is freed before leaving the function, or in an \lstinline!ExternalObject!,
see~\cref{external-objects}, should be allocated with the standard C mechanisms, like \lstinline[language=C]!calloc!.
\end{nonnormative}

\begin{nonnormative}
The reason why one should avoid, for instance, \lstinline[language=C]!malloc! for string allocation is that a Modelica simulation environment may have
its own allocation scheme, e.g., a special stack for local variables of a function.
\end{nonnormative}

\subsection{External Objects}\label{external-objects}

External functions may need to store their internal memory between function calls.
Within Modelica this memory is defined as instance of the
predefined class \lstinline!ExternalObject! according to the following rules:
\begin{itemize}
\item
  There is a predefined partial class \lstinline!ExternalObject!.
  \begin{nonnormative}
  Since the class is partial, it is not possible to define an instance of this class.
  \end{nonnormative}
\item
  An external object class shall be directly extended from
  \lstinline!ExternalObject!, shall have exactly two function definitions, called
  \lstinline!constructor! and \lstinline!destructor!, and shall not contain other elements.
  The functions \lstinline!constructor! and \lstinline!destructor! shall not be replaceable.
\item
  The \lstinline!constructor! function is called exactly once before the first use
  of the object. For each completely constructed object, the destructor
  is called exactly once, after the last use of the object, even if an
  error occurs. The \lstinline!constructor! shall have exactly one output argument
  in which the constructed instance derived from \lstinline!ExternalObject! is
  returned. The \lstinline!destructor! shall have no output arguments and the only
  input argument of the destructor shall be of the type derived from
  \lstinline!ExternalObject!. It is not legal to call explicitly the \lstinline!constructor! and
  \lstinline!destructor! functions. The constructor shall initialize the object, and
  must not require any other calls to be made for the initialization to
  be complete (e.g., from an initial algorithm or initial equation). The
  destructor shall delete the object, and must not require any other
  calls to be made for the deletion to be complete (e.g., from a \lstinline!when terminal()! clause). The constructor shall not assume that pointers sent
  to the external object will remain valid for the life-time of the external object.  An exception is that if the pointer to another external object is
  given as argument to the constructor, that pointer will remain valid as long as the other external object lives.
  \begin{nonnormative}
  External objects may be a protected component (or part of one) in a function.  The constructor is in that case called at the start of the function call,
  and the destructor when the function returns, or when recovering from errors in the function.
  \end{nonnormative}
  \begin{nonnormative}
  External objects may be an input (or part of an input) to a function, in that case the destructor is not called (since the external object is active before
  and after the function call).  Normally this is an external function, but it could be a non-external function as well (e.g.\ calling external functions one
  or more times).  The function input shall not have a default value using the constructor.
  \end{nonnormative}
\item
  Classes derived from \lstinline!ExternalObject! can neither be used in an
  extends-clause nor in a short class definition.
\item
  Only the constructor may return external objects and an external object
  can only be bound in component declarations and neither modified later
  nor assigned to.
  \begin{nonnormative}
  It follows that a function cannot return a component containing an external object, since only the constructor may return an external object and the constructor exactly returns the external object.
  \end{nonnormative}
\item
  External functions may be defined which operate on the internal memory
  of an \lstinline!ExternalObject!. An \lstinline!ExternalObject! used as input argument or
  return value of an external C function is mapped to the C type
  \lstinline!void*!.
\end{itemize}

\begin{example}
A user-defined table may be defined in the following way as an \lstinline!ExternalObject!
(the table is read in a user-defined format from file and has memory for the last used table interval):
\begin{lstlisting}[language=modelica]
class MyTable
  extends ExternalObject;
  function constructor
    input String fileName = "";
    input String tableName = "";
    output MyTable table;
    external "C" table = initMyTable(fileName, tableName);
  end constructor;

  function destructor "Release storage of table"
    input MyTable table;
    external "C" closeMyTable(table);
  end destructor;
end MyTable;
\end{lstlisting}
and used in the following way:
\begin{lstlisting}[language=modelica]
model test "Define a new table and interpolate in it"
  MyTable table=MyTable(fileName ="testTables.txt",
    tableName="table1"); // call initMyTable
  Real y;
equation
  y = interpolateMyTable(table, time);
end test;
\end{lstlisting}

This requires to provide the following Modelica function:
\begin{lstlisting}[language=modelica]
function interpolateMyTable "Interpolate in table"
  input MyTable table;
  input Real u;
  output Real y;
  external "C" y = interpolateMyTable(table, u);
end interpolateTable;
\end{lstlisting}
The external C functions may be defined in the following way:
\begin{lstlisting}[language=C]
typedef struct { /* User-defined datastructure of the table */
  double* array; /* nrow*ncolumn vector */
  int nrow; /* number of rows */
  int ncol; /* number of columns */
  int type; /* interpolation type */
  int lastIndex; /* last row index for search */
} MyTable;

void* initMyTable(const char* fileName, const char* tableName) {
  MyTable* table = malloc(sizeof(MyTable));
  if ( table == NULL ) ModelicaError("Not enough memory");
  // read table from file and store all data in *table
  return (void*) table;
};

void closeMyTable(void* object) { /* Release table storage */
  MyTable* table = (MyTable*) object;
  if ( object == NULL ) return;
  free(table->array);
  free(table);
}

double interpolateMyTable(void* object, double u) {
  MyTable* table = (MyTable*) object;
  double y;
  // Interpolate using "table" data (compute y)
  return y;
};
\end{lstlisting}
\end{example}