aeolus1d 0.3.0__tar.gz

aeolus1d-0.3.0/.gitignore

@@ -0,0 +1,127 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+# Repo-root build/ + dist/ only — the PyInstaller spec lives at
+# ``aeolus1d_gui/build/`` and is intentionally tracked.
+/build/
+/dist/
+# mkdocs build output.
+/site/
+.venv/
+venv/
+.env
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+# CI caches ``.cache/pip`` INTO the build workspace (see .gitlab-ci.yml's
+# ``cache.paths``). hatchling picks sdist contents from what git would track,
+# so while this was unignored ``python -m build`` packaged the entire pip
+# cache: the build-smoke artifact was 231.5 MB against 9.8 MB from a clean
+# tree, and a 231 MB upload over a home link resets often enough that the job
+# failed 4 of 5 attempts. That looked like flaky infrastructure for a whole
+# day. It also meant a release would have shipped a pip cache to PyPI.
+.cache/
+
+.ipynb_checkpoints/
+.idea/
+.vscode/
+*.swp
+*~
+
+run.h5
+*.h5
+!reference_data/*.npz
+outputs/
+
+# graphify outputs — knowledge-graph artifacts (HTML viz, raw
+# graph.json, GRAPH_REPORT.md). Regenerated on every run; no
+# value tracking.
+graphify-out/
+
+# Auto-generated TOML outputs from optimizer runs; intermediate
+# artifacts of long-running fits, not source.
+*.tuned.toml
+
+# Third-party / vendor case files used as local interop fixtures.
+# Cruise M / GT-Suite / GT-Power project files carry vendor IP and
+# proprietary engine-program data; keep them out of the repo.
+# Drop the file at the path below to enable the corresponding
+# integration tests; the tests skip cleanly when the file is
+# absent.
+tests/fixtures/interop/*.proj
+tests/fixtures/interop/*.gt.xml
+tests/fixtures/interop/*.bws
+tests/fixtures/interop/*.wvm
+tests/fixtures/interop/*.gtm
+tests/fixtures/interop/*.gtsub
+# Umbrella folder for user-supplied vendor case files used as
+# local interop fixtures. Stays untracked; the integration
+# tests resolve their fixtures from
+# ``local_cases/<vendor-subfolder>/`` and skip cleanly when
+# absent.
+/local_cases/
+# Defensive root-level globs so vendor case files (Cruise M
+# ``.proj`` archives, GT-Suite ``.gtm``/``.gtsub`` + their
+# binary turbo-map / parameter-table siblings) never end up
+# staged by accident, even if dropped at the repo root in their
+# own folder.
+*.proj
+*.gtm
+*.gtsub
+*.cmp
+*.trb
+*.glx
+*.rlt
+
+
+
+# screenshots from doc rendering issues
+ss*.png
+
+# Claude harness lock files
+.claude/
+
+# Numba JIT cache — primed by ``aeolus1d warmup`` (Phase 2). Bulky,
+# host-specific, and regenerated on demand.
+.numba_cache/
+
+# Transient interop diagnostic dumps (e.g. GT-Suite InteropReport
+# warnings). Captured per-session, not source.
+warnings.txt
+
+# Bundled-example plot artefacts — regenerated by ``plot_*.py``
+# scripts; the scripts are tracked, the PNGs are not.
+examples/plots/*.png
+
+# Validation dataset archives — the CSV under ``data/`` is tracked,
+# the upstream archive + HTML landing page from Mendeley / Ricardo /
+# Argonne / UMich are not (each has its own DATA_LICENSE).
+examples/validation/mendeley_ethanol_water/*.zip
+examples/validation/mendeley_ethanol_water/*.html
+examples/validation/ricardo_ktm/*.zip
+examples/validation/argonne_d3/*.zip
+examples/validation/umich_diesel/*.zip
+
+# ML chemistry surrogate — generated datasets + trained models (regenerable)
+ml_chemistry/data/
+ml_chemistry/models/
+
+# AVL comparison-plot aeolus1d-run cache (regenerable; written by
+# scripts/plot_avl_validation_comparison.py to skip the re-solve on
+# reference-only re-plots).
+examples/validation/**/.aeolus_run_*.pkl
+
+# Local scratch: ad-hoc diagnostics, audit notes, CI watchers, throwaway
+# harnesses. Never source — kept out of the tree so `git add -A` can't sweep it.
+.pipeline/
+
+# Hypothesis' example database — a machine-local cache the plugin writes into
+# the CWD. It is not source, and because it was never ignored, hatchling's
+# default sdist swept 630 of its files into every published tarball. The
+# allow-list in pyproject now keeps them out of the sdist regardless; this
+# keeps them out of `git add -A` as well.
+.hypothesis/

aeolus1d-0.3.0/AUTHORS.md

@@ -0,0 +1,14 @@
+# Authors
+
+aeolus1d is developed and maintained by:
+
+- **Niklas Nordin** <niklas.nordin@nequam.se>
+- **Claude** (Anthropic) — pair-programming assistant
+
+## Acknowledgements
+
+Phase-by-phase contributions are recorded in the git log
+(`git log --format='%h %s'`). The strict-mode arc (Phase 7g.3-burn-*),
+the implicit-solver Picard / JFNK work (Phase I-Y / I-8), and the
+AVL-inspired backlog sweep (Phase A1–H3, L1, E1–E4, F3, G2/G3, I2)
+are all in-tree in `src/aeolus1d/`.

aeolus1d-0.3.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+The full changelog lives at **[docs/changelog.md](docs/changelog.md)**
+— this file is a pointer so community-health scanners, GitHub
+release-notes auto-detection, and `pip show aeolus1d`-style tools
+find a `CHANGELOG.md` at the repo root.
+
+The `docs/` copy is the single source of truth; mirroring would
+drift. Use the table-of-contents below to jump straight to a
+version.
+
+
+## Releases
+
+- **Unreleased** — [v0.3.0 (pre-release) in flight on `main`](docs/changelog.md#v030-pre-release--state-space-linearization--engine-warm-up-arc)
+- **v0.2.0** (2026-05-17) — [standalone repo + validation closures + CI](docs/changelog.md#v020--standalone-repo--validation-closures--ci)
+- **Milestones 1-6** — [docs/changelog.md](docs/changelog.md#milestone-1--pipe-network-core)
+  (pipe-network core → MP5 dispatch closes + optimization driver)
+
+
+## Per-phase technical detail
+
+`docs/changelog.md` summarises each milestone at the
+sentence-per-phase level. For the full blow-by-blow — every
+``@register_closure``, every bench-line delta — see:
+
+- **[docs/phase-log.md](docs/phase-log.md)** — detailed per-phase
+  technical history.
+- **[docs/perf-history.md](docs/perf-history.md)** — Phase Perf-1
+  → Perf-17 before / after numbers.
+
+
+## Convention
+
+aeolus1d follows [Semantic Versioning](https://semver.org). Until
+v1.0, breaking changes happen between minor versions; the entry
+under each version in `docs/changelog.md` calls them out
+explicitly. Phase numbering is internal to the project (~600
+phases across 6 milestones at v0.2.0) and is not tied to SemVer.

aeolus1d-0.3.0/CITATION.cff

@@ -0,0 +1,37 @@
+cff-version: 1.2.0
+message: "If you use aeolus1d in academic work, please cite it as below."
+title: "aeolus1d — a 1D compressible gas-dynamics pipe-network solver"
+abstract: >-
+  aeolus1d is an open-source 1D compressible-Euler pipe-network solver
+  built for engine intake/exhaust simulation, aftertreatment chemistry,
+  and 1D wave-action workflows. Numba-JIT inner kernels run within
+  roughly 3× of hand-tuned Fortran; the solver ships HLLC + MUSCL/MP5,
+  implicit Euler / BDF2 / Radau IIA(3) with analytic Jacobians,
+  Strang-split chemistry, real-gas EOS, full engine + aftertreatment
+  component depth, a Qt/PyVista visual editor, and a validated TOML
+  case format.
+type: software
+authors:
+  - family-names: Nordin
+    given-names: Niklas
+    email: niklas.nordin@nequam.se
+    affiliation: nequam
+  - name: "Claude (Anthropic)"
+    affiliation: "Anthropic — pair-programming assistant"
+version: "0.3.0"
+date-released: "2026-08-16"
+license: MIT
+repository-code: "https://gitlab.com/niklas.nordin.swe/aeolus"
+url: "https://gitlab.com/niklas.nordin.swe/aeolus"
+keywords:
+  - cfd
+  - gas-dynamics
+  - engine-simulation
+  - aftertreatment
+  - 1d-wave-action
+  - numba
+  - compressible-euler
+# DOI placeholder — populated when a Zenodo release is cut (Phase 9
+# of the maturity remediation plan). Replace with the concrete DOI
+# at that point.
+# doi: 10.5281/zenodo.XXXXXXX

aeolus1d-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Code of Conduct
+
+The aeolus1d project adopts the
+[**Contributor Covenant, v2.1**](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
+as its code of conduct. The full text — covering expected behaviour,
+enforcement guidelines, and the four-tier consequences ladder — lives
+at the URL above. Treat that document as authoritative; this file
+just records the adoption and the local enforcement contact.
+
+
+## In short
+
+- Be respectful and constructive in issues, merge requests, code
+  review, and any other project space.
+- Disagree on technical substance, not on people.
+- Assume good faith. Ask clarifying questions before escalating.
+
+
+## Scope
+
+Applies to all project spaces — the GitLab repository (issues,
+merge requests, code review threads, the wiki) and any official
+channel (email, chat, video calls) where someone is representing
+the project.
+
+
+## Enforcement
+
+Report unacceptable behaviour to **niklas.nordin@nequam.se**.
+
+Reports are handled confidentially. Expect an acknowledgement
+within 72 hours and a substantive response within two weeks. The
+project follows the Contributor Covenant enforcement ladder:
+correction → warning → temporary ban → permanent ban, calibrated
+to the severity and pattern of the incident.
+
+Reporters acting in good faith will not face retaliation, even if
+the report is ultimately not actionable.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at the URL above. The Contributor Covenant
+is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

aeolus1d-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,150 @@
+# Contributing to aeolus1d
+
+Thanks for picking up the repo. This file covers the practical mechanics
+— how to install a dev environment, run the test gates, and shape a
+merge request so it lands quickly.
+
+For the wider community policy, see [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
+For security disclosure, see [`SECURITY.md`](SECURITY.md).
+
+
+## Getting set up
+
+```bash
+git clone https://gitlab.com/niklas.nordin.swe/aeolus
+cd aeolus1d
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pre-commit install
+```
+
+Optional extras (`gui`, `real-gas`, `docs`, `build`, `chemistry-yaml`,
+`interop`) are independently installable — see
+[`docs/installation.md`](docs/installation.md).
+
+Verify the install:
+
+```bash
+make test            # ~3 min parallel, skips @pytest.mark.slow
+aeolus1d bench nozzle  # quick smoke
+```
+
+
+## The local gates
+
+Every merge request has to clear these — they all run in CI but it's
+faster to catch failures locally first.
+
+| Gate | Command | What it checks |
+|---|---|---|
+| Lint | `make lint` (or `pre-commit run --all-files`) | ruff style + auto-fixes |
+| Types | `mypy --strict src/aeolus1d aeolus1d_gui` | strict typing, no Any-leaks |
+| Tests (fast) | `make test` | full suite minus `@slow`; ~3 min |
+| Tests (full) | `make test-all` | everything including benches |
+| Docs | `make docs` | `mkdocs build --strict` |
+
+`pre-commit install` wires the ruff hook so commits fail locally
+before they reach CI. Bypass with `--no-verify` only when you really
+know what you're doing.
+
+
+## Branching & merge requests
+
+- **One concern per MR.** A bugfix and a feature in the same branch
+  invariably slows review and bisecting.
+- **Branch naming.** `feat/<topic>`, `fix/<topic>`, `docs/<topic>`,
+  `perf/<topic>`, `hotfix/<topic>`. Topic in kebab-case.
+- **Commit messages.** Imperative mood, one-line subject under 72
+  chars, optional body explaining *why*. Match the existing log
+  style — see `git log --oneline` for examples.
+- **No `--amend` on pushed commits.** Create a new commit instead.
+  CI re-runs from scratch on push, so amending breaks bisect history.
+- **No `--no-verify`.** If a hook fails, fix the cause.
+
+
+## The phase-workflow rule (aeolus1d convention)
+
+Substantial features land as **phases** — each phase touches the same
+three surfaces together so the docs/examples never lag the code:
+
+1. **Code** — `src/aeolus1d/...` change + tests.
+2. **Example** — a bundled `examples/NN_<topic>.toml` (and matching
+   `plot_NN_<topic>.py` script under `examples/plots/` if useful)
+   that exercises the new feature end-to-end.
+3. **Documentation** — `README.md` milestone section *and*
+   `docs/changelog.md` *and* one of `docs/theory.md` /
+   `docs/concepts.md` / `docs/closures-reference.md` as appropriate.
+
+Commit the three pieces together in a single MR. If a phase is large,
+split it into sub-phases (e.g. `Phase 8m-ctrl-3`) — each sub-phase
+still ships the three surfaces.
+
+
+## Validation discipline
+
+Validation cases live under `examples/validation/<dataset>/` and have
+their own `run_validation.py` + `pass_criteria.toml`. **Don't loosen
+a passing tolerance to make a refactor green** — investigate the
+divergence first. The KTM and Mendeley suites are currently the
+quantitative truth-set; promoting them to gated CI tests is on the
+roadmap (see [`docs/roadmap.md`](docs/roadmap.md)).
+
+
+## Performance work
+
+Numeric kernels are `@njit(cache=True, fastmath=FASTMATH)`, where
+`FASTMATH` is the centralised flag in `aeolus1d._numba_flags` (overridable
+with `AEOLUS_FASTMATH=0` for IEEE-strict numerics). Performance MRs need
+a before/after measurement in the description (e.g.
+`tests/benchmarks/test_baseline_regression.py` output, or a one-off
+timer from a representative example). Hot-path changes that don't
+include numbers will be sent back with a request to measure.
+
+A hot-kernel change must also **preserve bit-identity** (the
+`regression` golden net catches a "faster but different" kernel) or be
+gated behind a numerics-changing flag with re-baselined snapshots — and
+the dev box is not a reliable benchmark host (see
+[ADR-0006](docs/adr/0006-hllc-core-microopt-rejected.md)).
+
+The historical performance baselines live in
+[`docs/perf-history.md`](docs/perf-history.md) and
+[`docs/benchmarks-baseline.md`](docs/benchmarks-baseline.md). Update
+the relevant table when you ship a win.
+
+
+## Architecture decisions (ADRs)
+
+Load-bearing decisions — especially the ones where the interesting part
+is the *rejected* alternative — are recorded as ADRs in
+[`docs/adr/`](docs/adr/README.md). Before re-litigating a settled design
+question (a different chemistry integrator, a matrix-free implicit solve,
+a hot-kernel rewrite), check whether an ADR already covers it.
+
+Write a new ADR when a change alters (or deliberately does *not* alter)
+the architecture or numerics and the rationale isn't recoverable from the
+code alone. Routine fixes and features don't need one — the changelog and
+`docs/phase-log.md` cover those. Format + conventions are in the
+[ADR overview](docs/adr/README.md).
+
+
+## Reporting bugs
+
+Open an issue on the project tracker with:
+
+1. A minimal TOML case that reproduces (the smaller the better — strip
+   to the offending pipe + closure).
+2. The full `aeolus1d run <case>.toml` console output.
+3. Your environment — run `aeolus1d doctor`, which bundles the aeolus1d
+   version, Python + platform, the core and optional dependency
+   versions, and the relevant `AEOLUS_*` / `NUMBA_*` env vars (add
+   `--json` for a machine-readable dump to attach to the report).
+
+For numerical disagreements with published data, include the dataset
+reference and the analytical or measured value you expected.
+
+
+## License of contributions
+
+By contributing you agree that your contribution is licensed under
+the project's MIT License (see [`LICENSE`](LICENSE)). No additional
+CLA is required.

aeolus1d-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niklas Nordin
+
+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.

aeolus1d-0.3.0/MAINTAINERS.md

@@ -0,0 +1,21 @@
+# Maintainers
+
+aeolus1d is currently maintained by a single maintainer:
+
+- **Niklas Nordin** — <niklas.nordin@nequam.se>
+
+(Claude, Anthropic's AI assistant, is credited as a pair-programming
+contributor in `CITATION.cff` / `pyproject.toml`; it is not a maintainer.)
+
+## What this means for you
+
+- **Bus factor is 1.** This is a known, documented risk rather than a hidden
+  one. Load-bearing design rationale is being migrated into in-repo
+  Architecture Decision Records (see the maturity roadmap) so the project's
+  reasoning survives independent of any single person.
+- **Support is best-effort.** There is no guaranteed response-time SLA
+  pre-1.0 — see [SUPPORT.md](SUPPORT.md) and [SECURITY.md](SECURITY.md).
+- **A second maintainer is actively welcome.** It is the single highest-value
+  contribution to the project's longevity. The path is the usual one: read
+  [CONTRIBUTING.md](CONTRIBUTING.md), pick up an issue, and land a few
+  well-scoped MRs; sustained, high-quality contribution earns commit rights.