modelica
A Modelica toolchain written only in Python. It reads Modelica source, flattens it to a DAE, simulates it, and draws it. It also speaks the two exchange standards of the Modelica Association: FMI 3.0 for one component, and SSP 2.0 for a system of them.
The distribution is named
modelica. The git repository keeps its older name,pymodelica. PyPI holds the namepymodelicafor an abandoned Modelon/JModelica.org upload.
pip install modelica # the core: parse, model structure, diagrams. No dependencies.
pip install "modelica[sim]" # adds numpy and scipy, and therefore simulation
Documentation: https://jorgeecardona.gitlab.io/pymodelica/ — the architecture, the example corpus, and seven notebooks that are executed when the site is built.
Status
Pre-alpha. This is a full rewrite of a Python 2 experiment from 2010. No code of that experiment is left. Only the goal is. Python 3.12 or later.
Why this exists
Python has the two ends of a Modelica toolchain and very little of the middle. FMPy and PyFMI run an FMU that some other tool compiled. The tools that compile Modelica — Dymola, OpenModelica, JModelica — are large programs, and none of them is Python.
The middle is not empty. pymoca parses Modelica and
flattens it, and Deltares runs it under RTC-Tools
to control water systems: that is a .mo file to a trajectory, in Python, in industrial
use. It gets there with a fixed step and smooth residuals, because its consumer is an
optimizer.
So the gap is narrower than "nothing does this", 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. And nothing treats the model itself — the flat equations, the incidence structure, the index — as an ordinary Python value that you can read and change.
What else exists is the evidence for both halves of that, tool by tool.
That gap is the project. Every stage is a value you can hold.
The layers
You can use each layer without the layers above it.
| Module | What it does |
|---|---|
modelica.lang |
Modelica source to tokens to an AST. The lexer and the parser are written by hand. They carry source positions, so an error can say where. |
modelica.build |
Python classes to the same AST values. A second front end, not a wrapper around the first. |
modelica.ir |
AST to a flat model: variables, equations, an expression IR. Then matching, BLT sorting and index reduction. |
modelica.sim |
Flat model to an ODE or DAE problem. Solver backends, and events. |
modelica.diagram |
Any of the above to a picture: components and connections, equations and variables, or blocks in solution order. |
modelica.fmi |
FMI 3.0. Read an FMU and simulate it, or export a flat model as one. |
modelica.ssp |
SSP 2.0. Read the .ssd, .ssv and .ssb files in a .ssp, and run a co-simulation master over the components. |
Read the architecture notes for the data model and the order the layers were built in.
What of Modelica it handles
The language is large and this is pre-alpha, so the honest summary is a table, not a claim of completeness. The per-model measurement against the full Modelica Standard Library lives in the coverage notes: about 95 % of its example models parse, fewer simulate end to end. The frontier there is one column below.
| Area | Handled | Not yet |
|---|---|---|
| Equations | der, algebraic, connect (flow/potential and signal), when with reinit, terminate, structural if-equations (a parameter or constant condition), for, assert |
an if-equation on a continuous condition (a run-time structural switch, which is a when) |
| Expressions | full arithmetic and relations, if-expressions, every built-in math function, smooth / noEvent / pre / homotopy, a second derivative written der(der(x)) |
spatialDistribution, delay |
| Structure | components, extends with modification, conditional components, redeclare, import (all three forms), nested packages |
operator overloading, external (C) functions, impure |
| Types | Real / Integer / Boolean, discrete variables, enumerations, unit and min/max attributes, type aliases |
|
| Functions | user-defined functions with algorithm bodies, if and for statements |
|
| Arrays | indexed access, array parameters and starts, element-wise array equations (der(x) = -x, a scalar broadcast, an element-wise call) and array products (the dot product, matrix-vector der(x) = A * x, matrix-matrix), a for loop, multi-dimensional grids |
array / and ^ (write them over the elements in a for loop) |
| Numerics | index reduction (Pantelides), alias elimination, BLT sorting, adaptive stiff integration (Radau, LSODA), state events, a sparse Jacobian | a symplectic integrator |
| Standards | FMI 3.0 (import and export), SSP 2.0 co-simulation |
The bundled Modelica Standard Library slice carries Units.SI, Electrical.Analog,
Mechanics.Translational and Rotational, Thermal.HeatTransfer, and a piece of Blocks,
under their real names, so a model that references Modelica.* resolves without configuration. It
is a curated subset, not the whole library.
See a model
A Modelica model is a graph. The components are the boxes and connect() gives the lines.
The source text holds that graph, but a person cannot see it there. After flattening it is
gone: the equations keep every piece of the information and none of the shape.
python -m modelica.diagram examples/models/DCMotor.mo examples/library/Electrical.mo \
examples/library/Rotational.mo examples/library/Machines.mo --depth 2 > motor.svg
The picture needs no other program. This package draws the SVG itself. The image names no colour, so it reads correctly on a light page and on a dark one.
from modelica import diagram
picture = diagram.of("examples/models/RLCCircuit.mo", "examples/library/Electrical.mo")
picture.write("rlc.svg") # an image
print(picture.to_mermaid()) # or text for a Markdown page
print(picture.to_dot()) # or source for Graphviz
A notebook shows the picture when you put it on the last line of a cell.
Development
make install-hooks # once, after you clone. A pre-commit hook 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, which is moon and uv. proto install brings up all of
it. moon.yml holds the order of every task, and CI runs one command: moon run :ci.
Releasing
There is no manual release step. The version in pyproject.toml is the only source of
truth.
- The pre-commit hook increases the patch version when a file under
src/**/*.pychanges. scripts/ci-version-guardfails the pipeline if the shipped source moved and the version did not. A hook can be bypassed. This cannot.- On
main,moon run :releasepublishes to PyPI, but only if that version is not there yet. It uses GitLab OIDC Trusted Publishing, so no API token is stored anywhere.
The same pipeline publishes the documentation to GitLab Pages.
The documentation
The documentation is at https://jorgeecardona.gitlab.io/pymodelica/. The same pipeline that tests the code builds it, and it executes every notebook on the way, so a page that stopped working fails the build.
The pages follow ASD-STE100 Simplified Technical English. How these pages are written lists the rules and the two places this project departs from them.
License
MIT © Jorge Cardona
Trademarks
Modelica® is a registered trademark of the Modelica Association. FMI and SSP are also its trademarks. This page uses those names to identify the language this software reads and the standards it implements.
1 maintainer
Metadata
1 maintainer
Release files for modelica 0.0.166
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| modelica-0.0.166.tar.gz | 821.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| modelica-0.0.166-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.1 MB
Release files / modelica-0.0.166.tar.gz
| Download URL | modelica-0.0.166.tar.gz |
|---|---|
| Size | 821.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7ce1f368c01a49c79412a66c36ad161a8e6d8996fa1f1847f6c1502584212134
|
|
BLAKE2b-256 checksum How to use checksums |
aa5eba6919efef8fe26cc851fc39c7fdcc48b2d8a90e87e42b7c03ec88bf6c0b
|
| 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.166-py3-none-any.whl
| Download URL | modelica-0.0.166-py3-none-any.whl |
|---|---|
| Size | 314.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
61278f3f798e8267991fd1a7fca162cc7e684a45c94954618ad3096be550fc93
|
|
BLAKE2b-256 checksum How to use checksums |
b98f9d77190f9ad353ffc61628b03ee5cceab015a8d1f6fd9c985f6c98abe032
|
| 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}
|
