Appendix D: Tooling Notes (sysml-rs)

The language chapters teach SysML v2 – the OMG specification, KerML, the standard library, and the modelling patterns any conformant tool should support. Real systems work, however, runs on a particular tool, and the particular tool used throughout this book is sysml-rs: an open-source SysML v2 toolchain (parser, analyzer, simulation runtime, language server, REST/MCP service, and editor extensions).

Product documentation for sysml-rs lives on its own portal, where it is maintained against the tool rather than against this book: rickymillar.github.io/sysml-rs. This appendix is the signpost between the two: for each tooling surface the chapters mention, a couple of sentences on what sysml-rs offers and a link to the page that documents it properly. Nothing here is required to write a SysML v2 model.

Spec vs. tooling. Everything in this appendix is sysml-rs-specific. Other SysML v2 tools may behave differently – they may pick different solvers, render diagrams differently, surface different diagnostics, or choose different defaults. Where a topic has a spec-faithful counterpart elsewhere in the book, this appendix cross-references it.

§Getting the tool

There is no published package yet; you build from source. The build has two genuine prerequisites beyond a Rust toolchain: fetching the OMG specification sources (the code generator derives element kinds and validation from them, so a bare cargo build fails without this step) and generating the tree-sitter parser (generated rather than committed; mind the ABI version the README pins, because a parser generated at the wrong ABI compiles and then crashes at parse time). The authoritative, maintained instructions are the Quick start in the sysml-rs README – follow that, not a summary.

§Running a model from the command line

The sysml binary checks files, evaluates expressions, simulates state machines, runs actions, executes verification cases, queries models (stats, find, trace, unverified), and exports PlantUML, canonical JSON, or a declared view’s ViewModel. Worked walkthroughs with real output live in CLI workflows on the portal; sysml help <command> is authoritative for any subcommand.

One caution worth carrying with you: the state-machine simulator can misreport the initial state and transition targets for some models, so cross-check a run against the transitions you wrote before you trust it. This and the other confirmed defects are tracked in Known limitations.

§Solver auto-selection

When the runtime detects the state-space pattern of Chapter 16 §16.B it wires an integrator automatically – a fixed-step Runge-Kutta, an adaptive one, or a stiff-system method – and locates threshold crossings in transition guards with sub-tick precision. You author the model, not the numerics. The runtime’s execution model, and the conscious simplifications it makes (it is a modelling runtime, not a calibrated physics engine), are documented in The runtime; the spec-side story of what the runtime is interpreting is Appendix E.

§Equations workbench

The equations workbench is the interactive surface for the binding-override pattern in Chapter 16 §16.C: it lists the model’s calculations, typesets them as math, exposes bindings as editable fields, and re-evaluates on change – through the same what-if path a sweep script uses, so both see the same answers. See The runtime for the execution substrate it sits on.

§Causal trace and breakpoints

A running session records every value change with its cause, and the trace is queryable backwards from any change (Chapter 16 §16.D). Breakpoints pause a session on model events – entering a state, a transition firing, a constraint flipping to Fail, a threshold crossing, or an arbitrary condition – without touching the model itself. Both are session-level runtime features: The runtime.

Two authoring habits pay off here regardless of tool: name your transitions, constraints, and actions descriptively (a trace through Idle->Heating and BrewTempReq reads far better than one through t_3 and c_17), and keep calculation bodies free of side effects so causal edges stay unambiguous.

§Editor support

The language server provides diagnostics with stable codes (Appendix F), hover with signatures and inherited members, quick-fixes (auto-import, keyword suggestions, ISQ-type replacement), live PASS/FAIL lenses on constraints, and full support for the sysml.toml manifest (Chapter 15). Editor setup and the extension surfaces are documented in Editors.

§Views and diagrams

Two conventions in sysml-rs’s diagrams are spec, not house style: definitions render with sharp corners and usages with rounded corners, as the SysML v2 graphical notation mandates, and every view definition derives from one of the eight standard view definitions, which determine what kind of diagram a view becomes (Chapter 13). Everything else – the card aesthetic, the colour palette, dark-mode behaviour, and the live overlays a running session paints onto a diagram – is sysml-rs rendering, documented in Views and diagrams along with the ViewModel contract diagrams travel over.

§The service, the API, and MCP

One in-process service backs every transport – CLI, language server, REST/WebSocket API, and MCP – so a model loaded through one is visible to the others. The interchange concepts are Appendix C; the route tables, security defaults, and MCP setup are Integrations.

§Worked examples

The models used throughout this book, and a larger catalogue of maintained runnable fixtures (hybrid dynamics, multi-file workspaces, deliberately-broken diagnostic demos), are catalogued in Examples. Every model there is executed by the regression suite, so they work at the commit you checked out.

What’s not in this appendix

The neighbouring appendices carry the topics this one does not:

• Appendix C (The Systems Modeling API) – the OMG interchange API: projects, commits, elements, and why commit-pinning matters.
• Appendix E (Physics-aware Simulation Reference) – the spec-side story of continuous behaviour: the state-space pattern, occurrences, spatial frames, performances.
• Appendix F (Diagnostic Codes) – the diagnostic-code families and how to read live diagnostics.