Transmission¶

Transmission Diagram

OTSO.transmission ¶

transmission(
    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 = {},
    rigidity_params: RigidityParams = {},
    coordinate_params: CoordinateParams = {},
    computation_params: ComputationParams = {},
    data_retrieval_params: DataRetrievalParams = {},
    custom_field_params: CustomFieldParams = {},
    transmission_params: TransmissionParams = {},
) -> list

Compute transmission function values as a function of particle rigidity 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 transmission function values and related metadata.

Parameters:

Stations (str | list) –

Station name(s) or identifiers used for cone 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
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)
transmission_params (TransmissionParams, default: {} ) –
Transmission function computation parameters

Available keys:
- 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:
- 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
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 ) –
[transmission_df, readme_text]
- transmission_df: Transmission functions as a function of rigidity in a dataframe
- readme_text: OTSO computation summary

Examples:

   from OTSO import transmission

   if __name__ == '__main__':

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

        transmission_results = transmission(Stations=stations_list,
                           computation_params={"corenum": 1, "threadnum": 8},
                           datetime_params={"year": 2005, "month": 5, "day": 1, "hour": 0},
                           integration_params={"gyropercent": 10},
                           magfield_params={"internalmag": "IGRF", "externalmag": "NONE"},
                           rigidity_params={"rigiditystep":0.01},
                           transmission_params={"transmission": True, "transmissionRstep": 0.0001, "transmissionsamples": 25})

        # Access the results
        transmission_df, metadata = transmission_result