Relativity-Simulator

Deterministic simulation and ray-tracing engine for General Relativity, Post-Newtonian dynamics, relativistic hydrodynamics, and polarized radiative transfer in curved spacetimes.

Documentation Map

Primary references:

System Description: scientific scope, runtime modes, validation targets.
Technical Architecture: subsystem structure, scheduling, concurrency, precision model.
Technical Manual: component-level implementation and engineering constraints.
Mathematical Formulation: equations, metrics, transport formalisms, PN terms.
File Formats & I/O: YAML schema, FITS/HDF5/VTK formats, SPICE/HORIZONS ingestion.
CLI & REPL Reference: interactive commands and headless exporter options.
Documentation Index: index of the documentation set.
Source Tree: repository layout.

Key Features

Spacetime Models
- Analytic metrics: Minkowski, Schwarzschild, Kerr, Reissner–Nordström, Kerr–Newman, Schwarzschild–de Sitter (Kottler) (Catalog & Gauges).
- Coordinate forms: Boyer–Lindquist, Kerr–Schild Cartesian, Eddington–Finkelstein, Painlevé–Gullstrand, isotropic (Coordinate Systems).
- Additional models: FLRW, Morris–Thorne, Alcubierre (Cosmological & Exotic Spacetimes).
- Image rendering of Schwarzschild–de Sitter, FLRW, Morris–Thorne and Alcubierre uses the Schwarzschild null tracer (Technical Manual).
- Numerical spacetime support: 3+1 BSSN metric grids with spatial and temporal interpolation (Metric Modules).
- Metric invariants and curvature tensors: Riemann, Ricci, and Kretschmann invariants (Diagnostics Window).
Geodesics and Integrators
- Adaptive explicit integrators: RK45 Dormand–Prince, Cash–Karp, Vernier 9.
- Symplectic integrators: Gauss–Legendre orders 4 and 6, Forest–Ruth post-Newtonian scheme.
- Predictor-corrector: Hermite 4th-order Aarseth scheme.
- Horizon-aware stepping and adaptive step-control infrastructure (Mathematical Formulation, Technical Manual).
- Image rendering integrates null rays with a fixed-step RK4 scheme; the integrator selected at runtime determines the N-body integration only (Technical Manual).
Relativistic Dynamics
- Post-Newtonian N-body dynamics: conservative 1PN Einstein-Infeld-Hoffmann, 2PN, and 3PN terms.
- Dissipative terms: 2.5PN radiation reaction and 3.5PN radiation dissipation.
- Spin dynamics: spin-orbit and spin-spin couplings.
- Dedicated Hulse–Taylor binary pulsar model (Dynamics Subsystem).
- Interaction layers: Coulomb, magnetic dipole, collision, thermodynamic, fragmentation, and annihilation (Dynamics Subsystem).
- Spacetime-source bodies with Kerr horizons, horizon absorption, and body merging (State Advance).
- Bulk body actions (velocity and spin assignment, grid snapping, scattering, mass equalization, parameter equalization, culling; Keybinds).
Gravimetry and Large-Scale Gravity
- Spherical harmonic gravity expansions up to degree and order 32 ($J_n$, $C_{nm}$, $S_{nm}$); Architecture).
- Analytical orbital precession and tidal Love number perturbations.
- Dark matter modules: NFW, Einasto, Burkert, and Hernquist profiles, Barnes–Hut octree acceleration, MOND, TeVeS, and (f(R)) Chameleon models.
Relativistic Hydrodynamics and Compact Objects
- GRHD/GRMHD 3+1 conservative formulation with WENO5-JS, WENO5-Z, and MP5 reconstructions.
- Approximate Riemann solvers: HLL, HLLC, and HLLD (Architecture).
- Divergence control: constrained transport 2D enforcing (\nabla \cdot \mathbf{B} = 0) (Architecture).
- EOS models: ideal gas, Synge, Mathews, relativistic Fermi gas, polytropic, and tabulated nuclear EOS (Mathematical Formulation).
- Compact-object models: Tolman-Oppenheimer-Volkoff (TOV) solver, Novikov–Thorne thin disk, and Fishbone–Moncrief torus.
- Conservative-to-primitive inversion solver (Technical Manual).
Radiative Transfer and Rendering
- Backward null geodesic ray tracing in curved spacetimes (Mathematical Formulation).
- Polarized transfer in full Stokes representation ((I,Q,U,V)) via Delano matrix exponentials; image rendering uses blackbody disk emission integrated with CIE 1931 matching functions.
- Radiative processes: synchrotron emission and absorption, thermal bremsstrahlung, and inverse Compton scattering (Architecture).
- Continuous spectral pipeline with CIE 1931 observer convolution (Mathematical Formulation).
- Vulkan compute pipeline in native FP64 with CPU SIMD (AVX2/AVX-512/Neon) and scalar fallbacks in double and single precision.
- Ray-traced ellipsoidal celestial bodies with procedural surface layers, atmospheric rims, central-source lighting, shadows, and relativistic Doppler beaming (Technical Manual).
- Procedural starfield or equirectangular panorama sky, four HDR tone mapping operators, and CPU color grading.
- Schematic projection overlay with first-order light deflection (Mathematical Formulation) and up to eight secondary observer viewports.
- Still frame and sequence image streaming in ten output formats (Capture Subsystem).
Deterministic Runtime and Reproducibility
- Synchronous input event journal primitive (EventJournal), decoupled from the command queue.
- Engine signature computation and SHA-256 ABI verification.
- Lock-free SPSC command and result queues and static worker thread pool.
- Allocation-free hot paths utilizing cache-aligned linear memory arenas (Technical Manual).
Scientific Data and Interoperability
- Declarative YAML scenario parser and serializer with hierarchical path resolution.
- SPICE binary SPK kernel evaluation, NASA JPL HORIZONS vector table ingestion, and astronomical frame transformations.
- FITS 4.0 2D radiance image and 3D spectral cube export with WCS metadata headers (Serialization).
- Custom binary HDF5-signature container serialization for worldlines, metric series, and covariance matrices.
- VTK XML PolyData (VTP) geometry export for rays, trajectories, and event horizon meshes.
- Incremental image codecs and stream writers (Serialization).
Capture and Experiment Control
- Scriptable multi-segment camera motion paths with 21 shape layers, 46 easing curves, and expression evaluations (Mathematical Formulation).
- Motion script serialization and scripted timeline events (Capture Subsystem).
- Deterministic and real-time capture pipelines with banded rendering, sub-frame temporal averaging, and automated ffmpeg video encoding.
- Multi-channel physics telemetry recording across 54 kinematic and relativistic channels in seven file formats (Capture Modules).
- Path preview generation for visual trajectory inspection in the schematic overlay (Capture Modules).
Interactive Workspace
- Primary viewport window with camera transport toolbar, hold-to-zoom magnification, and a configurable 25-element HUD (Technical Manual).
- Multi-window docking workspace with dedicated interfaces for master simulation controls, scenario selector, celestial body manager, curvature diagnostics, spectrograph, performance optimization, profiling, physical constants, key bindings, log console, and Capture Studio (Technical Manual).
- Four navigation modes (Free-Fly 6-DOF, Orbit Center, Spherical Boyer-Lindquist, Rocket Thrust) and 67 rebindable actions with QWERTY and AZERTY presets.
- Physical constants engine supporting SI, Planck, and Custom presets, with independent unit preferences across 19 physical quantities and dimensional expression parsing.
- Persistent configuration files under config/ (User Settings, Performance Profiler, Capture Studio Settings).
Uncertainty Quantification

Visual Overview

The visual renders and trajectory sequences below were recorded and generated using the integrated Capture Studio workspace widget.

Curved Spacetime Null Geodesic Ray-Tracing (Schwarzschild Metric, M = 60.00)

Schwarzschild Metric Flyby Trajectory (M = 60.00) Schwarzschild Metric Infall Trajectory (M = 60.00)

Building and Installation

Prerequisites

C++23 compiler: GCC 13+, Clang 16+, or MSVC 2022 (v19.36+).
CMake 3.25+.
OpenGL and GLFW (via CMake FetchContent).
Vulkan headers and loader (the compute context includes vulkan/vulkan.h); when no compute-capable device is present at run time, the CPU renderer is used.
glslangValidator (optional): used by CMake to compile the compute shader.
ffmpeg (optional, run time): video assembly in the Capture Studio.

Standard Build (Release with LTO)

cmake -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_LTO=ON
cmake --build build --config Release -j $(nproc)

Profile-Guided Optimization (PGO) Build

Instrumented build

cmake -B build-pgo -DCMAKE_BUILD_TYPE=Release -DENABLE_PGO_GENERATE=ON
cmake --build build-pgo --config Release -j $(nproc)
./build-pgo/headless_exporter --validate-benchmarks

Optimized build using profile data

cmake -B build-opt -DCMAKE_BUILD_TYPE=Release -DENABLE_PGO_USE=ON
cmake --build build-opt --config Release -j $(nproc)

Running Test Suite

ctest --test-dir build --output-on-failure

Generating Installation Packages (CPack)

cd build
cpack -G TGZ
cpack -G DEB  # Linux Debian/Ubuntu
cpack -G RPM  # Linux Fedora/RHEL
cpack -G NSIS # Windows Installer

Quickstart

Interactive REPL Mode

./build/engine_cli

Available interactive commands (warp, step, set mass, status, etc.) are documented in the Interactive Terminal Commands (REPL) and navigation keybindings in Navigation & Viewport Keybindings.

Headless Batch Execution

./build/headless_exporter --validate-benchmarks
./build/headless_exporter --scenario scenarios/kerr_accretion_disk.yaml --output-dir ./output --width 3840 --height 2160

Command-line options are documented in Headless Batch Exporter, declarative scenario definitions in Declarative Scenario Definition, and validation targets in Verification Criteria & Benchmark Protocols.

Third-Party Assets and Image Licenses

Sky and panorama assets:

ambientCG assets (CC0 1.0): assets/sky/ambientcg/LICENCE.txt
ESO Milky Way panorama (CC BY 4.0): assets/sky/eso/LICENCE.txt

Earth and planetary assets:

Solar System Scope Earth textures (CC BY 4.0): assets/earth/solarsystemscope/LICENCE.txt

License

This project is licensed under the MIT License. See LICENSE for details.

This site is open source. Improve this page.