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 = {},
    *args,
    **kwargs,
) -> 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
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="ON"): Enable scanning ("ON"/"OFF")
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).

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

Available keys:
- vx (list of float, default=-500): 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): IMF x-component (nT)
- by (list of float, default=5): IMF y-component (nT)
- bz (list of float, default=5): IMF z-component (nT)
- by_avg (float, default=0): Averaged IMF By over last 30mins (nT)
- bz_avg (float, default=0): Averaged IMF Bz over last 30mins (nT)
- density (list of float, default=1): Solar wind density (particles/cm³)
- pdyn (list of float, default=0): Solar wind dynamic pressure (nPa)
geomagnetic_params (GeomagneticParams, default: {} ) –
Geomagnetic indices (optional for auto-retrieval).

Available keys:
- Dst (list of float,, default=0): Dst index (nT)
- kp (list of float,, default=0): Kp index (0-9)
- n_index (list of float,, default=0): Newell coupling function
- b_index (list of float,, default=0): Boynton coupling function
- sym_h_corrected (list of float,, default=0): Corrected SYM-H index (nT)
tsyganenko_params (TsyganenkoParams, default: {} ) –
Tsyganenko model coefficients (optional for auto-retrieval).

Available keys:
- G1 (list of float,, default=0): Tsyganenko G1 coefficient
- G2 (list of float,, default=0): Tsyganenko G2 coefficient
- G3 (list of float,, default=0): Tsyganenko G3 coefficient
- W1 (list of float,, default=0): Tsyganenko W1 coefficient
- W2 (list of float,, default=0): Tsyganenko W2 coefficient
- W3 (list of float,, default=0): Tsyganenko W3 coefficient
- W4 (list of float,, default=0): Tsyganenko W4 coefficient
- W5 (list of float,, default=0): Tsyganenko W5 coefficient
- W6 (list of float,, default=0): 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=15): Gyration period percentage
- minaltitude (float, default=20): Minimum altitude (GDZ = km or other = Re)
- maxdistance (float, default=100): Maximum distance (Re)
- maxtime (float, default=0): Maximum time
- 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=None): Maximum number of integration steps
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

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