Satellites & Geometry¶
The satellites module provides essential functions for GNSS orbit propagation and observation geometry. It handles the transition from raw navigation messages to precise satellite positions and Ionospheric Pierce Points (IPP).
Orbital Models¶
PyTECGg supports different orbital propagation models depending on the GNSS constellation:
- Keplerian model: used for GPS, Galileo, and BeiDou; it computes positions based on orbital elements valid for a few hours.
- State-Vector model: used for GLONASS; it performs numerical integration (via a Numba-accelerated ODE solver) of instantaneous position, velocity, and acceleration vectors.
Ephemeris Preparation Notes¶
prepare_ephemeris now validates navigation records according to the orbit model actually used downstream:
- GPS, Galileo, BeiDou: the function keeps every valid broadcast record per satellite, checking only the orbital fields strictly required for Keplerian position propagation. Position computation later selects the record whose
toeis nearest to the observation epoch, since broadcast Keplerian parameters are only valid for ~±2 h aroundtoe— reusing a single record across a multi-hour file would otherwise introduce 50–200 m biases. Records more than 24 h from the observation epoch are not used. Galileo nav files repeat each record once per data source (F/NAV and I/NAV) with the same orbit; one record per epoch is kept, preferring I/NAV E1+E5b (source517). - GLONASS: the full message history is retained because state-vector propagation needs the closest valid epoch and the FDMA channel.
This means a navigation message is not discarded, as long as the orbital solution is still sufficient to compute satellite geometry.
Time Systems and Leap Seconds¶
Each broadcast record carries a leap_seconds field (UTC → GPST offset), chosen in this order:
GNSSContext.leap_seconds, if set (an explicit override).- The
LEAP SECONDSfield of the nav file header, whichread_rinex_navadds as aleap_secondscolumn. Nav files written after a new leap second carry the new value, so this follows future changes without aPyTECGgupdate. Files merged from several days keep each file's value. - The leap-second table
LEAP_SECONDS_UTC_GPSTinpytecgg.satellites.constants, for the record date, when the header has noLEAP SECONDSline (the field is optional). The table is checked against IERS Bulletin C up toLEAP_SECONDS_VALID_UNTIL; for later records a warning says the value may be stale.
Observation epochs from read_rinex_obs are on the GPST grid. During position computation they are shifted into the constellation's own time system before the elapsed time from the ephemeris epoch is computed: no shift for GPS / Galileo / QZSS, BDT for BeiDou (BDT = GPST − 14 s), and UTC for GLONASS (UTC = GPST − leap_seconds).
API Reference¶
prepare_ephemeris(nav, ctx)
¶
Prepare ephemeris data from RINEX navigation data using the settings in GNSSContext.
This function processes multiple GNSS constellations and formats data based on their specific orbit propagation models:
-
Keplerian Orbits (GPS, Galileo, BeiDou): Keeps every valid broadcast record per satellite. Position computation later picks the record nearest to the observation epoch, since broadcast Keplerian parameters are only valid for ~±2 h around toe.
-
State-Vector Orbits (GLONASS): All available ephemeris messages are collected for the satellite. This is required because GLONASS messages contain instantaneous state vectors (position/ velocity/acceleration) valid only for short periods (typically ± 15 minutes), requiring numerical integration from the closest epoch. Records off the satellite's orbital slot are dropped as mislabelled (see :func:
_drop_mislabelled_glonass_records).
Each record carries a leap_seconds value (UTC -> GPST), taken from
ctx.leap_seconds if set, else from the nav header LEAP SECONDS field
(the leap_seconds column added by :func:pytecgg.parsing.read_rinex_nav),
else from the leap-second table for the record date.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
nav
|
dict[str, DataFrame]
|
Navigation data from RINEX, keyed by constellation name (e.g., 'GPS', 'GLONASS'). |
required |
ctx
|
GNSSContext
|
Execution context containing target systems and settings. |
required |
Returns:
| Type | Description |
|---|---|
Ephem
|
Dictionary keyed by satellite ID (e.g., 'G01', 'R09'). Values are a list of broadcast records (one dict per valid message). |
satellite_coordinates(sv_ids, epochs, ephem_dict, **kwargs)
¶
Compute Earth-Centered Earth-Fixed (ECEF) coordinates for GNSS satellites.
The function supports GPS, Galileo, BeiDou (using Keplerian orbits) and GLONASS (using state-vector propagation).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sv_ids
|
Series
|
Series containing satellite identifiers (e.g., 'G01', 'E23', 'R01') |
required |
epochs
|
Series
|
Series containing observation times as datetime objects |
required |
ephem_dict
|
dict
|
Ephemeris data as returned by |
required |
**kwargs
|
Any
|
Additional parameters for GLONASS state-vector propagation: - t_res : float or None, optional Time resolution (in seconds) for sampling the ODE solver solution - if float: the trajectory is sampled at fixed intervals - if None (default): the solver selects internal time steps automatically. - error_estimate : Literal["coarse", "normal", "fine"], optional Error tolerance level: - "coarse": ~2000 meters precision, faster - "normal": ~200 meters precision, balanced (default) - "fine": ~20 meters precision, slower These additional parameters are ignored for non-GLONASS systems |
{}
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with columns: 'sv', 'epoch', 'sat_x', 'sat_y', 'sat_z' containing satellite ECEF coordinates in meters |
calculate_ipp(df, ctx, min_elevation=None)
¶
Calculate the Ionospheric Pierce Point (IPP) coordinates and satellite geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame
|
DataFrame containing satellite ECEF coordinates ('sat_x', 'sat_y', 'sat_z'). |
required |
ctx
|
GNSSContext
|
Context containing receiver position and IPP height. |
required |
min_elevation
|
float
|
Minimum elevation angle in degrees. If provided, observations below this threshold are filtered out. |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with added columns: 'lat_ipp', 'lon_ipp', 'azi', 'ele'. |
Ephem = dict[str, dict[str, Any] | list[dict[str, Any]]]
module-attribute
¶
Type alias for a dictionary containing processed ephemeris data.
It maps satellite IDs (e.g., 'G01') to their orbital parameters. Values are a list of broadcast records for every constellation (Keplerian and state-vector); downstream code picks the record nearest the observation epoch. A plain dict is still accepted for legacy / hand-built ephemerides.