pub struct Spacetime {
pub alpha: Real,
pub beta: Real,
pub kretschmann: Real,
}Expand description
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 Drift uses internally.
Fields§
§alpha: RealGravitational lapse (redshift) factor α.
This is the factor by which clocks run slower in a gravitational potential.
beta: RealLocal three-velocity β = v/c measured in the coordinate rest frame.
kretschmann: RealKretschmann 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§
Source§impl Spacetime
impl Spacetime
Sourcepub fn to_wire_bytes(&self) -> [u8; 24]
pub fn to_wire_bytes(&self) -> [u8; 24]
Serializes this Spacetime snapshot into a fixed 24-byte buffer.
All fields are stored as little-endian IEEE 754 f64.
Sourcepub fn from_wire_bytes(bytes: &[u8]) -> Option<Self>
pub fn from_wire_bytes(bytes: &[u8]) -> Option<Self>
Deserializes a Spacetime from exactly 24 bytes.
§Security
Accepts any f64 bit pattern (including NaN/Inf) to match the
type’s own invariants. Fixed size makes it immune to length-based
attacks. Safe for untrusted input.
Source§impl Spacetime
impl Spacetime
pub const fn new(alpha: Real, beta: Real, kretschmann: Real) -> Self
Sourcepub const fn proper_time_rate(&self) -> Real
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
Drift::proper_time_rate.
Sourcepub const fn from_gravitic_and_velocity(
alpha: Real,
velocity: Velocity,
kretschmann: Real,
) -> Self
pub const fn from_gravitic_and_velocity( alpha: Real, velocity: Velocity, kretschmann: Real, ) -> Self
Convenience for direct gravimeter / sensor paths.
Sourcepub const fn alpha_from_weak_field_potential(
grav_potential_over_c2: Real,
) -> Real
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 Spacetime)
is required.
Sourcepub const fn kretschmann_from_potential_and_scale(
grav_potential_over_c2: Real,
characteristic_length_scale: Real,
) -> Real
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.
Sourcepub const fn from_potential_velocity_and_scale(
grav_potential_over_c2: Real,
velocity: Velocity,
characteristic_length_scale: Real,
) -> Self
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 Spacetime)
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.
Sourcepub const fn grav_potential_from_alpha(alpha: Real) -> Real
pub const fn grav_potential_from_alpha(alpha: Real) -> Real
Recovers the Newtonian gravitational potential Φ (m²/s²) from the gravitational lapse factor α using the weak-field relation.
[ \alpha = \sqrt{1 + \frac{2\Phi}{c^2}} \quad\implies\quad \Phi = \frac{c^2}{2}(\alpha^2 - 1) ]
This is the inverse of Spacetime::alpha_from_weak_field_potential.
Sourcepub fn grav_potential_from_point_masses<I>(
position: Position,
bodies: I,
) -> Real
pub fn grav_potential_from_point_masses<I>( position: Position, bodies: I, ) -> Real
Computes the total Newtonian gravitational potential Φ at a given position from an arbitrary collection of point-mass bodies (Sun, Earth, Moon, planets, asteroids, etc.).
This is the standard method used by real mission planners (Apollo, Artemis, Mars orbiters, lunar landers) and in open-source astrodynamics libraries (SPICE/NAIF, Orekit, GMAT, poliastro). It evaluates
[ \Phi = -\sum_i \frac{GM_i}{r_i} ]
§Example (realistic cislunar trajectory)
use deep_time::{Position, Spacetime};
let bodies = [
(Position::from_au(0.0, 0.0, 0.0), 1.3271244e20), // Sun
(Position::from_au(1.0, 0.0, 0.0), 3.9860044e14), // Earth
(Position::from_au(1.00257, 0.0, 0.0), 4.9048695e12), // Moon
];
let position = Position::from_au(1.001, 0.001, 0.0); // e.g. spacecraft, asteroid, etc.
let phi = Spacetime::grav_potential_from_point_masses(
position,
bodies.iter().copied(),
);