Planet

Planet Diagram

OTSO.planet

planet(
    cutoff_comp: str = "Vertical",
    solar_wind_params: SolarWindParams = {},
    geomagnetic_params: GeomagneticParams = {},
    tsyganenko_params: TsyganenkoParams = {},
    datetime_params: DateTimeParams = {},
    magfield_params: MagFieldParams = {},
    integration_params: IntegrationParams = {},
    rigidity_params: RigidityParams = {},
    coordinate_params: CoordinateParams = {},
    computation_params: ComputationParams = {},
    data_retrieval_params: DataRetrievalParams = {},
    custom_field_params: CustomFieldParams = {},
    particle_params: ParticleParams = {},
    grid_params: GridParams = {},
    asymptotic_params: AsymptoticParams = {},
    transmission_params: TransmissionParams = {},
) -> list

Compute planetary cutoff grid using the OTSO framework.

Generates a global grid of geomagnetic cutoff rigidities across the Earth's surface. Users can also request the computation of asymptotic viewing directions and transmission functions by request. Useful for studying global cosmic ray accessibility patterns.

Parameters:

cutoff_comp (str, default: 'Vertical' ) –

Cutoff computation method ("Vertical", "Apparent", "Custom").
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
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.

Available keys:
- vx (float, default=-500): 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): IMF x-component (nT)
- by (float, default=5): IMF y-component (nT)
- bz (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 (float, default=1): Solar wind density (particles/cm³)
- pdyn (float, default=0): Solar wind dynamic pressure (nPa)
geomagnetic_params (GeomagneticParams, default: {} ) –
Geomagnetic indices.

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_params (TsyganenkoParams, default: {} ) –
Tsyganenko model coefficients.

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): Tsyganenko 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-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
grid_params (GridParams, default: {} ) –
Grid configuration parameters.

Available keys:
- latstep (float, default=-5): Latitude step size for grid
- longstep (float, default=5): Longitude step size for grid
- maxlat (float, default=90): Maximum latitude for grid
- minlat (float, default=-90): Minimum latitude for grid
- maxlong (float, default=360): Maximum longitude for grid
- minlong (float, default=0): Minimum longitude for grid
- array_of_lats_and_longs (list, default=None): Custom grid points
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
- threadnum (int, default=None): Number of threads per CPU core for Fortran computations
- 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 ) –
[planet_dataframe, asymptotic_dataframe, transmission_dataframe, readme_text]
- planet_dataframe: Global cutoff rigidity grid
- asymptotic_dataframe: Global asymptotic viewing directions for the energy/rigidity levels input.
- transmission_dataframe: Global tranmssion values for set rigidity values.
- readme_text: OTSO computation summary

Examples:

    from OTSO import planet

    if __name__ == '__main__':

        # Basic global grid
        planet_results = planet(
            cutoff_comp="Vertical",
            grid_params={"latstep": -10, "longstep": 15},
            computation_params={"corenum": 8, "threadnum": 1},
            datetime_params={"year": 2000},
            rigidity_params={"rigiditystep": 0.01},
            integration_params={"gyropercent":10}
        )


        # Access the results
        planet_df, asymptotic_df, transmission_df, metadata = planet_result