e1004-geomag

Use when defining the geomagnetic field environment model for a mission under ECSS-E-ST-10-04C: select the applicable geomagnetic field model (an IGRF-class internal field model alone at low/mid geoce

SKILL.md

GitHub

ECSS Geomagnetic Field Environment (space-systems/ecss/e1004-geomag)

Use when the task is selecting and applying a geomagnetic field model under ECSS-E-ST-10-04C clause 5.2, to characterize the Earth's internal magnetic field (and, where applicable, the external magnetospheric contribution) for a mission orbit, including epoch selection, secular-variation handling, and B,L coordinate usage.

Domain quick reference

  • The geomagnetic field has an internal (core-origin) component and an external (magnetospheric) component. The internal component dominates at low and mid geocentric distance and is well represented by an IGRF-class spherical-harmonic model alone. At high geocentric distance -- approaching and beyond the magnetopause region -- the external/magnetospheric contribution (solar-wind interaction, ring current, tail currents) becomes significant and an internal-only model understates the actual field; an external field model (e.g. a Tsyganenko-class model) must be added. Geomagnetic shielding of incident particle flux (Stormer cutoffs) is the sibling e1004-stormer leaf; trapped-belt long-term flux models are the sibling e1004-trapped-leo leaf -- both consume the field geometry this leaf characterizes rather than redefining it.
  • IGRF-class models are published as spherical-harmonic (Gauss) coefficient sets at fixed 5-year epochs, each accompanied by a secular-variation (SV) coefficient set describing the field's linear rate of change. Coefficients between two published epochs are interpolated; coefficients for dates after the latest published epoch are extrapolated by applying the SV rate, and that extrapolation is only certified accurate for a bounded number of years (nominally the 5 years following the latest epoch) until the next IGRF generation is released.
  • B,L coordinates express a field point by the local field magnitude B and the McIlwain L-shell parameter; L labels the dipole field line the point lies on and is the standard coordinate for characterizing trapped-radiation-belt structure. A dipole approximation gives the equatorial field magnitude on a given L-shell as the epoch equatorial surface field strength divided by L cubed.
  • This leaf scopes internal/external model selection by geocentric distance regime, IGRF epoch and secular-variation handling, and the B,L dipole-approximation field computation only. It does not implement the full spherical-harmonic synthesis of the real IGRF coefficient set -- that is an external reference implementation (see the informative e1004-ref-geomag reference-data leaf) -- nor does it compute Stormer cutoffs or belt fluxes.

Workflow

  1. For each geomagnetic analysis case, record its case id, the mission orbit's geocentric distance (Earth radii), the target date (decimal year) the field is needed for, the model the analysis declares it used, the epoch equatorial surface field strength (B0) for the nearest IGRF epoch, and the secular-variation rate for that epoch.
  2. Classify the case's geocentric distance into a field regime: "internal_only" at or below the internal/external threshold distance, "internal_plus_external" above it.
  3. Select the model required for that regime (IGRF-class internal field model alone, or that model combined with an external/magnetospheric field model) and compare it against the case's declared model; flag a mismatch rather than accepting an internal-only analysis at high geocentric distance.
  4. Determine the nearest IGRF epoch at or before the target date and the elapsed time since that epoch; verify the target date falls within the secular-variation extrapolation validity window (target date not before the earliest published epoch, and not more than the extrapolation limit beyond the latest published epoch).
  5. Apply secular variation: scale the epoch equatorial field strength by the secular-variation rate over the elapsed time to obtain the field strength applicable to the target date.
  6. Where a case supplies an L-shell value, compute the dipole equatorial field magnitude at that L-shell from the secular-variation-adjusted equatorial field strength.
  7. Mark the case compliant only when its declared model matches the regime's required model and its target date is within the epoch validity window; roll every case's compliance into the assessment record and do not close the geomagnetic field model definition while any case remains non-compliant.

Pitfalls

  • Using an internal-only IGRF model for a high-altitude or magnetopause-adjacent orbit instead of adding the external/magnetospheric contribution, understating the actual field (and, downstream, misjudging particle trajectories that depend on it).
  • Applying secular variation beyond its certified extrapolation window instead of flagging that a newer IGRF generation is needed, silently carrying growing error into the field estimate the further the target date drifts past the latest published epoch.
  • Treating the B,L dipole approximation as exact near the real, non-dipolar field (e.g. in the South Atlantic Anomaly) rather than as a simplified coordinate for belt characterization only.
  • Selecting an epoch by nearest calendar rounding instead of the correct interpolation/extrapolation rule, which silently drops the secular-variation correction that dominates the difference between adjacent epochs.

Behavior contract (gate 3)

The regime classification, model-selection, IGRF epoch validity, secular-variation, and B,L field-computation logic is exercised by the gate 3 contract test: scripts/test_e1004_geomag.py against scripts/e1004_geomag_logic.py (stdlib unittest, offline). Run: python3 scripts/test_e1004_geomag.py

Compliance

  • ECSS standards are freely downloadable (ESA); cite the source and paraphrase per standards-map.yaml.
  • compliance: STANDARDS-REF, gated: false.