GRANDlib Handbook

The GRANDlib Handbook, converted from the LaTeX source in resources/GRANDlib_Handbook.zip and included here so that it is searchable alongside the rest of the documentation.

Download the PDF

GRANDlib Handbook (PDF, 78 pages) – compiled from the same source by docs/dev/build_handbook_pdf.py, with the errata below reproduced after its table of contents and a build provenance block on the title page naming the commit it came from.

Note

The Handbook was written separately and is not updated with this documentation. It describes a Docker-based installation that is no longer maintained. Where it disagrees with the code, the code is right. Read Quick start guide and Installation and requirements first; come here for sim2root, granddb and the example scripts, which it covers in more detail.

• Introduction
• Installation
• Installation via Docker
  • Installation via Conda
• Directory Structure
• Data
  • download_data_grand.py
  • Docs
  • Env
  • Examples
  • Grand
  • Granddb
  • Quality
  • Scripts
  • Sim2Root
  • Src
  • Src_outlib
  • Tests
  • Wheel/
• Grandlib Classes
• ROOT Files

Errata

Every entry below was checked against the package rather than assumed.

Errata

Topic	The Handbook says	The code says	Where
Antenna arms	The “East-West arm” is “denoted as EW or X arm”, and South-North as “SN or Y arm”.	The opposite. X is the south-north arm and Y is the east-west arm, which is what the code does and what GRANDCS implies.	The Handbook has the X and Y antenna arms swapped
Air showers	GRANDlib “allows [us] to simulate air showers” and to “simulate air showers and generate corresponding electric field traces”.	It does not. Air showers and their radio emission come from ZHAireS or CoREAS; grand/sim/shower/gen_shower.py holds ShowerEvent, a container with load and dump, not a generator.	The simulation chain
Module names	Lists grand.io for file I/O and grand.topography for terrain.	Neither exists. They are grand.dataio and grand.geo.topography.	API reference
Docker install	Presents Docker as the first installation route, naming the published images grandlib/dev:1.x and 2.0.	Unmaintained. Those images are the newest published — 1.2 dates from 2023-01-14 — and pin ROOT 6.26.02 against 6.36 in the conda environment and 6.36/6.38 in CI, on an Ubuntu 20.04 base out of support since April 2025. Nothing builds them and no CI covers them. The supported route is the conda environment.	Installation and requirements
Reconstruction	Describes grand/recon/ as “Reconstruction Algorithms” and grand.aoi as providing “filtering and reconstruction”.	grand.recon was a placeholder: two classes with a constructor and no other method. It was removed in 2026-09, when reconstruction arrived as grand.analysis: direction, Xmax distance and an energy proxy.	API reference
Python dependencies (Docker)	Tells readers to pip install -r requirements_vers.txt for pinned versions.	Do not. That file was a 2022 pin set – numpy 1.22.1, and a Pillow with a critical advisory – that nothing ever built from, and it was removed on 2026-09-08. Use the conda environment, env/conda/grand-dev.yml. The online Directory Structure page is already corrected; the PDF is compiled from the unchanged source.	Installation and requirements
Commands	CoreasToRawROOT.py proton/; sim2root.py <path>/*.rawroot -d ... -e DC2Alpha; convert_efield2voltage.py <efield.root> -o out.root then convert_voltage2adc.py out.root -o adc.root.	Each fails. The CoREAS converter takes -d proton; sim2root.py needs -sl GP300; both conversion scripts take the folder sim2root.py wrote, not a file, and name their outputs into it. The Directory Structure page is corrected; the PDF is not.	Converting simulations: sim2root, The simulation chain
Installation commands	conda env create -f reqmt_grandenv_2509.yml after cd grand; grandlib_amd64.yml and requirements.txt; a docker run -v $PWD:/home/grandlib/dev:x line; Jupyter at https://localhost:8888.	The environment file is env/conda/grand-dev.yml; the other two files do not exist; the docker run line is malformed; Jupyter serves http://localhost:8888.	Installation and requirements
Removed code	Snippets use tests/tools/test_fake.py, tests/recon/test_elec_field.py, test_params_shower.py, grand.io.root_trees, from grand.topography import Topography and data/test_efield.root.	None of these exists any more. The readers are in grand.dataio, topography in grand.geo.topography, and the tests under tests/ as listed in Test suite.	API reference