Skip to content

docs: improve development and testing workflows #430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
plexoos merged 4 commits into from
Jul 30, 2026
+227 −113
Merged

docs: improve development and testing workflows #430

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
77c2e32
docs: improve development and testing workflows
plexoos Jul 30, 2026
937e824
Potential fix for pull request finding
plexoos Jul 30, 2026
c0c6ddf
fix
plexoos Jul 30, 2026
71925dc
minor fix
plexoos Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .devcontainer/compose.devcontainer.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
name: simphony-${USER:-dev}

services:
simphony:
build:
Expand Down
3 changes: 3 additions & 0 deletions .devcontainer/devcontainer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@
"containerUser": "dev",
"remoteUser": "dev",
"updateRemoteUserUID": true,
"hostRequirements": {
"gpu": "optional"
},
"features": {
"ghcr.io/devcontainers/features/github-cli:1": {},
"./features/llvm": {
Expand Down
103 changes: 67 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,60 +15,70 @@ The project builds on Simon Blyth's original
[Opticks](https://simoncblyth.bitbucket.io/opticks/) work and adapts that
approach for current OptiX- and Geant4-based simulation workflows.


## Quick start

### Build from source

If CUDA 12.1+, NVIDIA OptiX 7+, Geant4 11.3+, CMake 3.22+, and Python 3.10+
are already installed, you can build and test Simphony directly:

```shell
git clone https://github.com/BNLNPPS/simphony.git
cmake -S simphony -B build
cd simphony
cmake -S . -B build
cmake --build build
ctest --test-dir build
```

To build from source, install CUDA 12.1+, NVIDIA OptiX 7+, and Geant4 11.3+.
A CUDA-capable NVIDIA GPU is required only to run Simphony and its GPU-backed
examples.
You can edit and build without a GPU. Running Simphony and its GPU-backed tests
requires a CUDA-capable NVIDIA GPU.

Simphony can also be installed via Spack as a dependency:
### Use the Dev Container

For a ready-made environment, first install [Docker
Engine](https://docs.docker.com/engine/install/). Then install the [Dev Container
CLI](https://github.com/devcontainers/cli) and start the environment:

```shell
spack repo add https://github.com/BNLNPPS/spack-packages
spack install simphony
npm install -g @devcontainers/cli
git clone https://github.com/BNLNPPS/simphony.git
cd simphony
devcontainer up
devcontainer exec bash
Comment on lines +46 to +47

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Pass the workspace folder to Dev Container commands

Anyone copying this quick start will invoke the CLI without its workspace selector, so devcontainer up/exec cannot identify the checkout and exit instead of starting or entering the container. The CLI's official examples use devcontainer up --workspace-folder <path> and devcontainer exec --workspace-folder <path> ... (Dev Container CLI “Try it”); add --workspace-folder . here and to the repeated commands in docs/getting-started.md.

Useful? React with 👍 / 👎.

Comment on lines +43 to +47
```

To try the latest release image and verify that GPU-enabled code runs on your
machine, you can use either Docker or Apptainer/Singularity:
The source tree is mounted into the container. Once inside, use the same CMake
commands above and rerun only the relevant build and tests as you work.

The root `.env` selects the OS and toolchain versions. See [Choose dependency
versions](docs/getting-started.md#choose-dependency-versions) before changing
them.

To run GPU-backed code, install the [NVIDIA Container
Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
on the host. The Dev Container CLI detects the NVIDIA runtime and requests GPU
access automatically.

### Try a published image

To take the latest release for a quick test drive, use Docker or Apptainer:

```shell
docker run --rm --gpus all ghcr.io/bnlnpps/simphony simg4ox -g tests/geom/raindrop.gdml -m tests/run.mac
apptainer exec --nv docker://ghcr.io/bnlnpps/simphony simg4ox -g /workspaces/simphony/tests/geom/opticks_raindrop.gdml -m /workspaces/simphony/tests/run.mac
apptainer exec --nv docker://ghcr.io/bnlnpps/simphony simg4ox -g /workspaces/simphony/tests/geom/raindrop.gdml -m /workspaces/simphony/tests/run.mac
```

For local development, you can build the `develop` image yourself or use the
repository's [devcontainer configuration](.devcontainer/devcontainer.json). On
a reasonably provisioned machine, building the `develop` image can take under 10
minutes. See [Getting started](docs/getting-started.md) for Docker, Singularity,
and development-environment details.

## Supported Images

The `build-push-base.yaml` workflow publishes reusable `base` images for development environments and Docker build
cache warmup. The `build-push.yaml` workflow publishes the versioned container tags below to GHCR on pushes to `main`,
while `release.yaml` publishes the `latest` alias on tagged releases. Tag entries link to the
[Simphony package page](https://github.com/BNLNPPS/simphony/pkgs/container/simphony).

| Target | OS | CUDA | OptiX | Geant4 | Alias | Tag |
|---|---|---:|---:|---:|---|---|
| `base` | `ubuntu26.04` | `13.3.0` | `9.1.0` | `11.4.2` | | [cuda13.3.0-base-ubuntu26.04-optix9.1.0-geant411.4.2-cmake4.3.4](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `base` | `ubuntu24.04` | `13.0.3` | `9.0.0` | `11.4.2` | `base` | [cuda13.0.3-base-ubuntu24.04-optix9.0.0-geant411.4.2-cmake4.2.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `base` | `ubuntu24.04` | `12.5.1` | `9.0.0` | `11.4.1` | | [cuda12.5.1-base-ubuntu24.04-optix9.0.0-geant411.4.1-cmake3.28.3](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `base` | `ubuntu22.04` | `12.1.1` | `8.0.0` | `11.3.2` | | [cuda12.1.1-base-ubuntu22.04-optix8.0.0-geant411.3.2-cmake3.22.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `release` | `ubuntu26.04` | `13.3.0` | `9.1.0` | `11.4.2` | | [cuda13.3.0-release-ubuntu26.04-optix9.1.0-geant411.4.2-cmake4.3.4](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `release` | `ubuntu24.04` | `13.0.3` | `9.0.0` | `11.4.2` | `latest` | [cuda13.0.3-release-ubuntu24.04-optix9.0.0-geant411.4.2-cmake4.2.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `release` | `ubuntu22.04` | `12.1.1` | `8.0.0` | `11.3.2` | | [cuda12.1.1-release-ubuntu22.04-optix8.0.0-geant411.3.2-cmake3.22.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `develop` | `ubuntu24.04` | `13.0.3` | `9.0.0` | `11.4.2` | `develop` | [cuda13.0.3-develop-ubuntu24.04-optix9.0.0-geant411.4.2-cmake4.2.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `develop` | `ubuntu24.04` | `12.5.1` | `9.0.0` | `11.4.1` | | [cuda12.5.1-develop-ubuntu24.04-optix9.0.0-geant411.4.1-cmake3.28.3](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `develop` | `ubuntu22.04` | `12.1.1` | `8.0.0` | `11.3.2` | | [cuda12.1.1-develop-ubuntu22.04-optix8.0.0-geant411.3.2-cmake3.22.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
### Install with Spack

Simphony is also available through the BNLNPPS Spack repository:

```shell
spack repo add https://github.com/BNLNPPS/spack-packages
spack install simphony
```

See [Getting started](docs/getting-started.md) for targeted test commands,
container lifecycle tips, native builds, and NERSC usage.

## Documentation

Expand All @@ -77,3 +87,24 @@ while `release.yaml` publishes the `latest` alias on tagged releases. Tag entrie
- [Simulation inputs and outputs](docs/inputs-outputs.md)
- [Performance and debugging](docs/performance-and-debugging.md)
- [Examples](examples/README.md)

## Published container images

The project publishes reusable `base` images for development environments and
Docker build-cache warmup, along with versioned `release` and `develop` images.
Pushes to `main` update the versioned tags, while tagged releases update the
`latest` alias. Every tag below links to the [Simphony package
page](https://github.com/BNLNPPS/simphony/pkgs/container/simphony).

| Target | OS | CUDA | OptiX | Geant4 | CMake | Alias | Tag |
|---|---|---:|---:|---:|---:|---|---|
| `base` | `ubuntu26.04` | `13.3.0` | `9.1.0` | `11.4.2` | `4.3.4` | | [cuda13.3.0-base-ubuntu26.04-optix9.1.0-geant411.4.2-cmake4.3.4](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `base` | `ubuntu24.04` | `13.0.3` | `9.0.0` | `11.4.2` | `4.2.1` | `base` | [cuda13.0.3-base-ubuntu24.04-optix9.0.0-geant411.4.2-cmake4.2.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `base` | `ubuntu24.04` | `12.5.1` | `9.0.0` | `11.4.1` | `3.28.3` | | [cuda12.5.1-base-ubuntu24.04-optix9.0.0-geant411.4.1-cmake3.28.3](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `base` | `ubuntu22.04` | `12.1.1` | `8.0.0` | `11.3.2` | `3.22.1` | | [cuda12.1.1-base-ubuntu22.04-optix8.0.0-geant411.3.2-cmake3.22.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `release` | `ubuntu26.04` | `13.3.0` | `9.1.0` | `11.4.2` | `4.3.4` | | [cuda13.3.0-release-ubuntu26.04-optix9.1.0-geant411.4.2-cmake4.3.4](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `release` | `ubuntu24.04` | `13.0.3` | `9.0.0` | `11.4.2` | `4.2.1` | `latest` | [cuda13.0.3-release-ubuntu24.04-optix9.0.0-geant411.4.2-cmake4.2.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `release` | `ubuntu22.04` | `12.1.1` | `8.0.0` | `11.3.2` | `3.22.1` | | [cuda12.1.1-release-ubuntu22.04-optix8.0.0-geant411.3.2-cmake3.22.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `develop` | `ubuntu24.04` | `13.0.3` | `9.0.0` | `11.4.2` | `4.2.1` | `develop` | [cuda13.0.3-develop-ubuntu24.04-optix9.0.0-geant411.4.2-cmake4.2.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `develop` | `ubuntu24.04` | `12.5.1` | `9.0.0` | `11.4.1` | `3.28.3` | | [cuda12.5.1-develop-ubuntu24.04-optix9.0.0-geant411.4.1-cmake3.28.3](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
| `develop` | `ubuntu22.04` | `12.1.1` | `8.0.0` | `11.3.2` | `3.22.1` | | [cuda12.1.1-develop-ubuntu22.04-optix8.0.0-geant411.3.2-cmake3.22.1](https://github.com/BNLNPPS/simphony/pkgs/container/simphony) |
Loading
Loading