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:

1. Keplerian model: used for GPS, Galileo, and BeiDou; it computes positions based on orbital elements valid for a few hours.
2. State-Vector model: used for GLONASS; it performs numerical integration (via a Numba-accelerated ODE solver) of instantaneous position, velocity, and acceleration vectors.

---

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:

1. Keplerian Orbits (GPS, Galileo, BeiDou): Selects a single representative ephemeris message (the central one) per satellite.

2. 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.

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 single dict for Keplerian systems or a list of dicts for GLONASS.

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	Dictionary containing ephemeris data Expected format: {sv_id: dict} for Keplerian systems or {sv_id: list[dict]} for GLONASS.	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 specific orbital parameters, handling both Keplerian (single dict) and state-vector (list of dicts) models.