The Seam Is the System: A Pre-Run Audit for Co-Simulation Interfaces

Co-simulation is often treated as a wiring exercise: connect the plant model to the controller, select a communication step, and press run. The first time step usually corrects that impression. A model that behaves well in isolation can fail at the seam because an output was declared as an input, a sign convention was reversed between owners, or the communication interval quietly filtered the dynamics that mattered. These are not solver bugs. They are interface defects, and they deserve the same review discipline as a bracket or a control law.

The interface is a design deliverable

In a single-tool simulation, the model boundary is usually clear because one team owns the whole graph. In co-simulation, the boundary becomes a negotiated surface between models, tools, and often organizations. The plant model may come from a supplier, the controller from an internal controls group, and the environment from a third party. Each model can pass its own checks and still fail when connected because the coupling contract was never written down, let alone reviewed.

Treat the coupling interface as a controlled document. It should name every connection, its direction, its unit, its sign convention, its valid range, and its initialization behavior. It should also record the tool versions, the FMI version if FMUs are involved, the communication step size, and the owner of each side. Without that record, the first integration run becomes an investigation rather than a verification.

Causality: declarations are not suggestions

FMI makes causality explicit for a reason. An output is computed by the model; an input is supplied to it; a parameter is fixed for the run. A common failure is a variable that was designed as an output but connected as an input because the names looked plausible. The connection may compile and even run, but the model is now receiving a value it was supposed to produce.

Audit causality and variability together. Check that every connected input is actually declared as an input, that every connected output is declared as an output, and that parameters are not being driven by time-varying signals. For custom couplings, write the equivalent declaration in the interface document. The goal is not bureaucratic completeness; it is to prevent a model from silently reinterpretiing its own role.

Initialization is an ordered negotiation

Co-simulation initialization is not a formality. At time zero, each model needs a consistent state, defined inputs, and a known set of algebraic variables. If one model initializes before its input is available, it may hold a default that never gets corrected. If two models initialize simultaneously and each expects the other to provide a boundary value, the run may start from an inconsistent point and never recover.

Define the initialization order explicitly. State which model initializes first, which values are fixed at t=0, and how algebraic loops at the boundary are resolved. For FMU-based couplings, verify that the master algorithm honors the declared initialization sequence and that input values are set before the first communication step. Record any default values that persist when a signal is absent; defaults are legitimate, but they should be visible.

Variable roles, units, and the quiet incompatibilities

Units are a classic source of co-simulation error because they are easy to convert incorrectly and hard to see in a connection diagram. A torque in newton-meters connected to a model expecting pound-feet will produce a plausible but wrong response. The same applies to pressure, flow, current, and angular velocity. Audit units at the interface, not just inside each model.

Variable roles matter as well. A signal may be an input, an output, a parameter, or a local variable that should never cross the boundary. The interface document should state the role of every connected variable and the expected physical meaning. When a connection crosses domains—mechanical to electrical, hydraulic to thermal—the document should also state the power or signal convention used for the exchange.

Sign conventions: the most expensive minus sign

The sign convention is where co-simulation interfaces most often fail in ways that look like physics. A force may be positive in tension for one model and positive in compression for another. A motor torque may be positive in the driving direction for the controller and positive in the opposing direction for the plant. A flow may be defined into a volume for one model and out of it for the other.

These are not cosmetic differences. They change the feedback path. A reversed sign can turn a stable controller into an unstable one, or make a plant appear to have negative damping. Put the positive direction for every exchanged quantity in the interface document. Where possible, include a simple sign-check test: apply a known positive input, observe the expected output direction, and record the result in the model package.

Step size is a modeling decision

The communication step size is not just a performance setting. It determines how often the models exchange information, and therefore which dynamics can pass through the coupling. If the communication interval is long relative to a fast mode, the coupling will alias that mode or miss it entirely. The result may be stable but wrong, which is worse than an obvious divergence.

Justify the communication step against the fastest dynamic that must be represented and the fastest event rate that must be captured. Distinguish the solver step from the communication step; a fine internal solver step does not compensate for a coarse exchange interval. For event-driven models, define how events are communicated and whether the master algorithm can roll back or re-synchronize. Document the chosen step size and the reasoning behind it so that a later change is a reviewed decision rather than an experiment.

A checklist for the model package

Attach the following to the co-simulation model package before the first integration run:

• Interface control document with every connection, direction, unit, sign, range, and default value.
• Causality and variability declarations checked against actual use for every FMU variable.
• Explicit initialization order, including t=0 input values and boundary algebraic-loop handling.
• Sign convention statement for each exchanged physical quantity, with a simple sign-check result.
• Communication step size justified against the fastest relevant dynamics and event rate.
• Solver step and communication step recorded separately.
• Tool versions, FMI version, and platform assumptions recorded.
• Event handling and rollback behavior defined for the master algorithm.
• Regression test that exercises the interface at a known operating point.
• Named owner for each side of the coupling and a review date.

Make the contract enforceable

A checklist is useful only if it has a gate. Put the interface review before the first integration run, not after the first failed one. Keep the interface document under configuration control so that a change in step size or sign convention is visible to both model owners. Where possible, automate the mechanical checks: variable causality, unit compatibility, connection completeness, and version matching. Then run a short interface regression test whenever either model changes.

The seam is part of the system. When it is treated as a contract, co-simulation becomes easier to debug because the boundary is no longer a mystery. The first time step stops being a surprise and starts being a verification.