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.
166 lines
5.8 KiB
Markdown
166 lines
5.8 KiB
Markdown
# 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
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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`:
|
||
|
||
```sh
|
||
make -B -j CFLAGS='-std=c11 -pipe -Wall -Wextra -Wpedantic'
|
||
```
|
||
|
||
For a Debug build (`-O0 -g3`):
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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`:
|
||
|
||
```sh
|
||
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](usage.md#hdr-output). Use `ENABLE_HDR=0`
|
||
to rebuild without this feature.
|
||
|
||
## Optional HIP PSF acceleration
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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](benchmarks/hip_psf_2026-09-07.md); 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:
|
||
|
||
```sh
|
||
./build/Release/minkowski_sky --help
|
||
./build/Release/schwarzschild_sky --help
|
||
```
|
||
|
||
Run CPU regression checks:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
make PSF_BACKEND=hip SPACETIME=minkowski hip-psf-test
|
||
./build/Release/test_hip_psf
|
||
```
|
||
|
||
For rendering with real stellar data, continue with [README.md](README.md#prepare-the-stellar-catalog)
|
||
and the [rendering guide](usage.md).
|