Skip to main content

model-parser

Convert process-model definitions to and from a canonical intermediate representation (IR).

model-parser is the Advanced Process Control toolbox component that owns the model scaffold contract and the transformations around it. It parses an authoring format (today: the ExprTk-style INI used by the MPC / simulation toolchain) into a normalized, backend-independent canonical IR, and lowers that IR into generated Julia and Python model views.

authoring (ExprTk INI)  --parse-->  AST  --normalize-->  canonical IR (JSON)
                                                          |
                                          emit julia      --> ModelingToolkit .jl
                                          emit julia-rhs  --> numerical f!/outputs! .jl
                                          emit python     --> numerical functions .py
                                          emit cpp        --> (planned) realtime C++

The IR is the single semantic contract. Adding a backend means writing one lower + one export, not an N×N mesh of view-to-view translators. See docs/design/model-parser.md for the authoritative product specification and docs/decisions/ for the design decision records.

Why two languages?

Concern Home Why
CLI, AST, IR, JSON Schema, validators, codegen Python (this package) Parsing & orchestration strength; no symbolic runtime needed to emit code.
IR → MTK System, simulation, analysis, conformance Julia (julia/ModelParserJL) Natural fit for ModelingToolkit; reference for parity tests.

The Python CLI builds and validates the IR and generates Julia code; the Julia package can additionally load an IR directly into an MTK System for in-memory, dynamic workflows. Both consume the same IR. See ADR 0001.

Install

CLI from PyPI (end users)

The package on PyPI is apc-model-parser; the installed command is model-parser.

pipx install apc-model-parser
# or: uv tool install apc-model-parser
model-parser --help

Use pipx or uv tool when you only need the CLI in an isolated environment.

From source (development)

This repository uses uv for environments and tasks.

uv sync --all-groups    # include dev tools (ruff, pytest, mkdocs)
uv run model-parser --help

CLI

# 1. ExprTk INI  ->  canonical IR JSON
uv run model-parser parse examples/models/model_monod_simple.ini -o monod.ir.json

# 2. canonical IR  ->  ModelingToolkit (v11) Julia model
uv run model-parser emit julia monod.ir.json -o monod.jl

# 2a. canonical IR  ->  plain numerical ODE RHS (SciML-style f!)
uv run model-parser emit julia-rhs monod.ir.json -o monod_rhs.jl

# 2b. canonical IR  ->  Python ODE RHS and output functions
uv run model-parser emit python monod.ir.json -o monod.py

# Supporting commands
uv run model-parser validate monod.ir.json --profile julia-analysis
uv run model-parser inspect  monod.ir.json
uv run model-parser diff     monod.ir.json other.ir.json   # semantic IR diff
uv run model-parser bump     monod.ir.json other.ir.json   # suggested SemVer bump
uv run model-parser ast      examples/models/model_monod_simple.ini   # debug tree
uv run model-parser schema   -o schemas/canonical-ir.schema.json      # export schema

parse accepts --from exprtk-ini (default). validate accepts either an IR .json file or an INI file (parsed on the fly). Exit codes: 0 success, 1 validation errors, 2 usage / load failure.

How "stored MTK models" work

The persisted, version-controlled form of a model is the IR JSON plus the generated .jl script — not a serialized System object. ModelingToolkit v11 changed System internals significantly (precompilation, removal of defaults, deprecation of @mtkmodel), so serializing the live object is brittle across versions. Regenerating from the IR is the durable path. See ADR 0002 and docs/design/storing-mtk-models.md.

Development

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv run mkdocs build --strict   # same as CI

Documentation site (after Pages is set to GitHub Actions): https://advanced-process-control.github.io/model-parser/

Scope

In scope: authoring-format parsing, the canonical IR data model + JSON Schema, semantic & profile validation, IR↔backend lowering/codegen.

Out of scope: parameter identification, scenario execution, simulation result storage, controller synthesis, deployment. Those are sibling tools that consume the IR. The parser stays small (see AGENTS.md scope guardrails).

Metadata

Release files for apc-model-parser 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for apc-model-parser 0.2.3
File Size Uploaded Provenance Actions
apc_model_parser-0.2.3.tar.gz 117.5 kB With provenance Details for apc_model_parser-0.2.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for apc-model-parser 0.2.3
File Interpreter ABI Platform Actions
apc_model_parser-0.2.3-py3-none-any.whl Python 3 none any Details for apc_model_parser-0.2.3-py3-none-any.whl

Total release size: 147.7 kB

Release files / apc_model_parser-0.2.3.tar.gz

Download URL apc_model_parser-0.2.3.tar.gz
Size 117.5 kB
Tags Source
SHA-256 checksum
How to use checksums
8c08235b4210ae4f03f684c5436db5877fdb678e4d34360f65d51eeed20f499d
BLAKE2b-256 checksum
How to use checksums
30be68f3e5515e2995ea3602572b3685197adfcb9912ba4802f72784e4040d4c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.

Transparency log

Release files / apc_model_parser-0.2.3-py3-none-any.whl

Download URL apc_model_parser-0.2.3-py3-none-any.whl
Size 30.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
908001e2cb4c3559d267a00363a07de0849766d8a7e4c6985e6cc42275e76811
BLAKE2b-256 checksum
How to use checksums
65220cb5de2b3e42ed66cc3dbe5f2b559746e60485441cb15b28b3030658cbde
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.

Transparency log

Security for apc-model-parser 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for apc_model_parser-0.2.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page