Tutorials¶
Five guided walkthroughs that take you from "I read the README" to "I can author my own case AND turn the result into engine numbers." Each one is anchored on an existing example in the repo so you can run the same commands locally, see the same numbers, and modify-then-rerun without the cliff of starting from blank.
Every tutorial has a Terminal and a GUI path through the "Run it" step — they produce the same HDF5 output, just from different drivers. Pick whichever fits how you work; switch between them mid-tutorial if you want.
Where examples/… actually is
The tutorials write case paths as examples/39_4cyl_engine_turbo_scr.toml,
which is the path in a clone of the repository.
Installing with pip install aeolus1d puts the bundled cases inside
the package instead, so examples/ is not a directory in your shell's
working directory and those commands fail with case file not found.
Get the real location from the CLI — its first line is the directory:
aeolus1d examples # lists them, directory on line 1
EX="$(aeolus1d examples | head -1)"
aeolus1d run "$EX/39_4cyl_engine_turbo_scr.toml" --out engine.h5
Only the top-level examples/*.toml ship in the wheel. Anything
under a subdirectory (avl_cruise_m/, validation/, mechanisms/,
optimize/) needs a clone, and the plots/ scripts do too.
Choose your starting point¶
| You want to… | Start here | Time |
|---|---|---|
| Run your first aeolus1d case and understand the output | Your first run: Sod shock tube | ~10 min |
| Build a multi-pipe network (intake manifold style) | Networks and junctions | ~30 min |
| Simulate a full engine — injection, combustion, aftertreatment, audio | Engine simulation end-to-end | ~1 hr |
| Reduce a tracer to engine numbers — IMEP, heat release, SPL, energy balance | Post-processing walkthrough | ~30 min |
| Drive aeolus1d from Python — no TOML file anywhere | Building a model in pure Python | ~25 min |
The Python assembly ladder¶
The page above is the entry point; one page per component family follows it, each opening with the model it adds rather than repeating the basics.
| Family | Page | Time |
|---|---|---|
| Friction, wall heat, porous drag — and your own closure | Closures on a pipe | ~20 min |
| Composition columns, inert transport, reactions | Species and chemistry | ~15 min |
| Monolith bricks, and choosing a driver | Aftertreatment | ~20 min |
| Cylinder, crank, valve ports, the shared clock | Engines | ~25 min |
| Compressors, turbines, shafts, controllers | Turbo and control | ~20 min |
Task-based recipes¶
Short, focused walkthroughs that answer "how do I set up X?" rather than "how do I run example N?". Each one anchors on a bundled example you can copy + modify.
| You want to… | Start here | Time |
|---|---|---|
| Add a throttle BC + PI loop on manifold pressure | How to add a throttle controller | ~15 min |
| Wire EGR with O₂ closed-loop feedback | How to model EGR with O₂ feedback | ~20 min |
| Build a DOC + DPF + SCR chain with urea | How to set up an aftertreatment chain | ~30 min |
| Train + tune an ML surrogate for the surface-chemistry step | How to train an ML chemistry-rate surrogate | ~30 min |
What each tutorial covers¶
Your first run: Sod shock tube — runs the
canonical 1D shock-tube benchmark. Walks through what
aeolus1d run does, what comes out of the HDF5 file, how to
plot it, and how to compare against the analytical solution.
Pure single-pipe; no junctions, no engine, no chemistry. The
shortest path from zero to a meaningful result.
Networks and junctions — connects two pipes
through a 0-D plenum, demonstrating aeolus1d's network model.
Walks through the schema's polymorphic structure
([[pipe]] blocks, [[junction]] blocks, [[bc]]
blocks), opens the case in the GUI to drag components around,
and shows how the steady-state mass-flow constraint emerges.
Required reading before any engine work.
Engine simulation end-to-end — drives the 4-cylinder diesel example through the entire Phase 25 fuel chain. Injection → blowback → manifold transport → turbo pass-through → SCR brick HC oxidation → silencer → tailpipe audio. Probably the most fun aeolus1d session you can have on a laptop. Builds on the previous two tutorials.
Post-processing walkthrough — takes the HDF5 trace from the engine tutorial and reduces it to GT-POST / Cruise-M-grade engine numbers: per-cycle IMEP + PMEP + COV; heat-release inversion → CA10 / CA50 / CA90 + polytropic exponents; SPL / dB(A) / 1/3-octave / engine-order analysis on the tail-pipe probe; muffler transmission loss; Sankey-ready energy balance; cumulative-emissions integration; turbo operating-point overlay on the compressor map; drive- cycle integration. Closes the on-ramp story that the previous three tutorials open.
After the tutorials¶
When the four walk-throughs feel comfortable, the natural next steps are:
- Component index — the single cross-reference mapping every component to the model it uses, its theory section, a runnable example, and its tutorial. The fastest way to find "where is X documented, and what case can I copy?".
- Examples reference — categorical index
of every TOML in
examples/, grouped by topic. Pick whichever is closest to your problem and adapt it. - Theory — the equations + closures behind the numerics. Worth reading once you've seen results and want to understand why they look the way they do.
- GUI guide / CLI reference — depth on each driver mode.
aeolus1d optimize— fitting model parameters to measured data via the[optimize]block.
If you get stuck, the existing examples table is the fastest way to find a similar working case to crib from.