Planet

OTSO.planet

planet(cutoff_comp: str = 'Vertical', solar_wind: SolarWindParams = {}, geomagnetic: GeomagneticParams = {}, tsyganenko: 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 = {})

Compute planetary cutoff grid using the OTSO framework.

Generates a global grid of geomagnetic cutoff rigidities across the Earth's surface. Useful for studying global cosmic ray accessibility patterns.

Parameters:

• cutoff_comp (str, default: 'Vertical' ) –

  Cutoff computation method ("Vertical", "Custom", etc.).

• 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"
  • 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.

  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 (nT)
  • bz_avg (float, default=0): Averaged IMF Bz (nT)
  • density (float, default=1): Solar wind density (particles/cm³)
  • pdyn (float, default=0): Solar wind dynamic pressure (nPa)
• geomagnetic (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 (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"): "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
• 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
• 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"): Coordinate system used for calculations
  • inputcoord (str, default="GDZ"): Input coordinate system
• 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 –

  [planet_dataframe, summary_text] - planet_dataframe: Global cutoff rigidity grid - summary_text: Input parameter summary

Examples:

    import OTSO

    # Basic global grid
    planet_result = OTSO.planet(
        computation_params={"corenum": 4},
        grid_params={"latstep": 10, "longstep": 20}
    )

    # High-resolution polar region
    polar_data = OTSO.planet(
        grid_params={"latstep": 2, "longstep": 5, "maxlat": 90, "minlat": 60},
        datetime_params={"year": 2023, "month": 3},
        rigidity_params={"rigiditystep": 0.05}
    )

    # Access the results
    planet_df, metadata = planet_result