Warning, /eic-opticks/examples/async_gpu_launch/README.md is written in an unsupported language. File is not indexed.
0001 # Async GPU Launch Example
0002
0003 Demonstrates asynchronous CPU+GPU optical photon simulation using
0004 double-buffered genstep collection with Geant4's `G4TaskGroup`.
0005
0006 ## Architecture
0007
0008 ```
0009 CPU Event Loop GPU Worker (G4TaskGroup)
0010 ----------------- ------------------------
0011 Event N:
0012 EM shower -> Cerenkov/Scint
0013 Collect gensteps into buffer A
0014 Buffer A hits threshold
0015 Swap A <-> B
0016 Submit buffer A to GPU -------> Process buffer A:
0017 Event N+1: Load gensteps into SEvt
0018 Collect gensteps into buffer B gx->simulate()
0019 ... Save hits
0020 Done
0021 End of run:
0022 Flush buffer B ----------------> Process buffer B
0023 Wait for completion Done
0024 ```
0025
0026 The CPU never blocks waiting for the GPU (except at end-of-run flush).
0027 A single `G4Mutex` ensures only one GPU kernel runs at a time.
0028
0029 ## Modes
0030
0031 | Flag | Behavior |
0032 |----------|----------|
0033 | `--async` | (default) Double-buffered async GPU processing |
0034 | `--sync` | Original end-of-run batch GPU simulation |
0035
0036 ## Environment Variables
0037
0038 | Variable | Default | Description |
0039 |----------|---------|-------------|
0040 | `GPU_PHOTON_FLUSH_THRESHOLD` | 10000000 | Photons per GPU batch |
0041 | `OPTICKS_MAX_BOUNCE` | 1000 | Maximum optical photon bounces |
0042 | `OPTICKS_PROPAGATE_EPSILON` | - | Ray offset after boundary crossing |
0043 | `OPTICKS_PROPAGATE_EPSILON0` | - | Ray offset after bulk interaction |
0044
0045 ## Build (standalone)
0046
0047 ```bash
0048 mkdir build && cd build
0049 cmake .. -DCMAKE_PREFIX_PATH=/path/to/eic-opticks/install
0050 make
0051 ```
0052
0053 ## Build (in-tree)
0054
0055 The example is also built as part of the main eic-opticks build.
0056
0057 ## Run
0058
0059 ```bash
0060 # Async mode (default)
0061 ./run.sh
0062
0063 # Sync mode
0064 ./run.sh --sync
0065
0066 # Custom threshold (smaller batches = more CPU/GPU overlap)
0067 GPU_PHOTON_FLUSH_THRESHOLD=1000000 ./run.sh
0068 ```
0069
0070 ## Output
0071
0072 - `gpu_hits_batch_*.npy` — GPU hits per batch (async mode)
0073 - `gpu_hits.npy` — GPU hits (sync mode)
0074 - `g4_hits.npy` — Geant4 reference hits
0075
0076 All hit files use the sphoton layout: `(N, 4, 4)` float32 array with
0077 fields `pos/time`, `mom`, `pol/wavelength`, `flags`.
0078
0079 ## Supported Physics
0080
0081 Both Cerenkov and scintillation gensteps are collected. Multi-component
0082 scintillation (up to 3 time constants) is supported.
