Penrose

Penrose is a modular General Relativity framework for simulating and visualizing particle and photon trajectories in curved spacetime.

Originally developed as a Schwarzschild black hole ray tracer, Penrose is evolving into a general-purpose framework for relativistic spacetime simulation, geodesic integration, validation, and scientific visualization.

---

Features

• Schwarzschild spacetime implementation
• Relativistic photon ray tracing
• Fourth-order Runge–Kutta geodesic integration
• CPU reference physics pipeline
• GPU real-time visualization pipeline
• Scientific benchmarking and validation framework
• Modular architecture for future spacetime geometries

---

Roadmap

The long-term vision is to support arbitrary relativistic geometries, including:

• Schwarzschild
• Solar Gravitational Lens (SGL)
• Kerr
• Reissner–Nordström
• FLRW cosmology
• User-defined analytic metrics
• Numerical metric fields

The architecture is designed such that new spacetime models can be added with minimal modification to the existing framework.

---

Architecture

Penrose consists of two complementary systems.

Scientific Framework (CPU)

Responsible for:

• spacetime definitions
• geodesic dynamics
• numerical integration
• benchmarking
• validation

State
    │
Metric
    │
Dynamics
    │
Integrator
    │
Trajectory Solver
    │
Benchmarking

---

Visualization Pipeline (GPU)

Responsible for:

• real-time rendering
• OpenGL
• GLSL shaders
• interactive visualization

Camera
    │
Renderer
    │
Fragment Shader
    │
Geodesic Integration
    │
Pixel Color

The visualization pipeline is intentionally separated from the scientific framework. The CPU implementation serves as the reference implementation for correctness, while the GPU implementation is optimized for interactive rendering.

---

Repository Structure

penrose/

├── physics/              # CPU scientific pipeline
│   ├── state/            # Geodesic state vector
│   ├── metrics/          # Spacetime metrics and charts
│   ├── geodesics/        # Relativistic equations of motion
│   ├── integrators/      # Numerical integration methods
│   ├── simulation/       # Trajectory solving and termination
│   ├── validation/       # Scientific benchmarks
│   ├── export/           # CSV / data export helpers
│   ├── results/          # Simulation outputs
│   ├── analysis/         # Notebooks and plots
│   ├── scenes/           # (reserved)
│   └── cameras/          # (reserved)
├── realtime/             # GPU real-time visualization pipeline
│   ├── main.cpp          # Interactive application entry
│   ├── renderer/         # OpenGL rendering backend
│   ├── shaders/          # GLSL shaders
│   ├── resources/        # Textures and assets
│   ├── gpu/              # GLAD / OpenGL loader
│   ├── visualization/    # Frame-capture utilities
│   └── ui/               # (reserved)
├── shared/               # Code used by both pipelines (none yet)
│   ├── math/
│   ├── utilities/
│   └── common/
├── docs/                 # Documentation and architecture
├── notes/                # Research notes
├── vendor/               # Third-party libraries
├── CMakeLists.txt
└── README.md

---

Mathematical Pipeline

Every trajectory in Penrose follows the same physical workflow.

Matter / Energy
        │
        ▼
Metric Tensor
        │
        ▼
Christoffel Symbols
        │
        ▼
Geodesic Equation
        │
        ▼
Numerical Integration
        │
        ▼
Trajectory

For Schwarzschild spacetime, the metric is analytic. Future versions will support numerical metric fields and additional spacetime geometries.

---

Documentation

Additional documentation can be found in:

• docs/RUNNING.md — how to install, run, capture, and benchmark
• docs/architecture/
• docs/reports/
• docs/frame_capture/

---

Current Status

Penrose is under active development.

The current focus is the evolution from a Schwarzschild-specific renderer into a modular General Relativity framework capable of supporting multiple spacetime geometries, numerical backends, and scientific computing workflows.

Instructions

Make sure there is a C/C++ compiler like GCC installed.

Make sure CMake is installed

Add vcpkg at some root directory and run: git clone https://github.com/microsoft/vcpkg.git

Then run the following:

cd vcpkg
# On Windows:
bootstrap-vcpkg.bat
# On Linux/macOS:
./bootstrap-vcpkg.sh

Remember the path to vcpkg

To build and run the project

1. Generate the build files inside a "build" directory

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[PATH_TO_VCPKG]/scripts/buildsystems/vcpkg.cmake

2. Compile the code

cmake --build build --config Debug

Then the build is the build/Debug/Penrose.exe file. Run it from the Debug folder itself.

For detailed instructions, check running instructions.

---

Pipeline link:

Physics and Rendering Pipeline