Python Packages

Work in Progress

APIs may change and features may be incomplete.

Python packages for post-processing, visualization, and C++ access.

Two Ways to Install

1. As Python packages — pip install into a virtual environment for programmatic access or package development.

2. As a CLI tool (thor-tools) — uv tool install for the thor-tools command on PATH, with isolation managed by uv.

Packages

Package	Purpose
`thor-rt`	Python tools: shared utilities, MCRT analysis, raytracer visualization, workflow helpers, and `thor-tools` CLI
`thor-live`	Python client for live THOR sessions
`thor-mcp`	MCP interface to THOR; depends on `thor-live`
`thor-bindings`	C++ Python bindings via nanobind
`thor-testkit`	Regression test tools (internal)

Full Python environment (without C++ bindings)

From the repository root:

uv sync --extra all
source .venv/bin/activate

The repository's all extra installs thor-rt with its MCRT, raytracer, and absorption extras, plus thor-live, thor-mcp, and thor-testkit. It also includes the root documentation dependencies and default development group. It does not install or compile thor-bindings. Install the optional TensorFlow interpolation extra separately if needed.

Use uv sync --extra all for updates too. Include the extra when running commands through uv, for example uv run --extra all thor-tools --help, or activate .venv and run commands directly. A plain uv sync does not select this extra. --all-packages selects every workspace member, including thor-bindings.

The repository-level all extra selects the full Python environment; thor-rt[all] below selects only the analysis extras of that individual package.

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:

venv (standard library)uvconda

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

Packages live under python/ and use standard pyproject.toml builds.

Python package (into your environment)

With your virtual environment activated:

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[absorption]" # Absorption / sightline τ tools
pip install -e "$THOR_PATH/python/thor-rt"             # Shared utilities, container updates, and reference-data preparation

Some absorption functions need the C++ bindings

The τ engine (thor.absorption.compute_tau / tau_line / tau_lyman_continuum) calls thor-bindings. The absorption extra does not install that compiled package. If the bindings are missing, these functions raise an ImportError with installation instructions.

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 with uv's tool manager (uv manages an isolated environment for you):

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

# Base utilities, including reference-data preparation
uv tool install "$THOR_PATH/python/thor-rt"

# 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

The thor-rt package provides the thor-tools entry point. MCRT and raytracer sub-commands register as plugins:

thor-tools
├── container
│   ├── list
│   └── update

├── prepare
│   ├── list
│   ├── fetch
│   ├── verify
│   └── package
├── common
│   └── mesh-cache info
├── mcrt
│   ├── projection create
│   ├── spectrum plot
│   └── traces {analyze, info, summary, compare}
├── raytracer
│   ├── plot-frame
│   ├── render-movie
│   ├── batch-parallel-render
│   ├── merge-parallel-render
│   └── interpolate-movie
└── absorption
    └── abs-spectrum

See CLI Reference for full usage.

The base package also exposes thor.container.update_image() for downloading and updating Apptainer images from Python. See container updates for CLI and Python examples.

The base package also provides thor-tools prepare list, fetch, verify, and package. See Preparing reference data for installation and catalog details.