Flight¶

Flight Diagram

OTSO.flight ¶

flight(
    latitudes: Sequence[float],
    longitudes: Sequence[float],
    dates: Sequence,
    altitudes: Sequence[float],
    cutoff_comp: str = "Vertical",
    solar_wind_params: SolarWindParams = {},
    geomagnetic_params: GeomagneticParams = {},
    tsyganenko_params: TsyganenkoParams = {},
    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 cosmic-ray cutoff rigidities along a flight path using OTSO.

Calculates cutoff rigidities at specified time-varying locations, typically used for aircraft or satellite trajectory analysis. Supports automatic space weather data retrieval based on flight times. On request the asymptotic viewing directions and transmission functions can be computed as well.

Parameters:

latitudes (list) –

Latitude coordinates along flight path.
longitudes (list) –

Longitude coordinates along flight path.
dates (list) –

Date/time stamps for each location (datetime objects).
altitudes (list) –

Altitude coordinates in km along flight path.
cutoff_comp (str, default: 'Vertical' ) –

Cutoff computation method ("Vertical", "Apparent", "Custom").
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 (optional for auto-retrieval). Defaults are quiet-time medians (Kp <= 1) of OMNI data, 1996-2025.

All values should be provided as lists of floats, one per flight point.

Available keys:
- vx (list of float, default=-359.4): Solar wind velocity x-component (km/s)
- vy (list of float, default=0): Solar wind velocity y-component (km/s)
- vz (list of float, default=0): Solar wind velocity z-component (km/s)
- bx (list of float, default=0.11): IMF x-component (nT)
- by (list of float, default=-0.16): IMF y-component (nT)
- bz (list of 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 (list of float, default=4.94): Solar wind density (particles/cm³)
- pdyn (list of 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 (optional for auto-retrieval). Defaults are quiet-time medians (Kp <= 1) of OMNI data, 1996-2025.

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

Available keys:
- G1 (list of float,, default=0.38): Tsyganenko G1 coefficient
- G2 (list of float,, default=0.12): Tsyganenko G2 coefficient
- G3 (list of float,, default=0.47): Tsyganenko G3 coefficient
- W1 (list of float,, default=0.07): Tsyganenko W1 coefficient
- W2 (list of float,, default=0.06): Tsyganenko W2 coefficient
- W3 (list of float,, default=0.13): Tsyganenko W3 coefficient
- W4 (list of float,, default=0.03): Tsyganenko W4 coefficient
- W5 (list of float,, default=0.05): Tsyganenko W5 coefficient
- W6 (list of 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
- 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 ) –
[flight_df, asymptotic_df, transmission_df, readme_text, input_dataframe]
- flight_df: Cutoff rigidities along flight path
- asymptotic_df: Asymptotic viewing directions for input energy/rigidiy levels along flight path
- transmission_df: Transmission functions as a function of rigidity along the flight path
- readme_text: OTSO computation summary
- input_dataframe: Flight path input data

Examples:

    from OTSO import flight
    import datetime

    if __name__ == "__main__":

        latitude_list = [10, 15, 20, 25, 30]
        longitude_list = [10, 15, 20, 25, 30]
        altitude_list = [30, 40, 50, 60, 80]
        date_list = [
            datetime.datetime(2000, 10, 12, 8),
            datetime.datetime(2000, 10, 12, 9),
            datetime.datetime(2000, 10, 12, 10),
            datetime.datetime(2000, 10, 12, 11),
            datetime.datetime(2000, 10, 12, 12),
        ]

        # Example using grouped parameters
        flight_results = flight(
            latitudes=latitude_list,
            longitudes=longitude_list,
            dates=date_list,
            altitudes=altitude_list,
            cutoff_comp="Vertical",
            computation_params={"corenum": 1, "threadnum": 8},
            asymptotic_params={"asymptotic": "YES"},
            transmission_params={"transmission": True},
            integration_params={"gyropercent": 1}
        )

        # Access the results
        flight_df, asymptotic_df, transmission_df, metadata, input_df = flight_result