Geomagnetic Cutoff Rigidities
The GMRC class computes geomagnetic rigidity cutoffs — the minimum
rigidity a cosmic ray must have to reach Earth from a given direction at a
given location.
Cutoffs are determined via Monte Carlo: random (zenith, azimuth) directions are sampled, and for each direction the code scans rigidities from low to high until the trajectory escapes Earth's field.
Angles give the arrival direction; azimuth 0 = from north, 90 = from east, clockwise (see Conventions).
Two evaluation modes
evaluate() — Python-orchestrated
Supports all field types ("igrf", "dipole", "table"). Uses
ProcessPoolExecutor for igrf/dipole and ThreadPoolExecutor for
table (GIL released in C++).
from gtracr.geomagnetic_cutoffs import GMRC
gmrc = GMRC(location="Kamioka", iter_num=10000, bfield_type="igrf",
solver="rk4", n_workers=8)
gmrc.evaluate(dt=1e-5, max_time=1.)
evaluate_batch() — C++ batch mode (fastest)
The entire MC loop — RNG, coordinate transforms, rigidity scanning, and
threading — runs in a single C++ call via BatchGMRC. Requires
bfield_type="table". Achieves ~35k trajectories/second with solver="rk45".
gmrc = GMRC(location="Kamioka", iter_num=10000,
bfield_type="table", solver="rk45")
gmrc.evaluate_batch(dt=1e-5, max_time=1., base_seed=42)
Pass base_seed for reproducible results. If omitted, a random seed is
chosen at runtime.
Cutoffs outside the scanned range
For bisection, every sampled direction is kept. rcutoff is clipped to the scanned
rigidity range [min_rigidity, max_rigidity] (both ends included):
rcutoff == min_rigidity: the lowest rigidity already escapes, the cutoff is at or belowmin_rigidity;data_dict["above_rmax"]isTrue: no scanned rigidity escapes, the cutoff is abovemax_rigidityandrcutoffholdsmax_rigidityas a lower bound. Mask these directions or raisemax_rigidityif the high cutoffs matter.
Getting results
bin_results() (recommended)
Bins MC samples into a regular (azimuth, zenith) grid. Fast and appropriate for large sample counts.
az_centres, zen_centres, cutoff_grid = gmrc.bin_results(
nbins_azimuth=72, nbins_zenith=36
)
# cutoff_grid shape: (36, 72), NaN where no samples fell
interpolate_results() (legacy)
Scattered interpolation via scipy.interpolate.griddata.
az_grid, zen_grid, cutoff_grid = gmrc.interpolate_results()
Parameters
location also accepts a gtracr.location.Location object with explicit
latitude, longitude and altitude (km). This is useful when a downstream
atmosphere model supplies the site geometry. Its coordinates take precedence
over the built-in location table, even if its name matches a registered site.
The same object is accepted by Trajectory(location_name=...).
GMRC constructor
| Parameter | Default | Description |
|---|---|---|
location |
"Kamioka" |
Predefined detector location. |
iter_num |
10000 |
Number of MC samples. |
bfield_type |
"igrf" |
Field model: "igrf", "dipole", or "table". |
particle_type |
"p+" |
Particle label. |
date |
today | IGRF date ("yyyy-mm-dd"). |
min_rigidity |
5. (0.3 for penumbra) |
Lower bound of rigidity scan (GV). |
max_rigidity |
55. (100. for penumbra) |
Upper bound of rigidity scan (GV). |
delta_rigidity |
1. |
Rigidity step size (GV). |
n_workers |
physical CPUs | Number of parallel workers. |
solver |
"rk4" |
Integrator: "rk4", "boris", or "rk45". |
atol |
0. |
Absolute tolerance (RK45, dimensionless). |
rtol |
1e-7 |
Relative tolerance (RK45). |
escape_factor, time_factor |
4, 80 |
Escape criterion (see below); 0, 0 = fixed 10 R_E / max_time. |
method |
"bisection" |
"bisection" or "penumbra" (see below). |
ladder_delta |
0.005 |
Penumbra: relative rung spacing. |
coarse, guard |
8, 2 |
Penumbra: adaptive-scan parameters. |
store_ladder |
False |
Penumbra: keep the allowed/forbidden flag of every rung. |
evaluate_batch() parameters
| Parameter | Default | Description |
|---|---|---|
dt |
1e-5 |
Time step in seconds. |
max_time |
1. |
Integration time per trajectory (seconds); lower bound of the rigidity-aware budget. |
base_seed |
None |
Integer RNG seed for reproducibility. Random if None. |
zenith, azimuth |
None |
Penumbra only: explicit directions (degrees) instead of iter_num random draws. |
Penumbra-resolving cutoffs (method="penumbra")
The default method="bisection" assumes that every rigidity above the cutoff
is allowed and every rigidity below it is forbidden. It returns the first
escaping rigidity that the bisection lands on. Inside the penumbra, where
allowed and forbidden bands alternate, that value is none of the standard
cutoffs. Directions above max_rigidity are retained and flagged.
method="penumbra" scans a geometric rigidity ladder
R_k = R_min (1 + δ)^k, k = 0 … K−1, K = ⌈ln(R_max/R_min)/ln(1+δ)⌉ + 1. Rung k
covers [R_k/√q, R_k √q] with q = 1 + δ. For every direction, evaluate_batch()
returns the cutoffs of Cooke et al. (1991):
| key | definition |
|---|---|
r_upper (R_U) |
upper edge of the highest forbidden rung |
r_lower (R_L) |
lower edge of the lowest allowed rung |
r_eff (R_eff) |
R_U − Σ allowed rung widths in [R_L, R_U] (= bottom ladder edge + Σ forbidden widths); also stored as rcutoff |
flag |
0 resolved; 1 nothing forbidden (cutoff below the ladder, R_L = R_U = R_eff = bottom edge); 2 top rung forbidden (R_U, R_eff are lower bounds) |
Every direction is kept, including flag 1 and 2. R_eff is the cutoff to use for
fluxes: a sharp cut at R_eff gives the same transmitted rigidity range as
the band structure, measured in linear rigidity. The top rung centre may
lie slightly above max_rigidity.
gmrc = GMRC(location="Kamioka", bfield_type="table", solver="rk45",
method="penumbra", min_rigidity=0.3, max_rigidity=100.,
ladder_delta=0.005)
# fixed grid of directions
zen, az = np.meshgrid(np.arange(0., 181., 5.), np.arange(0., 360., 5.))
gmrc.evaluate_batch(zenith=zen.ravel(), azimuth=az.ravel())
r_eff = gmrc.data_dict["r_eff"]
Adaptive scan. First every coarse-th rung is traced, plus the bottom
rung. Each coarse interval within guard intervals of an allowed/forbidden
change is then traced rung by rung. The other intervals take the common
value of their two end rungs. With coarse=1 every rung is traced and the
result is exact on the ladder. The adaptive scan can miss a band narrower
than one coarse interval if it lies away from every detected change, most
often an isolated allowed band low in the penumbra. When that happens R_L
moves a lot, but R_eff hardly changes. Two IGRF directions at Kamioka
(δ = 0.5 %, 0.3–100 GV) each missed a single allowed rung: R_L moved by 22 % and 12 %,
R_eff by 0.4 %. In a 0.3–100 GV global study with the same scheme, adaptive
and full-ladder R_eff agreed to 0.41 % rms. R_eff changed by 0.35 % rms
between δ = 0.5 % and 0.25 %. Use R_L only from full-ladder scans.
Transmission functions. With store_ladder=True, gmrc.ladder holds the
rung centres and gmrc.ladder_allowed (shape (n, K), bool) the
allowed/forbidden flag of every rung and direction. Averaging the flags over
directions gives a transmission function.
When to use. Use penumbra mode whenever the cutoff feeds a flux calculation, a cutoff map at low or mid latitudes, or any direction close to the horizon. These are the cases where the penumbra is wide. Bisection is fine for quick looks where an error of a few GV inside the penumbra does not matter.
Escape criterion
A back-traced trajectory is allowed when it reaches the escape radius before it returns below the starting altitude, and forbidden when it returns or runs out of time. gtracr scales both limits with the rigidity of each trajectory (all solvers, the single-trajectory path and both GMRC modes):
r_esc = max(escape_radius, k · C_St(p)),
t_max = max(max_time, N · r_esc / (β c)),
where C_St = R_E √(B0 R_E |q| / p) is the Störmer length and
B0 = √(g10² + g11² + h11²) the dipole strength of the active field model,
computed once per tracer. The defaults are escape_factor k = 4 and
time_factor N = 80. escape_radius and max_time stay lower bounds.
escape_factor=0, time_factor=0 restores the fixed criterion (10 R_E within
max_time). Trajectory, GMRC and TrajectoryTracer.set_escape_scaling
accept both parameters.
Why. The fixed 10 R_E / 1 s criterion counts slowly escaping trajectories as forbidden: below about 10 GV, where 4 C_St exceeds 10 R_E, it overestimates the cutoff (dipole R_L at 60° up to 18 % high; South Pole 0.20 instead of 0.067 GV). Against N = 640 the defaults give R_eff within 0.5 % (dipole, Oulu) and 3 % at the South Pole (quasi-trapped orbits).
Validity. Only the internal field is modelled; beyond the magnetopause (about 10 R_E on the day side) the real field is not IGRF. Cutoffs below about 1 GV, at high latitudes, remain model values in either criterion; an external field model (e.g. Tsyganenko) lowers them further.
Cost. Unchanged above about 10 GV. Bisection at mid latitudes costs ×1.1–1.4; full high-latitude penumbra ladders ×7–17. A forbidden trajectory at 0.3 GV runs about 3·10⁷ RK4 steps of 10 µs (r_esc ≈ 56 R_E); the step budget is capped at 2·10⁸.
Solver recommendation
For GMRC evaluation, solver="rk45" with bfield_type="table" is
the fastest combination. The adaptive stepper takes ~100x fewer steps than
fixed-step RK4 for allowed trajectories, and the tabulated field eliminates
spherical harmonic computation.
Complete example
import numpy as np
from gtracr.geomagnetic_cutoffs import GMRC
from gtracr.plotting import plot_gmrc_heatmap
gmrc = GMRC(
location="Kamioka",
iter_num=100000,
bfield_type="table",
solver="rk45",
min_rigidity=1.,
max_rigidity=55.,
delta_rigidity=0.5,
)
gmrc.evaluate_batch(dt=1e-5, max_time=1.)
grids = gmrc.bin_results(nbins_azimuth=72, nbins_zenith=36)
print(f"Mean cutoff: {np.nanmean(grids[2]):.1f} GV")
plot_gmrc_heatmap(grids, gmrc.rigidity_list,
locname="Kamioka", plabel="p+", bfield_type="table")
