Tutorial notebooks

Fourteen worked notebooks live in notebooks/, numbered in reading order. Each carries its figures inline, so they can be read on GitHub without being run, and each ends with a footer pointing at the previous notebook, the next one, and the API reference.

They are the long form of Numerical recipes. A recipe is a few lines and its output; a notebook is the same calculation with the reasoning around it — why the convention is what it is, what happens at the edges, and what the numbers were checked against. Both call the same functions, so there is no third version to drift out of step.

To run them rather than read them:

pip install "magnus[notebooks]"
jupyter lab notebooks/

Note

The notebooks are not built into this documentation — executing fourteen of them on every docs build would take the better part of an hour, and they are more useful where their outputs are already stored. The links below go to GitHub, which renders them with their figures.

They are generated. notebooks/make_notebooks.py builds all fourteen, executes them and stores their outputs, and CI runs the same execution on every change to the notebooks or to the package: a notebook is documentation that claims to work, and running it is what makes the claim checkable. Edit the generator, not the .ipynb.

Start here

The conventions everything else assumes, and the two systems every treatment of oscillations opens with.

01. Introduction: The shortest path to a probability: single channels, arrays of energies and baselines, and what the returned matrix is indexed by.
02. Two-neutrino probabilities: Vacuum, constant density, exponential and Gaussian profiles, castle-wall and noisy potentials, the Earth and the Sun — each validated against the closed-form expression where one exists. The fullest tour of the supported matter profiles.
03. Three-neutrino probabilities: The same seven settings with three flavours and a CP-violating phase. Nothing about the method changes; the Hamiltonian is one dimension larger.

Geometry, and what experiments measure

Once the trajectory is a real one, the geometry starts to matter as much as the Hamiltonian.

04. Long baselines: Probabilities between two points on the Earth’s surface — the geometry of DUNE, T2K, Hyper-K and ESS. Give the coordinates and the chord follows.
05. Biprobability plots: Neutrino against antineutrino as the CP phase runs. The area enclosed is the CP violation an experiment is trying to measure.
06. Oscillograms: Probability across zenith angle and energy at once. The workload that most rewards passing arrays rather than looping.

New physics

Each of these is a different Hermitian matrix in the same slot, so the machinery is unchanged and only the Hamiltonian differs.

07. Sterile neutrinos: Four- and five-flavour systems, where the extra states do not couple to the weak interaction.
08. Non-standard interactions: A new matter potential with off-diagonal couplings the Standard Model does not have.
09. Lorentz-invariance violation: An energy dependence the vacuum term does not have.

What the method actually does

The two notebooks for readers who want to know why the answers are what they are, rather than how to ask for them.

10. Phase-averaged probabilities: What survives when the oscillation phase is unresolvable — and why an error that is a phase disappears under averaging while one that is an envelope does not.
11. The matrix exponential: How \(\exp(\Omega)\) is built, and why the route matters: the truncated series is anti-Hermitian, so its exponential is exactly unitary only if the exponential itself preserves that.
12. The strategy parameter: 'auto' against 'magnus', timed and scored against solve_ivp. The headline is not the speed: for three or more flavours the old default can hit its refinement caps and return a plausible, exactly unitary, wrong answer.

Where the limits are

The two notebooks that show what Magνs gets wrong, and how to tell the two kinds of wrong apart.

13. A tabulated solar model: A real BS05 profile rather than an exponential. A case that looks wrong by 1.4e-03 and is not: the error is a phase, and averaging removes 53x of it.
14. A supernova shock front: The contrast. Here averaging does essentially nothing, because a shock changes the adiabaticity of the level crossing and so moves the conversion probability itself. Wrong, and loud about it.
23. When averaging rescues you: The mechanism behind those two, isolated on a cheap vacuum probability: a phase error is suppressed a hundredfold by averaging, an envelope error by a fixed factor of about seven that no number of cycles improves.

Conventions worth getting right

Two notebooks about the places where a wrong answer looks exactly like a right one.

15. Antineutrinos, done properly: Conjugating the PMNS matrix and flipping the matter potential are two separate things, and doing one without the other returns a plausible wrong answer. Measured: 0.014 correct against 0.057 and 0.023 for the two halves.
18. Unusual density profiles: Five profiles with the same mean density differing by up to 0.98 in probability — and the single rearrangement that changes nothing, exactly, whenever \(\delta_{\rm CP}\) is 0 or \(\pi\).

Physics questions

16. Exact versus the approximations: The textbook closed forms are exact, and Magνs reproduces them to \(10^{-14}\). What breaks is substituting a mean density for a varying one: worth 0.51 in probability on a core-crossing chord.
17. Mass ordering and the octant: The ordering is carried entirely by the sign of D31. Through the core it separates the two by 0.48; the octant, by about 0.015.

Using and diagnosing the machinery

19. Bring your own Hamiltonian: The actual interface is one callable returning a Hermitian matrix. Covers the vectorisation trick, and what the Earth entry point declares on your behalf.
20. Numerical edge cases: Exact degeneracies, zero baselines and empty requests all return numbers rather than NaN. Plus what each of the nine warning classes means, and which to act on.
21. What rtol and atol promise: A stopping criterion, not an error bound. Measured against an independent solve_ivp oracle: a request for \(10^{-2}\) came back wrong by \(2.5\times10^{-2}\) and reported success.
22. Which engine answered, and why: Six engines in five families, and cross_check_strategies — an error bar that needs no oracle, because two different methods disagreeing is itself the signal.
24. Performance: What is worth doing, measured live — and, more usefully, when each trick is worth nothing at all.