Trajectory¶

Cosmic rays backtraced from random locations on Earth's surface with OTSO.trajectory using the IGRF and TSY89 models with kp = 0 for 1 January 2024 12:00 UT (the OTSO defaults). Rigidities range from 0.5 to 20 GV. Allowed particles (blue) escape the magnetosphere; forbidden particles (orange) return to Earth or remain trapped.

OTSO.trajectory ¶

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

Compute cosmic-ray particle trajectories using the OTSO framework.

Traces individual particles through the magnetosphere to determine their trajectories from given starting locations and rigidity. Returns a dictionary of trajectories and readme metadata for the computations.

Parameters:

Stations (str | list) –

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

Custom locations as [["NAME", lat, lon]].
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
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): Launch zenith angle
- azimuth (float, default=0): Launch azimuth angle
- rigidity (float, default=1): Particle rigidity (GV)
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
- Verbose (bool, default=True): Enable verbose output
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 ) –
[trajectory_data, readme_text]
- trajectory_data: Dictionary with positional, velocity, filter and asymptotic viewing directions information for trajectories (the "Filter" value gives why the trace stopped: 1 = escaped (magnetopause / outer boundary), -1 = reached minaltitude (Earth/atmosphere), -2 = maxdistance, -3 = maxsteps, -4 = maxtime, -5 = numerical failure (non-finite positions; the trace is not reliable))
- readme_text: OTSO computation summary

Examples:

    from OTSO import trajectory

if __name__ == '__main__':

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

    # Example using grouped parameters
    trajectory_results = trajectory(
        Stations=stations_list,
        particle_params={"rigidity": 0.6},
        computation_params={"corenum": 1},
    )

    trajectory_dict, metadata = trajectory_results

    # Accessing the Oulu trajectory value.
    Oulu_trajectory = next(
        (traj for traj in trajectory_dict if traj["station"] == "OULU"),
        None
        )