Deterministic simulation and ray-tracing engine for General Relativity, Post-Newtonian dynamics, relativistic hydrodynamics, and polarized radiative transfer in curved spacetimes.
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.
-
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.
-
Spherical harmonic gravity expansions up to degree and order 32 (
-
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).
-
Synchronous input event journal primitive (
-
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
- Bounded interval arithmetic adhering to IEEE 1788 (Description).
- Multidimensional zonotope enclosures with Girard order reduction (Description).
- Continuous Jacobi-Lyapunov covariance matrix differential propagation (Description).
- Generalized polynomial chaos expansions (gPCE) on Hermite and Legendre bases (Description).
The visual renders and trajectory sequences below were recorded and generated using the integrated Capture Studio workspace widget.
- 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.
cmake -B build -DCMAKE_BUILD_TYPE=Release -DENABLE_LTO=ON
cmake --build build --config Release -j $(nproc)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-benchmarkscmake -B build-opt -DCMAKE_BUILD_TYPE=Release -DENABLE_PGO_USE=ON
cmake --build build-opt --config Release -j $(nproc)ctest --test-dir build --output-on-failurecd build
cpack -G TGZ
cpack -G DEB # Linux Debian/Ubuntu
cpack -G RPM # Linux Fedora/RHEL
cpack -G NSIS # Windows Installer./build/engine_cliAvailable interactive commands (warp, step, set mass, status, etc.) are documented in the Interactive Terminal Commands (REPL) and navigation keybindings in Navigation & Viewport Keybindings.
./build/headless_exporter --validate-benchmarks
./build/headless_exporter --scenario scenarios/kerr_accretion_disk.yaml --output-dir ./output --width 3840 --height 2160Command-line options are documented in Headless Batch Exporter, declarative scenario definitions in Declarative Scenario Definition, and validation targets in Verification Criteria & Benchmark Protocols.
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
This project is licensed under the MIT License. See LICENSE for details.