Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Running Simulations

Rumoca offers two ways to run a simulation. They share the same compiler and runtime; the difference is where the configuration lives.

Direct Runs

Point rumoca sim at a .mo file for quick, one-off runs:

rumoca sim Ball.mo --model Ball --t-end 10 --solver rk-like

Everything is a CLI flag: --t-end (default 1.0), --dt, --solver, --source-root, --output. The result is an HTML report with interactive plots of every variable (default <MODEL>_results.html).

Direct runs are great while developing a model. As soon as a run has settings worth repeating, switch to a scenario.

Scenario Runs

A scenario is a rumoca-scenario.toml file colocated with the model it runs:

rumoca sim -c examples/simulation/rumoca-scenario.ball.toml

The scenario records the model file and name, simulation settings, plots, viewer/transport configuration, and source roots — one runnable thing per file. This keeps the CLI, VS Code, and the playground aligned: the play button runs the scenario instead of guessing solver and source roots from a bare .mo file.

See Scenario Files for the format.

Repository Simulation Scenarios

Runnable simulation scenarios live under examples/simulation/. These are the same files opened by the playground and VS Code scenario GUI.

SympyDecay

A one-state exponential decay, useful as a minimal solver and codegen smoke:

// rumoca-live-scenario: ../repo-examples/simulation/rumoca-scenario.sympy_decay.toml

rumoca sim -c examples/simulation/rumoca-scenario.sympy_decay.toml

Ball

The bouncing ball event model from Events and Discrete Behavior, saved as a reusable scenario:

// rumoca-live-scenario: ../repo-examples/simulation/rumoca-scenario.ball.toml

rumoca sim -c examples/simulation/rumoca-scenario.ball.toml

SwitchedRLC

A compact circuit-style example with switching behavior:

// rumoca-live-scenario: ../repo-examples/simulation/rumoca-scenario.switched_rlc.toml

rumoca sim -c examples/simulation/rumoca-scenario.switched_rlc.toml

NeuralODETensor

A tensor-shaped Neural ODE with matrix-vector network layers and a phase portrait plot:

// rumoca-live-scenario: ../repo-examples/simulation/rumoca-scenario.neural_ode_tensor.toml

rumoca sim -c examples/simulation/rumoca-scenario.neural_ode_tensor.toml

See Neural ODEs for the model structure and parameter-count formula.

NeuralPredatorPrey

A Lotka-Volterra-style Neural ODE whose tensor network predicts per-capita growth rates for prey and predator populations:

// rumoca-live-scenario: ../repo-examples/simulation/rumoca-scenario.neural_predator_prey.toml

rumoca sim -c examples/simulation/rumoca-scenario.neural_predator_prey.toml

NeuralLatentOscillator

A larger latent Neural ODE with eight hidden states, a learned residual vector field, a learned decoder, and about 19k trainable parameters by default:

// rumoca-live-scenario: ../repo-examples/simulation/rumoca-scenario.neural_latent_oscillator.toml

rumoca sim -c examples/simulation/rumoca-scenario.neural_latent_oscillator.toml

NeuralODEBackprop

A native backpropagation training demonstration. The model makes weights into states, computes mini-batch vector-field loss, and integrates gradient-descent updates directly:

// rumoca-live-scenario: ../repo-examples/simulation/rumoca-scenario.neural_ode_backprop.toml

rumoca sim -c examples/simulation/rumoca-scenario.neural_ode_backprop.toml

What a Run Produces

  • Batch runs write an HTML report with time-series plots of all variables, simulation details (solver, tolerances, timing), and any termination message (terminate(...) in the model).
  • Interactive runs (scenarios with transports/viewer sections) launch the runtime with a browser viewer and input routing instead — see Interactive Simulation.

Benchmarking

rumoca sim bench measures compile time, preparation time, and hot simulation throughput separately — useful when you care about iteration speed on a large model or are comparing solver settings:

rumoca sim bench Ball.mo --model Ball
rumoca sim bench -c rumoca-scenario.toml

Caching

Compilation artifacts are cached under the platform cache directory, so repeated runs of unchanged models skip recompilation. rumoca cache status shows usage; rumoca cache prune trims it. --cache-dir overrides the location for any command.