ECSS Space Environment — Geomagnetic Field Model Reference Data (space-systems/ecss/e1004-ref-geomag)
Use when the task is selecting geomagnetic field model reference data
under ECSS-E-ST-10-04C Annex E (informative) -- deciding whether the
Earth's internal field model alone describes the environment at a
given orbit altitude, or whether an external/magnetospheric model must
be added, validating the age of the internal-field coefficient set,
sizing the spherical-harmonic truncation to the altitude, picking an
external-field model tier from geomagnetic activity, and checking a
position against the magnetopause.
Domain quick reference
- The internal field (source: electric currents in Earth's core,
described by the IGRF coefficient set) dominates close to Earth. At
larger radial distance, external sources (magnetospheric ring
current, magnetopause current, tail current) become a comparable or
larger contributor, so a mission's field-model regime is
altitude-dependent: internal-only near Earth, internal-plus-external
further out, and beyond the nominal magnetopause standoff distance
the position must be checked against the magnetopause before an
internal/external Earth-field model is applied at all.
- The IGRF coefficient set is released in 5-year generations tied to a
generation epoch. Each generation's coefficients are definitive for
its own 5-year interval and are extended by predicted secular-
variation coefficients for one further 5-year interval; beyond that
second interval the generation is stale and a newer generation
should be selected.
- Higher spherical-harmonic degree/order terms of the internal field
decay rapidly with radial distance, so the degree/order needed for
an accurate field value falls as altitude increases: a low-altitude
mission needs the full-degree coefficient set, while a
geostationary-altitude or higher mission can use a low-degree
truncation without a meaningful accuracy loss.
- External/magnetospheric model selection is driven by geomagnetic
activity level (commonly indexed by Kp): quiet conditions are
adequately described by a static average external model, while
increasing activity requires models that take solar-wind and
interplanetary-magnetic-field inputs, up to the storm-time tier that
also needs a ring-current activity index.
- The magnetopause standoff distance (subsolar boundary between the
magnetosphere and the solar wind) compresses under higher solar-wind
dynamic pressure and expands under lower pressure; a position at or
beyond the standoff distance is outside (or at the boundary of) the
magnetosphere, where the Earth-field models above no longer apply.
Workflow
- Convert the mission altitude to radial distance from Earth's
center and classify the field-model regime: internal-only,
internal-plus-external, or beyond-the-nominal-magnetopause-limit.
Reject a negative altitude before classifying.
- Size the internal-field spherical-harmonic degree/order truncation
to the altitude -- do not carry the full-degree coefficient set
into a high-altitude computation where the extra terms are
negligible, and do not truncate a low-altitude computation where
the higher-degree terms are significant.
- Validate the internal-field coefficient generation epoch against
the evaluation date: definitive (within the generation's own
5-year interval), predictive (within the following 5-year secular-
variation interval), or stale (beyond both) -- flag a stale
generation for update before use.
- If the regime requires an external/magnetospheric model, select the
model tier from the geomagnetic activity index and record the
additional inputs (solar-wind dynamic pressure, interplanetary
magnetic field components, ring-current index) that tier requires.
- If the regime is beyond the nominal magnetopause limit, require the
solar-wind dynamic pressure, compute the standoff distance, and
classify the position as inside the magnetopause or at/beyond it
before assuming an Earth-field model applies.
- Aggregate the regime, degree/order, external-model selection, and
magnetopause position (when evaluated) into one field-model-source
determination for the mission.
Pitfalls
- Applying the full-degree internal-field coefficient set at every
altitude "to be safe" -- the higher-degree terms are not just
wasted computation at high altitude, carrying them without also
carrying their (larger, less certain) coefficient uncertainty
overstates the model's precision.
- Treating an internal-only regime as complete at higher altitude --
once the external-field contribution is comparable to the internal
field, omitting it is a model-completeness gap, not a conservative
simplification.
- Using a stale IGRF generation without flagging it -- a coefficient
set beyond its predictive secular-variation window is a documented
finding requiring an updated generation, not a silent degradation.
- Selecting a quiet-conditions external model tier regardless of
actual geomagnetic activity -- a storm-time environment needs the
ring-current-index-dependent tier; using the static quiet-tier model
understates the external field during activity.
- Assuming a position is inside the magnetosphere without checking the
magnetopause standoff distance against the actual solar-wind
pressure -- the standoff distance moves with pressure, so a fixed
assumed boundary can be wrong in either direction.
Behavior contract (gate 3)
The regime-classification, degree/order sizing, epoch-validation,
external-model-selection, and magnetopause-position logic is exercised
by the gate 3 contract test: scripts/test_e1004_ref_geomag.py against
scripts/e1004_ref_geomag_logic.py (stdlib unittest, offline). Run:
python3 scripts/test_e1004_ref_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-ref-geomag3description: "Use when selecting the geomagnetic field model reference data for a mission per ECSS-E-ST-10-04C Annex E: determine whether the internal field alone (IGRF) is sufficient for a given orbit altitude or an external/magnetospheric model must be added, validate an IGRF coefficient generation epoch as definitive, predictive, or stale, select the required spherical-harmonic degree/order truncation for the altitude, choose an external field model tier from the geomagnetic activity (Kp) index, and check a position against the solar-wind-pressure-dependent magnetopause standoff distance. Produces a structured field-model-source determination with explicit error paths for out-of-range inputs. Trigger: ecss, e-st-10-04c, geomagnetic field, igrf, external field model, magnetospheric model, magnetopause, kp index, space environment reference data."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-ref-geomag15 domain: space-systems16 subdomain: ecss17 tags: [ecss, e-st-10-04c, geomagnetic-field, igrf, external-field-model, magnetopause, space-environment]18 version: 0.1.019 author: Aero Agent Skills20---2122# ECSS Space Environment — Geomagnetic Field Model Reference Data (space-systems/ecss/e1004-ref-geomag)2324Use when the task is selecting geomagnetic field model reference data25under ECSS-E-ST-10-04C Annex E (informative) -- deciding whether the26Earth's internal field model alone describes the environment at a27given orbit altitude, or whether an external/magnetospheric model must28be added, validating the age of the internal-field coefficient set,29sizing the spherical-harmonic truncation to the altitude, picking an30external-field model tier from geomagnetic activity, and checking a31position against the magnetopause.3233## Domain quick reference3435- The internal field (source: electric currents in Earth's core,36 described by the IGRF coefficient set) dominates close to Earth. At37 larger radial distance, external sources (magnetospheric ring38 current, magnetopause current, tail current) become a comparable or39 larger contributor, so a mission's field-model regime is40 altitude-dependent: internal-only near Earth, internal-plus-external41 further out, and beyond the nominal magnetopause standoff distance42 the position must be checked against the magnetopause before an43 internal/external Earth-field model is applied at all.44- The IGRF coefficient set is released in 5-year generations tied to a45 generation epoch. Each generation's coefficients are definitive for46 its own 5-year interval and are extended by predicted secular-47 variation coefficients for one further 5-year interval; beyond that48 second interval the generation is stale and a newer generation49 should be selected.50- Higher spherical-harmonic degree/order terms of the internal field51 decay rapidly with radial distance, so the degree/order needed for52 an accurate field value falls as altitude increases: a low-altitude53 mission needs the full-degree coefficient set, while a54 geostationary-altitude or higher mission can use a low-degree55 truncation without a meaningful accuracy loss.56- External/magnetospheric model selection is driven by geomagnetic57 activity level (commonly indexed by Kp): quiet conditions are58 adequately described by a static average external model, while59 increasing activity requires models that take solar-wind and60 interplanetary-magnetic-field inputs, up to the storm-time tier that61 also needs a ring-current activity index.62- The magnetopause standoff distance (subsolar boundary between the63 magnetosphere and the solar wind) compresses under higher solar-wind64 dynamic pressure and expands under lower pressure; a position at or65 beyond the standoff distance is outside (or at the boundary of) the66 magnetosphere, where the Earth-field models above no longer apply.6768## Workflow69701. Convert the mission altitude to radial distance from Earth's71 center and classify the field-model regime: internal-only,72 internal-plus-external, or beyond-the-nominal-magnetopause-limit.73 Reject a negative altitude before classifying.742. Size the internal-field spherical-harmonic degree/order truncation75 to the altitude -- do not carry the full-degree coefficient set76 into a high-altitude computation where the extra terms are77 negligible, and do not truncate a low-altitude computation where78 the higher-degree terms are significant.793. Validate the internal-field coefficient generation epoch against80 the evaluation date: definitive (within the generation's own81 5-year interval), predictive (within the following 5-year secular-82 variation interval), or stale (beyond both) -- flag a stale83 generation for update before use.844. If the regime requires an external/magnetospheric model, select the85 model tier from the geomagnetic activity index and record the86 additional inputs (solar-wind dynamic pressure, interplanetary87 magnetic field components, ring-current index) that tier requires.885. If the regime is beyond the nominal magnetopause limit, require the89 solar-wind dynamic pressure, compute the standoff distance, and90 classify the position as inside the magnetopause or at/beyond it91 before assuming an Earth-field model applies.926. Aggregate the regime, degree/order, external-model selection, and93 magnetopause position (when evaluated) into one field-model-source94 determination for the mission.9596## Pitfalls9798- Applying the full-degree internal-field coefficient set at every99 altitude "to be safe" -- the higher-degree terms are not just100 wasted computation at high altitude, carrying them without also101 carrying their (larger, less certain) coefficient uncertainty102 overstates the model's precision.103- Treating an internal-only regime as complete at higher altitude --104 once the external-field contribution is comparable to the internal105 field, omitting it is a model-completeness gap, not a conservative106 simplification.107- Using a stale IGRF generation without flagging it -- a coefficient108 set beyond its predictive secular-variation window is a documented109 finding requiring an updated generation, not a silent degradation.110- Selecting a quiet-conditions external model tier regardless of111 actual geomagnetic activity -- a storm-time environment needs the112 ring-current-index-dependent tier; using the static quiet-tier model113 understates the external field during activity.114- Assuming a position is inside the magnetosphere without checking the115 magnetopause standoff distance against the actual solar-wind116 pressure -- the standoff distance moves with pressure, so a fixed117 assumed boundary can be wrong in either direction.118119## Behavior contract (gate 3)120121The regime-classification, degree/order sizing, epoch-validation,122external-model-selection, and magnetopause-position logic is exercised123by the gate 3 contract test: scripts/test_e1004_ref_geomag.py against124scripts/e1004_ref_geomag_logic.py (stdlib unittest, offline). Run:125python3 scripts/test_e1004_ref_geomag.py126127## Compliance128129- ECSS standards are freely downloadable (ESA); cite the source and130 paraphrase per standards-map.yaml.131- compliance: STANDARDS-REF, gated: false.