Add tutorials for FESTIM 2.2-rc.2 features

[RemDelaporteMathurin]

Covers the four user-facing features of v2.2-rc.2, which the book had no page for, and moves the rest of the book onto the new API.

environment.yml: festim==2.2rc1 → 2.2rc2. A clean drop-in — no new packages, so no effect on the Binder image layer size.

New chapter: Drift terms (content/drift/)

Nothing covered Soret or electromigration; advection appeared only inside two application pages.

• soret.md — a closed slab in a temperature gradient, run with and without the term. Checked against the analytical steady state c ∝ exp(Q*/k_BT) (9e-8) and the inventory conserved to 6e-14.
• electromigration.md — a charge sweep over z ∈ {−1, 0, +1}, checked against the Boltzmann distribution (1e-5).
• advection.md — the divergence form and OutflowBC, taught by running one channel twice: with no outlet condition the concentration peaks at 15.5× the inlet value against the now-closed end; with OutflowBC it maxes at 1.0. Then a uniform-field case where the diffusive flux is identically zero, so the SurfaceFlux reading of ⅔·v_max·L_y is provably the drift contribution.

New chapter: Manifold subdomains (content/manifolds/)

• manifold_basics.md — declaring a codim-1 subdomain, the bulk exchange pair and its units, codim-2 boundary conditions, trapping, and derived quantities in all three places. A grain boundary carrying 4.5× what the whole square does.
• pipe_wall.md — a coolant channel as a manifold: advection along it, a codim-2 inlet and an OutflowBC outlet. Pickup rate matches the wall permeation to 1.3%.

Reactions and exports

• species_reactions/generic_reactions.md — the ReactionBase / GenericReaction / ArrheniusReaction / DecayReaction hierarchy, rate coefficients as callables of T or of another species, and tritium → He-3 decay with T+He conserved to 1e-10.
• post_process/exports.md rewritten around SpeciesExport/TemperatureExport and the format argument (vtx / vtkhdf / xdmf / checkpoint), including a single-file vtkhdf multi-material export and a checkpoint round-trip.
• initial_conditions/concentration.md now does its checkpoint round-trip through FESTIM instead of raw io4dolfinx.

Deprecation sweep

F.Reaction → F.ArrheniusReaction, VTX*/XDMFExport → SpeciesExport/TemperatureExport, advection_terms → drift_terms, model.method_interface → Interface(method=...). No notebook emits a DeprecationWarning any more.

One physics fix

task06 was wrong under 2.2. Drift is now assembled in divergence form, so the boundary term constrains the total flux and an untagged boundary is a wall. Its right-hand boundary (id=3) was declared but never given a condition, and the flow leaves through it — so hydrogen was piling up against a closed end. It now carries an OutflowBC.

cfd.md needed only the rename: the lid-driven cavity has Dirichlet BCs on all four sides and a divergence-free field, so its results are unaffected.

Verification

• Every new and rewritten page executes clean with its asserts passing.
• All 9 modified notebooks re-execute clean: task01, task02, task04, task06, task08, task10, reactions, paraview, microstructure.
• Sphinx build passes; the 8 warnings are all pre-existing (surrogate.md, heat_transfer.md) or from untracked local scratch files — none from anything touched here.
• Not run: cfd.md, which needs the OpenFOAM cavity data that is untracked locally. Its change is the rename plus prose. Worth a run before merge, as it is the only untested file.
• A full jupyter-book build with execution on was not run (it force-executes the ML and CFD pages).

Upstream note

FESTIM's docs/source/userguide/subdomains.rst carries a note claiming SurfaceFlux is diffusive-only on a manifold carrying an AdvectionTerm. That is stale: pipe_wall.md measures +9.31e-3 at the manifold outlet, matching v·c_out = 9.33e-3, where diffusive-only would give −1.8e-5 — opposite sign, 500× smaller. The note predates the drift work by two days (f26b6677 vs f24bb099), and no matching warning exists in the source. Upstream's own test_outlet_flux_of_a_manifold_carrying_advection cannot catch it because it fixes c=0 at the outlet.

🤖 Generated with Claude Code