Trace

OTSO.trace

trace(Coordsys: str = 'GEO', solar_wind: SolarWindParams = {}, geomagnetic: GeomagneticParams = {}, tsyganenko: TsyganenkoParams = {}, datetime_params: DateTimeParams = {}, magfield_params: MagFieldParams = {}, computation_params: ComputationParams = {}, data_retrieval_params: DataRetrievalParams = {}, custom_field_params: CustomFieldParams = {}, integration_params: IntegrationParams = {}, coord_params: CoordinateParams = {}, grid_params: GridParams = {}, *args, **kwargs)

Trace magnetic field lines using the OTSO framework.

Computes magnetic field line trajectories across a global grid to visualize the magnetosphere structure. Useful for understanding magnetic connectivity and field line topology.

Parameters:

• Coordsys (str, default: 'GEO' ) –

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

• 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

• 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
• 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 - MHDfile (str, default=None): MHD simulation file - MHDcoordsys (str, default=None): MHD coordinate system

Returns:

• list –

  [trace_data, summary_text] - trace_data: Dictionary with magnetic field line positions - summary_text: Input parameter summary

Examples:

    import OTSO

    # Global field line tracing
    trace_result = OTSO.trace(
        grid_params={"latstep": 30, "longstep": 60},
        computation_params={"corenum": 4}
    )

    # High-resolution polar region tracing
    polar_trace = OTSO.trace(
        grid_params={"latstep": 5, "longstep": 10, "maxlat": 90, "minlat": 60},
        datetime_params={"year": 2023, "month": 3},
        magfield_params={"externalmag": "TSY01"}
    )

    # Access the results
    trace_dict, metadata = trace_result