Examples

Each TOML file under examples/ is a self-contained, runnable case exercising one feature.

TOML is not the only entry point

Every case on this page also ships a pure-Python builder under examples/python/, generated from the TOML and guarded against drifting from it. If you are embedding aeolus1d in a script, an optimiser or a test rather than running files, start at Examples in Python — and at the pure-Python assembly tutorial if you want the component objects (Pipe, Junction, BC callables) rather than the schema.

Plot scripts live in examples/plots/ and are matched to a case by index, not by full name — plot_03_two_pipes.py plots 03_two_pipes_junction.toml. Not every case has one (27 of the 77 indexed cases do not), and some plot indices have no TOML at all because the feature they demonstrate needs Python-API setup the TOML loader does not cover (plot_47_engine_metrics.py, plot_73_linearize_network.py, …).

Run any example via the CLI:

# From a pip install — the cases ship inside the package, and
# `aeolus1d examples` prints their directory on its first line:
aeolus1d run "$(aeolus1d examples | head -1)/03_two_pipes_junction.toml" --out run.h5

# From a clone, where examples/ is a real directory:
aeolus1d run examples/03_two_pipes_junction.toml --out run.h5

Only the top-level examples/*.toml are bundled into the wheel. Cases under subdirectories — avl_cruise_m/, validation/, mechanisms/, optimize/ — need a clone. The validation cases additionally need vendor datasets that are not redistributable, so they cannot run from a plain install at all.

…or open it in the GUI via File → Open.

Looking for the model / theory behind a given case? The Component index maps every component to its model, theory section, example, and tutorial in one table.

Solver fundamentals

File	Topic
01_single_pipe_sod.toml	Sod shock-tube on a single pipe (HLLC + 1st-order).
23_mp5_sod.toml	Same Sod tube, MP5 reconstruction (~50× lower error).
02_cd_nozzle.toml	Quasi-1D converging-diverging Laval nozzle.
24_hllc_lm_pulse.toml	HLLC-LM (Thornber) low-Mach correction.
40_implicit_adaptive_pipe.toml	Implicit BDF2 + adaptive Δt on a low-Mach porous-plug pipe (unlocks the acoustic-CFL headroom).

Networks + junctions

File	Topic
03_two_pipes_junction.toml	Two pipes joined by a 0-D plenum.
04_pulsed_intake.toml	Time-varying inlet pressure forcing a pipe.
06_helmholtz_quasi2d.toml	Quasi-2D (spatially resolved) plenum that nails the Helmholtz frequency.
10_cp_junction_kloss.toml	Corberán CP+h junction with port loss coefficients.
11_neck_pipe_junction.toml	Plenum-with-neck-pipe geometry.
12_cp_junction.toml	Plain Corberán CP+h junction.
13_ehr_helmholtz.toml	Extended Helmholtz Resonator (per-port u_n ODE).
14_py_junction_bc.toml	ML-callable junction BC seam.
22_lodi_port.toml	LODI / Poinsot-Lele characteristic port BC.

Closures + chemistry

File	Topic
05_catalyst_plug.toml	Two-phase catalyst (T_solid + Nusselt h·a_v·(T_s−T_g)).
07_catalyst_thermal_front.toml	Catalyst light-off transient.
08_reactive_pipe.toml	Single-species Arrhenius demo.
15_strang_chemistry.toml	Strang-split chemistry, scipy LSODA per cell.
16_bs_chemistry.toml	@njit Bader-Deuflhard semi-implicit BS chemistry.
20_multi_species.toml	Multi-species transport (Y_extras alongside Y).
21_multi_species_kinetics.toml	Multi-species + kinetics, py_reaction_multi seam.
35_mechanism_pipe.toml	CHEMKIN-mechanism kinetics driving a pipe (NH3 oxidation).
87_multicomponent_variable_gamma_shock_tube.toml	Per-cell variable γ(T, Y) built from a tracked N₂/CO₂/H₂O mixture ([pipe.species] per_cell_gamma = true) on a shock tube — the config path for the energy-consistent per-cell-γ recovery.
90_variable_cv_real_gas.toml	Temperature-dependent ideal-gas cv on a Redlich-Kwong pipe ([pipe.eos] cv_poly + validity band). A constant cv is ~14 % low at 900 K; the band clamp is required because an extrapolated NASA-7 fit goes negative and breaks the e(T) inversion. Opt-in and bit-identical when omitted.
91_cylinder_species_transport.toml	A real composition through an engine: the cylinder carries a well-mixed N₂/O₂/CO₂/H₂O inventory, burnt fuel deposits stoichiometric products into it, and the exhaust runner runs per_cell_gamma on the result. Disable the coupling and the same case dies with the degenerate-γ ZeroDivisionError that blocked temperature-dependent γ on the EPW diesel suites.
avl_cruise_m/c02012_gasoline.toml	Three-way catalyst (twc kind) on an imported AVL Cruise M gasoline case.
validation/heliyon_twc_co_oxidation/case_co2_production_300C.toml	TWC Brinkmeier O₂-storage (twc_brinkmeier) — CO oxidation at 300 °C (Heliyon CC-BY validation).

Aftertreatment

File	Topic
41_dpf_regen.toml	Diesel particulate filter — passive (NO2-driven) regen.
42_scr_urea_injector.toml	Selective catalytic reduction with urea-water injection.
43_scrf.toml	Combined SCR + filter (SCRF) — single brick.
45_two_stage_scr.toml	Two-stage SCR (high-T upstream, low-T downstream).
46_doc.toml	Diesel oxidation catalyst (DOC) — HC + CO Pt/Pd kinetics.
74_twc.toml	Three-way catalyst (twc_brinkmeier) — cerium oxygen-storage (OSC) discharge: CO₂ pulse then CO breakthrough.
48_hnco_hydrolysis.toml	HNCO hydrolysis branch of the urea decomposition chain.
49_dpf_no_inhibition.toml	DPF with Langmuir NO back-inhibition correction (Phase 8k).
50_dpf_active_regen.toml	DPF active-regen heater (2 kW deposits energy into T_cake).
53_dpf_heater_ctrl.toml	DPF active regen + closed-loop DPFHeaterController PI (Phase 8m-ctrl).
55_dpf_regen_hrr.toml	Same regen physics as 41 but driving the [case] dt_hrr_fraction heat-release-rate adaptive-Δt knob for fast-forward.
56_dpf_regen_lowmach.toml	Same regen physics under the quasi-steady (solver = "quasi_steady") low-Mach SIMPLE pressure-projection flow.
61_doc_sulfur_poisoning.toml	DOC doc_oxidation_S kind — sulfur poisoning + doc_sulfur controller-driven active desulfation.
76_wltp_lite_dpf.toml	WLTP-lite quasi-steady DPF drive-cycle run (dt_hrr_fraction + qs_dt_max fast-forward, 600 s).
84_dpf_substrate_inertia.toml	DPF substrate (SiC/cordierite) thermal-inertia element buffering gas-temperature transients (WHTC / cold-start).

Real-gas

File	Topic
09_real_gas_shock_tube.toml	RK / PR EOS on the Sod-style shock tube.
17_real_gas_nozzle.toml	Real-gas EOS through a varying-area nozzle.
18_real_gas_catalyst.toml	Real-gas + two-phase catalyst.
19_real_gas_plenum.toml	Real-gas pipes coupled through an EOS-aware plenum.
58_tabulated_eos_implicit.toml	Tabulated EOS arm ([gas.eos] kind = "tabulated") — CoolProp-populated (T, ρ) → (p, e, ∂p/∂T, ∂p/∂ρ) panel driving an implicit pipe.

Engine components

File	Topic
25_valve_inlet.toml	Cam-driven valve at a pipe inlet (continuous lift).
26_valve_orifice.toml	Orifice-flow valve (Winterbone-Pearson).
27_compressor.toml	Quasi-steady map-driven compressor.
28_turbo_shaft.toml	Compressor + Turbine on a shared shaft (turbocharger).
29_learned_junction_bc.toml	Trained NN port-state surrogate.
30_learned_turbo_map.toml	Trained NN compressor / turbine map surrogate.
31_cylinder.toml	Reciprocating cylinder with valve ports.
38_engine_turbo_scr.toml	Single-cylinder + turbocharger + SCR brick chain.
39_4cyl_engine_turbo_scr.toml	4-cylinder engine + turbocharger + aftertreatment.
44_egr_cooler.toml	EGR cooler ε-NTU lumped heat-exchanger.
50_two_cyl_engine.toml	360° parallel-twin SI engine.
51_vgt_boost_ctrl.toml	VGT vane + closed-loop boost-pressure PI controller.
52_knock_event.toml	Boosted SI cylinder with Wiebe combustion + closed-loop knock retard (Phase B22 TOML).
54_adaptive_picard_turbo.toml	Implicit-network turbo case with adaptive picard_max_iter controller.
55_vgt_3d_turbo.toml	3-D TurboMap (vane_open axis) — VGT off-design demo.
57_picard_stiffness_step.toml	Phase I-Y-tuning recipe — adaptive picard_max_iter on a turbo network with a mid-run stiffness step (3.0 bar → 9.0 bar).
83_turbo_robustness.toml	v0.5 turbo robustness pack — γ/R off-test-gas correction, near-surge mass-flow damping, shaft mechanical efficiency + bearing windage on a turbine + compressor shaft.
59_wastegate_boost_ctrl.toml	Closed-loop wastegate (Turbine.bypass_open) boost-pressure PI controller.
60_twin_sequential_turbo.toml	Two-stage / sequential turbocharger — HP + LP turbo-shaft pairs plumbed in series.
62_egr_valve_ctrl.toml	Closed-loop egr_valve controller modulating an EGR-valve orifice BC.
63_spark_timing_ctrl.toml	Closed-loop spark_timing PI controller on a boosted SI cylinder.
71_ktm_510_si.toml	KTM 510 cc single-cylinder NA SI engine (Aradhye & Bari IMECE2017-70638 bench).
72_throttle_demo.toml	Open-loop throttle BC (airbox-side stagnation reservoir) feeding an intake manifold.
88_dd13_diesel.toml	Detroit Diesel DD13 single-cylinder HD diesel (132×156 mm, CR 17.3) with predictive DI-diesel combustion (kind="diesel_predictive": Hardenberg-Hase ignition delay + Watson premixed fraction) + full Woschni (C2) wall heat. Geometry of the U-Mich DD13 validation dataset.
89_epw_diesel.toml	AVL EPW 6-cyl 12.9 L turbocharged HD diesel (compressor + VGT + HP-EGR, multi-Wiebe + Woschni-C2 + Zeldovich NOx). The full breathing rig from validation/avl_epw_diesel_steady.

Pipe hydraulics + wall heat transfer

File	Topic
77_pipe_flow_heat.toml	Flow-correlation (Nu) wall heat transfer on a plain pipe.
78_pipe_bend_loss.toml	Lumped minor (K-method) loss — Δp = K·½ρu² via the minor_loss closure.
79_orifice_plate.toml	Discharge-coefficient orifice plate (area-ratio Cd + Borda-Carnot recovery).
80_pipe_wall_warmup.toml	Standalone dynamic pipe wall with external convection + radiation (no coolant jacket).
81_bend_geometric.toml	Geometric bend-loss lookup (Idelchik smooth-bend) feeding the K-method closure.
82_multilayer_wall.toml	Multi-layer radial pipe wall (steel liner + insulation + shield).
75_coolant_pipe.toml	Intake pipe coupled to a 1-D coolant jacket through a per-cell dynamic wall thermal mass ([pipe.thermal_wall] kind = "dynamic").

Vehicle + driveline

File	Topic
85_vehicle_drive_cycle.toml	Closed-loop PI driver following a speed profile + 1-DOF longitudinal vehicle road-load model.
86_electrified_drive_cycle.toml	Parallel-hybrid drive cycle — adds a [powertrain] block (motor + engine) on top of the 85 vehicle case.

Plot scripts

examples/plots/ contains a Python plotting demo for every example TOML, plus standalone Python-API demos for features that need hand-rolled setup (parser benches, kinetics validation, etc.). Each plot script:

• Imports from the installed aeolus1d package.
• Runs the corresponding example (or a Python-built case).
• Saves a comparison figure to /tmp/aeolus_example_NN.png.

The plots are textbook-style: shock-tube traces, error curves, indicator diagrams, NOx hot-pocket two-zone snapshots, etc. A good starting point if you want to see what a feature actually looks like in output.

Adding a new example

Per the policy in examples/plots/README.md, every new feature ships at least one example: a TOML for additive features that fit the existing schema, or a plot_NN_<feature>.py Python-API demo for features that need bespoke setup. The example must exercise the behaviour, not just construct the type — that's what keeps the test of "does it actually do something" honest.