MediaCorrections#
- class MediaCorrections(name: str, instrument: Instrument, tropo_seasonal_file_path: str | Path | None = None, tropo_non_seasonal_file_path: str | Path | None = None, iono_file_path: str | Path | None = None)#
Bases:
MeasurementComputes path delays due to tropospheric and ionospheric media corrections.
This class is a subclass of
Measurementand provides correction models for signal propagation through Earth’s atmosphere. It is consumed byDopplerRealandSequentialRangingReal.Tropospheric delay (Chao mapping)
The total one-way excess tropospheric path length is the sum of seasonal and non-seasonal zenith delays mapped to slant via the Chao functions (Estefan 1995; Moyer eq. 10-8 to 10-10):
\[\Delta\rho_{tropo} = R_{dry}(\varepsilon)\,\Delta\tau_{dry} + R_{wet}(\varepsilon)\,\Delta\tau_{wet}\]where the dry and wet mapping functions are
\[R_{dry} = \frac{1}{\sin\varepsilon + \dfrac{A_{dry}}{\tan\varepsilon + B_{dry}}}, \qquad R_{wet} = \frac{1}{\sin\varepsilon + \dfrac{A_{wet}}{\tan\varepsilon + B_{wet}}}\]with constants \(A_{dry}=0.00143\), \(B_{dry}=0.0445\), \(A_{wet}=0.00035\), \(B_{wet}=0.017\). The zenith delays are represented by Fourier (seasonal) or normalized polynomial (non-seasonal) expansions loaded from JSON files at construction time.
Ionospheric delay
The dispersive ionospheric group delay scales as \(f^{-2}\):
\[\Delta\rho_{iono} \propto \frac{1}{f^2}\int N_e\,ds\]where \(f\) is the carrier frequency and \(N_e\) is the electron column density.
Sign conventions
DopplerReal: ionosphere enters with a negative sign (Moyer eq. 10-28, 10-29).SequentialRangingReal: ionosphere enters with a positive sign (Moyer eq. 10-27).
- Parameters:
- namestr
The name of the media correction model object.
- instrumentInstrument
The observation instrument or ground station to which the corrections apply.
- tropo_seasonal_file_pathPathLike, optional
Path to the JSON file containing seasonal tropospheric correction data: the TRIG (Fourier) climatology, e.g.
1972_001_2048_001_tro_modified.json. Defaults toNone. A file holding NRMPOW rows is a non-seasonal one and raisesMediaCorrections.TroposphereFileTypeError.- tropo_non_seasonal_file_pathPathLike, optional
Path to the JSON file containing non-seasonal tropospheric correction data: a monthly NRMPOW file
YYYY_DDD_YYYY_DDD_tro.json(seefind_tro_metadata()). Defaults toNone. A file holding TRIG rows is the seasonal one and raisesMediaCorrections.TroposphereFileTypeError. The troposphere delay needs both files; computing with only one of them raisesMediaCorrections.IncompleteTroposphereError.- iono_file_pathPathLike, optional
Path to the JSON file containing ionospheric correction data. Defaults to
None. With it set, the delays need the link frequency; computing without one raisesMediaCorrections.MissingIonosphereFrequencyError.
- Attributes:
- AUX_KEYS
component_labelsNames of the two components of a vector observable.
computed_measurements_dictAuxiliary TRK-2-34 tracking-data dictionary needed for the generation of the computed measurements of a real radiometric model.
default_dataset_nameDataset name used when the caller does not supply one.
dl_station_calDownlink station calibration [RU] written into simulated auxiliary data.
dsn_bandsDSN frequency-band parameters of this model, a read-only mapping from band letter to
DSNBand.epoch_secObservation epochs expressed as seconds of day.
instrumentThe instrument.
iono_file_pathAbsolute path to the selected ionosphere JSON, if set.
media_correctionsTropospheric and ionospheric path-delay model, or
Noneif not set.nameThe name of the model.
ramp_entriesNumber of entries of a simulated ramp table, at least 2.
ramp_marginSpan [s] a simulated ramp table extends before the first and after the last observation.
ramp_rateUplink frequency ramp rate [Hz/s] of the ramp table the
default_*_auxbuilders simulate.ramp_typeSFDU 9
ramp_typecode of the segments of a simulated ramp table.rcv_time_tag_delayReceive time-tag delay [s] written into simulated auxiliary data.
sigmaThe standard deviation of the measurement model.
solar_corona_coefficientCoefficient of the solar-corona group delay [us GHz^2 m^2] of a real model built with
solar_corona=True.transponder_delaySpacecraft transponder delay [RU] written into simulated auxiliary data by the
default_*_auxbuilders.tropo_non_seasonal_file_pathAbsolute path to the non-seasonal (monthly NRMPOW) troposphere JSON, if set.
tropo_seasonal_file_pathAbsolute path to the seasonal (TRIG) troposphere JSON, if set.
ul_station_calUplink station calibration [RU] written into simulated auxiliary data.
Methods
align_aux_to_epochs(source, key, target[, ...])Sample a TRK-2-34 record at the epochs of another record by time tag.
Compute the tropospheric mapping functions for dry and wet delays using the Chao model.
compute_partials(target, epoch_array, frame)Stacks together measurement _partials for an epoch array at different epochs.
computed_measurements(*args, **kwargs)Evaluate the forward model.
computed_rtlt_delays(query_time_et, ...[, ...])Compute the radio signal path delays due to Earth's media at a given epoch.
find_ion_metadata(folder, query_year, query_doy)Locate ionosphere metadata files covering a given year and day-of-year.
find_tro_metadata(folder, query_year, query_doy)Locate troposphere metadata files covering a given year and day-of-year.
for_pass(instrument, start_epoch_et, ...[, ...])Build a MediaCorrections for one pass, selecting the tropospheric and ionospheric files that cover the pass start date.
generate_measurement_dataset(dataset_name, ...)Generates a MeasurementDataSet object that can be used by filters downstream.
get_media_data_for_et(site_query, ...)Extract media-correction coefficients for a given DSN site and epoch, with optional wet/dry filtering.
ionosphere_mapping(E[, shell_height, ...])Thin-shell obliquity factor mapping a zenith ionospheric delay.
mediafun_nrmpow(query_time_et)Evaluate media correction function using a normalized power series expansion.
mediafun_trig(query_time_et)Evaluate media correction function using a trigonometric series expansion.
observed_measurements(file_name, meas_name, ...)Reads measurements from a .json file.
path_delay_to_light_time(delay_m)Convert a media path delay in metres into the light-time delay it causes.
residuals(observed_meas, computed_meas)Generates the measurement model's residuals given observed and computed ArrayWFrames.
resolve_elevation_mask(elevation_mask)Normalise an elevation mask to degrees.
rtlt_grad_pos_exact(n_hat_dn, n_hat_up, ...)Exact round-trip light-time gradient with respect to the spacecraft position.
rtlt_grad_station_exact(n_hat_dn, n_hat_up, ...)Exact round-trip light-time gradients with respect to the station position.
rtlt_leg_weights(n_hat_dn, n_hat_up, v_sc, ...)Sensitivity of the round-trip light time to a delay inside each leg's solution.
set_pass_epochs(pass_epochs)Enable per-pass biases.
set_trajectory(trajectory)Attach the reference trajectory supplying the STMs.
transponder_delay_seconds(delay_RU, ...)Convert a spacecraft transponder delay from range units to seconds.
update_reference_state(state_vector)Attach the estimated state the model should read its parameters from.
validate_aux(aux[, label])Check that an auxiliary-data dictionary is internally consistent.
write_observed_measurements(target, ...)Generates synthetic measurements and write them as a .json file.
zenith_delay_partials(query_time_et, ...[, ...])Derivatives of the one-way slant delays with respect to the estimated zenith delays at
query_time_et.See also
scarabaeus.DopplerRealReal Doppler model that consumes MediaCorrections.
scarabaeus.SequentialRangingRealReal ranging model that consumes MediaCorrections.
References
- classmethod for_pass(instrument, start_epoch_et, media_folder, tropo_seasonal_file_path=None, name=None)#
Build a MediaCorrections for one pass, selecting the tropospheric and ionospheric files that cover the pass start date.
Analysis scripts each carried their own copy of this selection logic, which is why it lives here now.
- Parameters:
- instrumentInstrument
The ground station observing the pass.
- start_epoch_etfloat
Ephemeris time of the first observation, used to pick the files.
- media_folderstr
Folder holding the tropospheric and ionospheric correction files.
- tropo_seasonal_file_pathstr, optional
Seasonal troposphere file. Needed whenever
media_folderholds a non-seasonal file for the pass, since the troposphere delay uses both.- namestr, optional
Name for the object. Defaults to one derived from the station.
- Returns:
- MediaCorrections
- Raises:
- MediaCorrections.IncompleteTroposphereError
If
tropo_seasonal_file_pathis given but no non-seasonal file inmedia_foldercovers the pass start date.
- static align_aux_to_epochs(source: dict, key: str, target: dict, invalid=None) ndarray#
Sample a TRK-2-34 record at the epochs of another record by time tag.
Each SFDU record of a tracking file has its own cadence (e.g. the uplink z-height correction every second, the ranging aux at the ranging cadence), so its rows do not correspond to the measurement rows. The value in force at each target epoch is the latest source entry at or before it (zero-order hold); target epochs earlier than the whole source take its first entry.
- Parameters:
- sourcedict
Record holding
year,doy,secandkey.- keystr
Field of
sourceto sample.- targetdict
Record holding the
year,doy,sectime tags to sample at, typically the measurement record (e.g.trk["2W_doppler"]).- invalidfloat, optional
Source entries equal to this value are skipped (e.g.
0for the uplink frequency of rows with no uplink).
- Returns:
- np.ndarray
source[key]at each target epoch, of lengthlen(target["sec"]).
- Raises:
- Measurement.AuxDataError
If
sourceholds no valid entry ofkey.
- static find_ion_metadata(folder: str, query_year: int, query_doy: int) Dict | None#
Locate ionosphere metadata files covering a given year and day-of-year.
This scans the specified folder for files named with any prefix followed by
YYYY_DDD_YYYY_DDD_ion.json(e.g.,orex_beno_2018_213_2018_244_ion.json). The method returns the metadata dictionary for the file whose interval contains the provided query year/day. Intervals crossing year boundaries are handled correctly.- Parameters:
- folderstr
Path to the folder containing ionosphere metadata files.
- query_yearint
Year of interest in four-digit format (e.g., 2018).
- query_doyint
Day-of-year (1–366) within query_year.
- Returns:
- metadatadict or None
Dictionary describing the matching file with fields: - “file” : filename - “start_year”, “start_doy” : start of coverage interval - “end_year”, “end_doy” : end of coverage interval Returns None if no file covers the query date.
Notes
If multiple files cover the same query date, the one with the tightest interval span is returned.
- static find_tro_metadata(folder: str, query_year: int, query_doy: int) Dict | None#
Locate troposphere metadata files covering a given year and day-of-year.
This scans the specified folder for files named according to the pattern
YYYY_DDD_YYYY_DDD_tro.json. Each file encodes the start and end year/DOY interval it covers. The method returns the metadata dictionary for the file whose interval contains the provided query year/day. Intervals that cross year boundaries (e.g.2017_335_2018_001_tro.json) are handled correctly.- Parameters:
- folderstr
Path to the folder containing the troposphere metadata files.
- query_yearint
Year of interest in four-digit format (e.g., 2017).
- query_doyint
Day-of-year (1–366) within query_year.
- Returns:
- metadatadict or None
Dictionary describing the matching file with fields:
"file": filename of the tro file"start_year","start_doy": start of coverage interval"end_year","end_doy": end of coverage interval
Returns
Noneif no file covers the query date.
- Raises:
- None
Notes
If multiple files cover the same query date, the one with the tightest interval span is returned.
Examples
meta = MediaCorrections.find_tro_metadata( folder="data/tropo", query_year=2017, query_doy=346 ) print(meta["file"]) # -> "2017_335_2018_001_tro.json"
- static ionosphere_mapping(E: float, shell_height: float = 450.0, earth_radius: float = 6371.0) float#
Thin-shell obliquity factor mapping a zenith ionospheric delay.
- Parameters:
- Efloat
Elevation angle in radians.
- shell_heightfloat, optional
Height of the equivalent thin shell in km, default 450, near the F2 peak.
- earth_radiusfloat, optional
Mean Earth radius in km, default 6371.
- Returns:
- float
Ratio of slant to zenith delay, one at the zenith and rising to roughly three at ten degrees elevation.
Notes
\[M(E) = \left[1 - \left(\frac{R\cos E}{R + h}\right)^2 \right]^{-1/2}\]The standard single-layer mapping. It is smoother than the \(1/\sin E\) of a plane-parallel atmosphere, which diverges at the horizon.
- static path_delay_to_light_time(delay_m)#
Convert a media path delay in metres into the light-time delay it causes.
The delays produced by this class are in metres, while the rest of the measurement pipeline works in km, so every use has to cross that boundary. Doing it here, once, keeps the factor out of the measurement models and lets the unit system verify it:
ArrayWUnitsdivision does not reconcile prefixes, so dividing a value in metres bycin km/sec silently yields a result 1000x too large, labelledsec. The explicitconvert_tobelow is what prevents that.- Parameters:
- delay_mArrayWUnits or float or array_like
One-way media path delay, in metres, as
computed_rtlt_delays()returns it. A bare number is taken to be in metres.
- Returns:
- float or numpy.ndarray
The corresponding delay in seconds, as a bare value: the measurement models fold it straight into arithmetic that mixes frequencies and range units, where a unit label would compose rather than convert.
- static resolve_elevation_mask(elevation_mask: ArrayWUnits | float) float#
Normalise an elevation mask to degrees.
- Parameters:
- elevation_maskArrayWUnits or float
Minimum elevation angle. An
ArrayWUnitsis converted from its own units, so radians work as well as degrees. A bare number is taken to be in degrees, which is what the parameter has always meant and what every default (10.0) is.
- Returns:
- float
The mask in degrees.
- Raises:
- ElevationMaskError
If the mask is not a number or an angle, or is outside 0 to 90 degrees. Also if it is a bare number that is not a whole number of degrees and is no more than pi/2: 0.17 could be 0.17 deg or 10 deg meant in radians, and reading it the wrong way silently keeps or drops the observations near the horizon. Such a mask has to carry its units. A larger bare number is read as degrees, since as radians it would be above 90 deg and be refused anyway.
Examples
Measurement.resolve_elevation_mask(10.0) # 10.0 Measurement.resolve_elevation_mask(ArrayWUnits(0.2, rad)) # 11.459... Measurement.resolve_elevation_mask(ArrayWUnits(0.5, deg)) # 0.5 Measurement.resolve_elevation_mask(0.5) # ElevationMaskError
- static rtlt_grad_pos_exact(n_hat_dn: ndarray, n_hat_up: ndarray, v_sc: ndarray, v_gs: ndarray, c: float) ndarray#
Exact round-trip light-time gradient with respect to the spacecraft position.
Chains Moyer (2000) Eqs. 12-12 (downleg) and 12-17 (upleg) through the reflection time \(t_2\), holding the reception time \(t_3\) fixed, so that \(\rho = t_3 - t_1\) and \(\partial \rho / \partial \mathbf{r}_{SC} = -\partial t_1 / \partial \mathbf{r}_{SC}\) [s/km]. With the Eq. 8-59/8-60 definitions, the spacecraft transmits on the downleg and the station on the upleg:
\[ \begin{align}\begin{aligned}\dot{p}_{23} = \hat{\mathbf{r}}_{23} \cdot \mathbf{v}_{SC} / c = -\hat{\mathbf{n}}_{dn} \cdot \mathbf{v}_{SC} / c, \qquad \dot{p}_{12} = \hat{\mathbf{r}}_{12} \cdot \mathbf{v}_{GS} / c = \hat{\mathbf{n}}_{up} \cdot \mathbf{v}_{GS} / c\\\dot{r}_{12} = \hat{\mathbf{n}}_{up} \cdot (\mathbf{v}_{SC} - \mathbf{v}_{GS}) / c, \qquad \dot{r}_{12} + \dot{p}_{12} = \hat{\mathbf{n}}_{up} \cdot \mathbf{v}_{SC} / c\end{aligned}\end{align} \]where the station terms cancel in the last sum. The gradient is then
\[\frac{\partial t_2}{\partial \mathbf{r}_{SC}} = -\frac{\hat{\mathbf{n}}_{dn}}{c\,(1 - \dot{p}_{23})}, \qquad \frac{\partial \rho}{\partial \mathbf{r}_{SC}} = -\frac{(1 - \dot{r}_{12} - \dot{p}_{12})\, \partial t_2 / \partial \mathbf{r}_{SC} - \hat{\mathbf{n}}_{up} / c} {1 - \dot{p}_{12}}\]- Parameters:
- n_hat_dnnumpy.ndarray, shape (3,)
Unit vector GS to SC on the downleg, \(\hat{\mathbf{n}}_{dn} = (\mathbf{r}_{SC}(t_2) - \mathbf{r}_{GS}(t_3)) / \rho_{dn}\).
- n_hat_upnumpy.ndarray, shape (3,)
Unit vector GS to SC on the upleg, \(\hat{\mathbf{n}}_{up} = (\mathbf{r}_{SC}(t_2) - \mathbf{r}_{GS}(t_1)) / \rho_{up}\).
- v_scnumpy.ndarray, shape (3,)
Spacecraft velocity at \(t_2\) [km/s], in the space-time frame the light time is solved in (see
_light_time_velocity()).- v_gsnumpy.ndarray, shape (3,)
Ground station velocity at \(t_1\) [km/s], in the same frame.
- cfloat
Speed of light [km/s].
- Returns:
- numpy.ndarray, shape (3,)
\(\partial \rho / \partial \mathbf{r}_{SC}\) [s/km].
References
[1]Moyer, T. D. (2000). Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation. JPL Publication 00-7.
- static rtlt_grad_station_exact(n_hat_dn: ndarray, n_hat_up: ndarray, v_sc: ndarray, v_gs: ndarray, c: float) tuple#
Exact round-trip light-time gradients with respect to the station position.
The station enters at reception \(t_3\) and at transmission \(t_1\), through the same Moyer (2000) 12-12/12-17 chain as
rtlt_grad_pos_exact(). Displacing the receiver at \(t_3\) moves the reflection time \(t_2\) (Eq. 12-12, with the station as the receiver), and the upleg carries that change to \(t_1\) through its own \(\dot{p}_{12}\) denominator (Eq. 12-17); displacing the transmitter at \(t_1\) enters the upleg only:\[\frac{\partial \rho}{\partial \mathbf{r}_{GS}(t_3)} = -\frac{(1 - \dot{r}_{12} - \dot{p}_{12})\,\hat{\mathbf{n}}_{dn}} {c\,(1 - \dot{p}_{23})(1 - \dot{p}_{12})}, \qquad \frac{\partial \rho}{\partial \mathbf{r}_{GS}(t_1)} = -\frac{\hat{\mathbf{n}}_{up}}{c\,(1 - \dot{p}_{12})}\]with \(\dot{p}\) and \(\dot{r}\) as defined in
rtlt_grad_pos_exact(): each leg’s range over c weighted byrtlt_leg_weights(). Their sum is-rtlt_grad_pos_exact(...): a common translation of station and spacecraft leaves the light time unchanged. Dropping the denominators, i.e. using \(-\hat{\mathbf{n}}/c\) on each leg, is off by the transmitters’ velocities over c, about 1e-4 relative with heliocentric velocities.- Parameters:
- n_hat_dnnumpy.ndarray, shape (3,)
Unit vector GS to SC on the downleg.
- n_hat_upnumpy.ndarray, shape (3,)
Unit vector GS to SC on the upleg.
- v_scnumpy.ndarray, shape (3,)
Spacecraft velocity at \(t_2\) [km/s].
- v_gsnumpy.ndarray, shape (3,)
Ground station velocity at \(t_1\) [km/s].
- cfloat
Speed of light [km/s].
- Returns:
- grad_t3numpy.ndarray, shape (3,)
\(\partial \rho / \partial \mathbf{r}_{GS}(t_3)\) [s/km], in the frame of the input vectors.
- grad_t1numpy.ndarray, shape (3,)
\(\partial \rho / \partial \mathbf{r}_{GS}(t_1)\) [s/km], in the same frame.
See also
rtlt_grad_pos_exactdefinitions of the inputs.
- static rtlt_leg_weights(n_hat_dn: ndarray, n_hat_up: ndarray, v_sc: ndarray, v_gs: ndarray, c: float) tuple#
Sensitivity of the round-trip light time to a delay inside each leg’s solution.
Uses the Moyer (2000) 12-12/12-17 chain of
rtlt_grad_pos_exact(). A delay \(\delta\tau_{23}\) in the downleg equation moves the reflection time \(t_2\), and the upleg carries that change to \(t_1\); a delay \(\delta\tau_{12}\) in the upleg equation moves \(t_1\) only:\[\frac{\partial \rho}{\partial \tau_{23}} = \frac{1 - \dot{r}_{12} - \dot{p}_{12}}{(1 - \dot{p}_{23})(1 - \dot{p}_{12})}, \qquad \frac{\partial \rho}{\partial \tau_{12}} = \frac{1}{1 - \dot{p}_{12}}\]with \(\dot{p}\) and \(\dot{r}\) as defined in
rtlt_grad_pos_exact(). Both are 1 to within the transmitters’ velocities over c, about 1e-4 with heliocentric velocities. They apply to what the iteration solves for, the geometric range and the Shapiro delay, and not to the media, corona and electronic delays, which are added after it converges.- Parameters:
- n_hat_dnnumpy.ndarray, shape (3,)
Unit vector GS to SC on the downleg.
- n_hat_upnumpy.ndarray, shape (3,)
Unit vector GS to SC on the upleg.
- v_scnumpy.ndarray, shape (3,)
Spacecraft velocity at \(t_2\) [km/s].
- v_gsnumpy.ndarray, shape (3,)
Ground station velocity at \(t_1\) [km/s].
- cfloat
Speed of light [km/s].
- Returns:
- w_dnfloat
\(\partial \rho / \partial \tau_{23}\), dimensionless.
- w_upfloat
\(\partial \rho / \partial \tau_{12}\), dimensionless.
See also
rtlt_grad_pos_exactdefinitions of the inputs.
- static transponder_delay_seconds(delay_RU: float, reference_frequency: float, range_unit: float) float#
Convert a spacecraft transponder delay from range units to seconds.
The delay is divided by
range_unit * reference_frequency, the rate of the clock the delay is counted against.- Parameters:
- delay_RUfloat
Transponder delay as the mission specifies it [RU].
- reference_frequencyfloat
The band’s range-unit reference frequency [1/s], i.e.
Measurement.DSNBand.ru_reference_frequency.- range_unitfloat
The range unit, from the pass’s exciter scalars.
- Returns:
- float
The delay [s].
Notes
Pass the band’s reference frequency, not its uplink frequency. The two differ by 18% in X band, and the delay enters the round-trip light time directly rather than acting as a scale factor, so substituting the uplink makes the delay 2.4 us longer – 1.4 km of two-way range. Tried on real tracking data, that drove the sequential-ranging residuals from 55-206 RU to 2330-2694 RU, so the reference frequency is what the data supports. Why a downlink-scale reference is the right one is an open question; see the attribute’s own note.
- static validate_aux(aux: dict, label: str = '') None#
Check that an auxiliary-data dictionary is internally consistent.
An aux dict describes two things sampled on two different grids: one value per observation, and one entry per ramp-table segment. Everything in each group has to be the same length, and a value meant to be per-observation has to be a sequence rather than a bare number.
Nothing checks that on the way in otherwise, and the failures it prevents surface far from their cause:
Mismatched lengths reach
RampTableManager.integrate(), which indexesramp_freqwith an index derived fromramp_secand raisedIndexError: index 9 is out of bounds for axis 0 with size 5from inside the forward model.A ragged per-observation group reaches
write_observed_measurements(), whose own check then refuses to write the file – correct, but one step later than here.
- Parameters:
- auxdict
The dictionary to check, as a
default_*_auxhelper or_read_aux()produces it.- labelstr, optional
Named in the error, to say which dictionary was wrong.
- Raises:
- TypeError
If aux is not a dict.
Noneis reported specifically, since that means the model was never given its auxiliary data.- ValueError
If the per-observation group or the ramp group is ragged. The message groups the keys by the length they have, since the odd one out is usually obvious once they are laid side by side.
Examples
aux = doppler_model.default_doppler_aux(t0, tf, N=20, band="S") scb.Measurement.validate_aux(aux, label="DSS-25 Range Rate")
- chao_mapping() tuple[float, float]#
Compute the tropospheric mapping functions for dry and wet delays using the Chao model.
- Parameters:
- Efloat
Elevation angle of the observation [rad].
- Returns:
- R_dryfloat
Dry mapping function value at the given elevation angle.
- R_wetfloat
Wet mapping function value at the given elevation angle.
Notes
The mapping functions are based on:
Estefan (1995), equations (7)–(8a,b).
Moyer (2000), equations (10–8 to 10–10).
The dry and wet components are computed as:
\[ \begin{align}\begin{aligned}R_{dry} = \frac{1}{\sin(E) + \frac{A_{dry}}{\tan(E) + B_{dry}}}\\R_{wet} = \frac{1}{\sin(E) + \frac{A_{wet}}{\tan(E) + B_{wet}}}\end{aligned}\end{align} \]with constants \(A_{dry} = 0.00143\), \(B_{dry} = 0.0445\), \(A_{wet} = 0.00035\), and \(B_{wet} = 0.017\).
References
[1]Estefan, J. A. (1995). Tropospheric Delay Effects on GPS Measurements.
[2]Moyer, T. D. (2000). Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation. JPL 00-7.
Examples
# Example: compute mapping functions at 30 degrees elevation import numpy as np E = np.deg2rad(30.0) R_dry, R_wet = scb.MediaCorrections.chao_mapping(E)
- compute_partials(target: Spacecraft, epoch_array: EpochArray, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER)) list#
Stacks together measurement _partials for an epoch array at different epochs.
- Parameters:
- targetSpacecraft
The target spacecraft.
- epoch_arrayEpochArray
The epochs.
- frameFrame, optional
The reference frame. Defaults to a J2000 Frame object.
- Returns:
- _partialslist
A list with all the _partials evaluated at different epochs in the
epoch_array.
- computed_measurements(*args, **kwargs)#
Evaluate the forward model. Implemented by every concrete model.
There is no shared implementation, but there is a shared contract – both
write_observed_measurements()andgenerate_measurement_dataset()unpack four values from this call, so a model that returns anything else fails at the call site with no explanation. Subclasses must return:t1, t2, t3, meas
measis the computed observable as anArrayWFrame. The three epochs describe where in time the observable lives, which for a two-way radiometric measurement is not one instant:t1Transmission from the ground station. Used as the regression abscissa when detrending residuals for outlier rejection (
_huber_mad_evaluate()).t2Reflection at the spacecraft. This is the one the estimator cares about: it is the epoch the filter associates the measurement with, and what measurements from different models are matched on (
_combine_indices_by_t2(), and the LKF).t3Reception at the ground station, i.e. the epoch the observation is time-tagged with in the data file. Currently carried through to the dataset for traceability rather than read by the estimator.
For a single-epoch observable – the optical models, where the observation is not spread across a light-time path in this way – all three collapse to the observation epoch. That is a correct statement about the observable, not padding to satisfy the signature.
- Raises:
- NotImplementedError
If a subclass has not implemented it.
- computed_rtlt_delays(query_time_et: float, target_spice_id: str, frequency: float | None = None, gs_delta_awf: ArrayWFrame | None = None, tropo_zenith_delay: float = 0.0, iono_zenith_delay: float = 0.0) tuple[ArrayWUnits, ArrayWUnits]#
Compute the radio signal path delays due to Earth’s media at a given epoch.
This method evaluates the tropospheric contribution (seasonal + non-seasonal, dry + wet) mapped by the Chao functions at the station elevation angle, and, if an ionospheric dataset is set (
self.iono_file_path), the ionospheric contribution scaled from the S-band calibration tofrequency.- Parameters:
- query_time_etfloat
SPICE Ephemeris Time (seconds past J2000) at which to evaluate the delay.
- target_spice_idstr
SPICE name or NAIF ID of the tracked target (e.g., spacecraft) used to compute the elevation angle at the DSN station.
- frequencyfloat, optional
Uplink or downlink frequency in Hz, used to scale the ionospheric group delay (proportional to \(1/f^2\)). Required when an ionosphere file is set; ignored otherwise.
- gs_delta_awfArrayWFrame | None, optional
Ground-station location offset, as in
Measurement._compute_precise_RTLT(). Not used yet: the elevation angle is computed at the nominal station location.- tropo_zenith_delayfloat, optional
Estimated additive tropospheric zenith delay [m], the
tropo_zenith_delay_<tag>state parameter, mapped to the slant path by the Chao wet mapping. Applied with or without a troposphere file. Defaults to0.0.- iono_zenith_delayfloat, optional
Estimated additive S-band ionospheric zenith delay [m], the
iono_zenith_delay_<tag>state parameter, scaled to frequency by Moyer 10-11 and mapped byionosphere_mapping(). Applied with or without an ionosphere file. Defaults to0.0.
- Returns:
- p_tropoArrayWUnits
One-way tropospheric path delay [m]. Sums the seasonal and non-seasonal dry and wet components and applies the Chao mapping functions at the current elevation angle. Zero when no tropospheric file covers the epoch.
- p_ionoArrayWUnits
One-way ionospheric path delay [m], scaled from the reference frequency to frequency by Moyer 10-11. Zero when no ionospheric file is set or none covers the epoch.
Both carry units because they cross a unit boundary on the way into the measurement models, which work in km: pass them to
path_delay_to_light_time()rather than dividing bycdirectly. They are also returned unit-bearing even when zero, so that a caller summing them never has to handle a bare0.
- Raises:
- MediaCorrections.IncompleteTroposphereError
If only one of the seasonal and non-seasonal troposphere files is set.
- MediaCorrections.MissingIonosphereFrequencyError
If an ionosphere file is set and
frequencyis None.- KeyError
If required keys are missing from the loaded JSON files (e.g.,
"aux_tropo").- FileNotFoundError
If one of the provided JSON file paths does not exist.
- ValueError
If the JSON content is malformed or contains invalid time ranges.
See also
MediaCorrections.get_media_data_for_etInterval selection and coefficient extraction for a given site/mode/time.
MediaCorrections.chao_mappingDry/wet mapping functions as a function of elevation angle.
MediaCorrections.mediafun_trigTrigonometric (seasonal) delay evaluator.
MediaCorrections.mediafun_nrmpowNormalized power-series (non-seasonal) delay evaluator.
Notes
The method expects JSON files at the paths
self.tropo_seasonal_file_pathandself.tropo_non_seasonal_file_path. Each should expose an"aux_tropo"table compatible withget_media_data_for_et().The elevation angle is computed via
get_elevation_angle()using the DSN station name fromself.instrument.nameand the provided target identifier.Mapping to slant delay is performed using
chao_mapping()(dry and wet components).The ionosphere calibration is the S-band (2295 MHz) delay, scaled by
(2295 MHz / frequency)**2(Moyer 10-11).
Examples
et = scb.SpiceManager.utc2et("2018-12-03 12:00:00 UTC") p_tropo, p_iono = media_correction.computed_rtlt_delays( query_time_et=et, target_spice_id="ORX", frequency=7.18e9, )
- generate_measurement_dataset(dataset_name: str | None = None, target: Body = None, observed_meas: tuple | list | None = None, epochs: EpochArray | None = None, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), noisy: bool = False) list[MeasurementDataSet]#
Generates a MeasurementDataSet object that can be used by filters downstream.
- Parameters:
- dataset_namestr, optional
The name of the MeasurementDataSet, which becomes the residual key in
solution.json. Defaults todefault_dataset_name—"<instrument>_<measurement_type>".- targetSpacecraft
The target spacecraft.
- observed_meastuple or list, optional
Observed measurements as
(epoch_array, meas_sec, meas_obs, outlier_flag). The computed values are evaluated atepoch_array. Give this orepochs, not both. Defaults toNone.- epochsEpochArray, optional
Epochs to simulate the measurements at, with no outliers flagged. Give this or
observed_meas, not both. Defaults toNone.- frameFrame, optional
The reference frame. Defaults to a J2000 Frame object.
- noisybool, optional
Indicates if noise is added to the measurements or not. Defaults to
False.
- Returns:
- mds_listlist[MeasurementDataSet]
A list of MeasurementDataSet objects representing the measurements with their key properties to be used by a filter.
- Raises:
- ValueError
If neither or both of
observed_measandepochsare given, ifobserved_meascarries fewer than four entries (the fourth is the outlier-flag array, without which the observations cannot be kept on one index set with their flags), or if the model has more than two components.
Notes
This is the single bridge from a measurement model to the estimator:
fit()andcompute()both come through here, andMeasurementDataSetis populated nowhere else. It pairs each observation with its computed value, residual, partial and sigma on one consistent set of indices, which is what lets several models with different epochs and different observables be combined into one filter update.That is also why it, rather than the caller, unpacks
t1, t2, t3fromcomputed_measurements(). The estimator needs the epochs alongside the observable –t2to match measurements across models,t1to detrend residuals during outlier rejection – so they have to survive the trip into the dataset. Seecomputed_measurements()for what each epoch means and why a single-epoch observable collapses all three.The MeasurementDataSet output is generated in 6 steps:
Computed measurements
Partials
Residuals
Sigmas
Outlier flag
Pack everything in a list
Pack the list in a MeasurementDataSet object
- get_media_data_for_et(site_query: str, wetdry_query: str | None, query_et: float) dict | None#
Extract media-correction coefficients for a given DSN site and epoch, with optional wet/dry filtering. Works for both troposphere tables (with ‘wet_or_dry’ and possibly ‘type’) and ionosphere tables (which may omit those fields).
- Parameters:
- dict_inputdict
Table-like dictionary with row-aligned lists: required: ‘dsn’, ‘start_day’, ‘start_time’, ‘end_day’, ‘end_time’ optional: ‘wet_or_dry’, ‘type’, any ‘C#’ coefficient fields, etc.
- site_querystr
DSN site code to filter (e.g., “C40”).
- wetdry_querystr or None
If provided and ‘wet_or_dry’ exists, filter by this mode (“WET”/”DRY”). If None or the column is missing, only the site filter is applied.
- query_etfloat
Ephemeris Time (ET) at which the values are requested.
- Returns:
- dict or None
A single-interval dictionary slice whose [start_et, end_et] contains query_et. All row-wise fields are reduced to the selected row; non row-wise/scalar fields are carried as-is. Returns None if no match.
- mediafun_nrmpow(query_time_et) float#
Evaluate media correction function using a normalized power series expansion. Applicable for seasonal, non-seasonal, and ionospheric corrections.
- Parameters:
- media_datadict
Dictionary containing the polynomial coefficients (C1–C10) and the interval bounds start_et and end_et. Coefficients are expected to be convertible to float.
- query_time_etfloat
Ephemeris Time (ET) at which the correction is to be evaluated.
- Returns:
- delta_sumfloat
Media correction value delay at the requested time, expressed in meters.
- Raises:
- KeyError
If one or more required coefficients (C1–C10) or ET bounds (start_et, end_et) are missing from media_data.
Notes
The function evaluates a normalized power series of the form:
\[ \begin{align}\begin{aligned}X = 2 \frac{t - A}{B - A} - 1\\\Delta(t) = C_0 X^0 + C_1 X^1 + C_2 X^2 + \ldots + C_9 X^9\end{aligned}\end{align} \]where \(A\) and \(B\) are the start and end ephemeris times of the interval, respectively.
Examples
# Example evaluation et = scb.SpiceManager.utc2et("2010-01-15 12:00:00 UTC") correction = scb.MediaCorrections.mediafun_nrmpow(media_data, et)
- mediafun_trig(query_time_et) float#
Evaluate media correction function using a trigonometric series expansion. Applicable for seasonal, non-seasonal, and ionospheric corrections.
- Parameters:
- media_datadict
Dictionary containing the trigonometric coefficients (C1–C10) and the interval bounds start_et and end_et. Coefficients are expected to be convertible to float.
- query_time_etfloat
Ephemeris Time (ET) at which the correction is to be evaluated.
- Returns:
- delta_sumfloat
Media correction value delay at the requested time, expressed in meters.
- Raises:
- KeyError
If one or more required coefficients (C1–C10) or ET bounds (start_et, end_et) are missing from media_data.
Notes
The function evaluates a truncated Fourier series of the form:
\[\Delta(t) = C_1 + C_2 \cos(X) + C_3 \sin(X) + C_4 \cos(2X) + C_5 \sin(2X) + C_6 \cos(3X) + C_7 \sin(3X) + C_8 \cos(4X) + C_9 \sin(4X)\]where \(X = 2 \pi (t - A)/P\), with \(A\) being the start_et and \(P\) the fundamental period C1.
Examples
# Example evaluation et = scb.SpiceManager.utc2et("2010-01-15 12:00:00 UTC") correction = scb.MediaCorrections.mediafun_trig(media_data, et)
- observed_measurements(file_name, meas_name: str = 'meas_sim', units: Units = unitless, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), **read_kwargs) ObsData#
Reads measurements from a .json file.
- Parameters:
- file_namestr
The filename of the .json file containig the measurement information.
- meas_namestr, optional
The name of the measurement data to access from the dictionary. Defaults to
'meas_sim'. Files written before the rename use'meas_ideal'; either name resolves to whichever block the file actually contains, with a DeprecationWarning on the fallback.- unitsUnits, optional
Units to be used to write the output AWU. Defaults to
unitless.- frameFrame, optional
Frame to be used to write the output AWF. Defaults to a J2000 Frame object.
- **read_kwargs
Options for the model’s own
_read_aux(), forwarded unchanged. Models with no auxiliary data to read ignore them.This is where
sc_transponder_delay_RUgoes for the DSN radiometric models, which is the only such option today. It is not a named parameter here because this signature is shared by every measurement model, optical ones included.
- Returns:
- ObsData
A
ObsDatanamed tuple with five fields, addressable by name or index:[0]meas_time_etEpochArrayObservation epochs. Built from the file’s UTC station tag via
YDS2et(); see the comment at the conversion below for why this carries SPICE’s time model deliberately.
[1]meas_secnumpy.ndarrayThe observation times as seconds of day, as given in the file.
[2]meas_obsArrayWFrameThe observed quantities, with units and frame attached.
[3]meas_outliersnumpy.ndarrayPer-observation outlier flags, 1 = reject. Seeded from the file’s own
outlier_flagand additionally set here for records carrying the-1no-data sentinel and for the rows the model knows to be invalid (_flag_invalid_rows()). Downstream this is the authoritative flag array: it is what the filter,outlier_flags()and the editors gate on, andgenerate_measurement_dataset()writes into it when the forward model cannot compute an observation.
[4]aux_dictdictAncillary per-observation data read by the model’s
_read_aux(ramp tables, transponder ratios, electronic delays, …). None for models that need none.
Notes
The writing of the json assumes or requires units and frames.
Every row in the file is returned, including rows flagged bad. Nothing is dropped here, so the observations, the
aux_dictand any later outlier rejection all stay on one consistent set of indices.
- residuals(observed_meas: ArrayWFrame, computed_meas: ArrayWFrame) ArrayWFrame#
Generates the measurement model’s residuals given observed and computed ArrayWFrames.
- Parameters:
- observed_measArrayWFrame
The observed measurements values (O).
- computed_measArrayWFrame
The computed measurements values (C).
- Returns:
- residualsArrayWFrame
AWF with the residual O-C.
- set_pass_epochs(pass_epochs: list[list] | None)#
Enable per-pass biases.
- Parameters:
- pass_epochslist[list[float]] | None
Observation epochs grouped by pass, e.g.
[[t0, t1], [t10, t11]]. PassNoneto revert to global-bias mode.
- set_trajectory(trajectory)#
Attach the reference trajectory supplying the STMs.
Read only by the analytical light-time partials, which map a deviation between the endpoints of an observable (see
_short_arc_stm()).- Parameters:
- trajectoryTrajectory
Trajectory carrying the STMs. Must span every epoch the model evaluates.
- update_reference_state(state_vector: StateArray)#
Attach the estimated state the model should read its parameters from.
Call this once per iteration, before
generate_measurement_dataset(). The model then pulls the entries belonging to this instrument, matched on its SPICE ID:meas_bias_ideal_*, as anArrayWUnits.gs_delta_location_ECEF_*, as anArrayWFrame.
- Parameters:
- state_vectorStateArray
The current estimated state. Its layout is also recorded, so that the partials can build a column for every estimated parameter beyond position and velocity.
- write_observed_measurements(target: Spacecraft, epoch_array: EpochArray = None, epoch_start: EpochArray = None, epoch_end: EpochArray = None, tstep: float = 1, frame: Frame = J2000 (0 - SOLAR SYSTEM BARYCENTER), noisy: bool = False, file_name: str = 'ideal_measurement', check_visibility: bool = False, elevation_mask: ArrayWUnits | float = 10.0, folder_path_override: str = None, fmt: str = 'json') None#
Generates synthetic measurements and write them as a .json file. The input of this method encapsulate the ones needed for the “computed_meas” method in each measurement model class.
- Parameters:
- targetSpacecraft
The target spacecraft for which the range measurement is to be computed.
- epoch_arrayEpochArray, optional
An array of epochs (times) at which the range measurements should be computed. If provided, overrides
epoch_start,epoch_end, andtstep.- epoch_startEpochArray, optional
The starting epoch for the range measurement computations. Required if
epoch_arrayis not provided.- epoch_endEpochArray, optional
The ending epoch for the range measurement computations. Required if
epoch_arrayis not provided.- tstepfloat, optional
The time step, in seconds, between consecutive range measurements. If epoch_array is not provided. Defaults to
1second.- frameFrame , optional
The reference frame in which the range computation is performed. Defaults to
None.- noisybool , optional
Whether to add noise to the computed range measurement. Defaults to
False.- file_namestr, optional
The filename of the JSON in which the measurement is saved, Defaults to
'ideal_measurement'.- check_visibilitybool, optional
When
True, epochs where the instrument cannot observe the target are removed before generating measurements. The specific check is instrument-dependent:GroundStationuses an elevation-angle test;Camerauses a FOV projection test. Defaults toFalse.- elevation_maskArrayWUnits or float, optional
Minimum elevation angle used by the
GroundStationvisibility check. AnArrayWUnitsis converted from its own units; a bare number is read as degrees (seeresolve_elevation_mask(), which refuses a bare one that could be radians). Ignored forCamerainstruments. Only relevant whencheck_visibility=True. Defaults to10.0degrees.- folder_path_overridestr, optional
If provided, the JSON file is saved directly to this path instead of the default
data/measurements/radiometricordata/measurements/opticalfolder. The directory is created automatically if it does not exist. Defaults toNone.- fmt{“json”, “pickle”}, optional
On-disk format; selects the
.jsonor.pklextension appended tofile_name. Read back transparently byobserved_measurements(). Defaults to"json".
- Returns:
- None
- zenith_delay_partials(query_time_et: float, target_spice_id: str, frequency: float | None = None) tuple[float, float]#
Derivatives of the one-way slant delays with respect to the estimated zenith delays at
query_time_et.This uses the same elevation computation as
computed_rtlt_delays(), so the factors are exactly the analytical partials of the delays the forward model applies fortropo_zenith_delayandiono_zenith_delayat that epoch.- Parameters:
- query_time_etfloat
Reception or transmission epoch [ET seconds].
- target_spice_idstr
SPICE name/ID of the tracked target.
- frequencyfloat, optional
Link frequency [Hz] of this leg, scaling the ionospheric term as in
computed_rtlt_delays().
- Returns:
- (d_tropo, d_iono)tuple[float, float]
\(\partial \rho_{tropo} / \partial \rho_{z,tropo}\) and \(\partial \rho_{iono} / \partial \rho_{z,iono}\), both dimensionless [m/m].
- AUX_KEYS = None#
- DL_STATION_CAL = 850000.0#
Default downlink station calibration [RU] of simulated auxiliary data, the starting
dl_station_calof a model.Representative, not physical: real passes carry the station value.
- DSN_BANDS = {'S': Measurement.DSNBand(name='S', uplink_multiplier=221, downlink_multiplier=240, turnaround_num=240, turnaround_den=221, exciter_scalar_num=221.0, exciter_scalar_den=7072.0, uplink_frequency=2110362223.0 Hz, ru_reference_frequency=2303391185.181818 Hz), 'X': Measurement.DSNBand(name='X', uplink_multiplier=749, downlink_multiplier=880, turnaround_num=880, turnaround_den=749, exciter_scalar_num=221.0, exciter_scalar_den=23968.0, uplink_frequency=7152313596.9977 Hz, ru_reference_frequency=8445767679.0 Hz)}#
Default DSN frequency-band parameters, keyed by band letter, each a
DSNBand. A model starts with these asdsn_bands.Supported bands are
'X'and'S'.'X'holds the values the measurement models used as literals before they were collected here, so it is the default everywhere and reproduces the previous numbers exactly.[1]Moyer, T. D., Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation, JPL Publication 00-7, Monograph 2, Deep Space Communications and Navigation Series, Chapter 13.
[2]DSN Telecommunications Link Design Handbook, 810-005, Module 201, Frequency and Channel Assignments.
- DSN_COMPLEX_ANTENNAS = {'C10': range(11, 31), 'C40': range(31, 51), 'C60': range(51, 71)}#
DSN antenna numbers of each complex, keyed by the complex code of the media calibration files: 11-30 Goldstone, 31-50 Canberra, 51-70 Madrid, inclusive.
[1]NTRS 19950013586, DSN station numbering.
[2]“TRK-2-23, Media Calibration Interface”, DSN No. 820-013.
- LIGHT_TIME_FRAMES = ('barycentric', 'geocentric')#
- LIGHT_TIME_SETTINGS = {'et_tai_iterations': 2, 'max_iterations': 10, 'tolerance': 1e-12}#
Default settings of the round-trip light-time solution of the real measurement models, which take a dictionary with any of these keys as
light_time_settings. They apply to both solvers,_compute_precise_RTLT()and_compute_geocentric_RTLT()."tolerance"[s]: each leg (t3 to t2, then t2 to t1) is corrected with Moyer 2000 eq. 8-72 until the correction is no larger than this. 1e-12 s is 0.3 mm of one-way path. The correction cannot fall much below the float spacing of the one-way light time: 9.1e-13 s from 4096 s (8.2 AU), 1.8e-12 s from 8192 s (16 AU). A tolerance under that floor makes every leg run to"max_iterations", so raise it for distant spacecraft."max_iterations": iteration cap of each leg. A leg that reaches it keeps its last estimate and does not raise."et_tai_iterations": evaluations of the ET - TAI series (Moyer 2000 eq. 2-26) when the reception time is converted from TAI to ET. Each one is made at the ET the previous one gave. The first starts from the approximate series, eq. 2-27.
[1]Moyer, T.D. (2000). Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation. JPL Publication 00-7, Monograph 2, Deep Space Communications and Navigation Series, Sec. 8.3.6 and Eq. 2-26.
- PARTIALS_METHODS = ('fd', 'analytical')#
- RAMP_AUX_KEYS = ('ramp_sec', 'ramp_day', 'ramp_freq', 'ramp_rate', 'ramp_type')#
Auxiliary-data keys of the ramp table every real radiometric model carries: start second of day, day of year, frequency, rate and type of each ramp segment.
- RAMP_ENTRIES = 12#
Default number of entries of a simulated ramp table, the starting
ramp_entriesof a model.
- RAMP_MARGIN = 3600.0 sec#
Default span a simulated ramp table extends before the first and after the last observation, the starting
ramp_marginof a model.The uplink transmit time precedes the first tag by the round-trip light time, so a table that starts at the first tag raises
RampCoverageError. One hour clears a spacecraft out to the asteroid belt.
- RAMP_RATE = 0.2826 sec^-2#
Default uplink frequency ramp rate of a simulated ramp table, the starting
ramp_rateof a model.A representative DSN ramp slope, not a physical constant: real passes carry their measured rate in the ramp table.
- RAMP_TYPE = 1#
Default ramp type of a simulated ramp table, the SFDU 9
ramp_typecode of a ramped segment; the startingramp_typeof a model.
- RAMP_YEAR_KEY = 'ramp_year'#
Auxiliary-data key of the year of each ramp segment. Optional: a table read without it is assumed to lie in the year of the observations.
- RCV_TIME_TAG_DELAY = 0.0008 sec#
Default receive time-tag delay of simulated auxiliary data, the starting
rcv_time_tag_delayof a model.Representative, not physical: real passes carry the station value.
- SOLAR_CORONA_DELAY_COEFF = 1.3446e-19#
Coefficient of the solar-corona group delay, in us GHz^2 m^2: delay [us] =
SOLAR_CORONA_DELAY_COEFF* STEC [electrons/m^2] / f^2 [GHz^2].The default of
_compute_SC_lt(), and the startingsolar_corona_coefficientof a radiometric model.[1]Ho, C. M. (2010). 106, Rev. B, Solar Corona and Solar Wind Effects. DSN Telecommunications Link Design Handbook, Eq. (1).
- TRANSPONDER_DELAY = 1e-05#
Default spacecraft transponder delay [RU] of simulated auxiliary data, the starting
transponder_delayof a model.Representative, not physical: real passes carry the calibrated delay.
- UL_STATION_CAL = 5000.0#
Default uplink station calibration [RU] of simulated auxiliary data, the starting
ul_station_calof a model.Representative, not physical: real passes carry the station value.
- property component_labels: tuple[str, str]#
Names of the two components of a vector observable.
A two-component measurement is split into one scalar dataset per component, and these are the suffixes those datasets carry — so they end up as the residual keys in
solution.json. Each model sets them in its__init__beside_measurement_type:AngularIdealmeasures("ra", "dec"),CentroidingIdeal("sample", "line").
- property computed_measurements_dict: dict#
Auxiliary TRK-2-34 tracking-data dictionary needed for the generation of the computed measurements of a real radiometric model. See the
computed_measurements_dictparameter ofDopplerRealandSequentialRangingRealfor the keys each requires.
- property default_dataset_name: str#
Dataset name used when the caller does not supply one.
"<instrument>_<measurement_type>", which is the convention the radiometric datasets already read as —DSS-14_RangeIdeal— and now the optical ones too. For a camera-based model the instrument is the camera, so a centroiding dataset comes out asNAC_CentroidingIdeal.Note that an
AngularIdealobserver is the spacecraft, not the camera (its name is resolved through SPICE), so a run that images with several cameras should passdataset_nameexplicitly to tell them apart.
- property dl_station_cal: float#
Downlink station calibration [RU] written into simulated auxiliary data. Starts as
DL_STATION_CAL.
- property dsn_bands: MappingProxyType#
DSN frequency-band parameters of this model, a read-only mapping from band letter to
DSNBand. Starts asDSN_BANDS.The
bandof a real model is looked up here, for the reference frequency that converts the transponder delay to seconds and the range unit of a tracking file without exciter scalars, and so is the band of thedefault_*_auxbuilders, which take its turnaround ratio, exciter scalars and uplink frequency.Set a whole new mapping to change it; its keys are upper-cased.
Examples
X = model.dsn_bands["X"] model.dsn_bands = { **model.dsn_bands, "X": dataclasses.replace(X, uplink_frequency=scb.ArrayWUnits(7.18e9, 1 / sec)), }
- property epoch_sec: EpochArray#
Observation epochs expressed as seconds of day.
- property instrument: Instrument#
The instrument.
- property media_corrections#
Tropospheric and ionospheric path-delay model, or
Noneif not set.
- property ramp_entries: int#
Number of entries of a simulated ramp table, at least 2. Starts as
RAMP_ENTRIES.
- property ramp_margin: ArrayWUnits#
Span [s] a simulated ramp table extends before the first and after the last observation. Starts as
RAMP_MARGIN; see_default_aux_grids()for why it is needed.Set an ArrayWUnits time, or a bare, non-negative number of seconds.
- property ramp_rate: ArrayWUnits#
Uplink frequency ramp rate [Hz/s] of the ramp table the
default_*_auxbuilders simulate. Starts asRAMP_RATE.Set an ArrayWUnits, converted to 1/s^2, or a bare number in Hz/s.
- property ramp_type: int#
SFDU 9
ramp_typecode of the segments of a simulated ramp table. Starts asRAMP_TYPE.
- property rcv_time_tag_delay: ArrayWUnits#
Receive time-tag delay [s] written into simulated auxiliary data. Starts as
RCV_TIME_TAG_DELAY.Set an ArrayWUnits time, or a bare number of seconds.
- property sigma: ArrayWUnits#
The standard deviation of the measurement model.
- property solar_corona_coefficient: float#
Coefficient of the solar-corona group delay [us GHz^2 m^2] of a real model built with
solar_corona=True. Starts asMediaCorrections.SOLAR_CORONA_DELAY_COEFF; seeMediaCorrections._compute_SC_lt.A fixed change of the delay model. To estimate a correction from the data, estimate
solar_corona_scaleinstead.
- station_eps_defaults = {'body_orientation_delta': 0.0001 rad, 'eop_delta_celestial_pole_x': 0.0001 rad, 'eop_delta_celestial_pole_y': 0.0001 rad, 'eop_delta_pole_x': 0.0001 rad, 'eop_delta_pole_y': 0.0001 rad, 'eop_delta_ut1': 1.0 sec, 'gs_delta_location_CYL': 1.0 km, 'gs_delta_location_ECEF': 1.0 km, 'iono_zenith_delay': 10.0 m, 'love_h2': 100.0, 'pole_dec': 0.0001 rad, 'pole_pm': 1e-06, 'pole_ra': 0.0001 rad, 'pole_w0': 0.0001 rad, 'shida_l2': 100.0, 'tropo_zenith_delay': 10.0 m}#
Finite-difference perturbations for station parameters, used only by
partials_method="fd"(_compute_partials_with_fd()); every analytical path differentiates the station in closed form. They live in the sameeps_dictas the spacecraftdx/dvxentries, keyed by StateDefinition parameter kind, so a model has one perturbation dictionary rather than two. The values are large because an RTLT solution and ramp integration lose significance in a small perturbation; they are numerical choices, not prior sigmas. The light time carries about 1e-13 s of noise per leg (SSB positions near 1.5e8 km), and a unit Love number moves a station by centimetres, so a Doppler fed by a step near one is mostly that noise. The tide and the zenith delays are exactly linear in their parameters, so their steps are as large as needed.
- property transponder_delay: float#
Spacecraft transponder delay [RU] written into simulated auxiliary data by the
default_*_auxbuilders. Starts asTRANSPONDER_DELAY.Only simulated data: a real pass takes the
sc_transponder_delay_RUgiven toobserved_measurements, or else the delay in its tracking file.
- property tropo_non_seasonal_file_path: Path | None#
Absolute path to the non-seasonal (monthly NRMPOW) troposphere JSON, if set.
- property tropo_seasonal_file_path: Path | None#
Absolute path to the seasonal (TRIG) troposphere JSON, if set.
- property ul_station_cal: float#
Uplink station calibration [RU] written into simulated auxiliary data. Starts as
UL_STATION_CAL.
- exception IncompleteTroposphereError#
Bases:
ValueErrorRaised when only one of the seasonal and non-seasonal troposphere files is set.
- exception MissingIonosphereFrequencyError#
Bases:
ValueErrorRaised when an ionosphere file is set but no link frequency is given to scale it.
- exception TroposphereFileTypeError#
Bases:
ValueErrorRaised when a seasonal troposphere file is given as non-seasonal, or the reverse.