# Model interfaces

When defining your model interfaces, it is wise to stick to certain conventions that ensure that your model can be easily used by other people, and coupled with other models, possibly in other simulation tools than the one you use. Such conventions include what variable types and units to use, especially for input and output values but also for parameters, as well as variable names and several other things. Model coupling is hard enough in itself, even without the added complications and extra work associated with ensuring that the output variables of one model are compatible with the input variables of the model you want to connect it with. Coupling conventions could even have an effect on the accuracy and stability of the simulations.

In this article, we provide some recommendations and guidelines for coupling of variables and, more generally, design of model interfaces. Other articles on this site go into more detail about specific domains and subsystems commonly involved in maritime simulations.

## Ground rules

There are a few basic guidelines that should always be followed, regardless of the model and the purpose for which it is created. Some of these look suspiciously similar to general software development guidelines, which should come as no surprise, considering that models are just highly specialised pieces of software.

**Use FMI and package your models as FMUs**. This way, your users are not forced to use the same simulation tools as you, but are free to use their preferred software and to freely combine your models with others.**Use standard units of measurement.**For the majority of cases, it is strongly recommended to use SI units, without prefixes such as “kilo-”, “micro-” and so on. Do not worry about whether the values the user will see on the screen are very large or very small; it should be the responsibility of the simulation software to scale/convert them to “user-friendly” units and values for display and editing purposes. (FMI also lets you specify the “display units” for your variables, which may be different from the units of the values that are passed between subsystems.) That said, there are certain domains and highly specialised applications where the principle of least astonishment dictates that other units be used, and then the next rule becomes very important.**Document your interfaces.**Provide a description of what each variable is, how it should be used, the units in which it is measured, whether there are limitations on its value, what its default/initial value is, and whether it has any non-obvious dependencies on other variables. FMI lets you put this information directly inside the FMU's model description file, in a structured form that allows the information to be interpreted and used by simulation software too, so it's not just for the benefit of human users.**Use clear, understandable variable names.**Avoid cryptic abbreviations, and do not assume that your users have a deep knowledge of the scientific context in which the model was made. There is generally little need to worry about the length of variable names; your users won't be writing them by hand most of the time anyway. They will be*reading*them, however, so make that as easy as possible. Example: If a variable represents angular velocity, calling it`angular_velocity`

(or`AngularVelocity`

or whichever convention you prefer) is usually vastly preferable to calling it`angvel`

or`omega`

or somesuch.

## 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.

The idea of power bonds comes from *bond graph theory*,
[1][2]
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.
[3]
There are also some online resources which may be informative:

### 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. Since this site champions a different convention, it's only appropriate to explain 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.
[4]
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. [5]

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
[6]
which differs by a constant factor of $\sqrt{2/3}$ and is not power invariant.)

## Specific domains

Coupling conventions are sometimes highly domain-dependent, and this site contains some articles that give more specific advice on domains and subsystems commonly involved in maritime simulations. These are:

- Hydrodynamic systems, such as ships' hulls, propellers, rudders, thrusters and so on.
- Power systems, including engines, generators and other power conversion and distribution components.
- Environment modelling, which describes how different subsystems can share the same virtual environment (waves, wind, currents, etc.)

^{↑}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.

^{↑}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.