Oroscope: terrain site search for particle-astrophysics observatories

Oroscope searches digital elevation models for ground that can host a particle-astrophysics observatory. Greek oros, mountain, and skopein, to look at.

It answers one structural question, and that is what lets a single engine serve experiments that look nothing alike:

From this patch of ground, is there a target surface at the right range, in the right direction, at the right relative orientation, with the right matter behind it?

GRAND wants terrain a few degrees below the horizon and tens of kilometres away, to catch radio from air showers started by Earth-skimming tau neutrinos. TAMBO wants a canyon wall two to five kilometres across, to catch the particles themselves. They differ in their numbers, not in their structure — so both are configurations of the same scan, and a search can report where each is viable and where the two coincide.

What it does

1. Screens terrain by slope, aspect, altitude and exclusion zones.

2. Scans arrival directions from every surviving pixel, finding where a tau could exit and how much rock lies behind it — one profile walk per (candidate, azimuth), serving every elevation bin at once.

3. Scores the result against per-experiment criteria, each a named component.

4. Cleans up morphologically, labels sites, and places detectors on a lattice in real ground coordinates.

5. Writes GeoTIFF, KML, PNG and JSON, plus a selection funnel, a provenance record, and a plain-language account of what was found and why.

What it is not

• Not a shower simulation. Development comes from a Gaisser–Hillas profile and an isothermal atmosphere. No Monte Carlo, no detector response, no trigger model.

• Not a flux or exposure calculation. It reports geometry and acceptance-shaped quantities; turning those into an event rate needs a flux and a response table.

• Not a substitute for a site visit. There is no slope stability, land access, power or cost.

• Not externally validated. The physics is checked against closed-form synthetic terrain and against itself. It has not been compared with any collaboration’s own simulated acceptance. Assumptions and limitations is blunt about what that means.

Getting started

pip install oroscope

or, for a clone with the notebooks, the configurations and the test suite:

git clone https://github.com/mbustama/oroscope.git
cd oroscope
pip install -e .

oroscope --config_path config/grand_colca_config.json

See Installation and Quickstart for the longer version, and The physics for what is actually being computed.

User Guide:

• Installation
  • Requirements
  • From PyPI
  • From a clone
  • Optional extras
  • Getting a DEM
  • Verifying the install
• Quickstart
  • Cut a region
  • Run a search
  • Read what it found
  • Combine two experiments
  • The physics on its own
  • Before a long run
  • Choosing parameters
  • When a search returns nothing
• How the search works
  • The one question
  • The seven stages
  • Striding and closing are one decision, not two
  • Why a product score has no safe threshold
  • Co-locating two arrays
  • What the answer is, and is not
  • Where to go next
• The command line
  • Everything here can be done from code
  • oroscope — run a search
  • oroscope-crop — cut a window out of a DEM
  • oroscope-combine — overlay two or more searches
  • oroscope-sensitivity — how firm is the answer?
  • oroscope-fetch-dem — download the elevation models
  • oroscope-fetch-roads — road geometry for the map
  • tools/make_animations.py — animations of the mechanism
  • tools/run_full_dem.py — the full-DEM runs
  • Where things are resolved from
  • Every option, in full
• Getting the data
  • Elevation models
  • Roads and settlements
  • Radio-frequency interference zones
• Tutorial notebooks
  • Start here
  • The physics
  • Two experiments
  • Seeing it move
  • Running one
  • Real ground, region by region
  • Going deeper
• The physics
  • The question a site search must answer
  • Tracing backwards from the detector
  • Two radii, because two different things propagate
  • The criteria, one at a time
  • Two signals, two physics
  • Joint particle + radio arrays
  • Scoring
  • From accepted pixels to a site
• Assumptions and limitations
  • Numbers that are assumptions, not measurements
  • The two that dominate a canyon result
  • Reported area is not physics-accepted area
  • Using published effective areas: what is corrected, and what is not
  • Physics that is not modelled
  • Terrain and data limitations
  • Where the results have been checked
  • A prediction worth falsifying
• Glossary
• Implementation notes
  • The shape of a run
  • Memory, which is the thing that actually breaks
  • Numerics and geometry
  • Things that were silently wrong once
  • Conventions worth keeping
  • Where the numbers live
• API reference
  • Physics
  • The arrival scan
  • Scoring
  • Aperture
  • The pipeline
  • Explaining a run
  • Tools
  • Figures
  • Fetching data
• References

Author

Written by Mauricio Bustamante (mbustamante@gmail.com). Bug reports and questions are best raised as GitHub issues.

License

Released under the GNU General Public License v3. The full text ships with the source, as LICENSE in the repository root.

Indices and tables

• Index

• Module Index