Cutoff¶

Cutoff Diagram

Vertical cosmic rays backtraced from the Oulu neutron monitor at decreasing rigidity using the IGRF and TSY89 models with kp = 0 for 1 January 2024 12:00 UT (the OTSO defaults). These conditions differ from the figure above (IGRF 2000 epoch), so the penumbra structure and cut-off values are not the same, mainly because the geomagnetic field has changed between the two epochs. Above the penumbra all trajectories are allowed (blue); within it allowed and forbidden (orange) bands alternate and the trajectories become increasingly complex; below it all are forbidden. The bar fills in the allowed and forbidden pattern at 0.005 GV resolution, and the upper, effective and lower cut-off rigidities (Ru, Rc and Rl) are marked at the end.

OTSO.cutoff ¶

cutoff(
    Stations: Union[str, Sequence[str]],
    customlocations: Optional[list] = None,
    cutoff_comp: str = "Vertical",
    solar_wind_params: SolarWindParams = {},
    geomagnetic_params: GeomagneticParams = {},
    tsyganenko_params: TsyganenkoParams = {},
    datetime_params: DateTimeParams = {},
    magfield_params: MagFieldParams = {},
    integration_params: IntegrationParams = {},
    particle_params: ParticleParams = {},
    rigidity_params: RigidityParams = {},
    coordinate_params: CoordinateParams = {},
    computation_params: ComputationParams = {},
    data_retrieval_params: DataRetrievalParams = {},
    custom_field_params: CustomFieldParams = {},
    asymptotic_params: AsymptoticParams = {},
    transmission_params: TransmissionParams = {},
) -> list

Compute geomagnetic cutoff rigidities for given neutron monitor stations, or user-defined locations.

Upon calling this function, OTSO will perform particle tracing simulations based on the specified parameters, returning the cutoff rigidities and related metadata. Asymptotic viewing directions and transmission functions can also be computed on request.

Parameters:

Stations (str | list) –

Station name(s) or identifiers used for cutoff calculations.
customlocations (list, default: None ) –

Custom locations as [["NAME", lat, lon]].
cutoff_comp (str, default: 'Vertical' ) –

Cutoff computation method ("Vertical", "Apparent", "Custom").
datetime_params (DateTimeParams, default: {} ) –
Date/time parameters.

Available keys:
- year (int, default=2024): Year (e.g., 2023)
- month (int, default=1): Month (1–12)
- day (int, default=1): Day (1–31)
- hour (int, default=12): Hour (0–23)
- minute (int, default=0): Minute (0–59)
- second (int, default=0): Second (0–59)
magfield_params (MagFieldParams, default: {} ) –
Magnetic field models.

Available keys:
- internalmag (str, default="IGRF"): "NONE", "IGRF", "Dipole", "Custom Gauss", "CHAOS"
- externalmag (str, default="TSY89c"): "NONE", "TSY87short", "TSY87long", "TSY89a", "TSY96", "TSY01", "TSY01S", "TSY04", "TSY89c", "TSY15N", "TSY15B", "TA16_RBF", "TSY89_refit", "MHD"
- boberg (bool, default=False): Enable Boberg extension
- bobergtype (str, default="EXTENSION"): "EXTENSION", "CONTINUOUS", "DST_DEPENDENT", "DST_MIDPOINT"
- magnetopause (str, default="Kobel"): "NONE", "Kobel", "Sibeck", "Lin", "Sphere", "aFormisano"
- spheresize (float, default=25): Spherical boundary radius (Re)
- AdaptiveExternalModel (bool, default=False): Auto-select external model
- optimise_tsy (bool, default=False): Use the faster implementation of the selected Tsyganenko model (affects externalmag="TSY01", "TSY01S", "TSY04", or "TSY96"; other models are unaffected by this flag). Both settings give numerically identical results (all known bugs are fixed in both); True is just faster
rigidity_params (RigidityParams, default: {} ) –
Rigidity scanning.

Available keys:
- startrigidity (float, default=20): Initial rigidity (GV)
- endrigidity (float, default=0): Final rigidity (GV)
- rigiditystep (float, default=0.01): Step size (GV)
- rigidityscan (str, default="ADAPTIVE"): Penumbra scanning ("ADAPTIVE"/"ON"/"OFF"). "ADAPTIVE" extends the fine scan until the penumbra is bounded by clean guard bands; "ON" uses a fixed ±0.75 GV window around a 0.25 GV coarse scan; "OFF" scans the full range
asymptotic_params (AsymptoticParams, default: {} ) –
Asymptotic computation parameters.

Available keys:
- unit (str, default="GeV"): level unit ("GeV", "GV")
- asymptotic (str, default="NO"): Enable asymptotic cone computation ("YES"/"NO")
- asymlevels (list, default=[0.1,0.3,0.5,1,2,3,4,5,6,7,8,9,10,15,20,30,50,70,100,300,500,700,1000]): level values for asymptotic computation
transmission_params (TransmissionParams, default: {} ) –
Transmission function computation parameters

Available keys:
- transmission (bool, default=False): Bool to enable or disable transmission computation
- transmissionRstep (float, default=0.001): R ± transmissionRstep defines the transmission rigidity sampling range
- transmissionsamples (int, default=20): the number of sample rigidities to test within the sampling range
solar_wind_params (SolarWindParams, default: {} ) –
Solar wind parameters. Defaults are quiet-time medians (Kp <= 1) of OMNI data, 1996-2025.

Available keys:
- vx (float, default=-359.4): Solar wind velocity x-component (km/s)
- vy (float, default=0): Solar wind velocity y-component (km/s)
- vz (float, default=0): Solar wind velocity z-component (km/s)
- bx (float, default=0.11): IMF x-component (nT)
- by (float, default=-0.16): IMF y-component (nT)
- bz (float, default=0.58): IMF z-component (nT)
- by_avg (float, default=-0.17): Averaged IMF By over last 30mins (nT)
- bz_avg (float, default=0.59): Averaged IMF Bz over last 30mins (nT)
- density (float, default=4.94): Solar wind density (particles/cm³)
- pdyn (float, default=1.31): Solar wind dynamic pressure (nPa); computed from density and velocity when 0, or when density or velocity is given without pdyn
geomagnetic_params (GeomagneticParams, default: {} ) –
Geomagnetic indices. Defaults are quiet-time medians (Kp <= 1) of OMNI data, 1996-2025.

Available keys:
- Dst (float, default=-4): Dst index (nT)
- kp (float, default=0.7): Kp index (0-9)
- n_index (float, default=0.145): Newell coupling function
- b_index (float, default=0.032): Boynton coupling function
- sym_h_corrected (float, default=-18.07): Corrected SYM-H index (nT)
tsyganenko_params (TsyganenkoParams, default: {} ) –
Tsyganenko model coefficients. Defaults are quiet-time medians (Kp <= 1) of OMNI data, 1996-2025.

Available keys:
- G1 (float, default=0.38): Tsyganenko G1 coefficient
- G2 (float, default=0.12): Tsyganenko G2 coefficient
- G3 (float, default=0.47): Tsyganenko G3 coefficient
- W1 (float, default=0.07): Tsyganenko W1 coefficient
- W2 (float, default=0.06): Tsyganenko W2 coefficient
- W3 (float, default=0.13): Tsyganenko W3 coefficient
- W4 (float, default=0.03): Tsyganenko W4 coefficient
- W5 (float, default=0.05): Tsyganenko W5 coefficient
- W6 (float, default=0.08): Tsyganenko W6 coefficient
integration_params (IntegrationParams, default: {} ) –
Integration settings.

Available keys:
- intmodel (str, default="Boris-Buneman"): "4RK", "5RK", "6RK", "Vay", "HC", "Boris-Buneman"
- gyropercent (float, default=1): Step size as a percentage of the gyration period. With adaptivestep=True (default) it caps each step using the local field; with adaptivestep=False the step is fixed for the whole trace at this percentage of the gyration period at the launch point
- minaltitude (float, default=20): Minimum altitude (GDZ = km or other = Re)
- maxdistance (float, default=100): Maximum path length travelled (Re), not distance from Earth; 0 disables this check (use 0 for long trapped-particle runs: a 0.6c proton travels 100 Re in ~4 s)
- maxtime (float, default=0): Maximum flight time in seconds (lab frame); 0 = no limit
- mintrapdist (float, default=0): Minimum trapping distance
- startaltitude (float, default=20): Starting altitude (GDZ = km or other = Re)
- betaerror (float, default=0.001): Maximum allowed beta error for integration steps %
- totalbetacheck (bool, default=False): Enable cumulative beta check during integration
- adaptivestep (bool, default=True): Enable adaptive time steps
- maxsteps (int, default=0): Maximum number of integration steps; 0 = no limit
particle_params (ParticleParams, default: {} ) –
Particle settings.

Available keys:
- Anum (int, default=1): Atomic number (-1=muon, 0=electron, 1=proton, 2=alpha)
- anti (str, default="YES"): YES = anti-particle, NO = particle
- zenith (float, default=0): Zenith angle for Custom cutoff computation
- azimuth (float, default=0): Azimuth angle for Custom cutoff computation
coordinate_params (CoordinateParams, default: {} ) –
Coordinate systems.

Available keys:
- coordsystem (str, default="GEO"): Output coordinate system; "GDZ", "GEO", "GSM", "GSE", "SM", "GEI", "MAG", "SPH", "RLL"
- inputcoord (str, default="GDZ"): Input coordinate system; "GDZ", "GEO", "GSM", "GSE", "SM", "GEI", "MAG", "SPH", "RLL"
computation_params (ComputationParams, default: {} ) –
Computation settings.

Available keys:
- corenum (int, default=None): Number of CPU cores for multicore processing
- threadnum (int, default=None): Number of threads per CPU core for Fortran computations
- Verbose (bool, default=True): Enable verbose output
- delim (str, default=";"): Delimiter for asymptotic output formatting
data_retrieval_params (DataRetrievalParams, default: {} ) –
Data retrieval.

Available keys:
- serverdata (str, default="OFF"): Server data retrieval from OMNI
- livedata (str, default="OFF"): real-time data retrieval from NOAA
custom_field_params (CustomFieldParams, default: {} ) –
Custom fields.

Available keys:
- g (list, default=None): Gauss g coefficients
- h (list, default=None): Gauss h coefficients
- max_degree (int, default=13): Max degree of spherical harmonic expansion
- MHDfile (str, default=None): MHD simulation file
- MHDcoordsys (str, default=None): MHD coordinate system
- MHDgridtype (str, default="auto"): How the MHD grid is looked up - "auto" detects per-axis spacing automatically, "uniform" forces the fast fixed-spacing path (only correct if every axis really is evenly spaced), "stretched" forces the general path needed for a grid whose resolution varies with position (e.g. finer near Earth)
- MHDinterpolation (str, default="trilinear"): How the field is reconstructed between grid points - "trilinear" is the classic fast corner-blend (kinked gradients at cell boundaries), "tricubic" is a smooth C^1 fit that's far more accurate in smooth field regions but can overshoot near sharp gradients/boundaries, "monotonic" is the same tricubic fit with overshoot limiting (recommended for general use), "divfree" returns the curl of an interpolated vector potential so the field is exactly divergence-free (for long quasi-trapped trajectories; less point-wise accurate than "tricubic"; the gridded field must itself be divergence-free, e.g. an external-only field - a warning is issued otherwise)

Returns:

list ( list ) –
[cutoff_dataframe, asymptotic_dataframe, transmission_dataframe, readme_text]
- cutoff_dataframe: Cutoff data values per input station in a pandas dataframe. (Ru, Rc, Rl, PTF)
- asymptotic_dataframe: Global asymptotic viewing directions for the energy/rigidity levels input.
- transmission_dataframe: Transmission pandas dataframe with transmission function values per input station as a function of rigidity
- readme_text: OTSO computation summary

Examples:

   from OTSO import cutoff

   if __name__ == '__main__':

        stations_list = ["OULU"] # list of neutron monitor stations (using their abbreviations)

        # Example using grouped parameters
        cutoff_results = cutoff(
           Stations=stations_list,
           cutoff_comp="Vertical",
           datetime_params={"year": 2005, "month": 5, "day": 1, "hour": 0},
           magfield_params={"internalmag": "IGRF", "externalmag": "NONE"},
           rigidity_params={"rigiditystep": 0.01}
        )

        # Access the results
        cutoff_data, asymptotic_data, transmission_data, metadata = result