connectors.tex

\chapter{Connectors and Connections}\label{connectors-and-connections}

This chapter covers connectors, \lstinline!connect!-equations, and connections.

Connectors and \lstinline!connect!-equations are designed so that different components can be connected graphically with well-defined semantics.
However, the graphical part is optional and found in \cref{annotations}.

\section{Connect-Equations and Connectors}\label{connect-equations-and-connectors}

Connections between objects are introduced by \lstinline!connect!-equations in the equation part of a class.
A \lstinline!connect!-equation\index{connect@\robustinline{connect}!equation} has the following syntax:
\begin{lstlisting}[language=grammar]
connect "(" component-reference "," component-reference ")" ";"
\end{lstlisting}

\begin{nonnormative}
A \emph{connector} is an instance of a \lstinline!connector!\indexinline{connector} class.
\end{nonnormative}

The \lstinline!connect!-equation construct takes two references to connectors, each of which is either of the following forms:
\begin{itemize}
\item
  \lstinline!$c_1$.$c_2$.$\ldots{}$.$c_n$!, where $c_1$ is a connector of the class, $n \geq 1$ and $c_{i+1}$ is a connector element of $c_i$ for $i = 1,\, \ldots,\, (n - 1)$.
\item
  \lstinline!m.c!, where \lstinline!m! is a non-connector element in the class and \lstinline!c! is a connector element of \lstinline!m!.
\end{itemize}

There may optionally be array subscripts on any of the components; the array subscripts shall be parameter expressions or the special operator \lstinline!:!.
If the connect construct references array of connectors, the array dimensions must match, and each corresponding pair of elements from the arrays is connected as a pair of scalar connectors.

\begin{example}
Array usage:
\begin{lstlisting}[language=modelica]
  connector InPort = input Real;
  connector OutPort = output Real;
  block MatrixGain
    input InPort u[size(A, 2)];
    output OutPort y[size(A, 1)];
    parameter Real A[:, :] = [1];
  equation
    y = A * u;
  end MatrixGain;
  Modelica.Blocks.Sources.Sine sinSource[5];
  MatrixGain gain (A = 5 * identity(5));
  MatrixGain gain2(A = ones(2, 5));
  OutPort x[2];
equation
  connect(sinSource.y, gain.u); // Legal
  connect(gain.y, gain2.u); // Legal
  connect(gain2.y, x); // Legal
\end{lstlisting}
\end{example}

The three main tasks are to:
\begin{itemize}
\item
  Elaborate expandable connectors.
\item
  Build connection sets from \lstinline!connect!-equations.
\item
  Generate equations for the complete model.
\end{itemize}

\subsection{Connection Sets}\label{connection-sets}

A connection set is a set of variables connected by means of \lstinline!connect!-equations.
A connection set shall contain either only flow variables or only non-flow variables.

\subsection{Inside and Outside Connectors}\label{inside-and-outside-connectors}

In an element instance \lstinline!M!, each connector element of \lstinline!M! is called an \firstuse{outside connector} with respect to \lstinline!M!.
Any other connector elements that is hierarchically inside \lstinline!M!, but not in one of the outside connectors of \lstinline!M!, is called an \firstuse{inside connector} with respect to \lstinline!M!.
This is done before resolving \lstinline!outer! elements to corresponding \lstinline!inner! ones.

\begin{example}
\begin{figure}[H]
  \begin{center}
    \includegraphics{innerouterconnector}
  \end{center}
  \caption{Example for inside and outside connectors.}
\end{figure}
The figure visualizes the following \lstinline!connect!-equations to the connector \lstinline!c! in the models \lstinline!m!$i$.
Consider the following \lstinline!connect!-equations found in the model for component \lstinline!m0!:
\begin{lstlisting}[language=modelica]
connect(m1.c, m3.c); // m1.c and m3.c are inside connectors
connect(m2.c, m3.c); // m2.c and m3.c are inside connectors
\end{lstlisting}
and in the model for component \lstinline!m3! (\lstinline!c.x! is a sub-connector inside \lstinline!c!):
\begin{lstlisting}[language=modelica]
connect(c, m4.c);   // c is an outside connector, m4.c is an inside connector
connect(c.x, m5.c); // c.x is an outside connector, m5.c is an inside connector
connect(c, d);      // c is an outside connector, d is an outside connector
\end{lstlisting}
and in the model for component \lstinline!m6!:
\begin{lstlisting}[language=modelica]
connect(d, m7.c);   // d is an outside connector, m7.c is an inside connector
\end{lstlisting}
\end{example}

\subsection{Expandable Connectors}\label{expandable-connectors}

If the \lstinline!expandable!\indexinline{expandable} qualifier is present on a connector definition, all instances of that connector are referred to as \firstuse[expandable connector]{expandable connectors}.
Instances of connectors that do not possess this qualifier will be referred to as \firstuse[non-expandable connector]{non-expandable connectors}.

Before generating \willintroduce{connection equations}, non-parameter scalar variables and non-parameter array elements declared in expandable connectors are marked as only being potentially present.
A non-parameter array element may be declared with array dimensions \lstinline!:! indicating that the size is unknown (note that the size of such a dimension cannot be determined using \lstinline!size!, see \cref{array-dimension-and-size-functions}).
This applies to both variables of simple types, and variables of structured types.

Then connections containing expandable connectors are elaborated:
\begin{itemize}
\item
  One connector in the \lstinline!connect!-equation must reference a declared component, and if the other connector is an undeclared element in a declared expandable connector it is handled as follows (elements that are only potentially present are not seen as declared):
  \begin{itemize}
  \item
    The expandable connector instance is automatically augmented with a new component having the used name and corresponding type.
  \item
    If the undeclared component is subscripted, an array variable is created, and a connection to the specific array element is performed.
    Introducing elements in an array gives an array with at least the specified elements, other elements are either not created or have a default value (i.e.\ as if they were only potentially present, and the same note regarding the use of \lstinline!size! also applies here).
  \item
    If the variable on the other side of the \lstinline!connect!-equation is \lstinline!input! or \lstinline!output! the new component will be either \lstinline!input! or \lstinline!output! to satisfy the restrictions in \cref{restrictions-of-connections-and-connectors} for a non-expandable connector.
    \begin{nonnormative}
    If the existing side refers to an inside connector (i.e.\ a connector of a component) the new variable will copy its causality, i.e.\ \lstinline!input! if \lstinline!input! and \lstinline!output! if \lstinline!output!, since the expandable connector must be an outside connector.
    \end{nonnormative}
    For an array the \lstinline!input!/\lstinline!output! property can be deduced separately for each array element.
  \end{itemize}

\item
  When two expandable connectors are connected, each is augmented with the variables that are only declared in the other expandable connector (the new variables are neither \lstinline!input! nor \lstinline!output!).
  This is repeated until all connected expandable connector instances have matching variables.
  \begin{nonnormative}
  I.e.\ each of the connector instances is expanded to be the union of all connector variables.
  \end{nonnormative}

\item
  The variables introduced in the elaboration follow additional rules for generating connection sets (given in \cref{generation-of-connection-equations}).

\item
  If a variable appears as an \lstinline!input! in one expandable connector, it should appear as a non-\lstinline!input! in at least one other expandable connector instance in the same augmentation set.
  An augmentation set is defined as the set of connected expandable connector instances that through the elaboration will have matching variables.
\begin{example}
\begin{lstlisting}[language=modelica]
expandable connector EngineBus
end EngineBus;

block Sensor
  RealOutput speed; // Output, i.e., non-input
end Sensor;
block Actuator
  RealInput speed; // Input
end Actuator;

model Engine
  EngineBus bus;
  Sensor sensor;
  Actuator actuator;
equation
  connect(bus.speed, sensor.speed); // sensor.speed is the non-input
  connect(bus.speed, actuator.speed);
end Engine;
\end{lstlisting}
\end{example}

\item
  All components in an expandable connector are seen as connector instances even if they are not declared as such.
  \begin{nonnormative}
  I.e.\ it is possible to connect to e.g.\ a \lstinline!Real! variable.
  \end{nonnormative}
\begin{example}
\begin{lstlisting}[language=modelica]
expandable connector EngineBus // has predefined signals
  import Modelica.Units.SI;
  SI.AngularVelocity speed;
  SI.Temperature T;
end EngineBus;

block Sensor
 RealOutput speed;
end Sensor;

model Engine
  EngineBus bus;
  Sensor sensor;
equation
  connect(bus.speed, sensor.speed);
  // connection to non-connector speed is possible
  // in expandable connectors
end Engine;
\end{lstlisting}
\end{example}

\item
  An expandable connector shall not contain a component declared with the prefix \lstinline!flow!\index{flow@\robustinline{flow}!in expandable connector}, but may contain non-expandable connector components with \lstinline!flow! components.
\begin{example}
\begin{lstlisting}[language=modelica]
import Interfaces=Modelica.Electrical.Analog.Interfaces;
expandable connector ElectricalBus
  Interfaces.PositivePin p12, n12; // OK
  flow Modelica.Units.SI.Current i; // Error
end ElectricalBus;

model Battery
  Interfaces.PositivePin p42, n42;
  ElectricalBus bus;
equation
  connect(p42, bus.p42); // Adds new electrical pin
  connect(n42, bus.n42); // Adds another pin
end Battery;
\end{lstlisting}
\end{example}

\item
  Expandable connectors can only be connected to other expandable connectors.
\end{itemize}

If a \lstinline!connect!-equation references a potentially present variable, or variable element, in an expandable connector the variable or variable element is marked as being present, and due to the paragraphs above it is possible to deduce whether the bus variable shall be treated as input, or shall be treated as output in the \lstinline!connect!-equation.
That \lstinline!input! or \lstinline!output! prefix is added if no \lstinline!input!/\lstinline!output! prefix is present on the declaration.

\begin{example}
\begin{lstlisting}[language=modelica]
expandable connector EmptyBus
end EmptyBus;

model Controller
  EmptyBus bus1;
  EmptyBus bus2;
  RealInput speed;
equation
  connect(speed, bus1.speed); // OK; only one undeclared and not subscripted.
  connect(bus1.pressure, bus2.pressure); // Error; both undeclared.
  connect(speed, bus2.speed[2]); // Introduces speed array (with element [2]).
end Controller;
\end{lstlisting}
\end{example}

An expandable connector array component for which \lstinline!size! is not defined (see \cref{array-dimension-and-size-functions}) is referred to as a \firstuse{sizeless array component}.
Such a component shall not be used without subscripts, and the subscripts must slice the array so that the sizeless dimensions are removed.

\begin{example}
Valid and invalid uses of sizeless array components:
\begin{lstlisting}[language=modelica]
expandable connector EngineBus
end EngineBus;

block Sensor
  RealOutput speed;
end Sensor;

model Engine
  parameter Integer n = 1;
  EngineBus bus;
  Sensor sensor;
  RealOutput sensorSpeeds[:];
equation
  /* Comments below refer to the use of sizeless array bus.speed. */
  connect(bus.speed[n], sensor.speed) ; // OK; subscript to scalar component.
  connect(bus.speed, sensorSpeeds); // Error; missing subscripts.
public
  Real s[:] = bus.speed; // Error; missing subscripts.
  Real s[2] = bus.speed[{1, 3}]; // OK; subscript selects fixed size sub-array.
end Engine;
\end{lstlisting}
\end{example}

After this elaboration the expandable connectors are treated as normal connector instances, and the connections as normal connections, and all potentially present variables and array elements that are not actually present are undefined.
It is an error if there are expressions referring to potentially present variables or array elements that are not actually present or non-declared variables.
This elaboration implies that expandable connectors can be connected even if they do not contain the same components.

\begin{nonnormative}
A tool may remove undefined variables in an expandable connector, or set them to the default value, e.g.\ zero for \lstinline!Real! variables.
\end{nonnormative}

\begin{nonnormative}
Expressions can only ``read'' variables from the bus that are actually declared and present in the connector, in order that the types of the variables can be determined in the local scope.
\end{nonnormative}

\begin{nonnormative}
Note that the introduction of variables, as described above, is conceptual and does not necessarily impact the flattening hierarchy in any way.
Furthermore, it is important to note that these elaboration rules must consider:
\begin{enumerate}
\item
  Expandable connectors nested hierarchically.
  This means that  both outside and inside connectors must be included at every level of the hierarchy in this elaboration process.
\item
  When processing an expandable connector that possesses the \lstinline!inner! scope qualifier, all outer instances must also be taken into account during elaboration.
\end{enumerate}
\end{nonnormative}

\begin{example}
Engine system with sensors, controllers, actuator and plant that exchange information via a bus (i.e.\ via expandable connectors):
\begin{lstlisting}[language=modelica]
import Modelica.Units.SI;
import Modelica.Blocks.Interfaces.RealInput;
// Plant Side
model SparkPlug
  RealInput spark_advance;
  $\ldots$
end SparkPlug;

expandable connector EngineBus
  // No minimal set
end EngineBus;

expandable connector CylinderBus
  Real spark_advance;
end CylinderBus;

model Cylinder
  CylinderBus cylinder_bus;
  SparkPlug spark_plug;
  $\ldots$
equation
  connect(spark_plug.spark_advance,
  cylinder_bus.spark_advance);
end Cylinder;

model I4
  EngineBus engine_bus;
  Modelica.Mechanics.Rotational.Sensors.SpeedSensor speed_sensor;
  Modelica.Thermal.HeatTransfer.Sensors.TemperatureSensor temp_sensor;
  parameter Integer nCylinder = 4 "Number of cylinders";
  Cylinder cylinder[nCylinder];
equation
  // adds engine_speed (as output)
  connect(speed_sensor.w, engine_bus.engine_speed);
  // adds engine_temp (as output)
  connect(temp_sensor.T, engine_bus.engine_temp);
  // adds cylinder_bus1 (a nested bus)
  for i in 1:nCylinder loop
    connect(cylinder[i].cylinder_bus,
    engine_bus.cylinder_bus[i]);
  end for;
end I4;
\end{lstlisting}
Due to the above connection, conceptually a connector consisting of the union of all connectors is introduced.

The \lstinline!engine_bus! contains the following variable declarations:
\begin{lstlisting}[language=modelica]
RealOutput engine_speed;
RealOutput engine_temp;
CylinderBus cylinder_bus[1];
CylinderBus cylinder_bus[2];
CylinderBus cylinder_bus[3];
CylinderBus cylinder_bus[4];
\end{lstlisting}
\end{example}

\section{Generation of Connection Equations}\label{generation-of-connection-equations}

When generating \firstuse[connection equation]{connection equations}, \lstinline!outer! elements are resolved to the corresponding \lstinline!inner! elements in the instance hierarchy (see instance hierarchy name lookup \cref{instance-hierarchy-name-lookup-of-inner-declarations}).
The arguments to each \lstinline!connect!-equation are resolved to two connector elements.

For every use of the \lstinline!connect!-equation
\begin{lstlisting}[language=modelica]
connect(a, b);
\end{lstlisting}
the primitive components of \lstinline!a! and \lstinline!b! form a connection set, together with an indication of whether they are from an inside or an outside connector.
The primitive elements are of simple types or of types defined as \lstinline!operator record! (i.e.\ a component of an \lstinline!operator record! type is not split into sub-components).
The elements of the connection sets are tuples of primitive variables together with an indication of inside or outside; if the same tuple belongs to two connection sets those two sets are merged, until every tuple is only present in one set.
Composite connector types are broken down into primitive components.
The \lstinline!outer! components are handled by mapping the objects to the corresponding \lstinline!inner! components, and the inside indication is not influenced.
The outer connectors are handled by mapping the objects to the corresponding inner connectors, and they are always treated as outside connectors.

\begin{nonnormative}
Rationale: The inside/outside as part of the connection sets ensure that connections from different hierarchical levels are treated separately.
Connection sets are formed from the primitive elements and not from the connectors; this handles connections to parts of hierarchical connectors and also makes it easier to generate equations directly from the connection sets.
All variables in one connection set will either be flow variables or non-flow variables due to restriction on \lstinline!connect!-equations.
The mapping from an \lstinline!outer! to an \lstinline!inner! element must occur before merging the sets in order to get one zero-sum equation, and ensures that the equations for the \lstinline!outer! elements are all given for one side of the connector, and the \lstinline!inner! element can define the other side.
\end{nonnormative}

The following connection sets with just one member are also present (and merged):
\begin{itemize}
\item
  Each primitive flow variable as inside connector.
\item
  Each flow variable \emph{added} during augmentation of expandable connectors, both as inside and as outside.
  \begin{nonnormative}
  Note that the flow variable is not directly in the expandable connector, but in a connector inside the expandable connector.
  \end{nonnormative}
\end{itemize}

\begin{nonnormative}
Rationale: If these variables are not connected they will generate a set comprised only of this element, and thus they will be implicitly set to zero (see below).
If connected, this set will be merged and adding this at the start has no impact.
\end{nonnormative}

Each connection set is used to generate equations for potential and flow (zero-sum) variables of the form
\begin{itemize}
\item
  $a_{1} = a_{2} = \ldots = a_{n}$ (neither flow nor stream variables)
\item
  $z_{1} + z_{2} + (-z_{3}) + \ldots + z_{n} = \mathbf{0}$ (flow variables)
\end{itemize}

The bold-face $\mathbf{0}$ represents an array or scalar zero of appropriate dimensions (i.e.\ the same size as $z$).

For an \lstinline!operator record! type this uses the operator \lstinline!'0'! -- which must be defined in the operator record -- and all of the flow variables for the \lstinline!operator record!
must be of the same \lstinline!operator record! type.
This implies that in order to have flow variables of an \lstinline!operator record! type the \lstinline!operator record! must define addition, negation, and \lstinline!'0'!; and these operations should define an additive group.

In order to generate equations for flow variables (using the \lstinline!flow!\indexinline{flow} prefix), the sign used for the connector variable $z_{i}$ above is +1 for inside connectors and -1 for outside connectors ($z_{3}$ in the example above).

\begin{example}
Simple example:
\begin{lstlisting}[language=modelica]
model Circuit
  Ground ground;
  Load load;
  Resistor resistor;
equation
  connect(load.p , ground.p);
  connect(resistor.p, ground.p);
end Circuit;

model Load
  extends TwoPin;
  Resistor resistor;
equation
  connect(p, resistor.p);
  connect(resistor.n, n);
end Load;
\end{lstlisting}
The connection sets are before merging (note that one part of the load and resistor is not connected):

\{\textless{}\lstinline!load.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.v!, inside\textgreater{}\}

After merging this gives:

\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}, \textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}, \textless{}\lstinline!resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}

And thus the equations:
\begin{lstlisting}[language=modelica]
load.p.v = load.resistor.p.v;
load.n.v = load.resistor.n.v;
load.p.v = ground.p.v;
load.p.v = resistor.p.v;
0 = (-load.p.i) + load.resistor.p.i;
0 = (-load.n.i) + load.resistor.n.i;
0 = load.p.i + ground.p.i + resistor.p.i;
0 = load.n.i;
0 = resistor.n.i;
\end{lstlisting}
\end{example}

\begin{example}
Outer component example:
\begin{lstlisting}[language=modelica]
model Circuit
  Ground ground;
  Load load;
  inner Resistor resistor;
equation
  connect(load.p, ground.p);
end Circuit;

model Load
  extends TwoPin;
  outer Resistor resistor;
equation
  connect(p, resistor.p);
  connect(resistor.n, n);
end Load;
\end{lstlisting}
The connection sets are before merging (note that one part of the load and resistor is not connected):

\{\textless{}\lstinline!load.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!resistor.n.v!, inside\textgreater{}\}

After merging this gives:

\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!resistor.n.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}

And thus the equations:
\begin{lstlisting}[language=modelica]
load.p.v = resistor.p.v;
load.n.v = resistor.n.v;
load.p.v = ground.p.v;
0 = (-load.p.i) + resistor.p.i;
0 = (-load.n.i) + resistor.n.i;
0 = load.p.i + ground.p.i;
0 = load.n.i;
\end{lstlisting}

This corresponds to a direct connection of the resistor.
\end{example}

\section{Restrictions of Connections and Connectors}\label{restrictions-of-connections-and-connectors}

\begin{itemize}
\item
  The \lstinline!connect!-equations (and the special functions for overdetermined connectors) can only be used in equations, and shall not be used inside \lstinline!if!-equations with conditions that are not parameter expressions, or in \lstinline!when!-equations.
  \begin{nonnormative}
  The \lstinline!for!-equations always have parameter expressions for the array expression.
  \end{nonnormative}
\item
  A connector component shall not be declared with the prefix \lstinline!parameter! or \lstinline!constant!.
  In the \lstinline!connect!-equation the primitive components may only connect parameter variables to parameter variables and constant variables to constant variables.
\item
  The \lstinline!connect!-equation construct only accepts forms of connector references as specified in \cref{connect-equations-and-connectors}.
\item
  In a \lstinline!connect!-equation the two connectors must have the same named component elements with the same dimensions; recursively down to the primitive components.
  The primitive components with the same name are matched and belong to the same connection set.
\item
  The matched primitive components of the two connectors must have the same primitive types, and flow variables may only connect to other flow variables, stream variables only to other stream variables, and causal variables (\lstinline!input!/\lstinline!output!) only to causal variables (\lstinline!input!/\lstinline!output!).
\item
  A connection set of causal variables (\lstinline!input!/\lstinline!output!) may at most contain variables from one inside \lstinline!output! connector (for state-machines extended as specified in \cref{merging-connections-to-multiple-outputs}) or one public outside \lstinline!input! connector.
  \begin{nonnormative}
  I.e., a connection set may at most contain one source of a signal.
  \end{nonnormative}
\item
  At least one of the following must hold for a connection set containing causal variables generated for a non-partial model or block:
\begin{enumerate}
\item
  the connection set includes variables from an outside public expandable connector,
\item
  the set contains variables from protected outside connectors,
\item
  it contains variables from one inside \lstinline!output! connector, or
\item
  from one public outside \lstinline!input! connector, or
\item\label{enum:exc-conn-case}%
  the  set is comprised solely of one variable from one inside \lstinline!input! connector that is not part of an expandable connector.
\end{enumerate}
\begin{nonnormative}
I.e., a connection set must -- unless the model or block is partial -- contain one source of a signal (\cref{enum:exc-conn-case} covers the case where a connector of a component is left unconnected and the source given textually).
\end{nonnormative}
\item
  Variables from a protected outside connector must be part of a connection set containing at least one inside connector or one declared public outside connector (i.e.\ it shall not be an implicitly defined part of an expandable connector).
  \begin{nonnormative}
  Otherwise it would not be possible to deduce the causality for the expandable connector element.
  \end{nonnormative}
\item
  In a connection set all variables having non-empty quantity attribute must have the same quantity attribute.
\item
  A \lstinline!connect!-equation shall not (directly or indirectly) connect two connectors of \lstinline!outer! elements.
  \begin{nonnormative}
  Indirectly is similar to them being part of the same connection set.
  However, connections to \lstinline!outer! elements are ``moved up'' before forming connection sets.
  Otherwise the connection sets could contain redundant information breaking the equation count for locally balanced models and blocks.
  \end{nonnormative}
\item
  Subscripts in a connector reference shall be parameter expressions or the special operator \lstinline!:!.
\item
  Constants or parameters in connected components yield the appropriate \lstinline!assert!-statements to check that they have the same value; connections are not generated.
\item
  For conditional connectors, see \cref{conditional-component-declaration}.
\end{itemize}

\subsection{Balancing Restriction and Size of Connectors}\label{balancing-restriction-and-size-of-connectors}

For each non-partial non-expandable connector class the number of flow variables shall be equal to the number of variables that are neither \lstinline!parameter!, \lstinline!constant!, \lstinline!input!, \lstinline!output!, \lstinline!stream! nor \lstinline!flow!.
The \emph{number of variables} is the number of all elements in the connector class after expanding all records and arrays to a set of scalars of primitive types.
The number of variables of an overdetermined type or record class (see \cref{overconstrained-equation-operators-for-connection-graphs}) is the size of the output argument of the corresponding \lstinline!equalityConstraint!() function.
\begin{nonnormative}
Expandable connector classes are excluded from this, since their component declarations are only a form of constraint.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
connector Pin // A physical connector of Modelica.Electrical.Analog
  Real v;
  flow Real i;
end Pin;

connector Plug // A hierarchical connector of Modelica.Electrical.MultiPhase
  parameter Integer m = 3;
  Pin p[m];
end Plug;

connector InputReal = input Real; // A causal input connector
connector OutputReal = output Real; // A causal output connector

connector Frame_Illegal
  Modelica.Units.SI.Position r0[3] "Position vector of frame origin";
  Real S[3, 3] "Rotation matrix of frame";
  Modelica.Units.SI.Velocity v[3] "Abs. velocity of frame origin";
  Modelica.Units.SI.AngularVelocity w[3] "Abs. angular velocity of frame";
  Modelica.Units.SI.Acceleration a[3] "Abs. acc. of frame origin";
  Modelica.Units.SI.AngularAcceleration z[3] "Abs. angular acc. of frame";
  flow Modelica.Units.SI.Force f[3] "Cut force";
  flow Modelica.Units.SI.Torque t[3] "Cut torque";
end Frame_Illegal;
\end{lstlisting}

The \lstinline!Frame_Illegal! connector (intended to be used in a simple multi-body package without over-determined connectors) is illegal since the number of flow and non-flow variables do not match.
The solution is to create two connector classes, where two 3-vectors (e.g., \lstinline!a! and \lstinline!z!) are acausal \lstinline!Real! and the other variables are matching pairs of \lstinline!input! and \lstinline!output!.
This ensures that the models can only be connected in a tree-structure or require a ``loop-breaker'' joint for every closed kinematic loop:
\begin{lstlisting}[language=modelica]
connector Frame_a "correct connector"
  input Modelica.Units.SI.Position r0[3];
  input Real S[3, 3];
  input Modelica.Units.SI.Velocity v[3];
  input Modelica.Units.SI.AngularVelocity w[3];
  Modelica.Units.SI.Acceleration a[3];
  Modelica.Units.SI.AngularAcceleration z[3];
  flow Modelica.Units.SI.Force f[3];
  flow Modelica.Units.SI.Torque t[3];
end Frame_a;

connector Frame_b "correct connector"
  output Modelica.Units.SI.Position r0[3];
  output Real S[3, 3];
  output Modelica.Units.SI.Velocity v[3];
  output Modelica.Units.SI.AngularVelocity w[3];
  Modelica.Units.SI.Acceleration a[3];
  Modelica.Units.SI.AngularAcceleration z[3];
  flow Modelica.Units.SI.Force f[3];
  flow Modelica.Units.SI.Torque t[3];
end Frame_b;
\end{lstlisting}

The subsequent connectors \lstinline!Plug_Expanded! and \lstinline!PlugExpanded2! are correct, but \lstinline!Plug_Expanded_Illegal! is illegal since the number of non-flow and flow variables is different if \lstinline!n! and \lstinline!m! are different.
It is not clear how a tool can detect in general that connectors such as \lstinline!Plug_Expanded_Illegal! are illegal.
However, it is always possible to detect this defect after actual values of parameters and constants are provided in the simulation model.

\begin{lstlisting}[language=modelica]
connector Plug_Expanded "correct connector"
  parameter Integer m=3;
  Real v[m];
  flow Real i[m];
end Plug_Expanded;

connector Plug_Expanded2 "correct connector"
  parameter Integer m=3;
  final parameter Integer n=m;
  Real v[m];
  flow Real i[n];
end Plug_Expanded2;

connector Plug_Expanded_Illegal "connector is illegal"
  parameter Integer m=3;
  parameter Integer n=m;
  Real v[m];
  flow Real i[n];
end Plug_Expanded_Illegal;
\end{lstlisting}
\end{example}

\section{Overconstrained Connections}\label{equation-operators-for-overconstrained-connection-based-equation-systems1}\label{overconstrained-connections}

There is a special problem regarding equation systems resulting from \emph{loops} in connection graphs where the connectors contain \emph{non-flow} (i.e., potential) variables \emph{dependent} on each other.
When a loop structure occurs in such a graph, the resulting equation system will be \emph{overconstrained}, i.e., have more equations than variables, since there are implicit constraints between certain non-flow variables in the connector in addition to the connection equations around the loop.
At the current state-of-the-art, it is not possible to automatically eliminate the unneeded equations from the resulting equation system without additional information from the model designer.

This section describes a set of equation operators for such overconstrained connection-based equation systems, that makes it possible for the model designer to specify enough information in the model to allow a Modelica environment to automatically remove the superfluous equations.

\begin{nonnormative}
Connectors may contain redundant variables.
For example, the orientation between two coordinate systems in $3$ dimensions can be described by $3$ independent variables.
However, every description of orientation with $3$ variables has at least one singularity in the region where the variables are defined.
It is therefore not possible to declare only $3$ variables in a connector.
Instead $n$ variables ($n > 3$) have to be used.
These variables are no longer independent from each other and there are $n - 3$ constraint equations that have to be fulfilled.
A proper description of a redundant set of variables with constraint equations does no longer have a singularity.
A model that has loops in the connection structure formed by components and connectors with redundant variables, may lead to a differential algebraic equation system that has more equations than unknown variables.
The superfluous equations are usually consistent with the rest of the equations, i.e., a unique mathematical solution exists.
Such models cannot be treated with the currently known symbolic transformation methods.
To overcome this situation, operators are defined in order that a Modelica translator can remove the superfluous equations.
This is performed by replacing the equality equations of non-flow variables from connection sets by a reduced number of equations in certain situations.

This section handles a certain class of overdetermined systems due to connectors that have a redundant set of variables.
There are other causes of overdetermined systems, e.g., explicit zero-sum equations for flow variables, that are not handled by the method described below.
\end{nonnormative}

\subsection{Connection Graphs and Their Operators}\label{overconstrained-equation-operators-for-connection-graphs}\label{connection-graphs-and-their-operators}

A type or record declaration may have an optional definition of function \lstinline!equalityConstraint!\indexinline{equalityConstraint} that shall have the following prototype:
% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
% - https://github.com/brucemiller/LaTeXML/issues/1477
% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
\begin{lstlisting}[language=modelica]
type Type // overdetermined type
  extends $\langle$$\mbox{\emph{base type}}$$\rangle$;
  function equalityConstraint // non-redundant equality
    input Type T1;
    input Type T2;
    output Real residue[$n$];
  algorithm
    residue := $\ldots$;
  end equalityConstraint;
end Type;

record Record
  $\langle$$\mbox{\emph{declaration of record fields}}$$\rangle$;
  function equalityConstraint // non-redundant equality
    input Record R1;
    input Record R2;
    output Real residue[$n$];
  algorithm
    residue := $\ldots$;
  end equalityConstraint;
end Record;
\end{lstlisting}
The array dimension $n$ of \lstinline!residue! shall be a constant \lstinline!Integer! expression that can be evaluated during translation, with $n \geq 0$.
The \lstinline!equalityConstraint! expresses the equality between the two type instances \lstinline!T1! and \lstinline!T2! or the record instances \lstinline!R1! and \lstinline!R2!, respectively, as the $n$ non-redundant equation residuals returned in \lstinline!residue!.
That is, the set of $n$ non-redundant equations stating that \lstinline!R1 = R2! is given by the equation (%
% Just a '0' doesn't work in \lstinline as reported in (closed as fixed on 2021-09-07):
% - https://github.com/brucemiller/LaTeXML/issues/1651 -- fixed on 'master'
\ifpdf
\lstinline!0!
\else
0
\fi
represents a vector of zeros of appropriate size):
\begin{lstlisting}[language=modelica]
  Record R1, R2;
equation
  0 = Record.equalityConstraint(R1, R2);
\end{lstlisting}
\begin{nonnormative}
If the elements of a record \lstinline!Record! are not independent from each other, the equation \lstinline!R1 = R2! contains redundant equations.
\end{nonnormative}

A type class with an \lstinline!equalityConstraint! function declaration is called \firstuse[overdetermined!type]{overdetermined type}.
A record class with an \lstinline!equalityConstraint! function definition is called \firstuse[overdetermined!record]{overdetermined record}.
A connector that contains instances of overdetermined type and/or record classes is called \firstuse[overdetermined!connector]{overdetermined connector}.
An overdetermined type or record may neither have flow components nor may be used as a type of flow components.
If an array is used as argument to any of the \lstinline!Connections.*! functions it is treated as one unit -- unlike \lstinline!connect!, there is no special treatment of this case, compare \cref{connect-equations-and-connectors}.

Every instance of an overdetermined type or record in an overdetermined connector is a node in a virtual connection graph that is used to determine when the standard equation \lstinline!R1 = R2! or when the equation \lstinline!0 = equalityConstraint(R1, R2)! has to be used for the generation of \lstinline!connect!-equations.
The edges of the virtual connection graph are implicitly defined by \lstinline!connect! and explicitly by \lstinline!Connections.branch!, see table below.
\lstinline!Connections! is a built-in package in global scope containing built-in operators.
Additionally, corresponding nodes of the virtual connection graph have to be defined as roots or as potential roots with functions \lstinline!Connections.root! and \lstinline!Connections.potentialRoot!, respectively.

The overconstrained equation operators for connection graphs are listed below.
Here, \lstinline!A! and \lstinline!B! are connector instances that may be hierarchically structured, e.g., \lstinline!A! may be an abbreviation for \lstinline!EnginePort.Frame!.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
\lstinline!connect(A, B)! & Optional spanning-tree edge & \Cref{modelica:optional-spanning-tree-edge}\\
\lstinline!Connections.branch(A.R, B.R)! & Required spanning-tree edge & \Cref{modelica:Connections.branch}\\
\lstinline!Connections.root(A.R)! & Definite root node & \Cref{modelica:Connections.root}\\
\lstinline!Connections.potentialRoot(A.R, $\ldots$)! & Potential root node & \Cref{modelica:Connections.potentialRoot}\\
\lstinline!Connections.isRoot(A.R)! & Predicate for being selected as root & \Cref{modelica:Connections.isRoot}\\
\lstinline!Connections.rooted(A.R)! & Predicate for being closer to root & \Cref{modelica:Connections.rooted}\\
\hline
\end{tabular}
\end{center}

\begin{operatordefinition*}[connect]\label{modelica:optional-spanning-tree-edge}\index{connect@\robustinline{connect}!overconstrained equation operator}
\begin{synopsis}\begin{lstlisting}
connect(A, B)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Defines \firstuse{optional spanning-tree edge} from the overdetermined type or record instances in connector instance \lstinline!A! to the corresponding overdetermined type or record instances in connector instance \lstinline!B! for a virtual connection graph.
The types of the corresponding overdetermined type or record instances shall be the same.
\end{semantics}
\end{operatordefinition*}

\begin{operatordefinition}[Connections.branch]
\begin{synopsis}\begin{lstlisting}
Connections.branch(A.R, B.R)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Defines a \firstuse{required spanning-tree edge} from the overdetermined type or record instance \lstinline!R! in connector instance \lstinline!A! to the corresponding overdetermined type or record instance \lstinline!R! in connector instance \lstinline!B! for a virtual connection graph.
This function can be used at all places where a \lstinline!connect!-equation is allowed.

\begin{nonnormative}
% TODO: Can't have angle brackets and \emph in the same mathescape due to LaTeXML issue:
% - https://github.com/brucemiller/LaTeXML/issues/1477
% Once we cut the MathJax dependency, change to single mathescape for better character spacing.
E.g., it is not allowed to use this function in a \lstinline!when!-clause.
This definition shall be used if in a model with connectors \lstinline!A! and \lstinline!B! the overdetermined records \lstinline!A.R! and \lstinline!B.R! are algebraically coupled in the model, e.g., due to \lstinline!B.R = f(A.R, $\langle$$\mbox{\emph{other unknowns}}$$\rangle$)!.
\end{nonnormative}
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[Connections.root]
\begin{synopsis}\begin{lstlisting}
Connections.root(A.R)
\end{lstlisting}\end{synopsis}
\begin{semantics}
The overdetermined type or record instance \lstinline!R! in connector instance \lstinline!A! is a \firstuse[definite root node]{(definite) root node}\index{root node!definite} in a virtual connection graph.

\begin{nonnormative}
This definition shall be used if in a model with connector \lstinline!A! the overdetermined record \lstinline!A.R! is (consistently) assigned, e.g., from a parameter expressions.
\end{nonnormative}
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[Connections.potentialRoot]
\begin{synopsis}\begin{lstlisting}
Connections.potentialRoot(A.R)
Connections.potentialRoot(A.R, priority=$p$)
\end{lstlisting}\end{synopsis}
\begin{semantics}
The overdetermined type or record instance \lstinline!R! in connector instance \lstinline!A! is a \firstuse{potential root node}\index{root node!potential} in a virtual connection graph with priority \lstinline!p! ($p \geq 0$).
If no second argument is provided, the priority is zero.
\lstinline!p! shall be a parameter expression of type \lstinline!Integer!.
In a virtual connection subgraph without a \lstinline!Connections.root! definition, one of the potential roots with the lowest priority number is selected as root.

\begin{nonnormative}
This definition may be used if in a model with connector \lstinline!A! the overdetermined record \lstinline!A.R! appears differentiated -- \lstinline!der(A.R)! -- together with the \emph{constraint equations} of \lstinline!A.R!, i.e., a non-redundant subset of \lstinline!A.R! maybe used as states.
\end{nonnormative}
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[Connections.isRoot]
\begin{synopsis}\begin{lstlisting}
Connections.isRoot(A.R)
\end{lstlisting}\end{synopsis}
\begin{semantics}
Returns true, if the overdetermined type or record instance \lstinline!R! in connector instance \lstinline!A! is selected as a root in the virtual connection graph.
\end{semantics}
\end{operatordefinition}

\begin{operatordefinition}[Connections.rooted]
\begin{synopsis}\begin{lstlisting}
Connections.rooted(A.R)
rooted(A.R) // deprecated!
\end{lstlisting}\end{synopsis}
\begin{semantics}
If the operator \lstinline!Connections.rooted(A.R)! is used, or the equivalent but deprecated operator \lstinline!rooted(A.R)!, then there must be exactly one \lstinline!Connections.branch(A.R, B.R)! involving \lstinline!A.R! (the argument of \lstinline!Connections.rooted! must be the first argument of \lstinline!Connections.branch!).
In that case \lstinline!Connections.rooted(A.R)! returns true, if \lstinline!A.R! is closer to the root of the spanning tree than \lstinline!B.R!; otherwise false is returned.

\begin{nonnormative}
This operator can be used to avoid equation systems by providing analytic inverses, see\linebreak[4] \lstinline!Modelica.Mechanics.MultiBody.Parts.FixedRotation!.
\end{nonnormative}
\end{semantics}
\end{operatordefinition}

\begin{nonnormative}
Note, that \lstinline!Connections.branch!, \lstinline!Connections.root!, \lstinline!Connections.potentialRoot! do not generate equations.
They only generate nodes and edges in the virtual graph for analysis purposes.
\end{nonnormative}


\subsection{Generation of Connection Graph Equations}\label{generation-of-connection-graph-equations}

Before connection equations are generated, the virtual connection graph is transformed into a set of spanning trees by removing optional spanning tree edges from the graph.
This is performed in the following way:
\begin{enumerate}
\item
  Every root node defined via the \lstinline!Connections.root!-equation is a definite root of one spanning tree.
\item
  The virtual connection graph may consist of sets of subgraphs that are not connected together.
  Every subgraph in this set shall have at least one root node or one potential root node in a simulation model.
  If a graph of this set does not contain any root node, then one potential root node in this subgraph that has the lowest priority number is selected to be the root of that subgraph.
  The selection can be inquired in a class with function \lstinline!Connections.isRoot!, see table above.
\item
  If there are n selected roots in a subgraph, then optional spanning-tree edges have to be removed such that the result shall be a set of n spanning trees with the selected root nodes as roots.
\end{enumerate}

After this analysis, the \firstuse[connection equations!overconstrained]{connection equations} are generated in the following way:
\begin{enumerate}
\item
  For every optional spanning-tree edge (i.e., a \lstinline!connect(A, B)! equation), in one of the spanning trees, the connection equations are generated according to \cref{generation-of-connection-equations}.
\item
  For every optional spanning-tree edge not in any of the spanning trees, the connection equations are generated according to \cref{generation-of-connection-equations}, except for overdetermined type or record instances \lstinline!R!.
  Here the equations \lstinline!0 = R.equalityConstraint(A.R, B.R)! are generated instead of \lstinline!A.R = B.R!.
\end{enumerate}

\subsection{Examples}\label{examples-of-overconstrained-connectors}

\begin{example}
\begin{figure}[H]
  \begin{center}
    \includegraphics{overdetermined}
  \end{center}
  \caption{Example of a virtual connection graph.}
\end{figure}
\end{example}

\subsubsection{A Power Systems Overdetermined Connector}\label{an-overdetermined-connector-for-power-systems}\label{a-power-systems-overdetermined-connector}

\begin{nonnormative}
An overdetermined connector for power systems based on the transformation theory of Park may be defined as:
\begin{lstlisting}[language=modelica]
type AC_Angle "Angle of source, e.g., rotor of generator"
  extends Modelica.Units.SI.Angle; // AC_Angle is a Real number
  // with unit = "rad"
  function equalityConstraint
    input AC_Angle theta1;
    input AC_Angle theta2;
    output Real residue[0] "No constraints";
  algorithm
    /* make sure that theta1 and theta2 from joining edges are identical */
    assert(abs(theta1 - theta2) < 1.e-10, "Consistent angles");
  end equalityConstraint;
end AC_Angle;

connector AC_Plug "3-phase alternating current connector"
  import Modelica.Units.SI;
  AC_Angle theta;
  SI.Voltage v[3] "Voltages resolved in AC_Angle frame";
  flow SI.Current i[3] "Currents resolved in AC_Angle frame";
end AC_Plug;
\end{lstlisting}
The currents and voltages in the connector are defined relatively to the harmonic, high-frequency signal of a power source that is essentially described by angle theta of the rotor of the source.
This allows much faster simulations, since the basic high frequency signal of the power source is not part of the differential equations.
For example, when the source and the rest of the line operates with constant frequency (= nominal case), then \lstinline!AC_Plug.v! and \lstinline!AC_Plug.i! are constant.
In this case a variable step integrator can select large time steps.
An element, such as a 3-phase inductor, may be implemented as:
\begin{lstlisting}[language=modelica]
model AC_Inductor
  parameter Real X[3,3], Y[3,3]; // component constants
  AC_Plug p;
  AC_Plug n;
  Real omega;
equation
  Connections.branch(p.theta,n.theta); //edge in virtual graph
  // since n.theta = p.theta
  n.theta = p.theta; // pass angle theta between plugs
  omega = der(p.theta); // frequency of source
  zeros(3) = p.i + n.i;
  X*der(p.i) + omega*Y*p.i = p.v - n.v;
end AC_Inductor
\end{lstlisting}
At the place where the source frequency, i.e., essentially variable theta, is defined, a \lstinline!Connections.root! must be present:
\begin{lstlisting}[language=modelica]
  AC_Plug p;
equation
  Connections.root(p.theta);
  der(p.theta) = 2*Modelica.Constants.pi*50 // 50 Hz;
\end{lstlisting}
The graph analysis performed with the virtual connection graph identifies the connectors, where the \lstinline!AC_Angle! needs not to be passed between components, in order to avoid redundant equations.
\end{nonnormative}

\subsubsection{A 3-Dimensional Mechanical Systems Overdetermined Connector}\label{an-overdetermined-connector-for-3-dimensional-mechanical-systems}\label{a-3-dimensional-mechanical-systems-overdetermined-connector}

\begin{nonnormative}
An overdetermined connector for 3-dimensional mechanical systems may be defined as:
\begin{lstlisting}[language=modelica]
type TransformationMatrix = Real[3,3];
type Orientation "Orientation from frame 1 to frame 2"
  extends TransformationMatrix;
  function equalityConstraint
    input Orientation R1 "Rotation from inertial frame to frame 1";
    input Orientation R2 "Rotation from inertial frame to frame 2";
    output Real residue[3];
    protected
    Orientation R_rel "Relative Rotation from frame 1 to frame 2";
  algorithm
    R_rel := R2*transpose(R1);
    /*
      If frame_1 and frame_2 are identical, R_rel must be
      the unit matrix. If they are close together, R_rel can be
      linearized yielding:
        R_rel = [ 1, phi3, -phi2;
        -phi3, 1, phi1;
        phi2, -phi1, 1 ];
      where phi1, phi2, phi3 are the small rotation angles around
      axis x, y, z of frame 1 to rotate frame 1 into frame 2.
      The atan2 is used to handle large rotation angles, but does not
      modify the result for small angles.
    */
    residue := { Modelica.Math.atan2(R_rel[2, 3], R_rel[1, 1]),
    Modelica.Math.atan2(R_rel[3, 1], R_rel[2, 2]),
    Modelica.Math.atan2(R_rel[1, 2], R_rel[3, 3])};
  end equalityConstraint;
end Orientation;

connector Frame "3-dimensional mechanical connector"
  import Modelica.Units.SI;
  SI.Position r[3] "Vector from inertial frame to Frame";
  Orientation R "Orientation from inertial frame to Frame";
  flow SI.Force f[3] "Cut-force resolved in Frame";
  flow SI.Torque t[3] "Cut-torque resolved in Frame";
end Frame;
\end{lstlisting}
A fixed translation from a frame \lstinline!A! to a frame \lstinline!B! may be defined as:
\begin{lstlisting}[language=modelica]
model FixedTranslation
  parameter Modelica.Units.SI.Position r[3];
  Frame frame_a, frame_b;
equation
  Connections.branch(frame_a.R, frame_b.R);
  frame_b.r = frame_a.r + transpose(frame_a.R)*r;
  frame_b.R = frame_a.R;
  zeros(3) = frame_a.f + frame_b.f;
  zeros(3) = frame_a.t + frame_b.t + cross(r, frame_b.f);
end FixedTranslation;
\end{lstlisting}
Since the transformation matrix \lstinline!frame_a.R! is algebraically coupled with \lstinline!frame_b.R!, an edge in the virtual connection graph has to be defined.
At the inertial system, the orientation is consistently initialized and therefore the orientation in the inertial system connector has to be defined as root:
\begin{lstlisting}[language=modelica]
model InertialSystem
  Frame frame_b;
equation
  Connections.root(frame_b.R);
  frame_b.r = zeros(3);
  frame_b.R = identity(3);
end InertialSystem;
\end{lstlisting}
\end{nonnormative}