Struct ObserverState 

pub struct ObserverState {
    pub time: Dt,
    pub position: Position,
    pub velocity: Velocity,
    pub grav_potential_m2_s2: Real,
    pub characteristic_length_scale: Real,
}

A snapshot of an observer’s relativistic state at a specific instant.

ObserverState combines time, position, velocity, and local gravitational information. It is the main input type used by relativistic light-time methods in this library.

Fields

time: Dt

The time of this state.

Any [Scale] is accepted. This time is treated as coordinate time for light-time calculations.

position: Position

Position of the observer in meters.

Typically expressed in a barycentric (solar-system barycenter) or heliocentric frame, depending on the application.

velocity: Velocity

Velocity of the observer in meters per second.

grav_potential_m2_s2: Real

Newtonian gravitational potential Φ at the observer’s location (in m² s⁻²).

This value is usually negative for bound orbits. It should normally include contributions from the Sun and all relevant planets.

characteristic_length_scale: Real

Characteristic length scale (in meters) over which the gravitational field varies significantly at this location.

• Use 0.0 (the default) for all solar-system, GNSS, and weak-field applications.
• Provide a non-zero value only when working in strong gravitational fields (e.g. near neutron stars or black holes), where the library’s higher-order curvature terms become relevant.

Implementations

impl ObserverState

pub const fn new( time: Dt, position: Position, velocity: Velocity, grav_potential_m2_s2: Real, ) -> Self

Creates a new ObserverState for typical solar-system, GNSS, or weak-field use.

This is the recommended constructor for most applications. It sets the characteristic_length_scale to 0.0, which disables higher-order curvature terms in the proper-time model.

Parameters

• time: The time of the state.
• position: Position in meters (usually barycentric or heliocentric).
• velocity: Velocity in m/s.
• grav_potential_m2_s2: Newtonian gravitational potential Φ at the location (in m²/s²).

pub const fn new_strong_field( time: Dt, position: Position, velocity: Velocity, grav_potential_m2_s2: Real, characteristic_length_scale: Real, ) -> Self

Creates a new ObserverState when strong-field effects or a non-zero characteristic length scale are relevant.

Use this constructor when you have gravimeter data or are working in regions where spacetime curvature varies significantly over short distances (e.g. near compact objects). The characteristic_length_scale parameter controls whether the library activates higher-order terms in the proper-time calculation.

For normal solar-system work, use Self::new instead.

Parameters

• time: The time of the state.
• position: Position in meters.
• velocity: Velocity in m/s.
• grav_potential_m2_s2: Newtonian gravitational potential Φ at the location (in m²/s²).
• characteristic_length_scale: Length scale (in meters) over which gravity varies at this location. Must be positive to have an effect.

pub const fn proper_time_rate(&self) -> Real

Returns the instantaneous proper-time rate dτ/dt for this observer.

This value indicates how fast a physical clock located at this state would advance relative to the time used by this ObserverState. A returned value of 1.0 means the clock advances at the same rate as the state’s time coordinate. Values are typically slightly different from 1.0 due to the effects of velocity and gravitational potential.

This rate is computed using the library’s unified proper-time model. It is used internally for light-time corrections and Doppler calculations.

pub const fn relativistic_clock_rate_ratio(&self, rx: ObserverState) -> Real

Returns the ratio of proper time rates between the receiver and transmitter for a one-way signal.

This method computes:

ratio = rx.proper_time_rate() / self.proper_time_rate()

Interpretation

• A value of 1.0 indicates that both clocks run at the same rate.
• A value less than 1.0 means the receiver’s clock runs slower than the transmitter’s clock. The receiver will observe a lower frequency than was emitted.
• A value greater than 1.0 means the receiver’s clock runs faster than the transmitter’s clock. The receiver will observe a higher frequency than was emitted.

The ratio captures the combined effect of special-relativistic time dilation (due to velocity) and general-relativistic gravitational time dilation.

Typical Usage (One-Way)

This ratio is often combined with the classical kinematic Doppler term to estimate the total one-way frequency shift:

approximate_frequency_shift ≈ ratio * (1 - v_radial / C)

where v_radial is the radial velocity (positive when the receiver is receding).

Two-Way Usage

For round-trip (two-way) measurements, square the one-way ratio:

let one_way_ratio = transmitter.relativistic_clock_rate_ratio(receiver);
let two_way_ratio = one_way_ratio * one_way_ratio;

This pattern is commonly used when correcting two-way Doppler (range-rate) data for relativistic clock effects.

Limitations

• This method only accounts for the difference in clock rates between the two ends.
• It does not include Shapiro delay or higher-order relativistic effects on signal propagation.
• The combination with classical Doppler shown above is a first-order approximation.

Parameters

• self — Transmitter state at the time of transmission.
• rx — Receiver state at the approximate time of reception.

Example

let ratio = transmitter.relativistic_clock_rate_ratio(receiver);

let v_radial = ...; // m/s, positive if receding
let classical_doppler = 1.0 - v_radial / C;

let approx_frequency_shift = ratio * classical_doppler;

pub const fn one_way_relativistic_delay( &self, rx: ObserverState, shapiro: Dt, samples: &[Spacetime], custom_shapiro_delay: Option<Dt>, ) -> Dt

Computes the additional delay that must be added to the Newtonian geometric light time |r_rx − r_tx| / c.

In simple terms, this method calculates the extra time delay caused by differences in clock rates between the transmitter and receiver (due to their relativistic states, including velocity and gravity) plus the gravitational Shapiro delay.

The returned value is a hybrid correction consisting of two parts:

• The difference in accumulated proper time between the transmitter and receiver (clock-rate effects).
• The gravitational (Shapiro) delay caused by spacetime curvature near a central mass.

This is the primary method for relativistic light-time calculations.

Optional Endpoint States

You may optionally supply a slice of Spacetime samples. When two or more samples are provided, only the first and last elements are used: the first becomes the effective transmitter state, and the last becomes the effective receiver state for the clock-rate correction.

This is useful when you have more accurate information about the local spacetime conditions exactly at transmission and reception.

If fewer than two samples are provided, the method falls back to using self and rx directly.

Note: This is an endpoint-based model. It does not perform numerical integration of proper time along the signal path.

Custom Shapiro / Propagation Delay

You can provide your own delay value via custom_shapiro_delay. When supplied, this value is used directly instead of the internally computed Shapiro delay.

This allows you to pass:

• A delay computed with a different Shapiro model
• A delay that includes additional propagation effects (such as solar plasma)
• A delay obtained from an external calculation

Parameters

• rx — Receiver state at the approximate arrival time.
• shapiro — Shapiro scale factor. Use Dt::SHAPIRO_SOLAR for normal solar-system work.
• samples — Optional Spacetime samples. Only the first and last are used when provided.
• custom_shapiro_delay — Optional custom delay to use instead of the standard Shapiro calculation.

Returns

The total relativistic correction to be added to the geometric light time.

Example

// Basic usage
let correction = tx.one_way_relativistic_delay(
    rx_approx,
    Dt::SHAPIRO_SOLAR,
    &[],
    None,
);

// With custom endpoint states and a custom delay
let path_samples = vec![tx_spacetime, rx_spacetime];
let custom_delay = compute_custom_delay(...);

let correction = tx.one_way_relativistic_delay(
    rx_approx,
    Dt::SHAPIRO_SOLAR,
    &path_samples,
    Some(custom_delay),
);

pub fn iterative_one_way_relativistic_delay_to<F>( &self, rx_provider: &mut F, shapiro: Dt, tolerance: Dt, max_iter: usize, ) -> (Dt, Dt, ObserverState)

where F: FnMut(Dt) -> ObserverState,

Iteratively solves the one-way light-time equation including relativistic corrections until the receive time converges to the requested tolerance.

This is the recommended high-precision solver for one-way light-time computations in modern deep-space navigation. It follows the formulation described in Moyer (2003) and works with any ephemeris source (SPICE kernels, numerical integrators, or analytical propagators).

The solver performs a fixed-point iteration on the light-time equation:

t_rx = t_tx + |r_rx(t_rx) − r_tx(t_tx)| / c + Δt_rel(t_tx, t_rx)

where Δt_rel is the relativistic correction returned by [one_way_relativistic_delay]. The iteration continues until the change in the estimated receive time falls below tolerance.

Parameters

• rx_provider — A mutable closure that returns the full relativistic state of the receiver at a given coordinate time. This allows the solver to work with any ephemeris or propagator without requiring a specific data structure.
• shapiro — Controls the gravitational (Shapiro) contribution. Use Dt::SHAPIRO_SOLAR for solar-system work or Dt::shapiro_from_grav_param for other central bodies.
• tolerance — Convergence tolerance on the change in receive time. A typical value for high-precision work is Dt::from_ns(1, Scale::TAI).
• max_iter — Maximum number of iterations before falling back. A value of 12–20 is usually sufficient for solar-system geometries.

Returns

A tuple containing:

• rel_correction — The final relativistic correction (clock-rate correction + Shapiro) evaluated at convergence.
• rx_time — The converged receive time in the coordinate scale of the transmitter.
• final_state — The receiver state at the converged receive time.

Examples

use deep_time::{Dt, ObserverState, Scale};

let tolerance = Dt::from_ns(1, Scale::TAI);

let (correction, rx_time, rx_state) = tx.iterative_one_way_relativistic_delay_to(
    &mut |t| {
        // Example: call into SPICE or your own propagator
        get_receiver_state_at(t)
    },
    Dt::SHAPIRO_SOLAR,
    tolerance,
    20,
);

// The total light time is:
let total_light_time = rx_time.to_diff_raw(tx.time);

References

• Moyer, T.D. (2003). Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation. JPL DESCANSO Vol. 2, Section 8 (Light-Time Solution).
• IAU Resolution B1.5 (2000) and subsequent updates on relativistic reference systems and time scales.
• Ashby, N. (2003). “Relativity in the Global Positioning System”. Living Reviews in Relativity.

Notes

The solver uses simple fixed-point iteration. For most solar-system geometries, convergence occurs within 3–6 iterations. The function always returns a result. If max_iter is reached, the last computed values are returned. The returned ObserverState is guaranteed to be consistent with the final rx_time.

pub fn round_trip_relativistic_correction<RxF, TxF>( &self, rx_provider: RxF, tx_provider: TxF, shapiro: Dt, tolerance: Dt, max_iter: usize, ) -> Dt

where RxF: FnMut(Dt) -> ObserverState, TxF: FnMut(Dt) -> ObserverState,

Computes the total relativistic correction for a two-way round-trip ranging measurement.

This method solves the uplink and downlink legs independently using the iterative light-time solver. This is the modern approach recommended by Moyer (2003) and used by deep-space networks (DSN, ESA, JPL).

Solving the legs separately is more accurate than older combined round-trip formulas when the two ends are in different gravitational environments or have significantly different velocities.

The returned value must be subtracted from the raw measured round-trip time to recover the geometric light time.

Parameters

• rx_provider — Closure that returns the relativistic state of the remote body (planet, spacecraft, etc.) at a given coordinate time. Used for both the uplink solution and to obtain the accurate state at uplink arrival for the downlink leg.
• tx_provider — Closure that returns the relativistic state of the local transmitter at a given coordinate time (e.g. a moving ground station or another spacecraft). Used for the downlink leg.
• shapiro — Shapiro scale factor applied to both legs. Use Dt::SHAPIRO_SOLAR for normal solar-system work.
• tolerance — Convergence tolerance for the underlying iterative solver (recommended: Dt::from_ns(1, Scale::TAI)).
• max_iter — Maximum iterations per leg (typically 12–20).

Returns

The total relativistic correction for the complete round trip. This value should be subtracted from the observed round-trip time.

Examples

use deep_time::{Dt, Scale};

let tolerance = Dt::from_ns(1, Scale::TAI);

let correction = earth_station.round_trip_relativistic_correction(
    &mut |t| get_spacecraft_state(t),      // remote body
    &mut |t| get_earth_station_state(t),   // local transmitter
    Dt::SHAPIRO_SOLAR,
    tolerance,
    15,
);

// Geometric light time = measured_round_trip_time - correction

References

• Moyer, T.D. (2003). Formulation for Observed and Computed Values of Deep Space Network Data Types for Navigation. JPL DESCANSO Vol. 2, Sections 8 and 11 (Two-Way Light Time).
• IAU Resolution B1.5 (2000) and updates on relativistic reference systems.
• Modern DSN and ESA ranging implementations.

Notes

This method performs two independent iterative solutions. The downlink leg uses the precise receiver state obtained at the end of the uplink solution, ensuring consistency between the two legs.

The method is suitable for Earth–Mars, Jupiter, Kuiper Belt, and interstellar-class distances.

pub const fn shapiro_delay_to(&self, rx: ObserverState, shapiro: Dt) -> Dt

Computes only the gravitational (Shapiro) delay for a one-way signal.

This method returns the classical coordinate-time Shapiro delay caused by spacetime curvature near a central mass. It deliberately excludes any differential proper-time (clock-rate) correction.

Use this method when you need only the traditional relativistic propagation delay used in most deep-space navigation, ranging, and orbit determination systems (consistent with Moyer 2003 DSN formulations).

If you need both the Shapiro delay and the differential clock-rate correction, use Self::one_way_relativistic_delay instead.

Parameters

• rx — Receiver state at the approximate arrival time.
• shapiro — Shapiro scale factor. Use Dt::SHAPIRO_SOLAR for normal solar-system work or Dt::shapiro_from_grav_param for other central bodies. Pass Dt::ZERO to disable the Shapiro contribution.

Returns

The Shapiro delay (Dt) to be added to the Newtonian geometric light time.

Example

let shapiro_correction = transmitter.shapiro_delay_to(receiver_approx, Dt::SHAPIRO_SOLAR);

pub const fn compute_differential_clock_correction( &self, rx: ObserverState, ) -> Dt

Computes only the differential clock-rate correction between self (transmitter) and rx (receiver). Does not include any Shapiro delay.

Internal helper.

Trait Implementations

impl Clone for ObserverState

fn clone(&self) -> ObserverState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ObserverState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for ObserverState

fn eq(&self, other: &ObserverState) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for ObserverState

impl StructuralPartialEq for ObserverState