Tutorial notebooks

Worked notebooks live in notebooks/, numbered in reading order. Each carries its figures inline, so they can be read on GitHub without being run.

A recipe (Recipes) shows a task in a few lines; a notebook works through it with the reasoning and the checks behind the numbers.

To run them, start Jupyter from the repository root in an installed environment (Installation and requirements), with the root on the Python path:

export PYTHONPATH=$PWD
jupyter lab notebooks/

The notebooks are not executed when this documentation is built; CI runs them every week and on every change, so their stored outputs stay current.

The notebooks

01. Coordinate systems

The frames and the conversions between them, with a detector layout and a shower axis drawn in each. The long form of Coordinates and conventions.

02. Reading and writing GRAND data

Builds a file from nothing and reads it back; how DataDirectory groups files. The long form of The data model.

03. The antenna response

The effective length against frequency and direction and its phase. Reproduces Fig. 5 of [2].

04. The RF chain

Each stage’s transfer function and the total of Fig. 8, cascaded in ABCD form.

05. Galactic noise

From the LFMap sky to the noise on an antenna arm, its variation over a sidereal day and a check against the tables.

06. From electric field to ADC counts

The whole chain, one stage at a time, on an input built in the notebook.

07. Topography

Heights, the geoid undulation, a terrain map and where an inclined shower axis meets the ground.

08. Pinning the chain

For anyone changing the simulation: what the regression test detects when one input changes.

09. Reading events

grand.aoi: events with their antennas on one clock and the pitfalls of looping over them.

10. Finding data

granddb, the data catalog: finding files locally and in repositories, with no database needed.

11. Reconstructing a shower

Direction, distance to the source and energy from recorded times and amplitudes, on known showers and on ten GP13 candidates.

12. The event viewer

Running examples/eventviewer/ and what each of its panels shows.

Note

Notebook 07 needs SRTM elevation tiles, which are not in version control. The cells that need them detect their absence and say so, so the notebook still runs on a fresh checkout; topography.update_data() fetches what a region needs.

Notebook 11 needs iminuit, which the conda environment carries; elsewhere, pip install -e ".[analysis]". Notebook 12 needs the viewer’s plotting stack, which the conda environment does not carry: install it with pip install -e ".[viewer]".

Where next