Struct LorentzTransform 

pub struct LorentzTransform { /* private fields */ }

Lorentz frame-boost transform for financial time series.

Applies the special-relativistic Lorentz transformation with velocity parameter beta = v/c to (t, x) coordinate pairs. The speed of light is normalized to c = 1.

Construction

use fin_stream::lorentz::LorentzTransform;

let lt = LorentzTransform::new(0.5).unwrap(); // beta = 0.5

Identity

beta = 0 is the identity: t' = t, x' = x.

Singularity avoidance

beta >= 1 would require dividing by zero in the Lorentz factor and is rejected at construction time with LorentzConfigError.

Implementations

impl LorentzTransform

pub fn new(beta: f64) -> Result<Self, StreamError>

Create a new Lorentz transform with the given velocity parameter.

beta must satisfy 0.0 <= beta < 1.0.

Errors

Returns LorentzConfigError if beta is negative, NaN, or >= 1.0.

pub fn from_rapidity(eta: f64) -> Result<Self, StreamError>

Construct a Lorentz transform from rapidity η = atanh(β).

Rapidity is the additive parameter for successive boosts along the same axis: composing two boosts η₁ and η₂ gives η₁ + η₂.

Errors

Returns StreamError::LorentzConfigError if eta is NaN, Inf, or results in |beta| >= 1.

pub fn from_velocity(v: f64, c: f64) -> Result<Self, StreamError>

Construct a LorentzTransform from a velocity v and speed of light c.

Computes beta = v / c and delegates to Self::new.

Errors

Returns StreamError::LorentzConfigError if c is zero, if v or c are non-finite, or if the resulting |beta| >= 1.

pub fn gamma_at(beta: f64) -> f64

Returns the Lorentz gamma factor for the given beta: 1 / √(1 − β²).

This is a pure mathematical helper — no validation is performed. Returns f64::INFINITY when beta == 1.0 and NaN when beta > 1.0.

pub fn relativistic_momentum(&self, mass: f64) -> f64

Relativistic momentum: m × γ × β (in natural units where c = 1).

Returns the momentum of a particle with rest mass mass moving at the velocity encoded in this transform. Negative mass is allowed for analytical purposes but physically meaningless.

pub fn kinetic_energy_ratio(&self) -> f64

Kinetic energy factor: γ − 1.

The relativistic kinetic energy is KE = (γ − 1) mc². This method returns the dimensionless factor γ − 1 so callers can multiply by mc² in their own units. Zero at rest (β = 0).

pub fn time_dilation_factor(&self) -> f64

Time dilation factor: γ (gamma).

Equivalent to gamma but named for clarity when used in a time-dilation context. A moving clock ticks slower by this factor relative to the stationary frame.

pub fn length_contraction_factor(&self) -> f64

Length contraction factor: L' = L / gamma.

The reciprocal of the Lorentz factor — always in (0.0, 1.0].

pub fn beta_from_gamma(gamma: f64) -> Result<f64, StreamError>

Computes beta (v/c) from a Lorentz gamma factor. Returns an error if gamma < 1.0.

pub fn rapidity(&self) -> f64

Rapidity: φ = atanh(β).

Unlike velocity, rapidities add linearly under boosts: φ_total = φ_1 + φ_2.

pub fn beta_times_gamma(&self) -> f64

Relativistic parameter β·γ — proportional to the particle’s 3-momentum.

Defined as β * γ = β / √(1 - β²). Useful for comparing relativistic momenta of different particles without specifying rest mass.

pub fn beta_from_rapidity(eta: f64) -> f64

Converts a rapidity value back to a velocity β = tanh(η).

This is the inverse of rapidity(). Always returns a value in (-1, 1).

pub fn proper_velocity(&self) -> f64

Proper velocity: w = β × γ.

Unlike coordinate velocity β, proper velocity is unbounded and equals the spatial displacement per unit proper time. Alias for beta_times_gamma.

pub fn beta(&self) -> f64

The configured velocity parameter beta = v/c.

pub fn gamma(&self) -> f64

The precomputed Lorentz factor gamma = 1 / sqrt(1 - beta^2).

gamma == 1.0 when beta == 0 (identity). gamma increases monotonically towards infinity as beta approaches 1.

pub fn transform(&self, p: SpacetimePoint) -> SpacetimePoint

Apply the Lorentz boost to a spacetime point.

Computes:

    t' = gamma * (t - beta * x)
    x' = gamma * (x - beta * t)

Complexity: O(1), no heap allocation.

pub fn inverse_transform(&self, p: SpacetimePoint) -> SpacetimePoint

Apply the inverse Lorentz boost (boost in the opposite direction).

Computes:

    t' = gamma * (t + beta * x)
    x' = gamma * (x + beta * t)

For a point p, inverse_transform(transform(p)) == p up to floating- point rounding.

Complexity: O(1), no heap allocation.

pub fn transform_batch(&self, points: &[SpacetimePoint]) -> Vec<SpacetimePoint>

Apply the boost to a batch of points.

Returns a new Vec of transformed points. The input slice is not modified.

Complexity: O(n), one heap allocation of size n.

pub fn inverse_transform_batch( &self, points: &[SpacetimePoint], ) -> Vec<SpacetimePoint>

Apply the inverse boost to a batch of points.

Equivalent to calling inverse_transform on each element. For any slice pts, inverse_transform_batch(&transform_batch(pts)) equals pts up to floating-point rounding.

Complexity: O(n), one heap allocation of size n.

pub fn dilate_time(&self, t: f64) -> f64

Time-dilation: the transformed time coordinate for a point at rest (x = 0) is t' = gamma * t.

This is a convenience method that surfaces the time-dilation formula for the common case where only the time axis is of interest.

Complexity: O(1)

pub fn contract_length(&self, x: f64) -> f64

Length-contraction: the transformed spatial coordinate for an event at the time origin (t = 0) is x' = gamma * x.

This is a convenience method that surfaces the length-contraction formula for the common case where only the price axis is of interest.

Complexity: O(1)

pub fn time_contraction(&self, coordinate_time: f64) -> f64

Proper time: coordinate_time / gamma.

The inverse of dilate_time. Converts a dilated coordinate time back to the proper time measured by a clock co-moving with the boosted frame — always shorter than the coordinate time by a factor of gamma.

Complexity: O(1)

pub fn is_ultrarelativistic(&self) -> bool

Returns true if this boost is ultrarelativistic (beta > 0.9).

At beta > 0.9 the Lorentz factor gamma > 2.3, and relativistic effects dominate. Useful as a sanity guard before applying the boost to financial time-series where very high velocities indicate data issues.

pub fn momentum_factor(&self) -> f64

Relativistic spatial momentum factor: gamma × beta.

This is the spatial component of the four-momentum (up to a mass factor). At beta = 0 the result is 0; as beta → 1 it diverges.

Complexity: O(1)

pub fn momentum(&self, mass: f64) -> f64

Relativistic momentum in natural units (c = 1): p = γ·m·β.

For a position-size analogy: mass represents a notional stake and beta represents velocity. The returned momentum scales that stake by the Lorentz factor, giving a measure of “relativistic commitment” that grows non-linearly as beta → 1.

Complexity: O(1)

pub fn relativistic_energy(&self, rest_mass: f64) -> f64

Relativistic total energy in natural units (c = 1): E = γ·m.

For rest_mass expressed in the same energy units as the result, this returns the total energy of a particle with that rest mass moving at the configured beta. At rest (beta = 0, gamma = 1) the result equals rest_mass.

pub fn kinetic_energy(&self, rest_mass: f64) -> f64

Relativistic kinetic energy in natural units (c = 1): (γ − 1) · m.

This is the total relativistic energy minus the rest energy, i.e. the work done to accelerate the particle from rest to beta. At rest (beta = 0, gamma = 1) the result is zero.

pub fn energy_momentum_invariant(&self, rest_mass: f64) -> f64

Lorentz invariant E² - p² for a particle with the given rest_mass.

In natural units (c = 1) this equals rest_mass² for any velocity, confirming that mass is a Lorentz scalar.

pub fn four_velocity_time(&self) -> f64

Time component of the four-velocity: u⁰ = γ.

In special relativity the four-velocity is (γ, γβ, 0, 0) (using the convention where c = 1). This returns the time component, which equals the Lorentz factor. At rest gamma = 1; as beta → 1 it diverges.

pub fn proper_time_dilation(&self, dt: f64) -> f64

Proper time dilation: the ratio of proper time elapsed in the moving frame to coordinate time dt elapsed in the rest frame.

proper_dt = dt / gamma — a moving clock runs slower.

pub fn spacetime_interval(p1: SpacetimePoint, p2: SpacetimePoint) -> f64

Computes the Lorentz-invariant spacetime interval between two events.

The interval is defined as ds² = (Δt)² - (Δx)² (signature +−). A positive result means the separation is time-like; negative means space-like; zero means light-like (the events could be connected by a photon).

This quantity is invariant under Lorentz boosts — apply(p1) and apply(p2) will yield the same interval as p1 and p2 directly.

Complexity: O(1)

pub fn velocity_addition(beta1: f64, beta2: f64) -> Result<f64, StreamError>

Relativistic velocity addition as a static helper.

Computes (beta1 + beta2) / (1 + beta1 * beta2) without constructing a full LorentzTransform. Useful when only the composed velocity is needed rather than the full transform object.

Errors

Returns StreamError::LorentzConfigError if either input is outside [0, 1) or if the composed velocity is >= 1.

pub fn proper_time(&self, coordinate_time: f64) -> f64

Proper time elapsed in the moving frame for a given coordinate time.

Returns coordinate_time / gamma. For beta = 0 (identity) this equals coordinate_time; as beta → 1 the proper time shrinks toward zero (time dilation).

Complexity: O(1)

pub fn inverse(&self) -> Self

Return a new LorentzTransform that boosts in the opposite direction.

If self has velocity beta, self.inverse() has velocity -beta. Applying self then self.inverse() is the identity transform.

This is equivalent to LorentzTransform::new(-self.beta) but avoids the error branch since negating a valid beta always produces a valid result.

Complexity: O(1)

pub fn time_dilation(&self, proper_time: f64) -> f64

👎Deprecated since 2.2.0:

Use dilate_time instead

Coordinate (lab-frame) time for a given proper time.

Alias for dilate_time.

pub fn compose(&self, other: &LorentzTransform) -> Result<Self, StreamError>

Compose two Lorentz boosts into a single equivalent boost.

Uses the relativistic velocity addition formula:

    beta_composed = (beta_1 + beta_2) / (1 + beta_1 * beta_2)

This is the physical law stating that applying boost self then boost other is equivalent to a single boost with the composed velocity.

Errors

Returns StreamError::LorentzConfigError if the composed velocity reaches or exceeds 1 (the speed of light), which cannot happen for valid inputs but is checked defensively.

pub fn boost_chain(betas: &[f64]) -> Result<Self, StreamError>

Compose a sequence of boosts into a single equivalent transform.

Applies compose left-to-right over betas, starting from the identity boost (beta = 0). An empty slice returns the identity.

Errors

Returns StreamError::LorentzConfigError if any beta is invalid or the accumulated velocity reaches the speed of light.

pub fn is_identity(&self) -> bool

Returns true if this transform is effectively the identity (beta ≈ 0).

The identity leaves spacetime coordinates unchanged: t' = t, x' = x. Uses a tolerance of 1e-10.

pub fn composition(&self, other: &Self) -> Result<Self, StreamError>

Relativistic composition of two boosts (Einstein velocity addition).

The composed transform moves at β = (β₁ + β₂) / (1 + β₁β₂), which is equivalent to adding rapidities: tanh⁻¹(β_composed) = tanh⁻¹(β₁) + tanh⁻¹(β₂).

Errors

Returns StreamError::LorentzConfigError if the composed beta reaches or exceeds the speed of light (should not happen for valid sub-luminal inputs).

pub fn doppler_factor(&self) -> f64

👎Deprecated since 2.2.0:

Use doppler_ratio instead

Relativistic Doppler factor for a source moving toward the observer at β.

D = √((1 + β) / (1 − β)). Alias for doppler_ratio.

pub fn aberration_angle(&self, cos_theta: f64) -> f64

Relativistic aberration angle for a light ray with direction cosine cos_theta.

Computes the observed angle using cos θ' = (cos θ + β) / (1 + β cos θ), returning the aberrated angle in radians in [0, π].

pub fn relativistic_mass(&self, rest_mass: f64) -> f64

👎Deprecated since 2.2.0:

Use relativistic_energy instead

Relativistic mass for a particle with rest_mass moving at β.

m = rest_mass × γ. Alias for relativistic_energy in natural units (c = 1).

pub fn energy_ratio(&self) -> f64

👎Deprecated since 2.2.0:

Use kinetic_energy_ratio instead

Ratio of kinetic energy to rest energy: γ - 1.

Alias for kinetic_energy_ratio.

pub fn warp_factor(&self) -> f64

Warp factor in the Star Trek convention: w = γ^(1/3).

A pure curiosity / educational mapping; warp 1 corresponds to β = 0 (rest), and higher warp values correspond to higher Lorentz factors.

pub fn four_momentum(&self, mass: f64) -> (f64, f64)

Four-momentum (E, p) in natural units (c = 1).

Returns (γ·mass, γ·mass·β) where the first component is the relativistic energy and the second is the relativistic momentum magnitude.

pub fn momentum_ratio(&self) -> f64

👎Deprecated since 2.2.0:

Use beta_times_gamma instead

Relativistic momentum per unit rest mass: γ × β.

Alias for beta_times_gamma.

pub fn is_ultra_relativistic(&self) -> bool

👎Deprecated since 2.2.0:

Use is_ultrarelativistic instead

Returns true if β > 0.9, the conventional ultra-relativistic threshold.

Alias for is_ultrarelativistic.

pub fn lorentz_factor_approx(&self) -> f64

First-order Taylor approximation of γ valid for small β: 1 + β²/2.

Accurate to ~0.1% for β < 0.1; diverges significantly above β ≈ 0.4.

pub fn velocity_ratio(&self, other: &Self) -> f64

Ratio of this transform’s β to another’s: self.beta / other.beta.

Returns f64::INFINITY if other.beta is zero and self.beta > 0, and f64::NAN if both are zero.

pub fn proper_length(&self, observed: f64) -> f64

Proper length from an observed (length-contracted) length: observed * gamma.

Inverse of length contraction: recovers the rest-frame length from an observed measurement made in the moving frame.

pub fn length_contraction(&self, rest_length: f64) -> f64

Observed (length-contracted) length given a rest_length: rest_length / gamma.

A moving object of rest length L₀ appears shortened to L₀ / γ in the observer frame.

pub fn light_cone_check(dt: f64, dx: f64) -> &'static str

Classifies a spacetime interval (dt, dx) as "timelike", "lightlike", or "spacelike".

Spacetime interval: s² = dt² - dx² (in natural units, c = 1).

• s² > 0 → timelike (causally connected)
• s² = 0 → lightlike (on the light cone)
• s² < 0 → spacelike (causally disconnected)

pub fn lorentz_invariant_mass(energy: f64, momentum: f64) -> Option<f64>

Lorentz-invariant rest mass from energy and momentum: m = sqrt(E² - p²).

In natural units (c = 1). Returns None if E² < p² (unphysical configuration).

pub fn aberration_correction(&self, cos_theta: f64) -> Option<f64>

Relativistic aberration: corrected cosine of angle when viewed from boosted frame.

cos_theta' = (cos_theta - beta) / (1 - beta * cos_theta). Returns None if the denominator is zero (numerically degenerate case).

pub fn doppler_ratio(&self) -> f64

Relativistic Doppler ratio: sqrt((1 + beta) / (1 - beta)).

Values > 1 represent blue-shift (approaching); < 1 red-shift (receding). At rest (beta = 0) returns 1.0.

pub fn time_dilation_ms(&self, proper_ms: f64) -> f64

Dilated coordinate time in milliseconds for a given proper time proper_ms.

t_coordinate = gamma * t_proper. A moving clock ticks slower by factor γ.

pub fn space_contraction(&self, proper_length: f64) -> f64

👎Deprecated since 2.2.0:

Use length_contraction instead

Length contraction: contracted length for a given proper (rest-frame) length.

Alias for length_contraction.

pub fn proper_acceleration(&self, force: f64, mass: f64) -> Option<f64>

Relativistic proper acceleration for a given coordinate force and rest mass.

a = F / (gamma^3 * m) — coordinate acceleration decreases as gamma grows. Returns None if mass is zero.

pub fn momentum_rapidity(&self) -> f64

Relativistic momentum proxy: gamma * beta (natural units, rest mass = 1).

Spatial component of the four-velocity; additive in rapidity space.

pub fn inverse_gamma(&self) -> f64

Inverse Lorentz factor: 1 / gamma.

Equals sqrt(1 - beta^2). Approaches 1 at low speeds; 0 at light speed.

pub fn boost_composition(beta1: f64, beta2: f64) -> Result<f64, StreamError>

Compose two collinear boosts: beta_total = (beta1 + beta2) / (1 + beta1*beta2).

Returns the combined beta from relativistic velocity addition. Returns Err if the result would equal or exceed c (|beta| >= 1).

Trait Implementations

impl Clone for LorentzTransform

fn clone(&self) -> LorentzTransform

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LorentzTransform

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

Formats the value using the given formatter.

impl Copy for LorentzTransform