Tutorials

These tutorials combine several SOLVAX components into complete workflows. They are intentionally small enough to run on a laptop and explicit enough to adapt to transport, kinetic, equilibrium, and PDE applications.

• Tutorial: a reusable block-tridiagonal transport solve
• Tutorial: matrix-free anisotropic PDE with a line preconditioner
• Tutorial: matrix-free Newton-Krylov for a nonlinear PDE
• Tutorial: differentiate a converged matrix-free solve

What each tutorial teaches

Tutorial	Main ideas
Tutorial: a reusable block-tridiagonal transport solve	storage, factor reuse, multiple RHS, residual checks, transpose solve
Tutorial: matrix-free anisotropic PDE with a line preconditioner	operator action, structured principal-part preconditioner, FGMRES diagnostics
Tutorial: matrix-free Newton-Krylov for a nonlinear PDE	Jacobian-free Newton-Krylov, structured Jacobian preconditioner, nonlinear/linear convergence flags
Tutorial: differentiate a converged matrix-free solve	primal/adjoint separation, implicit VJP, finite-difference validation

The repository also contains focused scripts in examples/, one per major capability. The documentation tutorials emphasize composition and engineering decisions; the example scripts emphasize minimal runnable demonstrations.

Kinetic generated-block example

Script	Device	Expected runtime	Output	Assumptions
examples/01_block_tridiagonal_kinetic.py	CPU or GPU	seconds	shapes, dense-reference error, one gradient	nearest-mode coupling; forcing and observable restricted to modes 0–2

The production solve in this example generates each dense block from compact streaming and collision coefficients. It materializes full bands only for the small validation cross-check; callers should not copy that reference step into production workflows.