Struct ClockDrift 

pub struct ClockDrift { /* private fields */ }

Quadratic polynomial that describes the accumulated difference between an observer’s proper time (the time measured by a real clock moving through spacetime) and a chosen coordinate time such as TT, TAI, or any other Scale.

The polynomial follows the classic form
Δt = constant + rate·Δt + accel·(Δt)²
where the three coefficients capture any fixed offset, constant drift, and quadratic acceleration of the clock. This structure is used throughout spacecraft navigation, GNSS systems, and relativistic timing pipelines to steer clocks, predict time offsets, and maintain synchronization over long durations.

All three coefficients are stored using the exact TSpan type, which guarantees 36-digit precision with no floating-point rounding errors even over centuries of integration.

Implementations

impl ClockDrift

pub const ZERO: Self

The zero polynomial representing no correction at all.
Use this when the observer’s clock is already perfectly synchronized with the chosen coordinate time.

pub const fn new(constant: TSpan, rate: TSpan, accel: TSpan) -> Self

Creates a new ClockDrift polynomial from its three exact coefficients.

pub const fn from_constant(c: TSpan) -> Self

Creates a ClockDrift consisting of a pure constant offset.
This is the most common constructor when only a fixed time bias is known (for example, after a one-time clock synchronization or leap-second adjustment).

pub const fn from_offset_and_rate(offset: TSpan, rate: TSpan) -> Self

Creates a ClockDrift consisting of a constant offset together with a constant linear drift rate.
This form is very common for GNSS receivers and spacecraft clock steering, where a steady fractional frequency offset must be corrected in addition to any fixed bias.

pub const fn constant(&self) -> &TSpan

pub const fn rate(&self) -> &TSpan

pub const fn accel(&self) -> &TSpan

pub const fn set_constant(&mut self, constant: TSpan) -> &mut Self

pub const fn set_rate(&mut self, rate: TSpan) -> &mut Self

pub const fn set_accel(&mut self, accel: TSpan) -> &mut Self

pub const fn with_constant(self, constant: TSpan) -> Self

pub const fn with_rate(self, rate: TSpan) -> Self

pub const fn with_accel(self, accel: TSpan) -> Self

pub const fn proper_time_rate(&self) -> Real

Returns the instantaneous proper-time rate dτ/dt (dimensionless).

This value tells you how fast a real physical clock (such as a spacecraft onboard clock) is advancing compared to coordinate time. A value of exactly 1.0 means the clock runs at the normal rate. Values slightly below 1.0 are typical when the clock is moving or sitting in a gravitational well.

The rate includes special-relativistic velocity effects, gravitational time dilation, and the library’s built-in Planck-scale saturation term.

pub const fn time_diff_after(&self, span: &TSpan) -> TSpan

Evaluates the polynomial at the given elapsed coordinate time span.

Returns the exact accumulated time difference (in seconds) between proper time and coordinate time after the interval span has passed. All arithmetic is performed with full 36-digit precision, ensuring no loss of accuracy even for multi-year integrations.

pub const fn from_velocity_potential_and_scale( velocity_m_s: Real, grav_potential_m2_s2: Real, characteristic_length_scale: Real, ) -> Self

Creates a ClockDrift directly from an observer’s velocity and total local gravitational potential using the library’s unified master-Lagrangian proper-time rate.

This is the recommended high-level constructor for nearly all users. It automatically computes the relativistic clock rate that includes both special-relativistic velocity effects and gravitational time dilation, then returns a ClockDrift that can be evaluated at any future time.

The characteristic_length_scale parameter controls whether the weak-field or strong-field formulation is used:

• In the weak-field regime (where |Φ|/c² ≪ 1), simply pass characteristic_length_scale = 0.0. This returns exactly the same relativistic clock rate used by JPL, ESA, GNSS systems, and all modern solar-system navigation pipelines.
• In strong-field conditions, supply a non-zero length scale (in meters) over which the gravitational potential changes at the observer’s location. This activates the library’s intrinsic Planck-scale saturation term when spacetime curvature becomes extreme.

pub const fn from_unified_proper_time_rate(u: Real, kretschmann: Real) -> Self

Canonical low-level constructor that implements the exact intrinsic expression from the master Lagrangian.

This function is the single source of truth for the proper-time rate calculation used throughout the library. Most users will never call it directly; the high-level constructors from_velocity_potential_and_scale and from_local_spacetime are the intended entry points.

The internal expression is
K_eff = [δ(1 + x) + x(1−δ)²] / (1 + x)
where δ = α²(1−β²) and x = ℓ_Pl⁴ 𝒦. The returned rate offset is then applied as a linear term in the ClockDrift polynomial.

pub const fn from_local_spacetime(spacetime: &LocalSpacetime) -> Self

Creates a ClockDrift from a fully resolved LocalSpacetime snapshot.

This is the canonical high-level entry point when you already hold a LocalSpacetime object containing the gravitational lapse factor α, the local velocity β, and the Kretschmann scalar. It internally computes the unified proper-time rate and packages the result as a ClockDrift polynomial ready for evaluation at any future time.

Trait Implementations

impl Clone for ClockDrift

fn clone(&self) -> ClockDrift

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClockDrift

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

Formats the value using the given formatter.

impl Hash for ClockDrift

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for ClockDrift

fn cmp(&self, other: &ClockDrift) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for ClockDrift

fn eq(&self, other: &ClockDrift) -> 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 PartialOrd for ClockDrift

fn partial_cmp(&self, other: &ClockDrift) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for ClockDrift

impl Eq for ClockDrift

impl StructuralPartialEq for ClockDrift