Tutorial Notebooks

[LouisDesdoigts]

Thought this might be a good place to discuss what the best way to lay out the tutorial/on-boarding scripts and to have a living document here to track the progress, since much of these notebooks will form the documentation anyway.

Present plan:

Tutorial 0: Package overview (primarily docs)

• Autodiff
• Jax
• Equinox
• ∂Lux
• Optics/NN's

Tutorial 1: Basic Usage - ∂Lux 101

• Layers, OpticalSystem
• PSF generation
• Multiple PSF generation

Tutorial 2: Model Optimisation

• Equinox, Optax and gradients
• Setting up basic optimisation schemes
• Complex optimisation schemes

Tutorial 3: Integrated Models

• How to work with and model supported optical models
• pysiaf (HST/JWST models)

Tutorial 4: Custom Layer Development

• Higher-level 'how it works' (eqx, jit, vmap, tracers)
• Sharp-bits (don't murder your sweet, innocent gradients)
• Writing a layer basics
• Advanced/parametric layers (circular aperture example)
• Chaining multiple wavefront operations into a single layer

Tutorial 5: Higher-Order Derivatives (Advanced ∂Lux, Pupil design paper)

• Correct way to take native jax grads w.r.t input vectors
• Covariance matrix/entropy calculations
• Parametrising model perturbations
• ChainConsumer/Posteriors
• Even more gradients: Optimising model entropies

---

To me, this seems like the clearest path from simple to complex, slowly building up conceptual and practical complexity. Please let me know what you think @benjaminpope @Jordan-Dennis

[Jordan-Dennis]

This looks great. If you want to focus on the later ones I can probably do some of the earlier ones. Is Tutorial 3 possible yet?

[benjaminpope]

Yes, this looks pretty good as a general strategy. I might add though, that some of what these docs are for is documentation, but some of it is advertising: a few .ipynb docs showing off

• pupil design
• flat field retrieval
• etc

would be neat to show off the power of ∂Lux.

[LouisDesdoigts]

Yeah I agree - I'm thinking tutorial 2 (model optimization) is FF recovery, forming the major part of the eventual paper. Tutorial 5 becomes the core of the pupil design paper