field-line-footpoint

Field-line footpoint: trace a spacecraft to its ionospheric conjugate

A guided version of the pyspedas geopack field-line tracing crib — map a near-Earth spacecraft position down a model field line to its ionospheric footpoint (for ground/auroral conjunctions) or out to the magnetic equator (for L-shell / drift-shell context). This is GUIDANCE around the existing evaluate_magnetic_field tool, which already performs the trace; no new tool or code is added.

When to use

• "Where does this spacecraft map to on the ground / in the ionosphere?" (conjugate ground station, auroral oval, SuperDARN/THEMIS-GBO conjunction.)
• "Trace this field line to the magnetic equator / give me its L-shell apex."
• "Are these two spacecraft on the same field line / drift shell?" (footpoint or L comparison.)

Tool chain (all already exist)

get_ephemeris (or fetch_data_product for a position dataset) → transform_coordinates (to GSM) → evaluate_magnetic_field(trace="ionosphere" | "equator", model=...) → read footpoints from the output .npz → (render_tplot for the per-sample series), all inside a create_spedas_analysis_bundle. For McIlwain L specifically, calculate_lshell is the equatorial-trace shortcut.

Backend (VERIFIED contract)

evaluate_magnetic_field wraps pyspedas geopack tigrf/tt89/tt96/tt01/tts04 (field) and ttrace2endpoint (tracing). Key facts that drive this skill:

• Input is a positions artifact: .npz with positions = N×3 in GSM, kilometers (and optional times); or .npy; or CSV/JSON with position_cols/time_col. Positions are not auto-transformed — you must hand it GSM.
• trace ∈ {none, ionosphere, equator}, mapped to ttrace2endpoint endpoints. "ionosphere" traces along the field line to the ionospheric foot; "equator" traces to the magnetic equator.
• Output is output_file as .npz: per-sample B (nT) for every position, plus footpoints when tracing, plus an L series for equator traces. The tool returns only the model, field_strength_nT min/max/mean, paths, and (for equator) an lshell_summary — never the raw arrays. Read the .npz yourself to get coordinates.
• model: igrf (default) is fast and parameter-free. Distorted external models (t89, t96, t01, ts04) require explicit parameters (geomagnetic / solar-wind drivers — e.g. Dst, Pdyn, By/Bz, G/W indices as the model demands); there is no hidden network I/O, so missing/garbage parameters give a silently wrong field, not an error.
• calculate_lshell is the same machinery specialized to an equator trace: equatorial foot radius in Re = McIlwain L; returns {min_L, max_L, mean_L} + paths, optional ionospheric footprint=True.