wyj
e1ec480669
Cooperate across 32 lanes per PSF and use two completion-protected staging slots with complete batch timing. Restore coarse OpenMP event production while serializing shared GPU submissions and direct fallback boundaries. Add bounded benchmarks, streaming and renderer regressions, and preserve validation evidence and ownership documentation.
5.8 KiB
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.
Optional dependencies are CFITSIO and pkg-config 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 both supported spacetimes:
| Executable | Spacetime |
|---|---|
build/Release/minkowski_sky |
Flat Minkowski spacetime |
build/Release/schwarzschild_sky |
Analytic Schwarzschild in ingoing Kerr–Schild coordinates |
To build only one:
make -j SPACETIME=minkowski backend
make -j SPACETIME=schwarzschild 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.
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, and single-frame/movie lens-map agreement. 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/test_hip_psf
For rendering with real stellar data, continue with README.md and the rendering guide.