Tutorial notebooks

Twelve 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 links to the previous and next.

None of them needs a real DEM. Every notebook builds its own terrain, because the DEMs are a quarter of a gigabyte and are not in the repository — a tutorial only its author can run is not a tutorial. Notebook 7 will use the Colca DEM for three of its eight animations when it is there, because those three are about what a criterion does to real ground, but it falls back to synthetic terrain and says on each figure which it used.

To run them rather than read them:

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

Note

The notebooks are not built into this documentation. Executing them on every docs build would be slow, and they are more useful where their outputs are already stored. They are executed in CI on every push, which is what makes their claim to work checkable rather than merely plausible.

Start here

1. Getting started: The question the tool answers, a piece of terrain, one scan, and what the observables mean.
2. The arrival scan: How one profile walk fills every elevation bin at once, why azimuths rather than bins set the cost, and why the ground at your own feet blocks every steep downward ray.

The physics

3. The physics toolkit: Tau decay lengths, shower development in grammage rather than metres, the Earth chord, and geomagnetic emission — all usable with no terrain at all.
4. Criteria and scoring: The three score shapes and their composition, plus two traps: a saturating score whose scale is wrong stops discriminating, and a product score has no safe threshold.

Two experiments

5. GRAND and TAMBO: The same engine, two experiments, and exactly which numbers differ. Recovers a canyon’s wall slope from the terrain it was built with.
6. Combining and sensitivity: Joint, union and co-location, then the more important question: how much a result depends on its assumptions. Read this one before quoting a capacity.

Seeing it move

7. Animating the mechanism: The eight animations in tools/make_animations.py, built and explained — what each one argues, and why the six rejected candidates are better served by a static figure. Ends with how to turn the MP4s into animated GIFs, both through the tool and with plain ffmpeg.

Running one

8. Explaining a run: The pipeline as an ordinary Python call, and how to read what it says: configuration as data, the memory pre-flight, the results dictionary it hands back, the funnel and its binding constraint, which sites are actually in the result, why each one is good and what held it back. Two searches — one that finds ground and one that finds none, because the empty result is the case a bare results file serves worst.

Real ground, region by region

These share a numbering block so a new region slots in without renumbering its neighbours. Each reads results produced locally by tools/run_full_dem.py rather than running the searches itself.

9. Arequipa, the full DEM: The run that had never been done: GRAND alone, TAMBO alone, and the combination, over the whole DEM rather than a crop, at 1 arc-second.
10. Ancash: The same three searches over the Cordillera Blanca and the Callejón de Huaylas, at the same resolution and with every transferable criterion unchanged — so a difference in the answer is a difference in the ground rather than in the question.
11. Lima: The third department, and the one that closes the set: desert shelf rising to the western Andean flank, against Arequipa’s plateau and Ancash’s Cordillera Blanca. It is mostly about the three-way comparison, because a difference between two regions can be a coincidence and a trend across three is harder to dismiss. Also the Cajatambo crop, cut from this DEM and run unbiased, and the table of how far a GRAND array of a given size sits from the best TAMBO site.
12. Peru, all of it: The search run over a whole country — 339 million pixels at 3 arc-seconds, in four minutes. As much about reading a coarse answer honestly as about Peru: why the resolution is forced rather than chosen, why the area is a bracket and the site count is worse than the area, and one worry that was checked and came back fine.

Going deeper

13. Turning the knobs: Each parameter turned, and what moves. Two of the five sit on cliffs and a third changes one reported number while leaving another alone. The striding penalty is shown to depend on how thin the accepted ground is, which is why the same knob costs 1.51× at Colca and 23.0× on the Callejón de Huaylas. Runs in seconds on terrain it builds itself.

Note

Notebooks 7 through 10 are not executed in CI. Seven renders eight animations and wants an ffmpeg the runner does not have; eight drives whole searches; nine and ten read stored full-DEM results that take tens of minutes to produce. They are run locally when a configuration changes; tests/test_docs.py checks statically that the API names they call still exist, which is the drift the execution would have caught.

Notebook 12 is executed, despite reading a store it will not find there. Every cell that needs the store is guarded and every other cell computes from the library, so on a bare runner it degrades to the prose and the arithmetic rather than failing — which is the behaviour worth having checked on every push.