Flight

Flight Diagram

OTSO.flight

flight(latitudes: Sequence[float], longitudes: Sequence[float], dates: Sequence, altitudes: Sequence[float], cutoff_comp: str = 'Vertical', solar_wind: SolarWindParams = {}, geomagnetic: GeomagneticParams = {}, tsyganenko: 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 = {}, *args, **kwargs)

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.

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", "Custom").
magfield_params (MagFieldParams, default: {} ) –
Magnetic field models.

Available keys:
- internalmag (str, default="IGRF"): "NONE", "IGRF", "Dipole", "Custom Gauss"
- externalmag (str, default="TSY89c"): "NONE", "TSY89c", "TSY01", "TSY15B", etc.
- boberg (bool, default=False): Enable Boberg extension
- bobergtype (str, default="EXTENSION"): Boberg extension type
- magnetopause (str, default="Kobel"): "NONE", "Kobel", "Sibeck", "Lin", "Sphere"
- 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")
solar_wind (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 (list of float, default=0): Averaged IMF By (nT)
- bz_avg (list of float, default=0): Averaged IMF Bz (nT)
- density (list of float, default=1): Solar wind density (particles/cm³)
- pdyn (list of float, default=0): Solar wind dynamic pressure (nPa)
geomagnetic (GeomagneticParams, default: {} ) –
Geomagnetic indices (optional for auto-retrieval).

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

Available keys:
- G1 (float, default=0): Tsyganenko G1 coefficient
- G2 (float, default=0): Tsyganenko G2 coefficient
- G3 (float, default=0): Tsyganenko G3 coefficient
- W1 (float, default=0): Tsyganenko W1 coefficient
- W2 (float, default=0): Tsyganenko W2 coefficient
- W3 (float, default=0): Tsyganenenko W3 coefficient
- W4 (float, default=0): Tsyganenko W4 coefficient
- W5 (float, default=0): Tsyganenko W5 coefficient
- W6 (float, default=0): Tsyganenko W6 coefficient
integration_params (IntegrationParams, default: {} ) –
Integration settings.

Available keys:
- intmodel (str, default="Boris"): "Boris", "4RK", "Vay", "HC"
- 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 (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"): Coordinate system used for calculations
- inputcoord (str, default="GDZ"): Input coordinate system
asymptotic_params (AsymptoticParams, default: {} ) –
Asymptotic computation parameters.

Available keys:
- unit (str, default="GeV"): Rigidity 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]): Rigidity levels for asymptotic computation
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
- MHDfile (str, default=None): MHD simulation file
- MHDcoordsys (str, default=None): MHD coordinate system

Returns:

list –

[flight_dataframe, summary_text, input_dataframe] - flight_dataframe: Cutoff rigidities along flight path - summary_text: Input parameter summary - input_dataframe: Flight path input data

Examples:

    import datetime
    import OTSO

    # Basic flight path analysis
    lats = [60.0, 65.0, 70.0]
    lons = [25.0, 20.0, 15.0] 
    alts = [35, 40, 45]  # km
    times = [datetime.datetime(2023, 6, 1, h) for h in [10, 11, 12]]

    flight_result = OTSO.flight(lats, lons, times, alts,
                               computation_params={"corenum": 2})

    # With automatic space weather data retrieval
    flight_auto = OTSO.flight(lats, lons, times, alts,
                             data_retrieval_params={"serverdata": "ON"})

    # Access the results
    flight_df, metadata, input_df = flight_result