aeolus1d 0.3.0__py3-none-any.whl

aeolus1d/__init__.py

@@ -0,0 +1,43 @@
+"""aeolus1d — 1D compressible gas-dynamics pipe-network solver."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+# Phase B11 — single source of truth for the package version.
+# ``pyproject.toml`` carries the canonical value; this lookup
+# pulls it via the installed metadata so a release bump only
+# touches one file. Editable installs without metadata
+# (``pip install -e .`` without a built wheel) fall back to
+# the development sentinel so ``aeolus1d.__version__`` is always
+# defined.
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    __version__ = version("aeolus1d")
+except (ImportError, PackageNotFoundError):  # pragma: no cover
+    __version__ = "0.0.0+dev"
+
+# Public API. Re-exported lazily (PEP 562) so ``import aeolus1d`` and
+# ``aeolus1d --version`` stay light — the solver / numba stack is only
+# imported when one of these names is actually accessed, not on every
+# ``import aeolus1d``. The canonical definitions live in ``aeolus1d.io.case``.
+_LAZY_EXPORTS = frozenset({"build_network", "load_case", "run_case"})
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY_EXPORTS:
+        from aeolus1d.io import case
+
+        return getattr(case, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | _LAZY_EXPORTS)
+
+
+if TYPE_CHECKING:  # give type-checkers / IDEs the concrete symbols
+    from aeolus1d.io.case import build_network, load_case, run_case
+
+__all__ = ["__version__", "build_network", "load_case", "run_case"]

aeolus1d/_compat.py

@@ -0,0 +1,94 @@
+"""Internal compatibility shims for Python version differences.
+
+Currently provides:
+
+* ``zip_strict`` — Python 3.9 lacks the ``strict=`` keyword on the
+  builtin ``zip``.
+* ``trapezoid`` — NumPy 2.0 renamed ``np.trapz`` to ``np.trapezoid``;
+  NumPy 1.x exposes only the legacy ``trapz`` name. The shim picks
+  whichever is available so the project supports both NumPy
+  versions on both Python floors.
+
+Drop this module when the project's ``requires-python`` floor
+reaches 3.10 **and** NumPy 1.x is dropped from the dependency
+matrix.
+
+The ``zip_strict`` overload signatures mirror the typeshed
+``builtins.zip`` overloads so call-site element types are preserved
+under ``mypy --strict``. The PEP 585 ``tuple[...]`` / ``Iterator[...]``
+(from ``collections.abc``) generics are 3.9-safe because every
+annotation here is stringified by ``from __future__ import
+annotations`` — mypy resolves them, but the runtime never evaluates
+them.
+"""
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable, Iterator
+from typing import Any, TypeVar, overload
+
+import numpy as np
+
+__all__ = ["trapezoid", "zip_strict"]
+
+
+def trapezoid(y: Any, x: Any = None, **kwargs: Any) -> Any:
+    """Composite-trapezoidal integral — NumPy-version-portable.
+
+    NumPy 2.0 renamed ``np.trapz`` to ``np.trapezoid``. Code that
+    imports ``np.trapezoid`` directly fails on NumPy 1.x (no
+    attribute); code that uses ``np.trapz`` fails on NumPy 2.x
+    (DeprecationWarning → AttributeError in 2.1+). This shim
+    dispatches to whichever name the active NumPy exposes.
+    """
+    fn = getattr(np, "trapezoid", None) or np.trapz
+    if x is None:
+        return fn(y, **kwargs)
+    return fn(y, x, **kwargs)
+
+_T1 = TypeVar("_T1")
+_T2 = TypeVar("_T2")
+_T3 = TypeVar("_T3")
+_T4 = TypeVar("_T4")
+_T5 = TypeVar("_T5")
+
+
+@overload
+def zip_strict(__i1: Iterable[_T1]) -> Iterator[tuple[_T1]]: ...
+@overload
+def zip_strict(__i1: Iterable[_T1], __i2: Iterable[_T2]) -> Iterator[tuple[_T1, _T2]]: ...
+@overload
+def zip_strict(
+    __i1: Iterable[_T1], __i2: Iterable[_T2], __i3: Iterable[_T3]
+) -> Iterator[tuple[_T1, _T2, _T3]]: ...
+@overload
+def zip_strict(
+    __i1: Iterable[_T1],
+    __i2: Iterable[_T2],
+    __i3: Iterable[_T3],
+    __i4: Iterable[_T4],
+) -> Iterator[tuple[_T1, _T2, _T3, _T4]]: ...
+@overload
+def zip_strict(
+    __i1: Iterable[_T1],
+    __i2: Iterable[_T2],
+    __i3: Iterable[_T3],
+    __i4: Iterable[_T4],
+    __i5: Iterable[_T5],
+) -> Iterator[tuple[_T1, _T2, _T3, _T4, _T5]]: ...
+
+
+if sys.version_info >= (3, 10):
+    def zip_strict(*iterables):  # type: ignore[no-untyped-def]
+        return zip(*iterables, strict=True)
+else:
+    def zip_strict(*iterables):  # type: ignore[no-untyped-def]
+        sentinel = object()
+        iters = [iter(it) for it in iterables]
+        while True:
+            row = tuple(next(it, sentinel) for it in iters)
+            if all(v is sentinel for v in row):
+                return
+            if any(v is sentinel for v in row):
+                raise ValueError("zip_strict: argument lengths differ")
+            yield row

aeolus1d/_numba_flags.py

@@ -0,0 +1,189 @@
+"""Centralised Numba kernel flags (plan 2.2 + **R2b**).
+
+The ``@njit`` kernels read their numerically-relevant flags from this module
+instead of hardcoding them, so the whole kernel set can be switched from one
+place::
+
+    AEOLUS_FASTMATH=0    # disable fastmath everywhere — reproducible, slower
+    AEOLUS_PARALLEL=0    # compile the five prange kernels serially
+
+``FASTMATH`` is a constant spliced into ~191 ``@njit(...)`` decorators.
+``PARALLEL`` is consumed through the :func:`njit_parallel` decorator factory,
+because the five parallel kernels do **not** share one flag set — see that
+function's table. Centralising them did *not* require unifying them, which is
+what had kept R2b deferred: the factory records each kernel's existing flags,
+so ``chem_bs_brinkmeier`` keeps ``fastmath`` off and ``chem_numbalsoda`` keeps
+``cache`` off, both bit-preserving.
+
+``FASTMATH`` defaults to ``True``. Flipping it changes Numba's compiled output —
+the numerically-relevant fastmath reordering (FMA contraction, reassociation).
+Measured on x86_64 / numba 0.64, the two modes agree to ~3e-15 relative (pure FP
+noise) but are not bit-equal, so each mode carries its own golden reference set
+(``snapshots/`` vs ``snapshots/fastmath0/``).
+
+**A fastmath build is not bit-reproducible.** This is worth stating plainly,
+because it is easy to assume otherwise and the project's regression net once
+claimed to verify it. Two independent effects, both measured on this codebase:
+
+* *Host-CPU dependent.* Numba compiles for the host CPU, and fastmath lets LLVM
+  exploit its features, so a ``tigerlake`` build is not bit-equal to a
+  ``generic`` one (3 of sod's 4 fields differ).
+* *Compilation-order dependent.* Even on one machine, the bits depend on which
+  kernels numba compiled earlier in the same process — running a network case
+  before a single-pipe MP5 case shifts the latter's pressure by ~1e-14.
+
+With fastmath OFF, IEEE-strict semantics forbid both transformations and results
+are bit-stable across CPU targets and compilation orders. That is why
+``tests/regression/test_golden_bit_identity.py`` — the ``assert_array_equal``
+tier — runs **only** under ``AEOLUS_FASTMATH=0``, and why the default build's
+end-to-end reproducibility is guarded by the measured-tolerance tier
+(``rtol=1e-8``, ~6 orders above the effects above) rather than by bit-equality.
+An ``assert_allclose(rtol=1e-8)`` cannot detect a 1-ULP shift, so it is the
+IEEE-strict tier that catches a kernel whose numerics silently moved.
+
+Cache isolation (audit 2026-06-10 batch C item 9)
+-------------------------------------------------
+Numba's on-disk cache key does **NOT** include the ``fastmath`` flag (it keys
+on the source file's stat + argument types only), so two ``AEOLUS_FASTMATH``
+values sharing one cache directory silently serve each other's stale
+binaries — confirmed empirically on this codebase. This module therefore
+routes each flag value to its own cache directory at import time (it is
+imported before any kernel module defines an ``@njit`` function):
+
+* ``AEOLUS_FASTMATH`` default (on) with no ``NUMBA_CACHE_DIR`` keeps numba's
+  stock per-source ``__pycache__`` caching — zero disruption, warm caches
+  preserved.
+* ``AEOLUS_FASTMATH=0`` redirects to
+  ``~/.cache/aeolus1d/numba/aeolus1d-fastmath-0``.
+* An existing ``NUMBA_CACHE_DIR`` is respected by appending the
+  ``aeolus1d-fastmath-{0|1}`` suffix under it for **both** flag values (a
+  user-shared cache dir is exactly the staleness hazard).
+
+Related gotcha (same staleness family, NOT fixed by per-flag dirs): numba's
+cache key also ignores ``inline="always"`` **callees** — editing an inlined
+callee module serves stale callers until the cached ``*.nbc`` / ``*.nbi``
+files are deleted (``find src/aeolus1d -name '*.nbc' -delete`` + same for
+``*.nbi``). Do that after editing any inline-always helper.
+
+This is the single reviewable source for the numerically-relevant kernel flags.
+``tests/unit/test_numba_flags.py`` pins them against drift — including that no
+kernel may hardcode ``fastmath=True`` or ``parallel=True`` and so escape the
+switches — and the run manifest (``aeolus1d.io.manifest``) records the active
+values.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+_FALSEY = {"0", "false", "no", "off", ""}
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() not in _FALSEY
+
+
+#: Whether the @njit kernels are compiled with ``fastmath``. Default True
+#: (bit-identical to the historical hardcoded value); set ``AEOLUS_FASTMATH=0``
+#: for IEEE-strict, cross-environment-reproducible numerics.
+FASTMATH: bool = _env_bool("AEOLUS_FASTMATH", True)
+
+#: Whether the five ``prange`` kernels compile with numba's parallel pass.
+#: Default True (bit-identical to the historical hardcoded ``parallel=True``);
+#: set ``AEOLUS_PARALLEL=0`` to compile them serially. Useful when a
+#: parallel-vs-serial discrepancy is suspected, which is not hypothetical here —
+#: see ``tests/unit/test_packed_pipes.py``, where a ``parallel=True`` kernel and
+#: its serial twin are cross-checked and the tolerance had to be set by what the
+#: toolchain actually guarantees.
+PARALLEL: bool = _env_bool("AEOLUS_PARALLEL", True)
+
+
+def _apply_cache_isolation() -> str:
+    """Route this process's numba on-disk cache to a per-flag directory (see
+    the module docstring). Returns the directory applied, or ``""`` when
+    numba's stock per-source ``__pycache__`` caching is kept (the warm
+    default).
+
+    ``PARALLEL`` participates for the same reason ``FASTMATH`` does: numba's
+    cache key excludes it too, so a serial build and a parallel build sharing
+    one directory would serve each other's stale binaries. The suffix only
+    *grows* when the flag is non-default, so every existing warm cache path is
+    untouched.
+    """
+    suffix = f"aeolus1d-fastmath-{1 if FASTMATH else 0}"
+    if not PARALLEL:
+        suffix += "-noparallel"
+    root = os.environ.get("NUMBA_CACHE_DIR", "").strip()
+    if root:
+        cache_dir = os.path.join(root, suffix)
+    elif not FASTMATH or not PARALLEL:
+        cache_dir = os.path.join(
+            os.path.expanduser("~"), ".cache", "aeolus1d", "numba", suffix,
+        )
+    else:
+        # Both flags at their defaults, no user cache dir → numba's stock
+        # behaviour (per-source __pycache__) is already exclusive to
+        # fastmath=1 / parallel=1 binaries; leave it untouched.
+        return ""
+    from numba import config as _numba_config  # deferred: heavy import
+
+    _numba_config.CACHE_DIR = cache_dir
+    return cache_dir
+
+
+#: The numba cache-directory override applied for this process; ``""`` means
+#: numba's stock per-source ``__pycache__`` caching is in effect.
+NUMBA_CACHE_DIR_EFFECTIVE: str = _apply_cache_isolation()
+
+
+def njit_parallel(
+    *,
+    cache: bool = True,
+    fastmath: bool = FASTMATH,
+) -> Any:
+    """``@njit`` decorator for the ``prange`` kernels, with ``parallel`` read
+    from :data:`PARALLEL` instead of hardcoded (plan item **R2b**).
+
+    Every kernel that used to write ``parallel=True`` inline now goes through
+    here, so the parallel flag is switchable and reviewable in one place —
+    exactly what ``FASTMATH`` already had.
+
+    **The five kernels, and why they are not uniform.** The reason R2b sat
+    deferred was a belief that centralising meant *unifying*, which would have
+    forced ``chem_bs_brinkmeier`` to newly opt into fastmath — a real behaviour
+    change on the stiff-chemistry solver. It does not: this factory records
+    each kernel's existing flags rather than imposing one set, so the table
+    below is a description, not a decision.
+
+    ======================================  =====  ========  ================
+    kernel                                  cache  fastmath  note
+    ======================================  =====  ========  ================
+    ``packed_pipes._packed_residual_fo_par``  yes  FASTMATH  the common case
+    ``packed_pipes._packed_min_dt_par``       yes  FASTMATH  the common case
+    ``implicit_kernels`` (block assembly)     yes  FASTMATH  the common case
+    ``chem_numbalsoda`` (GIL-free chem)       NO   FASTMATH  cache=False: the
+                                                            kernel closes over
+                                                            a runtime function
+                                                            address
+    ``chem_bs_brinkmeier`` (surface chem)     yes  **False** never opted into
+                                                            fastmath; keeping
+                                                            it off is
+                                                            bit-preserving
+    ======================================  =====  ========  ================
+
+    Omitting ``fastmath`` and passing ``fastmath=False`` compile identically
+    (numba's default is False — verified), so writing Brinkmeier's value
+    explicitly is documentation, not a numerical change.
+    """
+    from numba import njit  # deferred: heavy import
+
+    return njit(parallel=PARALLEL, cache=cache, fastmath=fastmath)
+
+
+def as_dict() -> dict[str, bool]:
+    """The active flag set, for the run manifest / diagnostics."""
+    return {"fastmath": FASTMATH, "parallel": PARALLEL}

aeolus1d/_resources.py

@@ -0,0 +1,57 @@
+"""Locate bundled data directories (``examples/``) across layouts.
+
+aeolus1d runs in three layouts and the bundled ``examples/`` tree sits in a
+different place in each:
+
+* **editable / source checkout** — ``<repo>/examples`` (a few parents up
+  from this module).
+* **PyInstaller one-folder bundle** — ``<bundle>/examples`` next to the
+  launcher, surfaced via ``sys._MEIPASS`` (the spec copies the tree there).
+* **pip wheel** — as of v0.3.0 the ``hatch_build.py`` build hook bundles the
+  top-level example cases into the wheel under ``aeolus1d/examples/`` (a sibling
+  of this module), so ``aeolus1d examples`` works from a plain ``pip install``.
+  A wheel built *without* that hook ships no examples and callers must still
+  tolerate ``None``.
+
+This module centralises that resolution so the CLI ``examples`` command and
+the GUI's example browser / guided tour all agree on where the examples are.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def bundle_root() -> Path | None:
+    """The PyInstaller bundle root (``sys._MEIPASS``) when frozen, else ``None``.
+
+    PyInstaller sets ``sys.frozen`` and ``sys._MEIPASS`` at runtime; in a
+    normal interpreter neither is present and this returns ``None``.
+    """
+    if getattr(sys, "frozen", False):
+        meipass = getattr(sys, "_MEIPASS", None)
+        if meipass:
+            return Path(meipass)
+    return None
+
+
+def examples_dir() -> Path | None:
+    """Return the bundled ``examples/`` directory, or ``None`` if unavailable.
+
+    Frozen bundle → ``<_MEIPASS>/examples``. Installed wheel (examples bundled
+    under ``aeolus1d/examples/``) or source / editable checkout → the nearest
+    ancestor ``examples/`` directory that contains ``*.toml`` cases — in a
+    wheel that ancestor is the package dir itself. A wheel built without the
+    bundling hook → ``None``.
+    """
+    root = bundle_root()
+    if root is not None:
+        cand = root / "examples"
+        return cand if cand.is_dir() else None
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        cand = parent / "examples"
+        if cand.is_dir() and any(cand.glob("*.toml")):
+            return cand
+    return None

aeolus1d/_tables.py

@@ -0,0 +1,109 @@
+"""Make the ascending-abscissa precondition of 1-D lookups self-enforcing.
+
+Every linear interpolator in this project — ``np.interp``, and the faster
+``bc.transient._interp1d_scalar`` that replaces it on the hot path — requires
+its abscissa to ascend, and **neither can detect a violation**. Both return a
+plausible-looking number computed from the wrong bracket. There is no
+exception, no NaN, and no warning; the run completes and the answer is wrong.
+
+This has already cost one real bug: a valve cam whose table wrapped past
+360 deg was silently never opened (fixed 2026-07-31, MR !371). The lesson
+recorded then was that the class generalises, and it does.
+
+Until now the only guard lived in ``io.validate._validate_schedule_ordering``,
+which covers three table kinds and **only on the TOML path** — so every
+Python-API entry point was unguarded. The check belongs where the table is
+consumed, not in a validator one of the two entry points happens to run.
+
+Design notes:
+
+* **Checked once, at table-build time.** These tables are built once and read
+  O(1e5-1e6) times; an O(n) check per lookup would be absurd. Every call site
+  here converts its sequence to an array exactly once, which is the natural
+  place.
+* **Non-decreasing, not strictly increasing.** A repeated abscissa value is a
+  legitimate way to encode a step change, and ``np.interp`` handles it (it
+  takes the later value). Only a *decrease* is rejected.
+* **Empty and single-point tables pass.** They have no ordering to violate,
+  and the interpolators already handle both.
+* **NaN is rejected.** A NaN abscissa makes every comparison false, so it
+  neither ascends nor descends and would slip past a naive ``>=`` check — the
+  same "NaN loses every comparison" mechanism that let a bad density through
+  the dt guard before ADR-0011.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+
+__all__ = ["ascending_or_raise", "is_ascending"]
+
+
+def is_ascending(xs: np.ndarray) -> bool:
+    """True when ``xs`` is non-decreasing and free of NaN."""
+    if xs.size == 0:
+        return True
+    if np.isnan(xs).any():
+        return False
+    if xs.size == 1:
+        return True
+    return bool(np.all(xs[1:] >= xs[:-1]))
+
+
+def ascending_or_raise(
+    xs: Sequence[float] | np.ndarray,
+    *,
+    name: str,
+    where: str,
+    hint: str = "",
+) -> np.ndarray:
+    """Return ``xs`` as a float array, raising if it does not ascend.
+
+    Parameters
+    ----------
+    xs
+        The abscissa (the ``xp`` of an ``np.interp``-style lookup).
+    name
+        The field name as the user wrote it, e.g. ``"SoC_grid"``.
+    where
+        What owns the table, e.g. ``"BatteryECM"`` — so the message names a
+        thing the caller can find.
+    hint
+        Optional extra sentence for cases with a known-common cause.
+
+    Raises
+    ------
+    ValueError
+        If any element decreases relative to its predecessor, or any is NaN.
+        The message names the first offending index and both values, because
+        "somewhere in a 400-point table" is not actionable.
+    """
+    arr = np.asarray(xs, dtype=np.float64)
+    if arr.ndim != 1:
+        raise ValueError(
+            f"{where}: {name} must be one-dimensional, got shape {arr.shape}."
+        )
+    nan_at = np.flatnonzero(np.isnan(arr))
+    if nan_at.size:
+        raise ValueError(
+            f"{where}: {name}[{int(nan_at[0])}] is NaN. A NaN abscissa loses "
+            f"every comparison, so the interpolator cannot bracket a query "
+            f"point and returns a wrong value silently."
+        )
+    if arr.size < 2:
+        return arr
+    bad = np.flatnonzero(arr[1:] < arr[:-1])
+    if bad.size:
+        i = int(bad[0]) + 1
+        tail = f" {hint}" if hint else ""
+        raise ValueError(
+            f"{where}: {name} must be non-decreasing, but {name}[{i}] = "
+            f"{arr[i]:g} < {name}[{i - 1}] = {arr[i - 1]:g}. Linear "
+            f"interpolation assumes an ascending abscissa and returns "
+            f"silently wrong values otherwise — it cannot detect this "
+            f"itself, so the run would complete with a plausible but "
+            f"incorrect answer.{tail}"
+        )
+    return arr

aeolus1d/_types.py

@@ -0,0 +1,103 @@
+"""Small shared enums and integer codes used by Numba kernels.
+
+These map Python-side names to integer codes so that @njit kernels can branch on
+them cheaply without calling back into Python.
+"""
+
+from enum import IntEnum
+
+
+class End(IntEnum):
+    LEFT = 0
+    RIGHT = 1
+
+
+class Limiter(IntEnum):
+    NONE = 0
+    MINMOD = 1
+    VAN_LEER = 2
+
+
+# ``[case] limiter`` name -> code. Lives here, beside the enum, because BOTH
+# builders need it and they cannot import from each other: ``io.case`` imports
+# ``io.build``, so the mapping cannot live in ``io.case`` where it started.
+# Keep in sync with the ``limiter`` Literal in ``io.schema.CaseHeader``.
+LIMITER_BY_NAME: dict[str, Limiter] = {
+    "minmod": Limiter.MINMOD,
+    "van_leer": Limiter.VAN_LEER,
+    "none": Limiter.NONE,
+}
+
+
+class RKScheme(IntEnum):
+    SSP_RK2 = 2
+    SSP_RK3 = 3
+
+
+class BCKind(IntEnum):
+    WALL = 0
+    STAGNATION_INLET = 1
+    PRESSURE_OUTLET = 2
+    NONREFLECTING = 3
+    # (A JUNCTION_PORT kind was reserved in milestone 1 but never used —
+    # ports are resolved inside aeolus1d.components.junction instead.)
+
+
+# --------------------------------------------------------------------------
+# Closure-kind enums.
+#
+# These mirror the integer dispatch codes registered in
+# ``aeolus1d.closures.registry`` (the single source of truth — see
+# ``register_closure``). Each member's *name* (lower-cased) must equal a
+# registered closure name and its *value* must equal that kind's dispatch code.
+# ``tests/unit/test_closure_registry.py`` locks this with a drift test, so a new
+# kind added to the registry without a matching member here fails loudly. They
+# stay hand-written (not generated) because static type-checkers and ``.value``
+# call sites need the members to exist statically — the same reason the schema
+# ``Literal[...]`` arms can't be registry-generated either.
+# --------------------------------------------------------------------------
+
+
+class FrictionKind(IntEnum):
+    NONE = 0
+    DARCY_CONST = 1
+    COLEBROOK = 2
+    MINOR_LOSS = 3
+    # PYTHON is provenance only: the @njit kernels never dispatch on it.
+    # ``_py_closure_kinds`` substitutes NONE whenever ``pipe.py_friction``
+    # is set, so the compiled side does flux+area and the Python source is
+    # overlaid afterwards. The code exists so a snapshot / GUI round-trip
+    # can still say WHICH closure the pipe carries.
+    PYTHON = 4
+
+
+class HeatKind(IntEnum):
+    NONE = 0
+    CONSTANT_TWALL = 1
+    EGR_COOLER = 2
+    CHARGE_AIR_COOLER = 3
+    FLOW_NU = 4
+
+
+class PorousKind(IntEnum):
+    NONE = 0
+    DARCY_FORCHHEIMER = 1
+    DARCY_FORCHHEIMER_KC = 2
+    # Provenance only, like FrictionKind.PYTHON — the @njit kernels never
+    # dispatch on it (``_py_closure_kinds`` substitutes NONE whenever
+    # ``pipe.py_porous`` is set).
+    PYTHON = 3
+
+
+class CatalystKind(IntEnum):
+    NONE = 0
+    TWO_PHASE_HEAT = 1
+    TWO_PHASE_HEAT_VAR_NU = 2
+    MECHANISM = 3
+
+
+class EOSKind(IntEnum):
+    IDEAL = 0
+    REDLICH_KWONG = 1
+    PENG_ROBINSON = 2
+    TABULATED = 3

aeolus1d/analysis/__init__.py

@@ -0,0 +1,61 @@
+"""Analysis tools — case inspection and post-processing.
+
+* :py:mod:`aeolus1d.analysis.cfl_inspector` — pre-run CFL /
+  max-wave-speed analysis, identifies which pipe + cell will
+  limit the timeloop's dt.
+* :py:mod:`aeolus1d.analysis.engine_metrics` — Phase 7g/7c per-cycle
+  indicated engine performance: IMEP, ISFC, η_i, p–V trace;
+  multi-cylinder fleet aggregation via MultiCycleAccumulator.
+* :py:mod:`aeolus1d.analysis.acoustics` — Phase 7g.2 frequency-
+  domain post-processing: SPL / dB(A), power spectrum, 1/1 and
+  1/3 octave-band reduction, engine-order analysis,
+  transmission / insertion loss for muffler design.
+* :py:mod:`aeolus1d.analysis.system_reports` — Phase 7g.2
+  system-level reports: turbo operating-point overlay on the
+  compressor map (with surge / choke envelope), per-cycle Sankey-
+  ready energy balance, cumulative emissions integration past a
+  probe, drive-cycle (NEDC / WLTP / FTP) integration harness,
+  steady-state / periodic-limit-cycle convergence detection.
+* :py:mod:`aeolus1d.analysis.linearize` — Phase L1 state-space
+  linearization ``(A, B, C, D)`` around a steady operating point,
+  for control synthesis / Bode / stability analysis in scipy or
+  python-control.
+"""
+
+from aeolus1d.analysis.engine_metrics import (
+    CycleAccumulator,
+    EngineMetrics,
+    FMEPCoeffs,
+    MultiCycleAccumulator,
+    cycle_summary,
+)
+from aeolus1d.analysis.linearize import (
+    InputHandle,
+    OutputProbe,
+    StateSpace,
+    linearize_single_pipe,
+)
+from aeolus1d.analysis.nox_post import (
+    equilibrium_NO_ppm,
+    estimate_engine_out_NOx_ppm,
+    integrate_zeldovich_nox,
+    lean_burnt_composition,
+    mass_fraction_NO_to_ppm,
+)
+
+__all__ = [
+    "CycleAccumulator",
+    "EngineMetrics",
+    "FMEPCoeffs",
+    "InputHandle",
+    "MultiCycleAccumulator",
+    "OutputProbe",
+    "StateSpace",
+    "cycle_summary",
+    "equilibrium_NO_ppm",
+    "estimate_engine_out_NOx_ppm",
+    "integrate_zeldovich_nox",
+    "lean_burnt_composition",
+    "linearize_single_pipe",
+    "mass_fraction_NO_to_ppm",
+]