Cone

OTSO.cone

cone(Stations: Union[str, Sequence[str]], customlocations: Optional[list] = None, solar_wind: SolarWindParams = {}, geomagnetic: GeomagneticParams = {}, tsyganenko: TsyganenkoParams = {}, datetime_params: DateTimeParams = {}, 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 = {}) -> list

Compute asymptotic viewing cones for given neutron monitor stations, or user-defined locations. Also computes cutoff rigidities.

Upon calling this function, OTSO will perform particle tracing simulations based on the specified parameters, returning the asymptotic viewing cones, rigidities, and related metadata.

Parameters:

• Stations (str | list) –

  Station name(s) or identifiers used for cone calculations.

• customlocations (list, default: None ) –

  Custom locations as [["NAME", lat, lon]].

• 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
• 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 ( list ) –

  [cone_dataframe, cutoff_dataframe, summary_text] - cone_dataframe: Asymptotic directions per rigidity (filter;lat;lon format) - cutoff_dataframe: Cutoff rigidity table (Ru, Rc, Rl) - summary_text: Input parameter summary

Examples:

    import OTSO

    # Basic usage with parameter groups
    cone_result = OTSO.cone(["OULU", "ROME"], 
                           computation_params={"corenum": 4},
                           datetime_params={"year": 2023, "month": 6})

    # With solar wind conditions
    cone_data = OTSO.cone(["DOMC"], 
                         solar_wind={"vx": -400, "by": 3.0, "bz": -2.0},
                         rigidity_params={"startrigidity": 15, "rigiditystep": 0.1})

    # Access the results
    cone_df, cutoff_df, metadata = cone_result