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
- 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.
- 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.
- 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.
- 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).
- 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.
- 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.
- 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.
1---2name: e1004-geomag3description: "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 geocentric distance, or that model combined with an external/magnetospheric field model at high geocentric distance) from the mission orbit's geocentric distance, determine the correct IGRF epoch and apply secular variation to update the reference internal field for the mission's target date, verify the target date remains within the secular-variation extrapolation validity window, compute the dipole-approximation B,L equatorial field magnitude for radiation-belt characterization, and validate that the analysis case's declared model and epoch handling meet these requirements. Trigger: geomagnetic field, IGRF, secular variation, B L coordinates, magnetospheric field, external field model, Tsyganenko, dipole approximation, e-st-10-04, ecss, space environment."4license: Apache-2.05compliance: STANDARDS-REF6standards:7 - id: ecss8 reference-only: true9gated: false10domain: space-systems11pack: space-systems12compatibility: "agentskills.io SKILL.md; any SKILL.md host (Claude Code, Hermes, OpenClaw)"13metadata:14 source: https://skillmd.com/skills/ashfordeou/e1004-geomag15 domain: space-systems16 subdomain: ecss17 tags: [ecss, e-st-10-04c, geomag, igrf, secular-variation, b-l-coordinates, external-field, space-environment]18 version: 0.1.019 author: Aero Agent Skills20---2122# ECSS Geomagnetic Field Environment (space-systems/ecss/e1004-geomag)2324Use when the task is selecting and applying a geomagnetic field model25under ECSS-E-ST-10-04C clause 5.2, to characterize the Earth's26internal magnetic field (and, where applicable, the external27magnetospheric contribution) for a mission orbit, including epoch28selection, secular-variation handling, and B,L coordinate usage.2930## Domain quick reference3132- The geomagnetic field has an internal (core-origin) component and33 an external (magnetospheric) component. The internal component34 dominates at low and mid geocentric distance and is well35 represented by an IGRF-class spherical-harmonic model alone. At36 high geocentric distance -- approaching and beyond the magnetopause37 region -- the external/magnetospheric contribution (solar-wind38 interaction, ring current, tail currents) becomes significant and39 an internal-only model understates the actual field; an external40 field model (e.g. a Tsyganenko-class model) must be added.41 Geomagnetic shielding of incident particle flux (Stormer cutoffs) is42 the sibling e1004-stormer leaf; trapped-belt long-term flux models43 are the sibling e1004-trapped-leo leaf -- both consume the field44 geometry this leaf characterizes rather than redefining it.45- IGRF-class models are published as spherical-harmonic (Gauss)46 coefficient sets at fixed 5-year epochs, each accompanied by a47 secular-variation (SV) coefficient set describing the field's48 linear rate of change. Coefficients between two published epochs49 are interpolated; coefficients for dates after the latest published50 epoch are extrapolated by applying the SV rate, and that51 extrapolation is only certified accurate for a bounded number of52 years (nominally the 5 years following the latest epoch) until the53 next IGRF generation is released.54- B,L coordinates express a field point by the local field magnitude55 B and the McIlwain L-shell parameter; L labels the dipole field56 line the point lies on and is the standard coordinate for57 characterizing trapped-radiation-belt structure. A dipole58 approximation gives the equatorial field magnitude on a given59 L-shell as the epoch equatorial surface field strength divided by L60 cubed.61- This leaf scopes internal/external model selection by geocentric62 distance regime, IGRF epoch and secular-variation handling, and the63 B,L dipole-approximation field computation only. It does not64 implement the full spherical-harmonic synthesis of the real IGRF65 coefficient set -- that is an external reference implementation66 (see the informative e1004-ref-geomag reference-data leaf) -- nor67 does it compute Stormer cutoffs or belt fluxes.6869## Workflow70711. For each geomagnetic analysis case, record its case id, the72 mission orbit's geocentric distance (Earth radii), the target73 date (decimal year) the field is needed for, the model the74 analysis declares it used, the epoch equatorial surface field75 strength (B0) for the nearest IGRF epoch, and the secular-variation76 rate for that epoch.772. Classify the case's geocentric distance into a field regime:78 "internal_only" at or below the internal/external threshold79 distance, "internal_plus_external" above it.803. Select the model required for that regime (IGRF-class internal81 field model alone, or that model combined with an82 external/magnetospheric field model) and compare it against the83 case's declared model; flag a mismatch rather than accepting an84 internal-only analysis at high geocentric distance.854. Determine the nearest IGRF epoch at or before the target date and86 the elapsed time since that epoch; verify the target date falls87 within the secular-variation extrapolation validity window88 (target date not before the earliest published epoch, and not more89 than the extrapolation limit beyond the latest published epoch).905. Apply secular variation: scale the epoch equatorial field strength91 by the secular-variation rate over the elapsed time to obtain the92 field strength applicable to the target date.936. Where a case supplies an L-shell value, compute the dipole94 equatorial field magnitude at that L-shell from the95 secular-variation-adjusted equatorial field strength.967. Mark the case compliant only when its declared model matches the97 regime's required model and its target date is within the epoch98 validity window; roll every case's compliance into the assessment99 record and do not close the geomagnetic field model definition100 while any case remains non-compliant.101102## Pitfalls103104- Using an internal-only IGRF model for a high-altitude or105 magnetopause-adjacent orbit instead of adding the106 external/magnetospheric contribution, understating the actual field107 (and, downstream, misjudging particle trajectories that depend on108 it).109- Applying secular variation beyond its certified extrapolation110 window instead of flagging that a newer IGRF generation is needed,111 silently carrying growing error into the field estimate the further112 the target date drifts past the latest published epoch.113- Treating the B,L dipole approximation as exact near the real,114 non-dipolar field (e.g. in the South Atlantic Anomaly) rather than115 as a simplified coordinate for belt characterization only.116- Selecting an epoch by nearest calendar rounding instead of the117 correct interpolation/extrapolation rule, which silently drops the118 secular-variation correction that dominates the difference between119 adjacent epochs.120121## Behavior contract (gate 3)122123The regime classification, model-selection, IGRF epoch validity,124secular-variation, and B,L field-computation logic is exercised by125the gate 3 contract test: scripts/test_e1004_geomag.py against126scripts/e1004_geomag_logic.py (stdlib unittest, offline). Run:127python3 scripts/test_e1004_geomag.py128129## Compliance130131- ECSS standards are freely downloadable (ESA); cite the source and132 paraphrase per standards-map.yaml.133- compliance: STANDARDS-REF, gated: false.