Compose Multidomain Twin

Composing a multi-domain Twin

A full mission layers cleanly — never blur the layers:

Rust ships parameterized behaviors; it never hardcodes a vehicle. A 6-wheel rover is a USD file, not a Rust struct — the physics/materials philosophy applied to whole vehicles.

Who computes what. Rust owns rigid-body kinematics and dynamics — bodies, colliders, contacts, joints. Modelica owns everything else that evolves: thermal, electrical, propulsion, structural. Modelica reaches physics through cosim ports, and may also carry GNC or flight-software math (an equation is an equation); what it must never become is a second physics engine. SysML owns requirement intent and traceability; Rhai observes the composed stage and emits the executable verdict. Rhai is the default scenario backend. Python is optional and is not part of the normal Twin workflow.

For mission-level work, apply the generic mission and engineering quality gates before composing domains. Establish the ConOps and operating modes, allocate requirements and interfaces down the product tree, choose fidelity by intended use, and define nominal, off-nominal, and recovery scenarios. Verify detached components before integration, validate the integrated Twin against ConOps, and baseline the exact sources, clocks, solver settings, and seeds used for each evidence run.

Start with a capability and exemplar audit

Before authoring a new vehicle, domain, controller, or Rust mechanism, inspect the target checkout and the repositories that supplied the request. Separate what is already implemented from what is merely not yet composed for this mission.

1. Identify the actual runtime checkout and the mission/research repository. Do not transfer a gap from one repository to the other without checking the target checkout.

2. Inventory assets/vessels/, assets/components/, assets/models/, assets/scenes/, and assets/scenarios/ with rg --files.

3. Select the closest production exemplar: read its reusable asset, its composing scene, and its authored test. A tutorial or demo may explain an idea but is not automatically the production contract.

4. Write a small private matrix before editing:

   Question	Answer
   Generic mechanism already exists?	yes/no + source path
   Closest reusable exemplar?	asset + scene + test
   Mission-specific authoring missing?	USD/Modelica/Rhai/data
   External dependency required?	yes/no + explicit scope
   Runtime evidence available?	parse/compile/readiness/behavior/visual

5. Classify the work as an engine substrate, reusable asset, mission assembly, external dependency, or evidence gap. Only an engine-substrate result justifies a Rust change. If a generic mechanism and exemplar already exist, compose and parameterize them first.

This audit is a decision aid, not a new persistent runtime registry. Keep the final ownership and parameters in the existing USD, Modelica, Rhai, and Twin contracts.

Check Twin-wide names before loading

Run the explicit namespace pre-flight after adding a source root, tool library, shader, or referenced USD asset:

query("ValidateTwin", #{path: "/work/rover-twin", policy: "error"});

Retain the returned operation_id and poll ValidateTwin with only that ID. Read ready.report; failed.diagnostic is terminal. Mounted browser callers use the current assigned twin://<authority> instead of a native folder. See validate-assets.

The inspector reports only collisions in the same resolver scope and includes every owner/source so the repair is made in the authored Twin. RunLint can run the same check against the active Twin with cmd("RunLint", #{scope: "twin", policy: "warn"}) on native or a mounted browser Twin. Retain its queued lint revision and inspect GetDiagnostics for the actual ready/failed scope. Source failures fail that scope regardless of collision policy, and retirement cancels its exact preparation. Keep resolver policy in assets/scripting/policy/lint_twin.rhai; do not add a Rust-side rename, silent precedence rule, or duplicate namespace registry.

Physics ports vs sensors — pick the wrong one and you author a bug

A physical part reads PHYSICS: a strut's glow takes the force port off its own prismatic joint, because a leg carries load when the ground pushes on it — not when an instrument says so. Flight software reads SENSORS, because a computer knows only what its instruments report: DescentGuidance reads the altimeter with its mount offset and rangeMax, not the true height.

Backwards costs real bugs. An altimeter's datum sits above the pads, so gating a strut on it forces a hand-copied constant to restate that offset, and the legs light before touchdown. When a constant in a .mo exists only to translate between two prims' positions, the wire is wrong.

A sprung mechanism belongs to the SOLVER, not to a domain model. A landing leg's passive shock absorber is a PhysicsPrismaticJoint with standard PhysicsDriveAPI:linear coefficients and the narrow PhysicsDriveAPI:linear coefficients. The native Avian prismatic joint is the sole axial mechanism in the existing substep solver, and its stroke and reaction are the joint's own displacement and output-only force ports. Do not write a .mo for the spring and do not animate it from Rhai: Modelica earns its keep where a domain equation has no solver already integrating it.

Sign is a property of the joint. force = stiffness * (targetPosition - displacement) makes the reaction opposite in sign to the displacement, so a compressed strut reads NEGATIVE displacement and POSITIVE force, and the axis points the way the strut extends. Author it once in physics:localRot0; never correct it downstream in a wire's lunco:factor:, which is a unit conversion.

A sensor reads physics; it never re-derives it. The touchdown switch and the collider contact ports share one computation (avian::contact_of). Two copies are free to drift, and nothing in the log says which one you are looking at.

No per-tick computation. Prefer an on-demand port read over a mirror component kept in step by a sync system, and Changed<T> over an unfiltered system. Never per-tick work in rhai — except in a rhai test, where stepping is the point.

Attach a program through the shared contract

Use AttachProgram { doc_id, spec } for a new Modelica participant. Python is an optional python-feature integration and should be used only when the Twin explicitly requires it; it is not the normal scenario backend. For Twin-owned requirements and verification cases, use sysml-requirements rather than adding requirement metadata to a program prim. The command validates the source path and explicit scalar interface, then authors the LunCoProgramAPI child, defaults, and native USD connections as one journal/undo change set. The Models palette and the assembly_edit Rhai tool call this same command; do not add a marker component or a source-specific Rust path.

assembly_edit::attach_program(doc, #{
    edit_target: "@root@",
    host_path: "/Lander",
    name: "Guidance",
    source_asset: "lunco://models/DescentGuidance.mo",
    inputs: [assembly_edit::program_input_connection("altitude", "/Lander.outputs:position_y")],
    outputs: [assembly_edit::program_output("force_y", ["/Lander.inputs:force_y"])],
    realtime_safe: true,
});

Every input has one authored default or one USD connection. Every output names its consuming USD input properties. An empty contract is source-only and must be completed before ListPorts, CosimStatus, or force exchange can prove a running participant. Use @root@ for persistent scene content and @runtime@ only when a live overlay is the explicit intent.

This skill is the assembly layer over the single-domain skills: build-usd-scene (author the scene), authoring-vessel-controllers (a vessel's GNC), author-scenario (behaviour), run-modelica (the .mo models), inspect-simulation (verify the chain). For reusable builders, component lints, and live typed-operation helpers, use author-rhai-tool. For architecture decisions and standard-schema checks, read luncosim-architecture. It is the gate against special-case Rust, duplicate USD vocabulary, and compatibility paths.

Use the generic assembly checkpoint

For a new rover, lander, or multi-domain scene, use the shared Rhai model_authoring facade before composing domain-specific policy:

1. model_context(doc, root, edit_target) reads the complete composed tree and preserves its generation.
2. readiness_report(doc, root, edit_target, policy) combines the explicit topology, physicality, mount, connection, control, and runtime checks.
3. scene_recipe returns dry references, terrain, camera, initial-state, route, and program records.
4. port_graph and wiring_plan discover and validate standard USD inputs:/outputs:/connectors: endpoints before typed SetConnection ops are reviewed.
5. publish_component validates a reusable component and returns an explicit Save-As plan.

Keep vehicle manifests, limits, and mission thresholds in the Twin's Rhai package. The facades do not create a Modelica compiler path, a vehicle schema, or a Rust builder. See the scripting guide for signatures and apply boundaries.

Componentized vehicle workflow

Build a vehicle as a small set of contracts, not one monolithic USD file. Put each independently reusable, articulated, or domain-owning subsystem in its own component boundary when it has a local frame, mount interface, mass or collision owner, parameters, or a useful independent test. Typical boundaries are an egress mechanism, landing leg, solar array, avionics package, payload adapter, and propulsion/attitude network. Keep one-off visual trim in the assembly when splitting it would add no reusable contract.

For each component, define its topology, frame/datum, known requirements and limits, and Rhai requirement test before composing it. Use the live headful Editor to author the component with typed USD operations, inspect and screenshot it, and run its boundary tests in the same runtime session. Then assemble through explicit references, host joints, collections, and native connections, and run a second integration suite for counts, placement, clearance, reference targets, joint endpoints, and cross-domain wires. A component pass is not an assembly pass.

For a repeated parametric component, use the dynamic assembly_builder::component_bundle_facts/component_bundle_plan pair to keep visual geometry, collision ownership, mass/inertia, dimensions, mount frames, and actuator endpoints in one validated contract. Keep deployment policy and mission values in Twin-owned Rhai/USD; the bundle does not create a Modelica participant, guess a physics joint, or add a vehicle-specific Rust schema. Add explicit typed body/joint or socket plans at the assembly boundary, then verify both the component contract and the composed Twin.

Keep the detail level at contract fidelity: standard USD primitives are enough for silhouettes, mounting envelopes, colliders, and tested interfaces. Add meshes or parametric detail only when it changes a requirement or the visible identity. Never flatten a referenced component into the assembly merely to avoid authoring its own contract. If a typed USD gap prevents creating a variant set, replacing a reference list, or authoring required metadata, report the Rust/typed-editor gap instead of using duplicate hidden geometry.

The Twin (on-disk mission unit)

A Twin = a folder + a twin.toml manifest that owns a default USD scene:

name = "luncosim"
version = "0.1.0"
description = "…"
[usd]
default_scene = "sandbox_scene.usda"   # loaded as the active stage on open; other .usda here are a referenceable library

Everything the mission needs lives under that folder: the scene, referenced vehicle assets, .mo models, .rhai scenarios. Open the Twin and the default scene loads.

Reuse the closest working composition

Copy the composition shape through USD references; do not copy a whole example into a new bespoke implementation. Preserve the exemplar's ownership, network roots, input/output contract, lifecycle, and test pattern. Override geometry, parameters, initial conditions, and mission policy in the new asset or scene.

For Modelica, first compose existing component classes through USD and the generated network wrapper. A new vehicle-level .mo is justified only when the required equations or public interface are absent. Do not create one file per mission domain merely to rename existing LunCo.* classes.

Decision 1 — a multi-domain vehicle is one program prim per domain + connections (SSP)

A program is a PRIM, not an attribute on the thing it drives — the same reason a UsdShade shader is a prim: it has typed ports, and ports connect. Model each physical domain as its own a Scope applying LunCoProgramAPI under the vehicle Xform, each naming its own .mo, wired through the port surface. This is FMI/SSP — no new machinery.

def Xform "Lander" (PhysicsRigidBodyAPI …, CollectionAPI:components) # body + network root
{
    float inputs:force_local_y.connect = </Lander/GNC.outputs:thrust>   # GNC thrust → body force

    def Xform "Battery" (
        prepend references = @lunco://components/power/battery.usda@</Battery>
    ) {}
    uniform token collection:components:expansionRule = "explicitOnly"
    prepend rel collection:components:includes = [</Lander/Battery>]

    def Scope "GNC" (prepend apiSchemas = ["LunCoProgramAPI"]) {
        uniform asset info:sourceAsset = @lunco://models/DescentGuidance.mo@
        uniform bool  lunco:program:realtimeSafe = true                 # it drives a force
        float inputs:altitude.connect     = </Lander.outputs:position_y>
        float inputs:descent_rate.connect = </Lander.outputs:velocity_y>
        # Consume the battery output at its authored USD path.
        float inputs:engine_enable.connect = </Lander/Battery.outputs:soc_out>
        float inputs:g = 1.62                                           # only if the Modelica contract declares a runtime input
    }
    def Scope "Therm" (prepend apiSchemas = ["LunCoProgramAPI"]) {
        uniform asset info:sourceAsset = @lunco://models/LunCo/Thermal/ThermalMass.mo@
    }
}

The electrical network is the explicit CollectionAPI:components collection on the assembly root. It does not need a domain-named child or an inputs:load wire. Battery.mo exposes a Pin, and a pin carries a flow variable — the current is the circuit's answer, not a number anyone writes in. Wire a physical bus by connect()-ing pins inside one Modelica model; only signals (a throttle, a setpoint, a temperature reading) cross as USD port connections. See 54 — The Electrical Domain.

A wire is a native USD connection, authored on the prim that CONSUMES the value. Do not host N solvers on one entity — that forces SimComponent to a multi-instance map and touches the propagation core. One program prim per domain gives the same composition with zero core change and clean per-domain telemetry.