Amari Relativistic Physics Library

A comprehensive Rust library for relativistic physics simulations using geometric algebra, designed for charged particle simulations and plasma physics applications involving particle trajectories through curved spacetime.

Overview

This crate leverages the geometric algebra (Clifford algebra) framework from amari-core to provide a mathematically rigorous foundation for relativistic physics calculations. It implements spacetime algebra (STA) for four-dimensional spacetime, geodesic integration for curved spacetime, and relativistic particle dynamics.

Key Features

• Spacetime Algebra: Four-vectors, Lorentz transformations using geometric algebra
• Geodesic Integration: Numerical integration of Einstein's geodesic equation
• Schwarzschild Metric: Spacetime around spherically symmetric masses
• Relativistic Particles: Energy-momentum relations, proper time evolution
• Charged Particle Applications: Ion beam trajectories, particle deflection

Mathematical Foundation

The library is built on spacetime algebra Cl(1,3) with signature (+---):

• γ₀² = +1 (timelike basis vector)
• γ₁², γ₂², γ₃² = -1 (spacelike basis vectors)
• Four-vectors: X = ctγ₀ + xγ₁ + yγ₂ + zγ₃
• Minkowski inner product: X·Y = X₀Y₀ - X₁Y₁ - X₂Y₂ - X₃Y₃

Example Usage

Basic Charged Particle Trajectory Simulation

use amari_relativistic::*;
use nalgebra::Vector3;

// Create gravitational field from massive object
let massive_object = schwarzschild::SchwarzschildMetric::sun();
let mut integrator = geodesic::GeodesicIntegrator::with_metric(Box::new(massive_object));

// Create 100 keV iron ion in strong gravitational field
let position = Vector3::new(2e11, 0.0, 0.0); // Distance from center
let direction = Vector3::new(-1.0, 0.0, 0.1); // Initial trajectory
let mut ion = particle::RelativisticParticle::with_energy(
    position,
    direction,
    100e3 * constants::E_CHARGE, // 100 keV
    55.845 * constants::AMU,     // Iron mass
    constants::E_CHARGE,         // Singly ionized
)?;

// Propagate through gravitational field
let trajectory = particle::propagate_relativistic(
    &mut ion,
    &mut integrator,
    30.0 * 86400.0,  // Integration time
    100.0,            // Time step size
)?;

println!("Final position: {:?}", ion.position_3d());
println!("Deflection: {:.2e} m",
         trajectory.last().unwrap().1.magnitude() - position.magnitude());

Light Deflection by Massive Objects

use amari_relativistic::*;

// Calculate light deflection for photon grazing massive object surface
let object_radius = 6.957e8; // meters
let deflection_angle = particle::light_deflection_angle(
    object_radius,
    constants::SOLAR_MASS
);

// Convert to arcseconds
let arcseconds = deflection_angle * 180.0 * 3600.0 / std::f64::consts::PI;
println!("Light deflection: {:.2} arcseconds", arcseconds);
// Expected: ~1.75 arcseconds (Einstein's prediction)

Four-Velocity and Spacetime Intervals

use amari_relativistic::spacetime::*;
use amari_relativistic::constants;
use nalgebra::Vector3;

// Create relativistic four-velocity
let velocity = Vector3::new(0.8 * constants::C, 0.0, 0.0); // 0.8c
let four_vel = FourVelocity::from_velocity(velocity);

println!("Lorentz factor γ = {:.3}", four_vel.gamma());
println!("Rapidity φ = {:.3}", four_vel.rapidity());

// Spacetime interval between events
let event1 = SpacetimeVector::new(0.0, 0.0, 0.0, 0.0);
let event2 = SpacetimeVector::new(1.0, 0.5 * constants::C, 0.0, 0.0);
let interval = event1.minkowski_dot(&event2);

if interval > 0.0 {
    println!("Timelike separation: Δτ = {:.6} s",
             interval.sqrt() / constants::C);
}

High-Precision Arithmetic for Spacecraft Orbital Mechanics

When precision is critical for spacecraft missions, use high-precision arithmetic:

use amari_relativistic::prelude::*;
use amari_relativistic::precision::*;
use amari_relativistic::precision_geodesic::*;
use amari_relativistic::constants;
use num_traits::float::FloatConst;

// High-precision orbital parameter calculation
let semi_major_axis = StandardFloat::from_f64(7000e3); // 7000 km
let eccentricity = StandardFloat::from_f64(0.01);
let mu = constants::precision::g::<StandardFloat>() * constants::precision::earth_mass::<StandardFloat>();

// Orbital period with high precision
let period = StandardFloat::from_f64(2.0) * <StandardFloat as PrecisionFloat>::PI() *
    (semi_major_axis.powf_precise(StandardFloat::from_f64(3.0)) / mu).sqrt_precise();

// Precision spacetime vector for spacecraft position
let spacecraft_pos = PrecisionSpacetimeVector::<StandardFloat>::new(
    StandardFloat::from_f64(0.0),
    StandardFloat::from_f64(7000e3),
    StandardFloat::from_f64(0.0),
    StandardFloat::from_f64(0.0)
);

println!("Orbital period: {:.12} s", period.to_f64());
println!("Spacecraft tolerance: {:.2e}", StandardFloat::orbital_tolerance().to_f64());

Compile-Time Verification with Phantom Types

When the phantom-types feature is enabled (default), you get compile-time guarantees:

use amari_relativistic::prelude::*;

// Verified spacetime vector with compile-time signature guarantees
let position = VerifiedSpacetimeVector::new(0.0, Vector3::zeros());
let velocity = Vector3::new(0.6 * C, 0.0, 0.0);

// Four-velocity is automatically normalized and verified at creation
let four_vel = VerifiedFourVelocity::from_velocity(velocity)?;
assert!(four_vel.is_normalized()); // Guaranteed by phantom types

// Particles must satisfy energy-momentum relation E² = (pc)² + (mc²)²
let particle = VerifiedRelativisticParticle::new(
    position, four_vel, 9.109e-31, -1.602e-19
)?;
assert!(particle.satisfies_energy_momentum_relation()); // Type-guaranteed

Formal Verification with Creusot Contracts

With the formal-verification feature on nightly Rust:

use amari_relativistic::prelude::*;

// Functions with mathematical guarantees proven at compile time
let boosted = verified_lorentz_boost(&vector, boost_velocity);
// Guaranteed: Minkowski norm preserved by Lorentz transformation

let collision_valid = verified_collision(&p1, &p2, &p3, &p4);
// Guaranteed: Energy and momentum conservation in particle collisions

Application Domains

Charged Particle Simulations

• Ion beam focusing and deflection
• Particle accelerator beam dynamics
• Plasma physics particle trajectories
• Industrial ion implantation processes

Astrophysics

• Planetary motion around compact objects
• Photon trajectories near black holes
• Gravitational lensing calculations
• Tidal effects and frame dragging

Fundamental Physics

• Tests of general relativity
• Precision orbit determination
• Relativistic corrections to classical mechanics
• Coordinate transformation verification

Performance Considerations

• Uses #[inline] for hot path functions
• Leverages SIMD through amari-core geometric algebra
• Symplectic integrators preserve energy conservation
• Adaptive step sizing for numerical stability

Integration with Amari Ecosystem

This crate builds upon:

• amari-core: Geometric algebra operations and multivectors
• amari-gpu: GPU acceleration for large-scale simulations
• amari-dual: Automatic differentiation for optimization
• amari-info-geom: Information geometry for parameter estimation

References

• Misner, Thorne & Wheeler, "Gravitation" (1973)
• Doran & Lasenby, "Geometric Algebra for Physicists" (2003)
• Jackson, "Classical Electrodynamics" (1999)
• Weinberg, "Gravitation and Cosmology" (1972) Integration tests demonstrating complete workflows Additional documentation tests to ensure examples compile and run correctly