dual-spacecraft-timing

Multi-spacecraft timing (CVA): boundary normal and phase speed

A guided version of the classic four-spacecraft timing / Constant-Velocity-Approach (CVA) crib sheet. Given the same boundary crossing observed at several spacecraft and their positions, it recovers the boundary normal n (unit vector) and the phase speed V along n. There is no "timing" backend tool and there should not be — the only data fetch is each spacecraft's position; the solve is a tiny local NumPy least-squares. The value is in the procedure, the geometry/conditioning check, and the interpretation.

When to use

• "I see this magnetopause/shock/discontinuity crossing at 4 spacecraft — what's the normal and speed?"
• "Use timing on the MMS/Cluster tetrahedron for this crossing."
• "How fast and in what direction is this boundary moving?" (single-spacecraft MVA gives orientation only, not speed — timing gives both.)

Tool chain (existing tools only)

create_spedas_analysis_bundle → get_ephemeris × N spacecraft (positions only) → local NumPy numpy.linalg.lstsq (no tool; run via the Bash python interpreter, writing inputs/outputs into the bundle) → optional render_tplot only if you want to overlay the per-spacecraft field traces that justify the crossing times.

Backend (VERIFIED contract)

• get_ephemeris(target, time, observer, frame) with time only returns a single-time STATE INLINE — a dict/array of position (and velocity) in the requested frame, in km. It is not a stored tplot variable and not an .npz. Read the returned position straight out of the response dict; do not look for a file unless you passed output_file.
• Default frame="ECLIPJ2000", observer="SUN". For magnetospheric boundaries you almost always want frame="GSE" (or GSM) and observer="EARTH". Pass them explicitly — the default Sun-centered ecliptic frame is wrong for a magnetopause and will silently give a nonsense normal.
• Target registry is enforced. get_ephemeris validates target against the SPICE mission registry and returns a structured unsupported_spice_target error for names it does not know (e.g. MMS1 is NOT in the registry). THEMIS A–E, Cluster-class, Van Allen Probes A/B and the heliophysics fleet are supported; for MMS-style fleets not in SPICE you must supply the per-spacecraft positions yourself (from the mission ephemeris CDF / user-provided km vectors) and skip straight to the solve.
• Kernels: a cold cache returns needs_confirmation / kernel_download_required; first check manage_data_cache(source_type="spice", action="status"), then retry the relevant get_ephemeris(...) call with allow_kernel_download=True after confirming the download. Do not route this skill through hidden source-specific kernel tools.
• The crossing times are NOT produced by any tool — they are identified by the user (or read off per-spacecraft field traces) as the moment each spacecraft sees the boundary.
• Timestamps for the solve are numeric Unix seconds. Convert each crossing time to a float epoch (seconds) before differencing; do not feed ISO strings into the arithmetic. (No FFT/spectral step here, but the same numeric-epoch rule applies.)
• render_tplot is optional and out-of-band: it draws ONE 2-D matrix per .npz — used here, if at all, only to display the field traces that anchor the crossing times, never for the timing result itself.