Skip to content

Quick start

This page assumes Python ≥ 3.10. The full install story (extras for the GUI / dev toolchain / real-gas, pinned requirements files, the standalone binary) lives on the installation page — this page only needs the base install. Allow ~30 s for pip install — numba and scipy ship large binary wheels.

Your first run — Sod shock tube in 5 minutes

One-time cold start. On a fresh environment Numba compiles the solver kernels on first use — a one-time ~19 s pause that otherwise happens silently inside your first aeolus1d run and looks like a hang. Run aeolus1d warmup first: it does the same compile out loud and caches the kernels on disk, so every later run starts in seconds. aeolus1d doctor reports whether the kernel cache is warm.

pip install aeolus1d      # solver + CLI; see installation.md for extras

aeolus1d warmup           # one-time ~19 s kernel compile (recommended)

# The bundled cases live INSIDE the package, not in your working
# directory. `aeolus1d examples` prints their directory on line 1.
aeolus1d run "$(aeolus1d examples | head -1)/01_single_pipe_sod.toml" --out sod.h5

Working from a clone instead? Then examples/ is a real directory and the shorter form works:

aeolus1d run examples/01_single_pipe_sod.toml --out sod.h5

aeolus1d run prints the final time, the per-pipe primitive ranges, and the HDF5 path it wrote. Inspect that result with a few lines of Python:

import h5py
import matplotlib.pyplot as plt

with h5py.File("sod.h5") as f:
    x   = f["pipes/tube/x"][:]
    rho = f["pipes/tube/rho"][:]

plt.plot(x, rho)
plt.xlabel("x"); plt.ylabel("ρ")
plt.title("Sod shock tube at t=0.2")
plt.savefig("sod.png")

You should see the canonical Sod triplet — left rarefaction, contact discontinuity, right shock — resolved over the 400-cell mesh. The MUSCL + minmod scheme used here matches the analytical Riemann solution from aeolus1d.bench.sod to L1(ρ) < 2 %.

That's the loop. From here:

  • More examples — aeolus1d examples lists every bundled TOML (Sod, CD nozzle, junctions, catalyst, real-gas, chemistry, cylinders, turbomachinery, …). Each one is a self-contained run.
  • The GUI — aeolus1d gui launches the drag-and-drop editor + post-processor (requires the [gui] extra; see installation).
  • The Python API — build cases in code, plug in custom closures, drive the timeloop directly.

The rest of this page covers each entry point in more depth.

CLI

Every bundled example is a self-contained run:

aeolus1d run examples/03_two_pipes_junction.toml --out run.h5

A successful run prints the final time, total walltime, and the HDF5 path. The HDF5 layout is documented in aeolus1d.io.writer — each pipe gets a group with rho / u / p / U / x / A_cell, and (when --trace-dt is set) a time_series group with the same fields shaped (n_samples, N).

Python API

from aeolus1d._types import End
from aeolus1d.bc import wall_bc, make_pressure_outlet_bc
from aeolus1d.components.pipe import Pipe
from aeolus1d.solver.network_timeloop import advance_network

pipe = Pipe(L=1.0, N=200, gamma=1.4, Ng=2, A=1.0e-3)
pipe.set_uniform(rho=1.2, u=0.0, p=1.0e5)
pipe.scheme = "muscl"   # 2nd-order; default is "first_order"

far = [
    (pipe, End.LEFT,  wall_bc),
    (pipe, End.RIGHT, make_pressure_outlet_bc(p_back=1.0e5, gamma=1.4)),
]
advance_network(pipes=[pipe], junctions=[], far_bcs=far,
                t_end=1.0e-3, cfl=0.4)

print(f"final density range: {pipe.U[:, 0].min():.3f} .. {pipe.U[:, 0].max():.3f}")

The same Pipe and Junction types accept all the optional features: eos_kind for a real-gas EOS (ideal / RK / PR / tabulated), set_species for chemistry, combustion=WiebeCombustion(...) for cylinders, py_friction / py_heat / py_porous for ML-replacement closures. Examples under examples/ cover each of these end-to-end.

For implicit time integration (Implicit Euler / BDF2 / Radau IIA(3) — allows CFL > 1 and avoids the acoustic-CFL stiffness floor for low-Mach engine flows), set the case's [case] rk = "implicit_euler" and run unchanged. The Newton matrix uses closed-form Jacobians for every shipped closure kind (Phases B16 → B22) and for the cubic EOS (Phase B20). The Picard outer iteration on Compressor/Turbine/LODI ghosts (Phase I-Y) is on by default with picard_max_iter = 3.

GUI

./aeolus1d_gui/run_gui.sh

(or python -m aeolus1d_gui from the repo root, or aeolus1d-gui if you pip installed with the [gui] extra). The first launch shows a Welcome dialog walking through the four panels.

Click a tile in the Palette dock (left) to add a component to the canvas (centre), draw connections by dragging from a component's port spheres (a lighter tint of its family colour) to a compatible port on another component, edit parameters in the Inspector dock (right), then press F5 — the Runner dock saves the case to a temp directory, runs the solver as a subprocess with stdout/stderr streaming into its console, and on success auto-loads the output HDF5 into the network-view tab with a colour map for ρ / u / p / T.

See GUI for a longer tour.