Local engine reference

These entry points use the current connected behavior profile shared by the Studio worker, CLI and VS Code extension. Install the core engine from this checkout to use them. Internal parser helpers and the legacy callback API are outside this reference’s scope.

Simulation configuration

class sysml2py.SimConfig(initial_time=0, end_time=None, step_size=1, steps_to_snapshot=1, max_steps=None, time_attribute=None, step_attribute=None)[source]

Times are numeric; snapshots are recorded every N completed steps.

The initial and final states are always recorded. A final partial step lands exactly on end_time, and callbacks receive its actual duration.

Variables:

  • initial_time (float) – Initial time in seconds, default zero.

  • end_time (float | None) – Final time in seconds. Connected models require a finite end time; the legacy runtime can also stop through callbacks.

  • step_size (float) – Positive time-step duration in seconds, default one.

  • steps_to_snapshot (int) – Record every N completed steps, default one.

  • max_steps (int | None) – Optional positive step limit; runtime resource limits may additionally apply.

  • time_attribute (str | None) – Fully qualified declared duration input populated with the connected simulation clock.

  • step_attribute (str | None) – Fully qualified declared duration input populated with the actual step duration.

Parameters:

  • initial_time (float)

  • end_time (float | None)

  • step_size (float)

  • steps_to_snapshot (int)

  • max_steps (int | None)

  • time_attribute (str | None)

  • step_attribute (str | None)

Time arguments also accept compatible quantity dictionaries, such as {"value": 500, "unit": "ms"}; validation normalizes them to seconds.

validate()[source]

Normalize time quantities and check finite values and positive limits.

Returns:

This configuration has been normalized in place.

Return type:

None

Raises:

ValueError – Times, step size or sampling/step limits are invalid.

Connected models

class sysml2py.modelgraph.ConnectedModel(graph, documents=None)[source]

A resolved model using the same behavior profile as Studio jobs and the CLI.

Prefer from_documents() over constructing this dataclass directly.

Variables:

  • graph (dict) – Resolved instances, attributes, connections and behaviors.

  • documents (list | None) – SysML source bundle and revision provenance. Source export and reference validation require these documents.

Parameters:

  • graph (dict)

  • documents (list | None)

classmethod from_documents(documents)[source]

Resolve linked SysML and supported Python source without executing it.

Parameters:

documents (Iterable[dict]) – Dependency-ordered sources with the root last. Each has project_id and source; language defaults to sysml and can be python. Revision metadata is retained.

Returns:

Profile-checked graph with converted SysML source.

Return type:

ConnectedModel

Raises:

  • ModelError – A declaration, connection, expression or unit is invalid.

  • ValueError – Python translation or reference validation fails.

  • RuntimeError – Typed Python needs an unavailable reference compiler.

This method does not fetch files or server revisions. Typed Python requires reference validation; SysML sources can be checked explicitly with validate() in addition to the execution-profile check.

to_sysml()[source]

Return the complete source bundle joined as standalone SysML text.

Returns:

Dependency sources followed by the root source.

Return type:

str

Raises:

ValueError – This object was constructed without source documents.

validate()[source]

Validate the complete bundle with the pinned reference compiler.

Returns:

Successful reference report, diagnostics and compiler metadata.

Return type:

dict

Raises:

  • ValueError – Source provenance is missing or reference validation fails.

  • RuntimeError – Java or matching reference compiler resources are absent.

input_schema()[source]

Describe undriven inputs and required values in the resolved model.

Returns:

Fully qualified paths mapped to unit, type, value, required and direction. Connected and bound targets are omitted.

Return type:

dict

simulate(config, *, snapshot_stride=None, inputs=None, initial_values=None, events=None)[source]

Execute the bounded behavior profile locally from its initial state.

Parameters:

  • config (sysml2py.SimConfig) – Time bounds, step size, sample stride, step limit and optional clock bindings. Connected simulation requires a finite end_time.

  • snapshot_stride (int | None) – Positive sampling stride overriding config.steps_to_snapshot; None uses that configuration value.

  • inputs (dict | None) – Undriven declared input paths mapped to scalars, {value, unit} quantities or {samples: [{time, value}], unit} ordered signals.

  • initial_values (dict | None) – Stored-attribute initial overrides; driven, bound and otherwise prohibited paths are rejected.

  • events (list[dict] | None) – Scheduled {time, target, event} records targeting declared state machines. Time is in seconds.

Returns:

rows with time first, attributes and corresponding units for the remaining columns, plus stop reason, evaluated checks, states and events. Initial and final snapshots are included. This local dictionary is not the remote results.json envelope.

Return type:

dict

Raises:

ValueError – Invalid timing, stride, input values, units or events.

sysml2py.modelgraph.compose_subsystems(package, components, connections, documents, *, official=True)[source]

Instantiate reusable definitions from dependency documents and wire ports.

Parameters:

  • package (str) – Identifier for the new composition package.

  • components (dict[str, str]) – Instance names mapped to fully qualified part definitions, such as {"battery": "Batteries::Cell"}.

  • connections (Iterable[tuple[str, str]]) – Directed source/target port pairs, such as ("battery.supply", "controller.input").

  • documents (Iterable[dict]) – Source documents defining the reusable types.

  • official (bool) – Run reference validation after profile checks. Defaults to True; False is only an explicit local development opt-out.

Returns:

Full bundle including the generated composition source.

Return type:

ConnectedModel

Raises:

  • ValueError – Invalid names, empty composition or incompatible connections.

  • RuntimeError – Required reference compiler resources are unavailable.

Typed Python authoring

sysml2py.authoring.compile_python(source, *, package='PythonModel', documents=(), official=True, validator=None)[source]

Translate restricted annotated Python into checked SysML without execution.

Parameters:

  • source (str) – Supported declarative Python source, not arbitrary scripts.

  • package (str) – Default generated package name, unless MODEL_PACKAGE is set.

  • documents (Iterable[dict]) – SysML dependency documents available during scoped name resolution and reference validation.

  • official (bool) – Require reference validation, default True. False is an explicit local development opt-out and does not certify conformance.

  • validator (Callable | None) – Optional reference-validation function used when official is True. It receives the combined SysML text and must raise on invalid source; None uses the pinned reference compiler.

Returns:

Generated root SysML after scope, type, unit and behavior checks. Dependencies are validated together but are not appended to this string.

Return type:

str

Raises:

  • ValueError – Python syntax, names, operations or generated SysML are invalid.

  • RuntimeError – Required reference compiler resources are unavailable.

For a runnable bundle use ConnectedModel.from_documents with the original Python and its dependencies; that path requires reference checks by default.

Reference validation

Java 17 or newer, the pinned compiler JAR and its matching standard library are required. A source checkout discovers its vendored resources. Installed wheels need SYSML_PILOT_JAR and SYSML_LIBRARY_PATH pointing to those resources. Missing tools are errors and are never treated as a valid model.

sysml2py.validation.validate_sysml(source, *, jar=None, library=None, timeout=120)[source]

Run syntax and semantic checks using the pinned SysML pilot compiler.

Parameters:

  • source (str) – Nonempty SysML source, including required dependency text.

  • jar (str | Path | None) – Compiler JAR. Defaults to SYSML_PILOT_JAR or the matching vendored file in a source checkout.

  • library (str | Path | None) – Standard library directory. Defaults to SYSML_LIBRARY_PATH or the checkout’s matching library.

  • timeout (float) – Maximum compiler process duration in seconds.

Returns:

Report containing valid, structured diagnostics, validator, compiler and source_sha256. Invalid source is a report with valid=False, not a successful conformance result.

Return type:

dict

Raises:

  • ValueError – Source is empty or not text.

  • RuntimeError – Java/compiler/library is missing or the compiler fails.

  • subprocess.TimeoutExpired – The compiler exceeds its deadline.

The repository pins a 2024-07 pilot snapshot. Passing it does not establish conformance with every later SysML release or support in the execution profile.

sysml2py.validation.require_valid_sysml(source, **options)[source]

Run reference validation and raise if the source is invalid.

Parameters:

  • source (str) – Complete SysML source bundle.

  • **options – jar, library and timeout for validate_sysml().

Returns:

Successful reference-validation report.

Return type:

dict

Raises:

  • ValueError – Source is invalid, with compiler errors in the message.

  • RuntimeError – Required reference resources are unavailable or fail.