Contributed engineering demos

Twelve contributed demonstrations have executable Python and SysML versions. Both resolve to the same connected-behavior-v2 graph and use the normal connected-model simulation engine. Python authoring uses declared state, scoped assignments, supported scalar mathematics and ordered actions. It is translated, not executed as arbitrary Python. No numerical callback escape hatch is used.

Install this repository’s build:

python -m pip install .

Run either source through the Python API:

from sysml2py.demos.profiles import execute

result = execute("cart", {"mass_kg": 4, "force_n": 12, "duration_s": 8},
                 language="python")
print(result["outputs"]["metrics"])  # Final position: 96 m

Or through the CLI:

python -m sysml2py.demos cart --language python --output cart-results.json
python -m sysml2py.demos cart --language sysml --output cart-results.json

The gallery displays live charts for these runs and offers separate Python and SysML source downloads. The ZIP includes both sources, parameters, a runner, license and validation provenance. Run python run.py --language python or python run.py --language sysml outside the checkout with this package installed. The bundled runner executes the downloaded files and writes sampled rows to results.json; it does not call a hidden numerical solver.

Inputs, initialization and timing

Only listed finite numeric inputs are accepted. Unknown keys, booleans, fractional counts and values outside the published bounds are rejected. Source defaults remain unchanged: the requested values are passed to declared input attributes. Dependent initial values, such as initial spring displacement or battery energy, are recalculated after inputs are applied. Each run starts with fresh state.

from sysml2py.demos.uploaded import MODELS
from sysml2py.demos.profiles import configuration, sources
from sysml2py.modelgraph import ConnectedModel

python, sysml = sources("cart")
config, inputs = configuration("cart", {"force_n": 40})
model = ConnectedModel.from_documents([{"project_id": "demo", "source": sysml}])
samples = model.simulate(config, inputs=inputs)
print(MODELS["cart"]["parameters"])  # Published input bounds

Time and step size are bound to the model’s declared time and dt inputs. The actual final partial step is supplied by the engine. Plot sampling is limited to 302 points and does not change the integration step. Interpolated acceleration times are estimates from sampled points. The source panel exposes applied inputs, clock paths, duration and integration step for each run.

Available models and integration settings

Identifier	Duration / step	Adaptation
cart	1-10 s / 0.1 s	Connected force ports; exact constant-force position update.
mass-spring	10 s / 0.002 s	Contributed semi-implicit acceleration, velocity and position order.
dc-motor	0.035 s / 50 microseconds	Maxon DCX 22 L parameters and sequential electrical/mechanical update.
pid-motor	0.12 s / 50 microseconds	Current-limited PID, anti-windup and load disturbance at 0.06 s.
vehicle-drivetrain	12 s / 0.01 s	EMRAX torque/power envelope; wheel forces aggregated without tire slip.
hybrid-powertrain / hybrid-p4	20 s / 0.01 s (P1), 0.05 s (P4)	Contributed power allocation, traction, fuel and battery accounting.
cubesat	1-5 synthetic 5400 s orbits / 60 s	Scheduled sunlight/contact, energy storage and conserved data flow.
orbit	1-6 orbits, rounded to 60 s / 60 s	Explicit RK4 J2 propagation; spherical Earth station geometry replaces WGS84 geodesy.
cubesat-orbit	6 orbits / 60 s	A connected contact signal drives radio transfer and bounded data storage.
landing-gear	55 s / 0.1 s	Quasi-static hydraulic flow replaces compressible inner RK4 dynamics; sequence, loads, interlocks and fault isolation remain explicit.
uav-propulsion	8-12 s / 0.02 s	Explicit midpoint integration; offline manufacturer fit and contributed throttle schedule.

The landing-gear adaptation does not reproduce pressure transients or exact report completion times. Its default retraction is about 30.8 s. The original PDF remains unchanged. Orbital contact times can also differ because of the spherical station approximation and synthetic epoch. Engineering assumptions in the original reports, including reduced-order fuel estimates and UAV transient constants, continue to apply. Manufacturing, TurtleBot3 and UR5e are excluded until corresponding implementations are supplied.

Units and language boundaries

Physical attributes use the existing ISQ quantity types and SI units, with normalization before dimensionless-only functions. Model coefficients carry explicit unit suffixes. Orbital states (km and km/s), information storage (Mbit) and UAV numerical states are normalized scalar coordinates: their documented units are not automatic dimensional guarantees. The current profile has no information-quantity type. No unsupported units, globals, imports, loops or callbacks are added to the authoring language to accommodate these demos.

The orbit RK4 and UAV midpoint stages are generated as readable, explicit assignments by scripts/build_demo_sources.py. Generation uses loops; the resulting model source does not. The cart and orbit/storage examples include actual connected signals, rather than merely showing two unrelated subsystems.

Validation and provenance

Every generated SysML source was checked with the pinned Systems Modeling 2024-07 pilot compiler, as a complete bundle. models/validation.json records individual Python and SysML SHA-256 hashes and the compiler’s aggregate report. The runtime checks these hashes before accepting a model. Numerical input changes do not change the source and therefore do not invalidate that report. Python compilation is checked against the exact prevalidated SysML text. Passing this snapshot does not establish compatibility with every later SysML release.

With the development formatter Black installed, regenerate after source changes:

python scripts/build_demo_sources.py
python scripts/build_demo_artifacts.py

The latter requires Java and the pinned compiler/library, fails on any compiler error, and writes artifacts only after successful validation. CI checks paired graph equivalence, parameter bounds, conservation, reference results, downloads, fault scenarios and official compilation. Source edits in a downloaded bundle trigger fresh official validation; configure SYSML_PILOT_JAR and SYSML_LIBRARY_PATH when using an installed wheel outside this checkout.

Ghadeer Zarifa contributed the original implementations in commit 3138d223800eb2bdf79743f64b6ae9ffd34eed1e. They remain unchanged in tests. models/provenance.json records their original paths and hashes. The four PDFs and contributed PNGs are distributed unchanged, with an allowlist determining which demo can expose each file. Uploaded figures are fixed reference results; the live SVG charts show the adapted model and current input values.

API reference

These entries are generated from Python docstrings during the documentation build.

sysml2py.demos.profiles.execute(identifier, parameters=None, *, language='sysml')

Run a contributed model through the bounded SysML execution engine.

Parameters:

• identifier (str) – One of the twelve available contributed demos.

• parameters (dict | None) – Partial bounded numeric input values.

• language (str) – sysml or python; both execute the same equations.

Returns:

Paired source, applied inputs, timing, initial hierarchy, chart series, metrics, checks and source validation provenance.

Return type:

dict

Raises:

• ValueError – Unknown inputs, invalid bounds or unsupported language.

• RuntimeError – Source artifacts no longer match their official report.

sysml2py.demos.profiles.sources(identifier)

Return the validated baseline Python and SysML source strings.

Parameters:

identifier (str) – A contributed gallery identifier.

Returns:

Restricted Python and its generated SysML. Runs supply numeric inputs separately, so this source remains identical for all runs.

Return type:

tuple[str, str]

sysml2py.demos.profiles.configuration(identifier, parameters)

Return clock settings and fully qualified inputs for ConnectedModel.

Parameters:

• identifier (str) – A contributed gallery identifier.

• parameters (dict) – Partial bounded numeric inputs; defaults fill omissions.

Returns:

Fixed integration settings and declared inputs.

Return type:

tuple[SimConfig, dict]

sysml2py.demos.source_archive.python_bundle(identifier)

Return a ZIP containing executable paired sources and a local runner.

Parameters:

identifier (str) – An available contributed demo identifier.

Returns:

ZIP with model.py, model.sysml, parameters.json, validation provenance and run.py. The runner executes the bundled sources.

Return type:

bytes