modelica 0.0.1__tar.gz

modelica-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+site/
+public/
+.moon/cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+logs/

modelica-0.0.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented here. Versions follow
+[semantic versioning](https://semver.org/); the version in `pyproject.toml` is the single
+source of truth and is bumped automatically when shipped source changes.
+
+## 0.0.1 — unreleased
+
+Project restart. The 2010 Python 2 / pyparsing prototype is retired (it remains in git
+history); nothing from it is carried forward.
+
+- Claim the `modelica` distribution name on PyPI.
+- Repository moved from GitHub to GitLab (`gitlab.com/jorgeecardona/pymodelica`).
+- Toolchain: uv + moon pinned via proto; ruff (`select = ["ALL"]`) and pyright strict.
+- Single-job GitLab CI driven by `moon run :ci`; PyPI releases via OIDC Trusted
+  Publishing; docs on GitLab Pages.
+- Python 3.11+ only.

modelica-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Cardona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modelica-0.0.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: modelica
+Version: 0.0.1
+Summary: Pure-Python Modelica toolchain: parse, flatten, simulate, and exchange via FMI 3.0 and SSP 2.0
+Project-URL: Homepage, https://gitlab.com/jorgeecardona/pymodelica
+Project-URL: Repository, https://gitlab.com/jorgeecardona/pymodelica
+Project-URL: Changelog, https://gitlab.com/jorgeecardona/pymodelica/-/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://jorgeecardona.gitlab.io/pymodelica/
+Author-email: Jorge Cardona <jorgeecardona@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: co-simulation,dae,digital-twin,fmi,fmu,modelica,simulation,ssp,system-modeling
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Provides-Extra: sim
+Requires-Dist: numpy>=2.0; extra == 'sim'
+Requires-Dist: scipy>=1.13; extra == 'sim'
+Provides-Extra: sundials
+Requires-Dist: scikit-sundae>=1.0; extra == 'sundials'
+Description-Content-Type: text/markdown
+
+# modelica
+
+A pure-Python Modelica toolchain: **parse** Modelica, **flatten** it to a DAE, **simulate**
+it, and interoperate with the two Modelica Association exchange standards — **FMI 3.0**
+for single components and **SSP 2.0** for systems of them.
+
+> Distribution name is `modelica`; the git repo keeps its historical name `pymodelica`.
+> (PyPI's `pymodelica` is held by an abandoned Modelon/JModelica.org upload.)
+
+```bash
+pip install modelica          # core: parse + model structure, zero dependencies
+pip install "modelica[sim]"   # + numpy/scipy for simulation
+```
+
+## Status
+
+Pre-alpha. This is a **full rewrite** of a 2010 Python 2 experiment — none of that code
+survives, only the goal. Python 3.11+.
+
+## Why
+
+The Python side of Modelica is split: [FMPy](https://github.com/CATIA-Systems/FMPy) and
+[PyFMI](https://github.com/modelon-community/PyFMI) *consume* FMUs that some other tool
+compiled, and the tools that actually compile Modelica (Dymola, OpenModelica, JModelica)
+are large non-Python programs. Nothing in Python takes Modelica source all the way to a
+running simulation, and nothing treats the model — flat equations, the incidence structure,
+the index — as an ordinary Python data structure you can inspect and rewrite.
+
+That gap is the project: a readable, dependency-light implementation where every stage is a
+value you can hold.
+
+## Layers
+
+Each layer is usable without the ones above it.
+
+| Module | Does |
+| --- | --- |
+| `modelica.lang` | Modelica source → tokens → AST (hand-written lexer/parser, positions carried for diagnostics) |
+| `modelica.ir` | AST → flat model (variables, equations, expression IR), then matching / BLT sorting / index reduction |
+| `modelica.sim` | flat model → ODE/DAE problem, solver backends, event (zero-crossing) handling |
+| `modelica.fmi` | FMI 3.0 — read and simulate an FMU; export a flat model as one |
+| `modelica.ssp` | SSP 2.0 — `.ssd`/`.ssv`/`.ssb` inside a `.ssp`, and a co-simulation master over the components |
+
+See [the architecture notes](docs/architecture.md) for the data model and the order things
+get built in.
+
+## Development
+
+```bash
+make install-hooks   # once after cloning: pre-commit (auto version bump + ruff), pre-push (full check)
+make check           # lint + typecheck + test, exactly what CI gates on
+make docs            # build the mkdocs site strictly
+```
+
+The toolchain is pinned in `.prototools` (moon + uv) — `proto install` brings up
+everything. All task ordering lives in `moon.yml`; CI is a single `moon run :ci`.
+
+## Releasing
+
+There is no manual release step. `pyproject.toml`'s `version` is the single source of
+truth:
+
+* the pre-commit hook auto-bumps the patch version whenever `src/**/*.py` changes;
+* `scripts/ci-version-guard` fails the pipeline if shipped source moved without a bump
+  (the non-bypassable counterpart);
+* on `main`, `moon run :release` publishes to PyPI **only if that version isn't there
+  yet**, via GitLab OIDC Trusted Publishing — no API token is stored anywhere.
+
+Docs are published to GitLab Pages from the same pipeline.
+
+## License
+
+MIT © Jorge Cardona

modelica-0.0.1/README.md

@@ -0,0 +1,73 @@
+# modelica
+
+A pure-Python Modelica toolchain: **parse** Modelica, **flatten** it to a DAE, **simulate**
+it, and interoperate with the two Modelica Association exchange standards — **FMI 3.0**
+for single components and **SSP 2.0** for systems of them.
+
+> Distribution name is `modelica`; the git repo keeps its historical name `pymodelica`.
+> (PyPI's `pymodelica` is held by an abandoned Modelon/JModelica.org upload.)
+
+```bash
+pip install modelica          # core: parse + model structure, zero dependencies
+pip install "modelica[sim]"   # + numpy/scipy for simulation
+```
+
+## Status
+
+Pre-alpha. This is a **full rewrite** of a 2010 Python 2 experiment — none of that code
+survives, only the goal. Python 3.11+.
+
+## Why
+
+The Python side of Modelica is split: [FMPy](https://github.com/CATIA-Systems/FMPy) and
+[PyFMI](https://github.com/modelon-community/PyFMI) *consume* FMUs that some other tool
+compiled, and the tools that actually compile Modelica (Dymola, OpenModelica, JModelica)
+are large non-Python programs. Nothing in Python takes Modelica source all the way to a
+running simulation, and nothing treats the model — flat equations, the incidence structure,
+the index — as an ordinary Python data structure you can inspect and rewrite.
+
+That gap is the project: a readable, dependency-light implementation where every stage is a
+value you can hold.
+
+## Layers
+
+Each layer is usable without the ones above it.
+
+| Module | Does |
+| --- | --- |
+| `modelica.lang` | Modelica source → tokens → AST (hand-written lexer/parser, positions carried for diagnostics) |
+| `modelica.ir` | AST → flat model (variables, equations, expression IR), then matching / BLT sorting / index reduction |
+| `modelica.sim` | flat model → ODE/DAE problem, solver backends, event (zero-crossing) handling |
+| `modelica.fmi` | FMI 3.0 — read and simulate an FMU; export a flat model as one |
+| `modelica.ssp` | SSP 2.0 — `.ssd`/`.ssv`/`.ssb` inside a `.ssp`, and a co-simulation master over the components |
+
+See [the architecture notes](docs/architecture.md) for the data model and the order things
+get built in.
+
+## Development
+
+```bash
+make install-hooks   # once after cloning: pre-commit (auto version bump + ruff), pre-push (full check)
+make check           # lint + typecheck + test, exactly what CI gates on
+make docs            # build the mkdocs site strictly
+```
+
+The toolchain is pinned in `.prototools` (moon + uv) — `proto install` brings up
+everything. All task ordering lives in `moon.yml`; CI is a single `moon run :ci`.
+
+## Releasing
+
+There is no manual release step. `pyproject.toml`'s `version` is the single source of
+truth:
+
+* the pre-commit hook auto-bumps the patch version whenever `src/**/*.py` changes;
+* `scripts/ci-version-guard` fails the pipeline if shipped source moved without a bump
+  (the non-bypassable counterpart);
+* on `main`, `moon run :release` publishes to PyPI **only if that version isn't there
+  yet**, via GitLab OIDC Trusted Publishing — no API token is stored anywhere.
+
+Docs are published to GitLab Pages from the same pipeline.
+
+## License
+
+MIT © Jorge Cardona

modelica-0.0.1/docs/architecture.md

@@ -0,0 +1,110 @@
+# Architecture
+
+The design rule for this rewrite: **every stage is a value you can hold.** Parsing returns
+an AST, flattening returns a flat model, causalization returns a sorted block structure,
+and simulation returns trajectories — each one an ordinary, inspectable Python object
+rather than state hidden inside a compiler. The 2010 prototype failed the other way: the
+grammar (pyparsing) *was* the program, so there was nothing to look at between "source" and
+"result".
+
+Nothing here is implemented yet. This is the target, and the order it gets built in.
+
+## The pipeline
+
+```
+Modelica source
+   │  modelica.lang            hand-written lexer + recursive-descent parser
+   ▼
+AST                            positions carried on every node (diagnostics)
+   │  modelica.ir              instantiation / flattening
+   ▼
+FlatModel                      variables + equations + expression IR
+   │  modelica.ir              matching, BLT sorting, index reduction
+   ▼
+CausalizedModel                sorted blocks, known index, states chosen
+   │  modelica.sim             residual/RHS construction
+   ▼
+Problem  ──►  Solver  ──►  Result
+```
+
+Two exchange formats cut across it:
+
+* **FMI 3.0** (`modelica.fmi`) attaches at both ends — read an FMU someone else compiled
+  and simulate it through the same `Problem`/`Solver` interface, or export a
+  `CausalizedModel` as an FMU.
+* **SSP 2.0** (`modelica.ssp`) sits above — a `.ssp` names components (usually FMUs) and
+  wires them, so it drives a co-simulation master over several `Problem`s at once.
+
+## Layer notes
+
+### `modelica.lang` — source → AST
+
+Hand-written lexer and recursive-descent parser against the Modelica Language
+Specification 3.x grammar. No parser-generator and no `pyparsing`: the grammar is stable
+and small enough to write out, and only a hand-written parser gives usable errors
+("expected `end <name>;` at 12:5, to close `model Foo` opened at 3:1"). AST nodes are
+frozen dataclasses carrying source spans.
+
+### `modelica.ir` — AST → solvable system
+
+The interesting layer, and the one the whole project stands on.
+
+* **Flattening** — resolve `extends`, expand components and `for`-equations, apply
+  modifications, connect `connect()` equations into their potential/flow forms. Output:
+  a `FlatModel` of typed variables and scalar equations over an expression IR.
+* **Expression IR** — separate from the AST on purpose. The AST mirrors what was written;
+  the IR is what gets differentiated and evaluated, so it is small, typed, and closed under
+  symbolic differentiation.
+* **Matching + BLT** — bipartite matching of equations to unknowns, then Tarjan SCC to get
+  block-lower-triangular form: which equations must be solved simultaneously and which are
+  a straight assignment sequence.
+* **Index reduction** — Pantelides to find the structurally singular subsets, symbolic
+  differentiation of those equations, and the dummy-derivative method to select states.
+  A high-index DAE is the normal case for a physical model written with `connect()`; a
+  toolchain that cannot reduce the index cannot simulate a mechanical model at all.
+
+### `modelica.sim` — running it
+
+`Problem` is the interface every backend consumes: an explicit ODE where causalization
+achieved one, a residual DAE otherwise. Backends:
+
+* **scipy** (`sim` extra) — `solve_ivp` for ODE form, plus root-finding for the algebraic
+  blocks. The default, because it installs everywhere.
+* **SUNDIALS IDA** via [scikit-SUNDAE](https://github.com/NREL/scikit-sundae) (`sundials`
+  extra) — real index-1 DAE integration with consistent initialization. Optional because it
+  needs a compiled SUNDIALS.
+
+Events (zero crossings from `if`/`when`, and state events generally) are the part that
+makes this harder than "call an integrator": the solver must stop at the crossing, the
+model is re-initialized, and integration restarts. That is designed in from the start, not
+bolted on.
+
+### `modelica.fmi` — FMI 3.0
+
+`modelDescription.xml` parsed into dataclasses (variables, causality/variability, model
+structure, unit definitions), the FMU's shared library loaded through `ctypes`, and both
+interface types wrapped: Model Exchange (the FMU supplies the derivatives, we integrate)
+and Co-Simulation (the FMU integrates itself between communication points). Export goes the
+other way: a `CausalizedModel` plus a generated `modelDescription.xml`, with the FMU's C
+entry points backed by the Python evaluator.
+
+### `modelica.ssp` — SSP 2.0
+
+A `.ssp` is a zip: `SystemStructure.ssd` (components, connectors, connections, possibly
+nested systems), `.ssv` parameter sets, `.ssb` bindings. Parsed into a composition graph,
+resolved against the FMUs it references, and executed by a co-simulation master that steps
+the components and exchanges signals at communication points. SSP 2.0 specifics that matter
+to the data model: FMI 3.0 component support, the `structuralParameter` connector kind,
+clocked connectors, and arrays in connectors/connections.
+
+## Build order
+
+1. `lang` + `ir` far enough to flatten a trivial `model` into scalar equations.
+2. `sim` on the explicit-ODE case, scipy backend — first end-to-end simulation.
+3. Matching/BLT, then Pantelides + dummy derivatives — first physical model with
+   `connect()`.
+4. `fmi` import (read + simulate an existing FMU) — validates the variable/model-structure
+   data model against real files.
+5. Events.
+6. `fmi` export.
+7. `ssp` composition + co-simulation master.

modelica-0.0.1/docs/changelog.md

@@ -0,0 +1,3 @@
+# Changelog
+
+--8<-- "CHANGELOG.md"

modelica-0.0.1/docs/index.md

@@ -0,0 +1,31 @@
+# modelica
+
+Pure-Python Modelica toolchain: parse Modelica, flatten it to a DAE, simulate it, and
+exchange models via **FMI 3.0** and **SSP 2.0**.
+
+```bash
+pip install modelica          # core: parse + model structure, zero dependencies
+pip install "modelica[sim]"   # + numpy/scipy for simulation
+```
+
+!!! warning "Pre-alpha"
+    A full rewrite of a 2010 prototype, in progress. The API is not stable and the layers
+    below are being built bottom-up. Python 3.11+.
+
+## The layers
+
+| Module | Does |
+| --- | --- |
+| `modelica.lang` | Modelica source → tokens → AST |
+| `modelica.ir` | AST → flat model; matching, BLT sorting, index reduction |
+| `modelica.sim` | flat model → ODE/DAE problem; solvers and events |
+| `modelica.fmi` | FMI 3.0 — import, simulate, and export FMUs |
+| `modelica.ssp` | SSP 2.0 — system composition and a co-simulation master |
+
+Start with [Architecture](architecture.md) for the data model and the build order.
+
+## Standards targeted
+
+* **Modelica Language Specification 3.x**
+* **FMI 3.0** — [fmi-standard.org](https://fmi-standard.org/)
+* **SSP 2.0** — [ssp-standard.org](https://ssp-standard.org/)

modelica-0.0.1/pyproject.toml

@@ -0,0 +1,123 @@
+[project]
+# modelica — a pure-Python Modelica/FMI/SSP toolchain: parse Modelica, flatten it to a
+# DAE, simulate it, and interoperate with the two Modelica Association exchange standards
+# (FMI 3.0 for single components, SSP 2.0 for systems of them).
+#
+# The distribution name is `modelica`, not `pymodelica`: PyPI's `pymodelica` is held by an
+# abandoned Modelon/JModelica.org upload (version "trunk"). The git repo keeps the
+# historical name; the import package matches the distribution.
+name = "modelica"
+version = "0.0.1"
+description = "Pure-Python Modelica toolchain: parse, flatten, simulate, and exchange via FMI 3.0 and SSP 2.0"
+readme = "README.md"
+# 3.11+, no compatibility shims: this is a full rewrite of a 2010 Python 2 codebase, and
+# the modelling layer leans on 3.11 features (Self, StrEnum, exception groups for
+# multi-error diagnostics, and the tomllib/typing niceties) rather than back-porting them.
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jorge Cardona", email = "jorgeecardona@gmail.com" }]
+keywords = [
+    "modelica",
+    "fmi",
+    "fmu",
+    "ssp",
+    "simulation",
+    "dae",
+    "co-simulation",
+    "digital-twin",
+    "system-modeling",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+# Deliberately dependency-free at the core. The parser is hand-written (no pyparsing —
+# that was the 2010 design and it could not carry error positions), the FMI/SSP layers
+# read XML from the stdlib, and numeric backends arrive as extras so `import modelica`
+# stays cheap for tooling that only reads model structure.
+dependencies = []
+
+[project.optional-dependencies]
+# Numerics for the simulation layer. scipy covers ODE + the algebraic solves; the SUNDIALS
+# IDA binding for real (index-1) DAEs is a separate extra because it needs a compiled
+# SUNDIALS and must not be a hard requirement of `pip install modelica`.
+sim = ["numpy>=2.0", "scipy>=1.13"]
+sundials = ["scikit-sundae>=1.0"]
+# docs are an *extra* (not a uv dependency-group) so external services can install them via pip
+docs = ["mkdocs>=1.6", "mkdocs-material>=9.5"]
+
+[project.urls]
+Homepage = "https://gitlab.com/jorgeecardona/pymodelica"
+Repository = "https://gitlab.com/jorgeecardona/pymodelica"
+Changelog = "https://gitlab.com/jorgeecardona/pymodelica/-/blob/main/CHANGELOG.md"
+Documentation = "https://jorgeecardona.gitlab.io/pymodelica/"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modelica"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "docs", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6",
+    "pyright>=1.1.390",
+    "pytest>=8",
+    "pytest-cov>=6",
+    "numpy>=2.0",
+    "scipy>=1.13",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# Strict: everything on, each opt-out justified.
+select = ["ALL"]
+ignore = [
+    "E501",    # line length is the formatter's job (line-length = 100)
+    "COM812",  # trailing commas conflict with `ruff format` (ruff's own recommendation)
+    "D1",      # not every helper owes a docstring; the ones that exist explain *why*
+    "D401",    # docstrings here are narrative rationale, not imperative summaries
+    "TRY003", "EM101", "EM102",  # inline exception messages; msg-variable style adds noise
+    "CPY001",  # per-file copyright headers; LICENSE covers the repo
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "S101",    # asserts are the point of tests
+    "PLR2004", # literal expectations in asserts are clearer than named constants
+    "ARG",     # pytest fixture signatures are fixed; params can go unused
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.isort]
+known-first-party = ["modelica"]
+
+[tool.pyright]
+include = ["src", "tests"]
+extraPaths = ["src"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"

modelica-0.0.1/src/modelica/__init__.py

@@ -0,0 +1,21 @@
+"""Pure-Python Modelica toolchain: parse, flatten, simulate, exchange.
+
+The package is layered, and each layer is usable without the ones above it:
+
+* ``modelica.lang``  -- Modelica source -> tokens -> AST (hand-written lexer/parser).
+* ``modelica.ir``    -- AST -> flat model: variables, equations, an expression IR;
+  then matching/BLT sorting and index reduction down to a solvable system.
+* ``modelica.sim``   -- the flat model as an ODE/DAE problem plus solver backends and
+  event (zero-crossing) handling.
+* ``modelica.fmi``   -- FMI 3.0: read/simulate an existing FMU, and export a flat model
+  as one.
+* ``modelica.ssp``   -- SSP 2.0: system composition (.ssd/.ssv/.ssb inside a .ssp) and a
+  co-simulation master over the components it names.
+
+``import modelica`` pulls in no third-party dependency; numerics live behind the ``sim``
+extra so that tooling which only reads model *structure* stays cheap to install.
+"""
+
+__version__ = "0.0.1"
+
+__all__ = ["__version__"]

modelica-0.0.1/tests/test_version.py

@@ -0,0 +1,22 @@
+"""The version in ``modelica.__version__`` mirrors pyproject's.
+
+scripts/bump-version rewrites both, and this is what catches it when only one of them moves.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from pathlib import Path
+
+import modelica
+
+
+def test_version_matches_pyproject() -> None:
+    pyproject = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    assert modelica.__version__ == data["project"]["version"]
+
+
+def test_version_is_semver() -> None:
+    assert re.fullmatch(r"\d+\.\d+\.\d+", modelica.__version__)