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++ Guidelines

Thor uses modern C++20 with SYCL. We follow the style specified in ./.clang-format.

A few more specs:

  • We use sp(VAR), dp(VAR), and fp(VAR) for floating-point casting. Former indicate single- and double-precision, while fp is set to the compile-time configuration type
  • Similarly, ip(VAR) casts to the compile-time (signed) 4 or 8 byte integer type.
  • Mark device 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.

AI Authorship Attribution

This project uses AI-assisted development (Claude Code) extensively since November 2025. 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.