longeron

The spine of your system model. longeron is a Python package that defines, exports, imports, and executes SysML v2 models. The import name is longeron. The parsers are generated with ANTLR 4 from combined SysML v2 and KerML grammars, and the full official SysML-v2-Release corpus parses and builds (grammar conformance).

SysML® is a registered trademark of the Object Management Group. This project is not affiliated with or endorsed by OMG, and is not a conformance-certified implementation.

Install

pip install longeron

The core install has one hard dependency, the ANTLR runtime. Solver, visualization, and interchange features live behind extras (extras table).

Capabilities

Verb

What you get

Define

Parse SysML v2 textual notation into a fully-typed Python object model, import a model from its JSON export, or build models programmatically from dataclasses. Multi-file workspaces merge under one root; a content-addressed cache makes warm loads ~1000x faster.

Export

Serialize any model to JSON, back to parseable SysML v2 text, project it onto KerML, or emit OMG Systems-Modeling-API JSON records. Parse → print → parse round-trips preserve the model; JSON → model → JSON is lossless.

Validate

longeron.validate() / longeron lint: dangling references, expression-name typos, duplicate names, specialization cycles, state-machine problems; diagnostics carry file:line:column. Names resolve against the vendored standard library (a bare Real passes with no import; a typo like Reall warns), and plain definitions carry their implied specializations (part def → Parts::Part, action def → Actions::Action, which is how start/done resolve); opt out with stdlib=False / --no-stdlib. --strict promotes the resolution-failure family to errors. A stdlib-only dimensional lint checks [SI::kg]-style annotations: mass + flightTime warns as dimension-mismatch, and cross-scale °C + K errors as scale-mismatch.

Execute

Evaluate expressions, run calc definitions, instantiate part definitions (against the bundled standard library if you opt in), check constraints and requirements, run action definitions with succession-driven control flow, and simulate hierarchical/parallel state machines with a clock.

Verify

longeron.analysis.verify hunts requirement violations from nothing but the model text, four tiers over one oracle. hunt samples and shrinks over model-derived input domains (Hypothesis), pairing each catch with interpreter-bisected boundary edges. sequences finds the minimal event sequence that drives a state machine into violation. cover builds t-way covering arrays (in-house IPOG, stdlib only), with Z3 filtering infeasible rows and recall measured against exhaustive ground truth. prove returns Z3 absence proofs, with exact rational bounds attributed to their binding constraint. Solvers only propose; every verdict is the interpreter’s.

Analyze

longeron.analysis: trade studies enumerate variation-point catalogs interpreter-exact (a CP-SAT encoder agrees mix-for-mix); the OpenMDAO bridge carries whole M0 individuals and file artifacts across build_problem, not just scalars, and derives connections from the model’s own flow usages; longeron.m0 rolls up populations of individuals; the MAUT scoreboard scores requirements with model-declared weights and utility shapes; the linked mission dashboard trades three missions on one screen behind an honest Pareto front; geometry checks (view-cone occlusion, rotor-disc clearance) run over meshes baked from the model.

Visualize

longeron.diagrams: interactive ELK diagrams in JupyterLab (structure, state machines, action flow) with click-selection that resolves back to model elements. longeron.widgets is the catalog: 17 lazy entries covering the explorer, the workbench and inspector, the diagram views, replay, the scoreboard, both dashboards, the 3D mesh and mission viewers, and the 3D RDF graph with its force-to-hierarchy morph. A JupyterLab launcher tile opens the workbench with zero notebooks.

Review & edit

The inspector shows units first-class (1.5 kg, a read-only Unit row, Real [kg]), and longeron.edit validates before it mutates: a fake unit is refused with nearest-spelling hints, a dimension change is refused naming both dimensions, and compact input (17 mg) normalizes through the model’s own prefix definitions. Renames rewrite every textual reference or roll back. save_workspace writes tracked edits back to their source files; a change it cannot map refuses, names why, and writes nothing.

Query & retrieve

Project any model onto RDF (longeron.rdf, rdflib) and ask SPARQL questions over structure, specializations, typed attribute values, variation points, and requirements. A dependency-free RAG substrate (longeron.rag) chunks the model into stable, re-parseable SysML fragments keyed by qualified name, walks semantic neighborhoods, and does keyword search — retrieval for LLM agents that cite names and resolve them through the interpreter for ground truth.

Serve & sync

longeron serve exposes any workspace as an OMG Systems-Modeling-API server with honest git-backed history: API commits are the git commits touching your .sysml sources, and pushed changes are materialized as text for you to review and commit — never auto-committed. longeron.client.Client fetches models from (and pushes changes to) any pilot-style server, and /x/ extension endpoints add validate/instantiate/simulate/render over HTTP.

Full loop

Read a model, execute it, snapshot the results back into the model as bound part usages, and save (.sysml, .json, or .kerml).

The builder covers the full grammar: every construct the SysML grammar accepts (interfaces, views, flows, allocations, metadata annotations, satisfy/verify/frame, filtered imports, …) maps to a model class — there is no lossy fallback. KerML support is asymmetric by design: parse_kerml_text validates KerML sources syntactically, and to_kerml projects SysML models onto the kernel language.

The approach

Five principles hold everywhere, stated here as design facts:

  • Model-derived, never invented. The unit table derives from the model’s own definitional algebra (newton = kg*m/s^2 lives in the vendored library and seeds the table); no unit is hand-coded. verify mines its input domains from the model’s constraints through Z3 and flags any fallback. Geometry renders from M0 populations: the individuals that exist, keyed per configuration. The OMG standard library is vendored, not reimplemented.

  • One truth, many projections. Every surface reads the same model object, and the tutorials assert the agreement where projections overlap: the model’s closed-form payload ceiling matches verify’s independently bisected edge, the CP-SAT enumeration equals the interpreter’s set, and SPARQL answers are checked against the trade dashboard.

  • Honest refusal over silent corruption. A fake unit is refused with nearest-spelling hints. A rename that would capture a name rolls back and lists the affected references. A workspace save that cannot map a change refuses, names why, and writes nothing.

  • Honest absence, counted claims. The corpus badge claims only positive acceptance; rejection is its own suite, and the two known permissiveness gaps stay visible as strict xfails. Vacuous verification passes are recorded, never coerced into failures. Covering-array recall is measured against exhaustive ground truth, never assumed.

  • The interpreter is the sole semantic oracle. Z3, CP-SAT, and Hypothesis only propose; every verdict is the interpreter’s. A SAT witness is believed only after the interpreter re-checks it.

Where to go next