Skip to content

Python Packages

Work in Progress

These packages are under active development as functionality is being moved in from external analysis packages. APIs may change and features may be incomplete or missing.

THOR ships a set of Python packages for post-processing simulation output, visualizing results, and accessing the C++ engine from Python.

Two Ways to Use THOR's Python Tools

1. As Python packages
Install into a virtual environment with pip install for direct programmatic access to THOR's Python APIs, or when developing the packages themselves.

2. As a CLI tool (thor-tools command)
Install globally with uv tool install to access the thor-tools command from anywhere on your system. Best for general analysis workflows. No virtual environment needed—uv manages isolation automatically.

Packages

Package Purpose
thor-rt Python tools: shared utilities, MCRT analysis, raytracer visualization, workflow helpers, and thor-tools CLI
thor-bindings C++ Python bindings via nanobind
thor-testkit Regression test tools (internal)

Environment Setup

First, set the path to your THOR repository:

export THOR_PATH=/path/to/thor

Before installing THOR's Python packages, create an isolated environment using your preferred tool:

python -m venv thor-env
source thor-env/bin/activate  # Linux/macOS
On Windows: thor-env\Scripts\activate

uv venv thor-env
source thor-env/bin/activate

conda create -n thor python=3.11
conda activate thor

Once activated, proceed with the installation steps below.

Installation

All packages live in the python/ directory and use standard pyproject.toml builds.

Python package (into your environment)

With your virtual environment activated (see Environment Setup):

pip install -e "$THOR_PATH/python/thor-rt[all]"

You can also install subsets:

pip install -e "$THOR_PATH/python/thor-rt[mcrt]"       # MCRT commands only
pip install -e "$THOR_PATH/python/thor-rt[raytracer]"  # Raytracer commands only
pip install -e "$THOR_PATH/python/thor-rt"             # Base CLI only (no commands)

C++ Bindings (optional)

thor-bindings requires the same build environment as THOR itself (see Installation):

pip install -e "$THOR_PATH/python/thor-bindings"

CLI tool (no virtual environment needed)

Install thor-tools globally using uv's tool manager. This creates an isolated environment automatically:

# With all plugins (MCRT + raytracer)
uv tool install "$THOR_PATH/python/thor-rt[all]"

# MCRT commands only
uv tool install "$THOR_PATH/python/thor-rt[mcrt]"

# Raytracer commands only
uv tool install "$THOR_PATH/python/thor-rt[raytracer]"

After installation, thor-tools is on your PATH. Verify with uv tool list.

To update after pulling new changes:

uv tool install "$THOR_PATH/python/thor-rt[all]" --reinstall

CLI

Installing thor-rt provides the thor-tools command. MCRT and raytracer sub-commands are registered as plugins:

thor-tools
├── mcrt
│   ├── projection create
│   └── traces {analyze, info, summary, compare}
└── raytracer
    ├── plot-frame
    ├── render-movie
    ├── batch-parallel-render
    ├── merge-parallel-render
    └── interpolate-movie

See CLI Reference for full usage.