Struct LocalSpacetime 

pub struct LocalSpacetime {
    pub alpha: Real,
    pub beta: Real,
    pub kretschmann: Real,
}

The three local spacetime quantities that fully determine how fast an observer’s proper time advances relative to coordinate time.

This structure holds the gravitational lapse factor, the observer’s local velocity, and the curvature information needed for the library’s unified proper-time model. It is the low-level input that ClockDrift uses internally.

Fields

alpha: Real

Gravitational lapse (redshift) factor α.
This is the factor by which clocks run slower in a gravitational potential.

beta: Real

Local three-velocity β = v/c measured in the coordinate rest frame.

kretschmann: Real

Kretschmann scalar (a scalar measure of spacetime curvature).
In the weak-field regime — where |Φ|/c² ≪ 1 and the gravitational field varies over macroscopic distances — this value is effectively zero and can safely be left at its default. It only becomes numerically relevant in strong-field environments such as:

• the surface or immediate vicinity of neutron stars (where |Φ|/c² ≈ 0.15–0.25);
• regions near a black-hole event horizon (e.g. the photon rings imaged by the Event Horizon Telescope around M87* or Sgr A*);
• the final inspiral and merger phases of binary neutron-star or black-hole systems (as observed by LIGO/Virgo in events such as GW170817 or GW150914).

In these regimes a realistic non-zero value (estimated from the local potential and a characteristic length scale) activates the library’s intrinsic Planck-scale saturation term.

Implementations

impl LocalSpacetime

pub const fn new(alpha: Real, beta: Real, kretschmann: Real) -> Self

pub const fn proper_time_rate(self) -> Real

Returns the instantaneous proper-time rate dτ/dt from this snapshot.

Convenience method that internally uses the same unified calculation as ClockDrift::proper_time_rate.

pub const fn from_gravitic_and_velocity( alpha: Real, velocity: Velocity, kretschmann: Real, ) -> Self

Convenience for direct gravimeter / sensor paths.

pub const fn alpha_from_weak_field_potential( grav_potential_over_c2: Real, ) -> Real

Converts the Newtonian gravitational potential Φ/c² (where Φ < 0 for bound orbits) into the relativistic lapse factor α = √(1 + 2Φ/c²).

This function implements the standard weak-field approximation used in general relativity. It is valid when the dimensionless gravitational potential satisfies |Φ|/c² ≪ 1. In this regime spacetime is nearly flat, gravitational time dilation is a small perturbation, and higher-order curvature effects can safely be neglected. The resulting α gives the factor by which clocks tick more slowly in a gravitational well relative to a distant reference clock.

This approximation is excellent for solar-system navigation, GNSS satellites, most spacecraft operations, and any environment where |Φ|/c² remains much smaller than ~0.01. It is exported from deep_time::alpha_from_weak_field_potential and is the recommended way to obtain the lapse factor when you have the local Newtonian potential.

The weak-field regime breaks down in strong-gravity environments where |Φ|/c² approaches or exceeds ~0.1. Such conditions occur near:

• the surface or immediate vicinity of neutron stars (where |Φ|/c² ≈ 0.15–0.25);
• regions near a black-hole event horizon (e.g. the photon rings imaged by the Event Horizon Telescope around M87* or Sgr A*);
• the final inspiral and merger phases of binary neutron-star or black-hole systems (as observed by LIGO/Virgo in events such as GW170817 or GW150914).

In those extreme regimes this function alone is no longer sufficient; a full strong-field treatment (including curvature information passed to LocalSpacetime) is required.

pub const fn kretschmann_from_potential_and_scale( grav_potential_over_c2: Real, characteristic_length_scale: Real, ) -> Real

Kretschmann scalar from total relativity Computes the Kretschmann scalar (\mathcal{K}) from the total gravitational relativity experienced by a local observer at the observer’s spacetime point.

This is the canonical, physics-true convenience function for the master Lagrangian. It uses:

• phi = Φ/c² — the total local gravitational potential (redshift/gravity effect) felt by the observer from all masses.
• characteristic_length_scale — the typical length scale (in meters) over which the gravitational field varies at the observer’s location.

For existing weak-field users (Earth orbit, GNSS, solar-system navigation): Supply your existing phi value and set characteristic_length_scale = 0.0. The function safely returns 0.0 (the correct value in double precision).

For strong-field / future users (black-hole flybys, neutron stars, direct gravimeters, or full metric evaluation): Supply the measured or computed (\phi) and the real local length scale (or the value from your metric). The function returns a physically accurate non-zero curvature.

pub const fn from_potential_velocity_and_scale( grav_potential_over_c2: Real, velocity: Velocity, characteristic_length_scale: Real, ) -> Self

Recommended constructor for most users.

Computes both the gravitational lapse factor α and an estimate of the Kretschmann scalar from the dimensionless gravitational potential Φ/c² and a characteristic length scale.

The lapse factor α is computed using alpha_from_weak_field_potential, which is the standard weak-field expression α = √(1 + 2Φ/c²). It is valid when the dimensionless gravitational potential satisfies |Φ|/c² ≪ 1. In this regime spacetime is nearly flat, gravitational time dilation is a small perturbation, and higher-order curvature effects can safely be neglected. The resulting α gives the factor by which clocks tick more slowly in a gravitational well relative to a distant reference clock.

This approximation is excellent for solar-system navigation, GNSS satellites, most spacecraft operations, and any environment where |Φ|/c² remains much smaller than ~0.01. It is exported from deep_time::alpha_from_weak_field_potential and is the recommended way to obtain the lapse factor when you have the local Newtonian potential.

The weak-field regime breaks down in strong-gravity environments where |Φ|/c² approaches or exceeds ~0.1. Such conditions occur near:

• the surface or immediate vicinity of neutron stars (where |Φ|/c² ≈ 0.15–0.25);
• regions near a black-hole event horizon (e.g. the photon rings imaged by the Event Horizon Telescope around M87* or Sgr A*);
• the final inspiral and merger phases of binary neutron-star or black-hole systems (as observed by LIGO/Virgo in events such as GW170817 or GW150914).

In those extreme regimes this function alone is no longer sufficient; a full strong-field treatment (including curvature information passed to LocalSpacetime) is required.

For the characteristic_length_scale parameter:

• In weak-field conditions, pass 0.0. This returns exactly the same clock rate as the classic relativistic formulation and sets the Kretschmann scalar to zero (its default value for all ordinary navigation, GNSS, or solar-system work).
• In strong-field conditions, supply the typical length scale (in meters) over which the gravitational field varies significantly at the observer’s location. This allows the library to estimate the Kretschmann scalar and activate the intrinsic Planck-scale saturation term when curvature becomes extreme.

Trait Implementations

impl Clone for LocalSpacetime

fn clone(&self) -> LocalSpacetime

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LocalSpacetime

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

Formats the value using the given formatter.

impl PartialEq for LocalSpacetime

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

impl StructuralPartialEq for LocalSpacetime