pub struct Spacetime {
pub alpha: Real,
pub beta: Real,
pub kretschmann: Real,
}Expand description
Snapshot of the local quantities that set a clock’s rate (d\tau/dt).
Think of this as “how gravity and motion look right here, right now” for a clock:
- α — gravitational redshift factor (deeper in a well → smaller α → slower clocks).
- β — speed as a fraction of light speed ((v/c)).
- kretschmann — a curvature measure; leave at
0.0for almost all Earth/solar-system work.
Trajectory APIs either take Spacetime samples directly, or build them
from velocity and potential via
Spacetime::from_potential_velocity_and_scale.
Instantaneous rate: Spacetime::proper_time_rate.
Fields§
§alpha: RealGravitational lapse (redshift) factor α.
Clocks run slower where gravity is stronger: α < 1 in a potential well. In the weak field, α ≈ √(1 + 2Φ/c²) with Φ < 0.
beta: RealLocal three-velocity β = v/c in the coordinate rest frame used for the analysis.
kretschmann: RealKretschmann scalar (curvature invariant), in geometric units of the model.
For solar-system, GNSS, and similar work leave this 0.0 — the
curvature correction is negligible. Non-zero values matter only in
extreme gravity (near compact objects), where you may estimate K from
potential and a length scale (see
Spacetime::kretschmann_from_potential_and_scale) or supply K from a
metric.
Implementations§
Source§impl Spacetime
impl Spacetime
pub const fn new(alpha: Real, beta: Real, kretschmann: Real) -> Spacetime
Sourcepub const fn proper_time_rate(&self) -> Real
pub const fn proper_time_rate(&self) -> Real
Instantaneous proper-time rate (d\tau/dt) for this snapshot.
Dimensionless: 1.0 means the clock tracks coordinate time; values a
little below 1.0 are typical when moving or sitting in a gravitational
well. Same calculation as Drift::proper_time_rate after
Drift::from_spacetime.
Sourcepub const fn from_gravitic_and_velocity(
alpha: Real,
velocity: Velocity,
kretschmann: Real,
) -> Spacetime
pub const fn from_gravitic_and_velocity( alpha: Real, velocity: Velocity, kretschmann: Real, ) -> Spacetime
Build from lapse α, a velocity vector, and Kretschmann K.
Sets β from Velocity::beta. Pass kretschmann = 0.0 for ordinary
weak-field work.
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
Weak-field lapse from dimensionless potential: α = √(1 + 2Φ/c²).
Given how deep you are in a gravity well (as Φ/c²), return the factor by which clocks run slow. Φ is negative for bound gravity, so α < 1.
§Validity
Good when |Φ|/c² ≪ 1 (Earth, solar system, most spacecraft). Not
sufficient alone near neutron stars or black holes (|Φ|/c² ≳ 0.1); then
you need a strong-field metric treatment and usually a non-zero
Kretschmann on Spacetime.
§Note on units
Argument is Φ/c² (dimensionless), not Φ in m²/s². Trajectory
*_from_states APIs take SI Φ and divide by (c^2) for you.
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
Estimate Kretschmann scalar (\mathcal{K} \approx 48,\phi^2 / L^4).
Optional helper to guess curvature from potential strength and a length
scale. For normal flight timing you do not need this: pass
characteristic_length_scale = 0.0 and get K = 0.
§Parameters
grav_potential_over_c2— Φ/c² (typically negative). The estimate uses φ², so the sign of φ does not matter for K.characteristic_length_scale— meters. Use0.0to disable (recommended default). A positive L is a curvature scale; for a single spherical mass the Schwarzschild match is L = r with |φ| = GM/(c² r). L cannot be recovered from φ alone in general.
Background: relativity model.
Sourcepub const fn from_potential_velocity_and_scale(
grav_potential_over_c2: Real,
velocity: Velocity,
characteristic_length_scale: Real,
) -> Spacetime
pub const fn from_potential_velocity_and_scale( grav_potential_over_c2: Real, velocity: Velocity, characteristic_length_scale: Real, ) -> Spacetime
Build Spacetime from dimensionless potential Φ/c², velocity, and length scale.
Turn “how deep in the well” and “how fast I’m moving” into the α, β, K snapshot used for clock rates.
§Parameters
grav_potential_over_c2— Φ/c² (dimensionless), not SI Φ.velocity— m/s; only speed enters (via β).characteristic_length_scale— pass0.0for solar-system / GNSS work (K = 0). Positive L only if you want the optional K estimate.
For SI potential (m²/s²), divide by (c^2) first, or use trajectory
proper_time_*_from_states which does that conversion.
Weak-field α is valid for |Φ|/c² ≪ 1. Strong gravity needs more than this constructor alone.
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
Newtonian point-mass potential Φ = −Σ GMᵢ / rᵢ at a position (m²/s²).
Sums “how much gravity well” you feel from a list of bodies treated as
point masses. The result is negative near masses. Use it to build
samples for trajectory proper-time APIs, or convert to α via
Φ/c² and Spacetime::alpha_from_weak_field_potential.
§Limits
Point masses only — no Earth (J_2), no tides, no extended bodies. Fine for rough multi-body Φ or cislunar order-of-magnitude work; LEO-grade timing usually needs multipoles from a full gravity model.
Body positions and the evaluation point must share the same coordinate frame.
§Example
use deep_time::{Position, Spacetime};
let bodies = [
(Position::from_au(0.0, 0.0, 0.0), 1.3271244e20), // Sun GM
(Position::from_au(1.0, 0.0, 0.0), 3.9860044e14), // Earth GM
(Position::from_au(1.00257, 0.0, 0.0), 4.9048695e12), // Moon GM
];
let position = Position::from_au(1.001, 0.001, 0.0);
let phi = Spacetime::grav_potential_from_point_masses(
&position,
bodies.iter().cloned(),
);
assert!(phi < 0.0);