Crate use_relativity

Expand description

§use-relativity

Small special relativity scalar helpers for RustUse.

§Install

[dependencies]
use-relativity = "0.0.1"

§Foundation

use-relativity provides small special relativity scalar helpers for Lorentz factor, time dilation, length contraction, mass-energy relations, relativistic momentum, rapidity, velocity addition, and simple longitudinal Doppler calculations.

Inputs are expected to be SI-style numeric values:

meters per second for speed and velocity
seconds for time
meters for length
kilograms for mass
joules for energy
kilogram meters per second for momentum
hertz for frequency

Positive beta in the Doppler helpers means the source is approaching the observer.

This crate keeps SPEED_OF_LIGHT locally for convenience. Broader physical constants belong in the top-level use-constants set.

Unit abstractions belong in the top-level use-units set.

§Example

use use_relativity::{RelativisticBody, SPEED_OF_LIGHT, beta, dilated_time, velocity_addition};

assert_eq!(beta(SPEED_OF_LIGHT * 0.5), Some(0.5));
assert!((dilated_time(10.0, SPEED_OF_LIGHT * 0.6).unwrap() - 12.5).abs() < 1.0e-12);
assert!((velocity_addition(SPEED_OF_LIGHT * 0.5, SPEED_OF_LIGHT * 0.5).unwrap()
    - (SPEED_OF_LIGHT * 0.8))
    .abs()
    < 1.0e-3);

let body = RelativisticBody::new(1.0, SPEED_OF_LIGHT * 0.6).unwrap();

assert!(body.total_energy().unwrap() > body.rest_energy().unwrap());

§When to use directly

Choose use-relativity when you need small scalar special relativity helpers without a full unit, geometry, or simulation system.

§Scope

APIs stay f64-first and focus on scalar special relativity helpers.
General relativity, tensor calculus, curved spacetime, and numerical simulation are out of scope.
Full constants systems and unit abstractions belong in use-constants and use-units.

§Status

use-relativity is a pre-1.0 crate with a deliberately small API. Small special relativity scalar helpers.

Modules§

prelude: Re-exports for ergonomic glob imports.

Structs§

RelativisticBody: A body with scalar rest mass and signed velocity.

Constants§

SPEED_OF_LIGHT: Speed of light in vacuum, in meters per second.

Functions§

beta: Computes the dimensionless speed ratio β = v / c.
beta_from_rapidity: Computes β = tanh(φ) from rapidity.
contracted_length: Computes contracted length L = L0 / γ from proper length L0.
dilated_time: Computes dilated coordinate time t = γτ from proper time τ.
doppler_factor_longitudinal_from_beta: Computes the longitudinal relativistic Doppler factor D = sqrt((1 + β) / (1 - β)).
energy_momentum_relation: Computes total energy from rest mass and momentum using E = sqrt((pc)² + (mc²)²).
is_subluminal_speed: Returns true when speed is finite, non-negative, and strictly less than the speed of light.
lorentz_factor: Computes the Lorentz factor γ from a speed magnitude in meters per second.
lorentz_factor_from_beta: Computes the Lorentz factor γ = 1 / sqrt(1 - β²) from a non-negative beta magnitude.
mass_from_rest_energy: Computes rest mass m = E0 / c² from rest energy in joules.
observed_frequency_longitudinal: Computes observed longitudinal Doppler-shifted frequency f_observed = f_emitted * D.
proper_length: Computes proper length L0 = Lγ from a contracted length L.
proper_time: Computes proper time τ = t / γ from dilated coordinate time t.
rapidity_from_beta: Computes rapidity φ = atanh(β) from a signed beta.
relativistic_kinetic_energy: Computes relativistic kinetic energy KE = (γ - 1)mc² in joules.
relativistic_momentum: Computes relativistic momentum p = γmv.
rest_energy: Computes rest energy E0 = mc² in joules.
rest_mass_from_momentum_speed: Computes rest mass from relativistic momentum and velocity using m = p / (γv).
speed_from_beta: Computes the speed magnitude v = βc in meters per second.
speed_from_rapidity: Computes signed velocity v = c * tanh(φ) from rapidity.
total_energy: Computes total relativistic energy E = γmc² in joules.
velocity_addition: Computes relativistic velocity addition u = (v + w) / (1 + vw / c²).