Skip to content

Development

Guide for contributing to Thor.

Setup

Prerequisites

Clone and Build

git clone --recursive https://github.com/cbyrohl/thor.git
cd thor

# Install dev dependencies
uv sync --group=ci-tests --group=docs

# Debug build
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_COMPILER=acpp

cmake --build build

Memory Usage

Compilation can require large amounts of memory. If you run out of memory during the build, reduce the number of concurrent builders by adding -j1 to the build command: 

cmake --build build -j1

Project Structure

thor/
├── src/
│   ├── datasets/           # Dataset implementations
│   ├── drivers/            # Simulation drivers
│   ├── interactors/        # Define photon interactions
│   ├── outputprocessors/   # Output handling
│   ├── photongenerators/   # MC package spawning
│   ├── rngs/               # Random number generators
│   └── main.cpp            # Entry point
├── tests/                  # Unit tests (Catch2)
├── regression_tests/       # End-to-end simulation tests
├── scripts/                # Utility scripts (PractRand testing, etc.)
└── extern/                 # (submodule) dependencies

Key Components

  • Datasets (src/datasets/): Computational meshes and geometry
  • Drivers (src/drivers/): Simulation algorithms (MCRT, ray tracing)

Code Style

C++20 with SYCL, formatted via ./.clang-format.

  • sp(VAR), dp(VAR), fp(VAR): cast to single, double, or compile-time FP.
  • ip(VAR): cast to the compile-time IP (32- or 64-bit signed integer).
  • Mark device-callable functions with SYCL_EXTERNAL.

Testing

The project includes both unit and regression tests. For a detailed explanation of the testing frameworks and how to run tests, please see the Testing documentation.

Documentation media assets

Images and videos referenced from docs/ are not committed to the repository — .gitignore blocks *.png, *.webp, *.webm, and *.mp4. They are hosted as assets on a rolling GitHub release at thor-rt/docs-assets and referenced from markdown as full URLs.

Uploading

Stage the file anywhere on disk, then run:

./scripts/upload-docs-asset.sh path/to/banner.webp path/to/clip.webm

The script bootstraps the docs-assets release on first use, uploads with --clobber (re-uploads overwrite), and prints the canonical URLs to paste into markdown.

URL pattern

https://github.com/thor-rt/docs-assets/releases/download/docs-assets/<filename>

Naming rules

  • Filenames are unique on the release. Don't re-upload to the same name unless you intend to replace the live content for every page that references it; bump a version suffix (banner_v2.webp) when in doubt.
  • Orphaned assets stay until cleaned up explicitly: gh release delete-asset docs-assets --repo thor-rt/docs-assets <filename>.

Sanity checks

# What's currently on the release
gh release view docs-assets --repo thor-rt/docs-assets --json assets -q '.assets[].name'

# What URLs the docs reference
grep -rhoE 'releases/download/docs-assets/[A-Za-z0-9._-]+' docs/ | sort -u

If something is in the second list but not the first, it's a broken image on the deployed site. If only in the first, it's an orphan.

AI Authorship Attribution

This project uses AI-assisted development (Claude Code) extensively. AI-generated code is tagged for transparency:

  • Functions: [AI-Claude] tag at the end of the \brief Doxygen line
  • Tests: [AI] tag in Catch2 test tags, e.g., [mytag][AI]
  • Shell scripts: [AI-Claude] at end of first description comment line
  • Python modules: [AI-Claude] at end of first docstring line

Tags are removed after in-depth human review and approval.

Contributing

Contribute by submitting pull requests from your fork and the new feature branch.

Report issues at GitHub Issues.