# Model interfaces

In order to ensure interoperability, modularity and re-use between different models/simulators, well-defined interfaces are needed. Such simulator interfaces are a set of conventions that, if adhered to, allow a model/simulator to be coupled with other models/simulators using some simulation tool. Here, we will distinguish between *low-level interfaces*, by which we mean the interfaces between different software modules, and *high-level interfaces*, which relate to the physical phenomena and systems being modelled. This article describes different types of interfaces and gives some general recommendations.

## Low-level interfaces

A low-level interface concerns itself with the details exchange of information between different software modules. This typically includes communications protocols, application programming interfaces (APIs) and application binary interfaces. At this level, we are not concerned about the physical interpretation of the data that is being exchanged; it is all bits and bytes that need to get from one place to another.

There is much to say about this topic, but we'll keep it short. Most simulation interfaces are proprietary and tool-specific. One, however, stands out as being open and freely usable, as well as vendor and software neutral: FMI. Therefore, we strongly recommend its use.

## High-level interfaces

### Energy transfer

For connections that represent some kind of energy transfer from one system to another, such as the mechanical energy transferred by a rotating driveshaft or the electrical energy transferred by a power cable, we recommend the use of *power bonds*.

A power bond between two subsystems A and B consists of two variable couplings, where one represents an *effort*, and the other represents a *flow*. For an electrical connection, for example, the effort is the electromotive force (i.e., voltage) while the flow is the current. The two couplings are oppositely directed, meaning that if A has effort as an output variable, then it has flow as an input variable, while they must be the other way around for B. This is illustrated in the figure on the right.

Normally, the product of an effort and a flow has units of *power* (watt) and is a direct measure of the power that is transferred between the two subsystems. This makes it very easy to keep track of the energy flow through the system, to see where energy is produced and dissipated, and to locate violations of energy conservation. (If nothing else, this can be useful for debugging model code.) This feature is employed to good effect in the ECCO method.

The following table shows the standard definitions and units for different energy domains:

Energy domain | Effort | Effort units | Flow | Flow units |
---|---|---|---|---|

Mechanical (translation) | Force | N | Linear velocity | m/s |

Mechanical (rotation) | Torque | Nm | Angular velocity | rad/s |

Electrical | Electromotive force | V | Current | A |

Hydraulic | Pressure | Pa | Volumetric flow rate | m^{3}/s |

Thermal | Temperature | K | Entropy flow rate | W/K |

The figure below shows a simplified diesel-electric propulsion system, and illustrates how different energy domains can be seamlessly connected through power bonds in a simulation:

Some physical connections may be represented by multiple power bonds. The most straightforward example is probably a force acting on a body in three dimensions, which can be represented with one mechanical power bond for each spatial dimension.

#### Force-position coupling

Today, the most common way to model a force acting on some body is through a *force-position* coupling; that is, one model outputs a force while the other model outputs its position. This site champions a different convention, and here's why:

A force-position coupling between subsystems A and B works well enough if A only needs to know B's position. However, if A needs B's *velocity*, it has to differentiate the position, and numerical differentiation is notoriously inaccurate and hard to get right
[1].
Numerical integration, on the other hand, is less susceptible to errors, so it makes sense to output the highest-order derivative that is likely to be needed in other subsystems, which is normally the velocity. Of course, the best course of action for the author of model B is to supply *both* position and velocity as outputs, so it can be coupled in either way.

The above also holds for rotational systems, which can be realised as torque–angular velocity or as torque–angle. Here, of course, we have the added complication that the angle is periodic, so that an angle $\theta$ is equivalent to $\theta + 2 \pi n$ for n=1,2,3,\ldots$.

#### 3-phase electrical connections

For DC or single-phase AC connections, a power bond is realised with voltage as the effort variable and current as the flow variable. This can be trivially extended to 3-phase AC connections, which can simply be modeled as three single-phase connections—that is, as 3 effort variables and 3 flow variables corresponding to the voltages and currents in the 3 phases, respectively.

We then use what is called a *stationary* reference frame. For 3-phase systems, a common alternative is to use a *rotating* reference frame, as this simplifies some models. The transformation from the stationary frame to the rotating frame is called the direct-quadrature-zero transformation, or *dq0* for short. Assuming a balanced system, this transformation has the effect of reducing the three AC signals to two DC signals. However, it requires that the phase angle be sent along with the two voltages, as shown in the figure on the right.

The transform applied to time-domain voltages in the ABC frame is \begin{equation} \begin{bmatrix} u_d \\ u_q \\ u_0 \end{bmatrix} = \sqrt{\frac{2}{3}} \begin{bmatrix} \cos(\theta) && \cos(\theta - \frac{2\pi}{3}) && \cos(\theta + \frac{2\pi}{3}) \\ -\sin(\theta) && -\sin(\theta - \frac{2\pi}{3}) && -\sin(\theta + \frac{2\pi}{3}) \\ \frac{1}{\sqrt{2}} && \frac{1}{\sqrt{2}} && \frac{1}{\sqrt{2}} \end{bmatrix} \begin{bmatrix} u_a \\ u_b \\ u_c \end{bmatrix}, \end{equation} where $\theta = \omega t + \delta$ is the angle between the rotating and fixed coordinate system and $\delta$ is the initial phase shift [2].

In a balanced system, $u_0$ will be zero. The reverse transform, from the dq0 frame to the ABC frame, is:
\begin{equation}
\begin{bmatrix} u_a \\ u_b \\ u_c \end{bmatrix}
= \sqrt{\frac{2}{3}} \begin{bmatrix}
\cos(\theta) && -\sin(\theta) && \frac{1}{\sqrt{2}} \\
\cos(\theta - \frac{2\pi}{3}) && -\sin(\theta - \frac{2\pi}{3}) && \frac{1}{\sqrt{2}} \\
\cos(\theta + \frac{2\pi}{3}) && -\sin(\theta + \frac{2\pi}{3}) && \frac{1}{\sqrt{2}} \end{bmatrix}
\begin{bmatrix} u_d \\ u_q \\ u_0 \end{bmatrix}
\end{equation}
(Note: This is the *power invariant* form of the transformation matrices, which we recommend for use in modular model couplings. There are other variants, most notably the original formulation by Park
[3]
which differs by a constant factor of $\sqrt{2/3}$ and is not power invariant.)

#### Bond graph theory

The idea of power bonds comes from *bond graph theory*,
[4][5]
which is a method for representing dynamic systems graphically, and for systematic derivation of system equations from the graphs. A proper introduction to formal bond graph theory is beyond the scope of this article, and one can make efficient use of power bonds in simulations without a full understanding of the theory. However, for those who are interested in learning more, we recommend the book by Karnopp et al.
[6].
There are also some online resources which may be informative:

^{↑}William H. Press; Saul A. Teukolsky; William T. Vetterling; Brian P. Flannery, 2002.

*Numerical recipes in C++: The art of scientific computing.*2nd edition. Cambridge University Press, ISBN 0-521-75033-4.

^{↑}H. M. Paynter, 1961.

*Analysis and design of engineering systems: Class notes for M.I.T. course 2.751.*M.I.T. Press, Boston.

^{↑}Dean C. Karnopp; Donald L. Margolis; Ronald C. Rosenberg, 2012.

*System dynamics: Modeling, simulation and control of mechatronic systems.*5th edition. John Wiley & Sons, Inc., Hoboken, New Jersey, ISBN 978-0-470-88908-4.