Appendix E. Physics-aware Simulation Reference

This appendix is the reference for modelling continuous and hybrid behaviour in SysML v2: which language constructs carry physical meaning, what the standard library defines for them, and where the spec ends and a particular runtime begins. The solver machinery that executes these models – integrators, differential-algebraic assembly, numerical mechanics – is product territory and lives in the sysml-rs portal’s runtime documentation; this appendix keeps the language story.

Scope tags. Each section is tagged [SPEC] or [EXTENSION] so you can tell the spec story from the sysml-rs story at a glance. The headline rule: the modelling pattern (specialise GetDerivative, type ports with ISQ::* quantities, write conservation as assert constraint) is spec language. The runtime mechanism that turns the pattern into a numerically integrated trajectory is a sysml-rs extension, and other SysML v2 implementations may execute the same model differently or not at all.

E.1 The state-space representation pattern – [SPEC]

The State-Space Representation (SSR) pattern is how SysML v2 models continuous dynamics. There are three modelling moves; all three are pure spec:

calc def HeaterRhs :> GetDerivative {
    in t : Real; in temp : Real;
    in heaterPower : Real; in ambientTemp : Real;
    attribute heatLossCoeff : Real := 0.2;
    attribute thermalMass : Real := 4180.0;
    return dT_dt = (heaterPower - heatLossCoeff * (temp - ambientTemp))
                   / thermalMass;
}

calc def BrewerReady :> GetOutput {
    in temp : Real;
    return ready : Boolean = temp >= 90.0 and temp <= 96.0;
}

action def BrewerDynamics :> ContinuousStateSpaceDynamics {
    in brewer : Brewer;
    action stateEqs : HeaterRhs {
        in t = simulationTime;
        in temp = brewer.waterTemp;
        in heaterPower = brewer.heaterPower;
        in ambientTemp = 20.0;
    }
}

GetDerivative, GetOutput, and ContinuousStateSpaceDynamics are defined in the standard library’s StateSpaceRepresentation domain package, so that is the package to import when you specialise them. (AnalysisTooling is a different domain package: it defines the ToolExecution and ToolVariable metadata, including the toolName attribute a model can use to request a particular analysis tool.) The author specialises the patterns; a runtime detects the specialisation and wires the integration. A spec-faithful SSR model can be picked up by any conformant runtime.

A note on what’s gone. Earlier sysml-rs material used non-spec metadata fields (@ToolVariable { derivative = "..." }, @ToolExecution { signal = "..." }) to declare ODE structure. Those fields have been removed. @ToolExecution { toolName = ... } remains, because toolName is the spec-defined attribute from AnalysisTooling; sysml-rs reads it as solver-selection metadata. Old models carrying the removed fields should be rewritten using the SSR pattern above.

E.2 Hybrid models: states with continuous behaviour – [SPEC] pattern, [EXTENSION] execution

A hybrid model is a state machine whose states each select different continuous dynamics – boilers, bouncing balls, valves, and clutches all evolve continuously and jump discretely at thresholds. The modelling recipe is spec language end to end:

1. Write a state machine with named states (Heating, Idle, Falling, Rising).
2. Write one calc def :> GetDerivative per state.
3. Write transitions whose triggers mention the continuously-varying values (accept when temp >= 100.0).

Worked snippet (the bouncing ball, condensed from the workspace’s examples/bouncing-ball/):

state def BallMode {
    state Falling;
    state Rising;
    transition first Falling accept when y <= 0.0 and v < 0.0 then Rising;
    transition first Rising accept when v <= 0.0 then Falling;
}

calc def FallingRhs :> GetDerivative {
    in t : Real; in y : Real; in v : Real;
    return dy_dt = v;
    return dv_dt = -9.81;
}

calc def RisingRhs :> GetDerivative {
    in t : Real; in y : Real; in v : Real;
    return dy_dt = v;
    return dv_dt = -9.81;   // Rising and Falling share gravity; reset of v is in the transition.
}

The transition’s effect (not shown) reverses v with a coefficient of restitution. What executes this – integrating the active state’s derivative, watching every trigger, switching dynamics when a transition fires – is the runtime’s job, not the model’s. How sysml-rs’s runtime does it, and the simplifications it makes, are documented on the runtime page.

E.3 Change triggers and threshold crossings – [SPEC] concept, [EXTENSION] precision

accept when temp >= 100.0 is spec syntax: a change trigger that fires when its condition becomes true. When the condition mentions a continuously-varying value, a runtime has to decide when it became true – and the honest answer usually falls between two integration steps. sysml-rs locates the crossing within the step and fires the transition there, rather than a step late; that is why a thermostat trips cleanly at 100 °C and a bouncing ball bounces at y = 0 instead of slightly below the floor.

Authoring habits that make threshold behaviour clean under any runtime:

• Express thresholds as direct comparisons on a state variable (temp >= 100.0), not as derived expressions.
• Avoid pairs of transitions that would both fire on the same crossing – pick one canonical guard.
• For signals that chatter near a threshold, model an explicit hysteresis margin (temp >= 100.0 to enter, temp <= 95.0 to leave).

E.4 Occurrences and Life – [SPEC]

The spec’s Occurrence model (Occurrences.kerml in the Kernel Semantic Library) gives every happening a temporal identity. A Life is the complete temporal extent of an occurrence; an occurrence’s snapshots are its instantaneous time slices; and the library defines temporal relations between occurrences – HappensBefore (one occurrence completes before another begins) and HappensDuring (one occurrence’s extent lies within another’s).

This is the lifecycle layer everything dynamic hangs off. A simulation trajectory is an occurrence unfolding; a verdict stream is a time-indexed reading of snapshots; “did the pump start before the valve opened?” is a HappensBefore question. Chapter 16 §16.A develops the run-as-occurrence framing; Appendix J covers the occurrence vocabulary in depth.

E.5 Spatial frames – [SPEC]

SpatialFrames.kerml (Kernel Semantic Library) supplies the spec’s spatial surface. A SpatialFrame is a three-dimensional body that provides a spatial extent for positions to be measured against, and the library defines functions such as PositionOf (the position of a point relative to a frame at a given time) and CurrentPositionOf (the same, against a clock’s current time).

A model that imports SpatialFrames::* can declare frames, place occurrences within them, and ask “where is X, in frame F, at time t?” as a model-level query. Spatial frames matter most for multi-body mechanical systems and any model that must switch between body-fixed and inertial coordinates.

E.6 Performances and Evaluation – [SPEC]

Performances.kerml (Kernel Semantic Library) defines a Performance as an execution of a behaviour – itself a kind of occurrence, so everything in E.4 applies to it. An Evaluation is the performance of a function: the act of computing a result, as an occurrence with its own temporal extent, with BooleanEvaluation as the predicate case. StatePerformances.kerml adds StatePerformance and StateTransitionPerformance – a state being occupied, a transition being taken – plus helpers such as allSubstatePerformances for walking a nested state machine’s performance record.

This is the layer verification ultimately reads: when a verification case runs against a simulation (Chapter 10), the constraint checks it performs over the trajectory are, in the library’s terms, boolean evaluations over performances.

E.7 What sysml-rs’s runtime adds – [EXTENSION]

sysml-rs extends the spec here. When a model types its ports and attributes with ISQ::* quantities (Chapter 14), sysml-rs classifies each port’s physical role – effort, flow, displacement, momentum, and friends – from the type’s dimensions, and synthesizes the corresponding conservation obligations at connection junctions. Nobody writes “current in equals current out”; the runtime adds that obligation when it sees the topology, and a violated balance surfaces as an ordinary Fail verdict. On top of that, the runtime selects a numerical integrator automatically (fixed-step and adaptive Runge-Kutta methods, and a stiff-system method), honouring @ToolExecution { toolName = ... } when a model requests one explicitly.

None of this is spec, and sysml-rs’s physics is deliberately simplified – it executes idealised models for insight, and is labelled as such; it is not a calibrated physics engine. The mechanism, its limits, and the confirmed defects are documented on the portal: The runtime and Known limitations.

Tooling cross-references. The physics diagnostic family (PH codes, including the “did you mean ISQ type?” quick-fix) is described in Appendix F. Runnable physics examples – bouncing-ball, damped-oscillator, dc-motor, the espresso fixtures, and the rest – are catalogued on the portal’s Examples page.