GR-raytracing/build.md

Build guide

Run these commands from the repository root. The build uses GNU Make and produces standalone executables under build/Release/ or build/Debug/.

Dependencies

The default CPU build needs:

• A C11 compiler and OpenMP runtime (for example, GCC with libgomp).
• GNU Make.
• libpng headers and library for PNG output.
• pkg-config, used to locate and link FFTW.
• FFTW 3 built with OpenMP, discovered through pkg-config fftw3_omp (sci-libs/fftw[openmp] on Gentoo). This is required for the CPU fast-mode fast convolution; HIP and dummy PSF builds do not link FFTW.
• POSIX threads, used by the bounded movie output writer. It is provided by the OpenMP runtime on the supported toolchains, so no extra package is needed.

Optional FFTW wisdom can be generated once and reused across runs with --fast-fftw-plan wisdom-update --fast-fftw-wisdom FILE followed by --fast-fftw-plan wisdom --fast-fftw-wisdom FILE. The matching FILE.meta sidecar records the transform size, supersample, kernel radius, worker count, FFTW version, and precision; a mismatch is reported and the run fails instead of silently replanning.

Optional dependencies are CFITSIO for HDR/FITS output, and HIP/ROCm with hipcc and a compatible GPU for HIP PSF accumulation.

CPU build

make -j

With no explicit SPACETIME setting, this builds all supported spacetimes:

Executable	Spacetime
build/Release/minkowski_sky	Flat Minkowski spacetime
build/Release/schwarzschild_sky	Analytic Schwarzschild in ingoing Kerr–Schild coordinates
build/Release/alcubierre_sky	Analytic moving Alcubierre warp bubble, x_s(t)=v_s t (no capture)

To build only one:

make -j SPACETIME=minkowski backend
make -j SPACETIME=schwarzschild backend
make -j SPACETIME=alcubierre backend

Each executable contains one metric provider, selected at compile time. PSF_BACKEND=cpu is the default. Release builds use -O2 -DNDEBUG; the default compiler flags also include -march=native, targeting the build machine's CPU. For a binary intended for other CPUs, override CFLAGS:

make -B -j CFLAGS='-std=c11 -pipe -Wall -Wextra -Wpedantic'

For a Debug build (-O0 -g3):

make -j BUILD_TYPE=Debug

Debug executables are placed in build/Debug/.

Output formats

PNG is enabled by default. If libpng is unavailable, build with binary PPM output instead and use a .ppm output filename:

make -B -j ENABLE_PNG=0

To enable the optional --hdr-output switch, install CFITSIO and pkg-config, then build the desired spacetime with ENABLE_HDR=1:

make -j SPACETIME=schwarzschild ENABLE_HDR=1 backend

The executable keeps its usual name, build/Release/schwarzschild_sky. --hdr-output writes a linear RGB FITS file alongside the ordinary single-frame image; see usage.md. Use ENABLE_HDR=0 to rebuild without this feature.

Optional HIP PSF acceleration

make -j PSF_BACKEND=hip SPACETIME=minkowski backend
make -j PSF_BACKEND=hip SPACETIME=schwarzschild backend

These produce build/Release/minkowski_sky_hip and build/Release/schwarzschild_sky_hip, separately from the CPU executables. HIPCC can override the default hipcc command. ENABLE_HDR=1 can be combined with either HIP build.

HIP accelerates cache-eligible PSF accumulation; ray tracing and catalog mapping remain on the CPU. PSFs requiring direct evaluation retain the CPU reference path with ordered HDR transfers. HIP initialization or execution errors terminate the render instead of silently selecting the CPU backend.

HIP catalog mapping uses OpenMP producers (OMP_NUM_THREADS) with one private 16,384-event chunk per worker. A shared GPU sink owns one double HDR image and PSF cache, plus two pinned upload slots protected by completion events. Each PSF uses a group of 32 threads to visit adjacent pixels; weights, support and HDR precision remain unchanged. CPU direct fallbacks exclude other submissions through the complete download/evaluate/upload boundary.

Every batch contributes to the final HIP timings. Long submissions print progress about every five seconds (completed counts cover reclaimed slots). The producer summary reports summed worker wall time in generation and submission/fallback, including lock/device waits in the latter; these overlapping times must not be added to GPU timings or interpreted as process CPU time. The two upload slots bound staging memory and allow CPU production ahead of GPU completion; copies and kernels still execute in order on one stream.

Diagnostic dummy PSF backend

To inspect production chunk geometry without starting HIP or allocating an HDR framebuffer, build the diagnostic-only dummy backend:

make -j1 PSF_BACKEND=dummy SPACETIME=schwarzschild ENABLE_HDR=1 backend
OMP_NUM_THREADS=16 OMP_DYNAMIC=FALSE \
  ./build/Release/schwarzschild_sky_dummy --lens-map-input MAP.grlens \
  --all-sky-catalog CATALOG_DIR --output PROTECTED_OR_UNUSED.png [normal PSF options]

The dummy executable requires an imported lens map and the PSF cache; it rejects --psf-direct. It runs the real OpenMP triangle scheduling, catalog query, inverse mapping, redshift/color/flux preparation, and cache/direct/min-Y classification, but records chunk statistics instead of accumulating pixels. --output and --hdr-output are accepted only for command parity: neither PNG nor FITS is created or modified. Reports separate full 16,384-event chunks from the final partial chunk of each worker and include event-producing triangle counts, occupied 32-pixel center tiles, bounding-box diagonals, and successive triangle-centroid jumps. This is a scheduling diagnostic, not a rendering or backend-performance benchmark.

With both Minkowski binaries built using ENABLE_HDR=1, python3 tests/test_hip_renderer.py build/Release/minkowski_sky build/Release/minkowski_sky_hip runs small CPU/HIP fallback and min-Y comparisons sequentially. Each renderer subprocess has a 30-second timeout.

For a bounded production-cache benchmark, build and then run one process at a time, with a timeout:

make PSF_BACKEND=hip SPACETIME=minkowski hip-psf-bench
./build/Release/benchmark_hip_psf --help
OMP_NUM_THREADS=16 timeout --kill-after=5s 45s ./build/Release/benchmark_hip_psf 4096 16

Arguments are event count (default 4096, maximum 65536) and screen spread in pixels (default 16, maximum 3840). The benchmark runs a serial CPU HDR reference before HIP and checks double values. See the bounded investigation and original logs; its speedups do not establish a full-sky render time.

Rebuilding and checks

Build type, spacetime, HDR, and PSF backend configurations have separate object paths. Changes to flags such as ENABLE_PNG, CC, or CFLAGS require a forced rebuild with make -B and the intended settings. make clean removes the entire build/ directory; keep rendered images and other retained output under output/.

Inspect the available runtime options:

./build/Release/minkowski_sky --help
./build/Release/schwarzschild_sky --help

Run CPU regression checks:

make test

The CPU suite includes both coordinate-camera builders, CLI validation, small PNG renders, single-frame/movie lens-map agreement, the tone-map regression, and the standalone sensor-bloom model regression (make sensor-bloom-test). An isolated make sensor-bloom-bench target times only the bloom model on synthetic frames; it is not part of make test. The reference image checks require Python 3 and CFITSIO. The original Schwarzschild HDR fixture is retained with a float32 relative tolerance of 2^-23 (zero absolute tolerance): replacing the specialized static tetrad with metric-based orthonormalization changes four components by one ULP. The Minkowski fixture still requires exact equality.

The HIP regression requires an actual compatible GPU. The Make target builds the test executable; run it separately:

make PSF_BACKEND=hip SPACETIME=minkowski hip-psf-test
./build/Release/obj/minkowski/standard_sink1_hip/test_hip_psf

For rendering with real stellar data, continue with README.md and the rendering guide.