Warning, /eic-opticks/docs/getting-started.md is written in an unsupported language. File is not indexed.
0001 # Getting started
0002
0003 This guide covers the system requirements, build steps, container workflows,
0004 and a sample NERSC batch job for running Simphony.
0005
0006 ## Prerequisites
0007
0008 Building from source requires the software stack listed below. Running
0009 Simphony and the GPU-backed tests additionally requires a CUDA-capable NVIDIA
0010 GPU.
0011
0012 - CUDA 12.1+
0013 - NVIDIA OptiX 7+
0014 - Geant4 11.3+
0015 - CMake 3.18+
0016 - Python 3.10+
0017
0018 OptiX releases have specific [minimum NVIDIA driver
0019 requirements](https://developer.nvidia.com/designworks/optix/downloads/legacy):
0020
0021 | OptiX version | Release date | Minimum driver required |
0022 |--- |---: |--- |
0023 | 9.1.0 | December 2025 | 590 |
0024 | 9.0.0 | February 2025 | 570 |
0025 | 8.1.0 | October 2024 | 555 |
0026 | 8.0.0 | August 2023 | 535 |
0027 | 7.7.0 | March 2023 | 530.41 |
0028 | 7.6.0 | October 2022 | 522.25 |
0029 | 7.5.0 | June 2022 | 515.48 |
0030 | 7.4.0 | November 2021 | 495.89 |
0031 | 7.3.0 | April 2021 | 465.84 |
0032 | 7.2.0 | October 2020 | 455.28 |
0033 | 7.1.0 | June 2020 | 450 |
0034 | 7.0.0 | August 2019 | 435.80 |
0035
0036 Optionally, if you plan to develop or run the simulation in a containerized
0037 environment, ensure that your system has the following tools installed:
0038
0039 - [Docker Engine](https://docs.docker.com/engine/install/)
0040 - NVIDIA container toolkit ([installation guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html))
0041
0042 ## Build
0043
0044 ```shell
0045 git clone https://github.com/BNLNPPS/simphony.git
0046 cmake -S simphony -B build
0047 cmake --build build
0048 ```
0049
0050 ## Docker
0051
0052 Try the latest published release image and verify that GPU-enabled code runs on
0053 your machine:
0054
0055 ```shell
0056 docker run --rm --gpus all ghcr.io/bnlnpps/simphony bash -lc 'simg4ox -g tests/geom/raindrop.gdml -m tests/run.mac'
0057 ```
0058
0059 Build the latest `simphony` image by hand:
0060
0061 ```shell
0062 docker build -t ghcr.io/bnlnpps/simphony:latest https://github.com/BNLNPPS/simphony.git
0063 ```
0064
0065 Build the development image locally:
0066
0067 ```shell
0068 docker build -t ghcr.io/bnlnpps/simphony:develop --target=develop .
0069 ```
0070
0071 On a reasonably provisioned machine, building the `develop` image can take
0072 under 10 minutes.
0073
0074 The repository also includes a ready-to-use devcontainer configuration in
0075 `.devcontainer/devcontainer.json` for IDE-based development workflows.
0076
0077 Example commands for interactive and non-interactive tests:
0078
0079 ```shell
0080 docker run --rm -it -v $HOME/.Xauthority:/root/.Xauthority -e DISPLAY=$DISPLAY --net=host ghcr.io/bnlnpps/simphony:develop
0081
0082 docker run --rm -it -v $HOME:/esi -v $HOME/simphony:/workspaces/simphony -e DISPLAY=$DISPLAY -e HOME=/esi --net=host ghcr.io/bnlnpps/simphony:develop
0083
0084 docker run ghcr.io/bnlnpps/simphony bash -c 'simg4ox -g tests/geom/sphere_leak.gdml -m tests/run.mac -c sphere_leak'
0085 ```
0086
0087 ## Singularity
0088
0089 Run the latest published release image with the same smoke test:
0090
0091 ```shell
0092 singularity exec --nv docker://ghcr.io/bnlnpps/simphony:latest bash -lc 'simg4ox -g tests/geom/raindrop.gdml -m tests/run.mac'
0093 ```
0094
0095 ```shell
0096 singularity run --nv -B simphony-prefix/:/opt/simphony -B simphony:/workspaces/simphony docker://ghcr.io/bnlnpps/simphony:develop
0097 ```
0098
0099 ## Running a test job at NERSC (Perlmutter)
0100
0101 To submit a test run of `simphony` on Perlmutter, use the following example.
0102 Update any placeholder values as needed.
0103
0104 ```shell
0105 sbatch scripts/submit.sh
0106 ```
0107
0108 ```bash
0109 #!/bin/bash
0110
0111 #SBATCH -N 1 # number of nodes
0112 #SBATCH -C gpu # constraint: use GPU partition
0113 #SBATCH -G 1 # request 1 GPU
0114 #SBATCH -q regular # queue
0115 #SBATCH -J simphony # job name
0116 #SBATCH --mail-user=<USER_EMAIL>
0117 #SBATCH --mail-type=ALL
0118 #SBATCH -A m4402 # allocation account
0119 #SBATCH -t 00:05:00 # time limit (hh:mm:ss)
0120
0121 # Path to your image on Perlmutter
0122 IMAGE="docker:bnlnpps/simphony:develop"
0123 CMD='cd /src/simphony && simg4ox -g $OPTICKS_HOME/tests/geom/sphere_leak.gdml -m $OPTICKS_HOME/tests/run.mac -c sphere_leak'
0124
0125 # Launch the container using Shifter
0126 srun -n 1 -c 8 --cpu_bind=cores -G 1 --gpu-bind=single:1 shifter --image=$IMAGE /bin/bash -l -c "$CMD"
0127 ```
