Run Modelica

Run Modelica models & build experiments

lunica exposes a reflect-registered command API and structured query providers over POST /api/commands. Drive everything with curl. The mcp__lunco__* tools mirror this API but are frequently down — use curl as the primary surface; only fall back to MCP if a human explicitly asks.

0. Launch an app in API mode

Modelica runs inside any app that embeds LunCoApiPlugin + the Modelica workbench. Build the named binary in the current worktree, then invoke it directly. The API server only exists when you pass --api. Default port is 4101 (lunco_api_contracts::DEFAULT_API_PORT).

Before creating a new Modelica file, inventory the maintained package roots and the closest composed USD network in the current checkout. Reuse existing component classes through USD or the generated wrapper when their equations and public contract fit; add a new mission/vehicle model only when the equation or interface is genuinely absent. An isolated Modelica compile proves neither USD wiring nor runtime physics.

Compile admission preserves an existing participant/vehicle name; generated class identity belongs to simulation metadata. Verify a control HUD against the physical vehicle identity after compile and reload.

For shared plume calculations, reuse LunCo.Propulsion.computePlumePhotometry. PlumePhotometry supplies named USD ports; RCSJet calls the function directly with static nozzle parameters. See USD-driven visuals for the fixed-size result contract. Validate model refactors through the production rcs_feed_starvation and rocket_engine_plume_defaults scene gates, then measure cold solver preparation and running-step cost separately.

For material-dependent equations, use the component's typed SysML material assignment and property source described in the mission engineering material gate. Keep values and units typed until the Modelica-source emission boundary, and derive generated parameter literals from that source rather than maintaining a second hand-edited material table in .mo. The shared material catalogue and generic cross-domain binding are not yet established; if the current bridge cannot provide a required property with its unit and applicability, report that generic gap instead of substituting a copied constant.

For radiation or surface thermal models, also resolve the typed finish/coating assigned to the analyzed face and use its sourced engineering optical/thermal properties. UsdShade shader presets are presentation mappings only and must not be used as Modelica property sources.

In luncosim, switch to the Modelica view before plotting/screenshotting. The compile/run/experiment commands and query providers work regardless (they're headless-safe), but the diagram/plot panels only paint when their perspective is active. Switch with:

curl -s -X POST http://127.0.0.1:4101/api/commands -H "Content-Type: application/json" \
  -d '{"type":"ExecuteCommand","command":"ActivatePerspective","params":{"id":"modelica_analyze"}}'
# other ids: "sandbox_view", "rover_build". Reset a broken layout: {"type":"ExecuteCommand","command":"ResetWorkspaceLayout","params":{}}

• Add --no-ui for a headless compile/run server (no window, no GPU). The API surface is identical; screenshots, diagrams, and 3D viz are what you lose (so perspective switching is moot). GetExperimentResult/SnapshotVariables still give full numeric results headless.
• Use production luncosim for scene-test and visual evidence. Use luncosim-server or luncosim --no-ui for numeric/API evidence only, and report the binary, revision, readiness state, and evidence type separately.
• Launch your own session on an explicitly free API port. Never reuse or stop another session. Verify PID, executable, and checkout before controlling your session; use its API Exit and verify shutdown before replacing its binary.
• Standalone Modelica ports exclude entities with SimComponent; the co-simulation backend owns their topology publication. Live sample changes must not invalidate resolved handles without a structural contract change.

No-API alternative

The standalone runner is owned by lunco-modelica-execution, not lunco-modelica-core. For a one-shot current-source compile and fixed-step solve with CSV output:

cargo run -p lunco-modelica-execution --bin modelica_run -- \
  assets/models/AnnotatedRocketStage.mo AnnotatedRocketStage.RocketStage \
  --duration 30 --dt 0.001 --input valve_command=0.7 \
  --record altitude,velocity --output /tmp/run.csv

This runner uses the shared compiler and solver path, but it is not a substitute for the active Twin/API test when the source depends on Twin-indexed packages, Editor state, or scene composition.

Wait for readiness with an until loop (never chained sleeps):

until curl -s -o /dev/null -X POST http://127.0.0.1:4101/api/commands \
  -H "Content-Type: application/json" \
  -d '{"type":"ExecuteCommand","command":"Ping","params":{}}'; do sleep 1; done

Stop with the Exit command (never pkill/kill — those need user confirm):

curl -s -X POST http://127.0.0.1:4101/api/commands \
  -H "Content-Type: application/json" -d '{"type":"ExecuteCommand","command":"Exit","params":{}}'

Structured package lookup

Attach a Modelica source to a USD body

For a multi-domain run, use the shared AttachProgram { doc_id, spec } command instead of writing marker components or maintaining a separate binding table. The spec authors the LunCoProgramAPI child, explicit scalar inputs and outputs, and native USD connections in one journaled change set. In Rhai the same surface is assembly_edit::attach_program(...) with assembly_edit::program_input_connection(...), assembly_edit::program_input_default(...), and assembly_edit::program_output(...) helpers. Verify the result with ListPorts, CosimStatus, and GetBrokenConnections; a source without declared ports is reported as source-only and does not step.

Modelica packages under assets/models/<Root>/ and inside a Twin use the standard package.mo/package.order layout and members' within declarations. A Twin may declare [modelica].paths (Twin-relative, with "." meaning the Twin root) and externals in twin.toml. Without that section, the Modelica owner derives roots from the indexed Twin .mo files, so package discovery does not depend on a hard-coded folder. A qualified reference such as LunCo.Electrical.Battery is resolved by its root segment through the normal Modelica search-path inventory; do not add a library-specific Rust load call. Every live compile admits its required roots through the existing LoadSourceRoot worker path before it sends Compile. File-backed source assets carry root requirements from their prepared AST interface, document compiles derive them from the primary and sibling ASTs, and a generated policy's source_roots list is its required root manifest. The worker commits root preparations in admission order before compilation, rejects unadmitted roots, and reports failed roots without retrying synchronous discovery. Synchronous compiler helpers remain for CLI and batch callers. The worker's successful load acknowledgement carries the authored top-level namespaces parsed by that exact source-set operation. The registry retains those names on the scoped owner entry, and compile admission resolves each qualified namespace to its unique source-set ID. Missing or ambiguous namespace ownership is a terminal diagnostic. Failed or stale acknowledgements cannot publish Ready or recreate a retired namespace; Twin close removes the entry and its names. Verify Twin package admission through the existing authored path_interoperability.rhai namespace assertions: load a Twin package, compile a separate wrapper using its qualified member, inspect the solved output, then verify a missing namespace produces a terminal compile error. An unqualified source asset already present in an admitted root compiles the root-owned class only when its exact source CID is in the admitted content closure. Changed or conflicting source text is rejected; update and readmit the source root before compiling it. This prevents a second URI from duplicating the same root definition while preserving the root's authority. The policy list does not replace composed USD facts for member-class discovery. The worker's prepared-solve cache keys library state from the revisions that ModelicaCompiler records while admitting source roots. Its source key is captured from the successful strict compiler's participating-source closure before clearing user overlays. Generated class/network-title identity is normalized; equations, parameters, initial values, participating siblings, and contributing library bytes remain structural. Unrelated sibling edits and runtime document IDs do not invalidate prepared solve IR. The captured key remains with the immutable DAE through shared reuse and resets; the precompile DAE cache uses the full submitted input set until the strict closure is known. It does not scan the complete Modelica tree during the first live stepper build.

For preparation evidence, use actual owner INFO logs: cache=memory-hit at in-memory admission, cache=disk-hit after persistent lookup, and cache=miss when lowering runs. Disk preparation includes lookup, lowering, and total duration plus the source key. Stepper construction is not evidence of cache reuse.

Generated USD networks compile their complete synthesized source plus admitted source roots; unrelated editor documents are not sibling inputs. The reserved bundled generated/ filename namespace drives provenance and structural cache classification. Verify repeat-load cache reuse while changing document-open order; authored Modelica documents retain their multi-document source sets.

Domain discovery does not resynthesize ordinary scene-owned networks when a content prim receives its GID: that identity does not enter their namespace. Instance-scoped identities and unsettled provenance remain discovery inputs, alongside prim paths, stage revisions, wiring, and member-source events.

Initial network results may publish as a bounded four-root prefix only while their own fixed-clock admission hold is present and no prior projection is installed. Live replacements remain one per Update; repeated results for a root wait for ECS publication. Worker completion never bypasses the oldest request or its Twin/stage/instance validation.

On native runs, one dedicated Rumoca actor owns the mutable session and shared DAE cache. Source-root installation, Compile, Reset, parameter updates, and cache-invalidating Step auto-init share a FIFO. The worker commits results in submission order after entity-session and library-generation checks; a Step that needs a rebuild resumes only after its initialization commits. These continuations leave the Modelica command owner free to service other entities, and actor requests plus solve preparations share bounded admission. Persistent solve-cache reads and writes run with DAE lowering in the preparation pool; the native owner thread does not perform cache I/O or fall back to synchronous lowering. Wasm keeps compilation inside its Modelica Web Worker.

Shared immutable RAM caches use the captured lunco_modelica_runtime::ModelicaCacheLimits resource: positive compiled and prepared entry capacities, each defaulting to 64 per worker. Follow the Modelica cache contract for configuration timing, FIFO reuse, and browser startup/respawn admission. Entry caps bound graph count rather than heap bytes; eviction preserves live owners. Run the generic immutable_reuse_cache_ tests and compile the browser worker bundle when changing configuration transport. Do not infer Twin teardown from shared immutable cache contents. For shared browser worker transport changes, run the generic worker_lifecycle_ tests in a real browser and compile both Modelica execution and DEM bake consumers. Replacement must release the old handlers, including replacement inside an executing callback; failed replacement leaves an empty slot. For native compiler heartbeat changes, run the generic compile_heartbeat_ lifetime tests; ensure normal, error, and unwind exit interrupt the wait and release the owned thread.

Native optional solve-cache reuse captures the cache-owned lunco_modelica_worker::worker::PreparedSolveDiskLimits resource before ModelicaExecutionPlugin starts the worker. Defaults are 32 retained records, 64 MiB compressed, 256 MiB decoded, and a 64 MiB zstd window; see the cache ownership contract for valid ranges and configuration timing. Missing records are cache misses; rejected existing records warn and recompute admitted equations. Invalid limits are a typed worker startup failure. For decode changes, run the generic prepared_solve_disk_cache_ tests; do not substitute repository models for the inline-storage boundary fixtures. For publication/retention changes, also run persistent_solve_cache_ and storage cache_directory_transaction_ tests, including the native Windows CI path. Keep heavy encoding outside the storage transaction; never remove its lock file or broaden retention beyond the owned cache namespace. Optional publication failures warn while preserving the admitted solver result.

On native desktop startup, cache-miss solve-IR lowering runs in the worker's bounded preparation pool because the DAE input and solve options are immutable. The worker alone commits the resulting solve model and constructs the live stepper; Step, Reset, parameter updates, and source-root changes remain ordered behind that commit. Persistent solve-IR entries are keyed by structural source identity, the content-sensitive admitted-library revision, solver, and parameter overrides. A source-root change clears worker-local prepared models while retaining disk entries for future matching revisions. Readiness is still the completion barrier, so physics must not be started before /api/ready reports ready=true, world_hold=false, and pending_count=0.

Bundled and workspace source roots are parsed to completion before admission and installed as one parsed source set. A failed member therefore keeps the root out of the Rumoca session; do not treat a nonzero parsed count as readiness.

The registry marks each root as Application- or Twin-owned. Twin root IDs include the stable Twin ID. TwinClosed removes only that Twin's source sets and queues ordered unloads to the Rumoca actor; other Twin and application roots remain.

Twin closure also retires its open Modelica documents through the core CloseDocument owner, including linked execution entities. Workspace replacement closes every editor document before TwinAdded; unfinished UI preparations are canceled and file-read completions are fenced by their admitted runtime owner. Individual document closure also cancels parse preparation, save-close continuations, and document-owned modals before retiring the editor state. Reopening the same Twin starts fresh. RestartScene leaves editable documents resident while rebuilding their scene-owned execution.

Operation IDs fence an in-flight file read from installing a source set after its owner closes. If the worker has not created its channel yet, pending unloads stay queued and are sent before a later Twin load. A disconnected channel is a terminal unload failure: it reports a runtime fault, retains the queued operation, and blocks later Twin root admission instead of retrying on every update.

For policy-owned generated models, keep contract assertions in authored assets/scenarios/tests/*.rhai scenes; standalone live probes may use assets/scripting/tests/*.rhai. Rust should provide the composed facts and invoke the registered policy; Rhai should assert the generated source, topology, layout, and UI metadata. The policy result is strict: it must return source, units, layout.units, layout.members, source_roots, and member_output_aliases (the last may be an explicit empty array). Missing or invalid fields are projection errors; do not add a Rust-side generated-model fallback. layout.units uses root-diagram coordinates, while each entry in layout.members is local to the owning unit diagram; member overlaps are checked within that unit coordinate system.

On native development checkouts, the active prelude and policy files are read from assets/scripting/ at startup, so Rhai edits require a restart rather than a Rust rebuild. A present editable directory is authoritative: unreadable or empty directories and parse failures are errors. Packaged/wasm builds use their compiled-in asset set because no editable source tree is available.

When reviewing a generated diagram, click its generated browser row first. A single-unit network opens the unit-level class and shows its real members; multi-unit networks open the root wrapper. Use FitCanvas after drill-in when the tab was opened alongside the root, since navigation is scoped to the focused Modelica tab.

For electrical generated networks, verify the unit diagram's labelled power bus and follow at least one routed connect(...) branch through the rail. The Rhai policy uses readable network_system/network_unit_N unit instances and a topology-derived hub with adaptive branch lanes, so inspect a larger network with FitCanvas rather than assuming the six-member demo's geometry scales. Components that need directional presentation apply LunCoModelicaTopologyAPI with source, storage, or load; this metadata does not alter acausal solver direction. Member icons must resolve from their native Modelica classes; a fabricated card or direct solar-to-motor wire is a projection defect, not an acceptable fallback.

When an authored Modelica endpoint also carries InputPorts, that component is the single public command boundary. SetPorts and Rhai writes land there, and the generic Modelica bridge mirrors only names accepted by the compiled model into its solver input buffer. External live SetPorts commands with a stable producer id enter the shared next-fixed-tick queue and are captured as ordered named writes; Simulation-clock Rhai writes remain derived behavior. Do not add a vehicle-specific setter. External API/direct and non-Simulation Rhai ReleasePort/ReleaseControl commands use the same producer identity and ordered session boundary. Releases clear local holds only; Twin policy sends explicit setpoints with SetPorts. Battery empty events use the authored 0.1% usable-storage reserve in Battery.mo, not a solver-epsilon comparison.

Node movement has two valid outcomes. On an editable .mo document, drag a component and verify that the standard annotation(Placement(...)) changes in the source and survives a re-projection. On a generated document, the canvas is intentionally read-only because USD plus the Rhai policy owns the source; use Duplicate to edit, then perform the same placement check. A drag that appears to work but disappears on reload is a product bug, not an acceptable generated-model editing mode.

Use the shared AST strip_within_prefix for qualified lookup and editing; similarly spelled package prefixes must not match an authored within package. Reuse the AST's qualified_name_segments and parent_qualified for class paths; quoted identifiers containing dots remain one segment. Extraction checks do not prove the compiler accepts that qualified name: validate compilation separately through its actual command/error boundary.

For class source extraction, reuse lunco-modelica-ast::ast_extract::class_full_text_span from the same parsed bytes. Its inline seam test covers same-line enclosing declarations and class qualifiers; do not derive declaration bounds by scanning backward through arbitrary identifiers. Read-only library views also require exact qualified identity. The generic library extraction seam checks sibling leaf names and a missing sibling without reading repository fixtures.

Duplicate admission pins its original target scope and resident source snapshot. Check an exact nested qualified class when sibling packages share a short name; known-source errors must report failure without installing a substitute document. Closing the source or target lifetime during preparation must cancel publication and release pending names, tabs and status. Use inline parser tests for span and rewrite boundaries, and authored Rhai commands/queries for these public lifecycle outcomes. assets/scenarios/tests/modelica_duplicate_lifecycle.rhai exercises qualified siblings and quoted names, error diagnostics and exact-name reuse, observed pending source-close cancellation, original-target Twin replacement without retagging, and a valid successor. Run it in a UI-capable host with Application/Retain lifetime and API-authored root_a, root_b, entry_scene fixtures. Asynchronous folder scanning permits a duplicate to install while its old Twin is live; the gate preserves that valid retained-source outcome. Exact Twin/connection retirement of never-ready tasks belongs to the generic resource seam test, since public folder replacement cannot force that worker boundary. Native preparation runs on the existing task pool; browser Bevy tasks retain the browser editor's deferred parsing contract.

Projection must remain responsive while a native package or inherited icon is being resolved. Verify that /api/ready stays responsive, the canvas shows an explicit loading/error state, and the completion event reprojects the authored icons. Do not add a synchronous parse, mutex wait, invented icon, or domain specific visual retry path to hide a miss.

Energy-flow animation is generic Modelica behavior, not generated-policy code: LunCo.Electrical.Pin.i is a standard flow Real, just like the rocket and lander FluidPort flow variables. Confirm the connector projection reports the flow variable and that a non-zero live instance.p.i moves dots along the rendered edge; zero current must remain visually idle. If dots are absent, inspect the flow metadata and node-state keys at the shared canvas owner before adding any policy-specific renderer.

1. The request envelope

Everything is one endpoint: POST /api/commands. The JSON shape is always {"type":"ExecuteCommand","command":"<Name>","params":{...}}. Always include params even when empty ("params":{}) — this keeps every request explicit and discoverable.

curl -s -X POST http://127.0.0.1:4101/api/commands \
  -H "Content-Type: application/json" \
  -d '{"type":"ExecuteCommand","command":"<Name>","params":{ ... }}'

Two kinds of command share this envelope:

• Commands (fire-and-forget mutations): return {"data":{"accepted":true}}; result-returning commands put their command-specific payload in the same data envelope. Invalid parameters return HTTP 422. A deferred command may complete its command acknowledgement later on the same request; that acknowledgement is not necessarily completion of the domain work. In particular, RunExperiment returns its exact experiment_id once the run is registered, while the numerical solve continues asynchronously.
• Query providers (return data): return the payload directly, e.g. {"runs":[...]}. ListRuns, GetExperimentResult, DescribeModel, SnapshotVariables, CompileStatus, GetDiagnostics, ListCompileCandidates, ListBundled, ListOpenDocuments, FindModel are all query providers — invoked with the same tagged ExecuteCommand form. Built-in discovery and entity listing use their own explicit type values.

doc_id: 0 always means "the active document/tab".

2. Two run modes — pick the right one

3. Recipe A — run a model live (interactive)

API=http://127.0.0.1:4101/api/commands
post(){ curl -s -X POST $API -H "Content-Type: application/json" -d "$1"; }

# 1. Open a model. Prefer the unified opener (bundled example / qualified source-library name / path):
post '{"type":"ExecuteCommand","command":"Open","params":{"uri":"bundled://SpringMass.mo"}}'
#    bundled://Name.mo | Modelica.Blocks.Examples.PID_Controller | /abs/path.mo | mem://Untitled
#    List embedded examples first: {"type":"ExecuteCommand","command":"ListBundled","params":{}}

# 2. Wait for the AST parse (background). Poll CompileStatus until ast_parsed:true:
post '{"type":"ExecuteCommand","command":"CompileStatus","params":{"doc_id":0}}'   # -> {state, ast_parsed, candidates, picker_pending, ...}
#    Read parser/compiler/lint findings and actionable Rumoca suggestions.
#    Poll while complete is false; pending is not a clean result.
post '{"type":"ExecuteCommand","command":"GetDiagnostics","params":{"doc_id":0}}' # -> {state,complete,channels[],diagnostics:[{domain,source,code,severity,message,uri,line,column,suggestion}]}

# 3. Compile + play. class REQUIRED if the file has >1 non-package class
#    (the GUI picker can't be shown over the API). Discover choices:
post '{"type":"ExecuteCommand","command":"ListCompileCandidates","params":{"doc_id":0}}'   # -> {candidates:[{qualified,short}]}
post '{"type":"ExecuteCommand","command":"RunActiveModel","params":{"doc_id":0,"class":"SpringMass"}}'

# 4. Read live values (t + parameters + inputs + variables). Filter with names:
post '{"type":"ExecuteCommand","command":"SnapshotVariables","params":{"doc_id":0,"names":["x","v"]}}'

# 5. Poke a runtime input live (no recompile, admitted for the next fixed tick):
#    For an open workbench model, use doc_id and keep producer_id stable.
post '{"type":"ExecuteCommand","command":"SetModelInput","params":{"doc_id":0,"name":"F","value":10.0,"producer_id":4101}}'
#    For a live Twin participant, use its stable target_gid from ListEntities
#    and leave doc_id at 0; do not pass both selectors.
post '{"type":"ExecuteCommand","command":"SetModelInput","params":{"doc_id":0,"target_gid":123456,"name":"throttle","value":0.5,"producer_id":4101}}'

# 6. Pause / Resume / Reset / Restart:
post '{"type":"ExecuteCommand","command":"PauseActiveModel","params":{"doc_id":0}}'
post '{"type":"ExecuteCommand","command":"RestartActiveModel","params":{"doc_id":0}}'   # reset t=0 then run

RunActiveModel = compile-if-stale then play. If already compiled & clean it just unpauses (no recompile). CompileModel compiles only (stays paused); ResumeActiveModel unpauses only.

If a live compile fails on an unbalanced DAE, its ordinary Modelica Error event in Recent status events explains why simulation did not start and lists the unknowns Rumoca's structural matcher could not pair with equations, plus their categories and referencing equation rows. Selecting the row expands the full message. GetDiagnostics also returns the explanation with the structured compiler findings. Those names identify values the current equations cannot determine; add or correct independent equations or constraints. The diagnostic DAE is never simulated.