modelica
A Modelica toolchain in pure Python: parse .mo source, flatten it to a DAE, simulate it,
and draw it, with FMI 3.0 and SSP 2.0 support. Every stage is an ordinary Python
value you can read and change. For engineers and researchers who want Modelica semantics
inside Python rather than behind a separate compiler.
Install name is
modelica. The git repository keeps its older name,pymodelica, because PyPI'spymodelicaholds an abandoned Modelon/JModelica.org upload. The import package and the distribution are bothmodelica.
Install
pip install modelica # core: parse, model structure, diagrams. No dependencies.
pip install "modelica[sim]" # adds numpy and scipy, and with them simulation
Status: pre-alpha. A full rewrite of a 2010 Python 2 experiment; no code of it is left, only the goal. Python 3.12 or later.
Quickstart
From Modelica source to a trajectory in four values. Each line is a stage you can stop at.
from modelica.lang import parse
from modelica.sim import flatten, causalize, simulate # needs the sim extra: pip install "modelica[sim]"
source = """
model NewtonCooling "A hot object cooling toward ambient"
parameter Real T_amb = 25;
parameter Real k = 0.5;
Real T(start = 90, fixed = true);
equation
der(T) = -k * (T - T_amb);
end NewtonCooling;
"""
flat = flatten([parse(source)], "NewtonCooling") # AST -> flat DAE
system = causalize(flat) # matching, BLT sort, index reduction
result = simulate(system, stop=10.0) # integrate (Radau by default)
print(system.states) # ('T',)
print(result.time) # the solver's own steps
print(result["T"]) # the trajectory, indexed by the name you wrote
result.plot() returns an interactive chart that writes itself to a self-contained HTML
page with no CDN behind it (result.plot().save("cooling.html")), and in a notebook it
renders when it is the last line of a cell. result.write("cooling.mat") writes a
Dymola-format .mat that ModelicaRes, DyMat and BuildingsPy read.
The layers compose from source to picture the same way. This draws a model to SVG with no other program:
python -m modelica.diagram examples/models/RLCCircuit.mo examples/library/Electrical.mo > rlc.svg
from modelica import diagram
picture = diagram.of("examples/models/RLCCircuit.mo", "examples/library/Electrical.mo")
picture.write("rlc.svg") # an image, light- and dark-safe (it names no colour)
print(picture.to_mermaid()) # or text for a Markdown page
print(picture.to_dot()) # or source for Graphviz
Why modelica
Python has the two ends of a Modelica toolchain and little of the middle.
FMPy and
PyFMI run an FMU that some other tool
compiled. The tools that compile Modelica — OpenModelica (and its OMPython bridge),
Dymola, JModelica — are large programs, and none of them is Python. If you want a
mature, near-complete Modelica compiler for production, reach for one of those; this is not
that yet.
So the gap is narrow and specific, and it is two things:
- Nothing in Python takes Modelica source to a trajectory the way a hybrid model needs — adaptive stiff integration, index reduction, and events the solver stops at.
- Nothing treats the model itself as an ordinary Python value — the flat equations, the incidence structure, the index — that you can read, inspect and change.
That gap is the project. Choose modelica when you want Modelica semantics as a library:
to inspect the flat DAE, script the toolchain, or embed a solver in your own Python. Choose
OpenModelica or Dymola when you need breadth of language coverage today.
Key features
- Two front ends, one IR. A hand-written lexer and recursive-descent parser carry source
positions, so an error says where; a Python builder API (
modelica.build) produces the same AST values. The two are cross-checked against each other. - Dependency-free core.
import modelicapulls in nothing. Numerics arrive as thesimextra (numpy + scipy), so tooling that only reads model structure stays cheap to install. - The flat model is a value. Flattening resolves
extends, modifications andconnect()into scalar variables and acausal equations; causalization does alias elimination, matching, Tarjan BLT sorting and Pantelides index reduction. States, candidate state sets, index and blocks are all readable off theSystem. - Hybrid simulation. Adaptive stiff integration (Radau, LSODA via SciPy), state and time
events with
reinit, a sparse Jacobian, and asserts checked along the trajectory. The IR is compilable by construction:emitwrites the model as straight-line arithmetic. - Diagrams with no extra program. Any layer draws to SVG, Mermaid or DOT — components and connections, the incidence of equations against variables, or blocks in solution order.
- FMI 3.0. Read and simulate an existing FMU, or export a flat model as one
(
modelica.fmi). - SSP 2.0. Read the
.ssd/.ssv/.ssbfiles inside a.sspand run a co-simulation master over the components (modelica.ssp). - A bundled Modelica Standard Library slice under the real
Modelica.*names:Units.SI,Electrical.Analog,Mechanics.TranslationalandRotational,Thermal.HeatTransfer, and a piece ofBlocks. A curated subset, not the whole library.
The layers
Each layer is usable without the ones above it.
| Module | What it does |
|---|---|
modelica.lang |
Modelica source to tokens to an AST, with source positions. |
modelica.build |
Python classes to the same AST values. A second front end. |
modelica.ir |
AST to a flat model; then matching, BLT sorting and index reduction. |
modelica.sim |
Flat model to an ODE/DAE problem; solver backends and events. |
modelica.diagram |
Any of the above to a picture: components, incidence, or blocks. |
modelica.fmi |
FMI 3.0: read an FMU and simulate it, or export a flat model as one. |
modelica.ssp |
SSP 2.0: read a .ssp and run a co-simulation master. |
What of Modelica it handles
The language is large and this is pre-alpha, so the honest summary is a table. About 95 % of the Modelica Standard Library example models the project measures against parse; fewer simulate end to end. The per-model coverage notes track the frontier.
| Area | Handled | Not yet |
|---|---|---|
| Equations | der, algebraic, connect (flow/potential and signal), when with reinit, terminate, structural if-equations, for, assert |
an if-equation on a continuous condition |
| Expressions | full arithmetic and relations, if-expressions, every built-in math function, smooth / noEvent / pre / homotopy, der(der(x)) |
spatialDistribution, delay |
| Structure | components, extends with modification, conditional components, redeclare, import, nested packages |
operator overloading, external (C) functions, impure |
| Types | Real / Integer / Boolean, discrete variables, enumerations, unit and min/max attributes, type aliases |
|
| Functions | user functions with algorithm bodies, if and for statements |
|
| Arrays | indexed access, array parameters and starts, element-wise array equations and products (dot, matrix-vector, matrix-matrix), for loops, multi-dimensional grids |
array / and ^ |
| Numerics | index reduction (Pantelides), alias elimination, BLT sorting, adaptive stiff integration (Radau, LSODA), state events, sparse Jacobian | a symplectic integrator |
| Standards | FMI 3.0 (import and export), SSP 2.0 co-simulation |
Development
make install-hooks # once after cloning: pre-commit bumps the version and runs ruff
make check # lint, typecheck and test. This is what CI runs.
make docs # build the documentation site, strictly
.prototools pins the toolchain (moon and uv); proto install brings it up. moon.yml
holds every task and CI runs one command, moon run :ci. See
AGENTS.md for the full build/test/convention detail and
CONTRIBUTING.md for how to send a change.
Links
- Repository: https://gitlab.com/cardona-oss/pymodelica
- PyPI: https://pypi.org/project/modelica/
- Documentation: https://cardona-oss.gitlab.io/pymodelica/
- Changelog:
CHANGELOG.md
License
MIT © Jorge Cardona
Trademarks
Modelica® is a registered trademark of the Modelica Association. FMI and SSP are also its trademarks. This package is an independent open-source implementation, not affiliated with or endorsed by the Modelica Association; the names identify the language it reads and the standards it implements.
1 maintainer
Metadata
1 maintainer
Release files for modelica 0.0.205
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| modelica-0.0.205.tar.gz | 866.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| modelica-0.0.205-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.2 MB
Release files / modelica-0.0.205.tar.gz
| Download URL | modelica-0.0.205.tar.gz |
|---|---|
| Size | 866.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2261070a080ce930c2a08f61d8e2a79b593aa64fbc02141081f6f05cad9338c0
|
|
BLAKE2b-256 checksum How to use checksums |
277d63d0ec81fcf7e32de0de2366b1d61333e7dda6c7c2bf603afe3eebf16bf3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / modelica-0.0.205-py3-none-any.whl
| Download URL | modelica-0.0.205-py3-none-any.whl |
|---|---|
| Size | 329.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a8365ed4d4cb1e6f66fbe8be89ca0063abca4536ed94cc32eac3ee4aa9fcb222
|
|
BLAKE2b-256 checksum How to use checksums |
4d5341878368eba7990180d61564534ff1dfe19a5bd01f95474b1a19272ba98b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for modelica 0.0.205
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.
