Trace

OTSO.trace

trace(
    coordsys: str = "GEO",
    solar_wind_params: SolarWindParams = {},
    geomagnetic_params: GeomagneticParams = {},
    tsyganenko_params: TsyganenkoParams = {},
    datetime_params: DateTimeParams = {},
    magfield_params: MagFieldParams = {},
    computation_params: ComputationParams = {},
    data_retrieval_params: DataRetrievalParams = {},
    custom_field_params: CustomFieldParams = {},
    integration_params: IntegrationParams = {},
    coordinate_params: CoordinateParams = {},
    grid_params: GridParams = {},
    *args,
    **kwargs,
) -> list

Trace magnetic field lines using the OTSO framework.

Traces magnetic field lines across a global grid to visualize the magnetosphere structure. Useful for understanding magnetic connectivity and field line topology. Computation also returns the McIlwain L value for the field line and invariant latitude for the origin location of the field line. Users should be cautious when interpreting low- or high-latitude origin invariant latitudes as they are ill-defined in such locations.

Parameters:

• Coordsys (str) –

  Coordinate system for field line positions.

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

  [trace_data, readme_text]

  • trace_data: Dictionary with magnetic field line positions
  • readme_text: OTSO computation summary

Examples:

   from OTSO import trace

   if __name__ == '__main__':

       # Example using grouped parameters
       trace_results = trace(
           computation_params={"corenum": 4},
           magfield_params={"externalmag":"TSY89c"},
           grid_params={"latstep": -30, "longstep": 180, "maxlat": 60, "minlat": 0},
       )

        # Access the results
        trace_dict, metadata = trace_result