CLI Reference
thor-tools is the entry point for THOR's Python tools. Sub-commands are registered as plugins by individual packages.
Container commands
container update
Download a registry SIF, validate its structure, and atomically create or replace
the local image. This command is included in the base thor-rt install and
requires Apptainer.
thor-tools container update
thor-tools container update --image omp
thor-tools container update ./thor-omp.sif --image omp
| Argument / option | Default | Description |
|---|---|---|
DESTINATION |
thor-<image>_dev.sif |
Local file to create or replace; parent must exist |
--image |
generic |
Supported choices: generic, omp; each pulls its :dev tag |
--runtime |
apptainer |
Apptainer executable name or path |
Pull and SIF validation failures return a nonzero exit code and preserve the existing image. Differing or unavailable Python/container revisions warn; updates continue by default. See container updates for authentication, Python usage, and update behavior.
container list
List supported image names and their fixed registry URLs without contacting the
registry. Only generic and omp are supported.
Reference Data
The base package provides thor-tools prepare list, fetch, verify, and package.
It can download versioned catalogs, verify checksums and Cloudy table formats,
and print the YAML paths needed by a simulation. See
Preparing reference data for catalog manifests and usage.
MCRT Commands
All MCRT commands take a THOR configuration YAML file as the first argument.
mcrt projection create
Create a 2D surface brightness projection from MCRT photon data.
thor-tools mcrt projection create config.yaml
thor-tools mcrt projection create config.yaml --type peel --nbins 512 --zoom 2.0
thor-tools mcrt projection create config.yaml -o projection.png -f png --no-show
| Option | Short | Default | Description |
|---|---|---|---|
--type |
-t |
peel |
Photon type: input, peel, or original |
--nbins |
-n |
Number of pixels per side | |
--size |
-s |
Image size in simulation units | |
--zoom |
-z |
1.0 |
Zoom factor |
--vmin |
Minimum value for color scale | ||
--vmax |
Maximum value for color scale | ||
--output |
-o |
Output file path | |
--format |
-f |
npz |
Output format: npz or png |
--show/--no-show |
--no-show |
Show interactive plot window |
mcrt spectrum plot
Extract and plot a spectrum from MCRT photon output, with optional analytic overlay.
thor-tools mcrt spectrum plot config.yaml
thor-tools mcrt spectrum plot config.yaml --compare-analytic sphere --tau0 1e6 --show
thor-tools mcrt spectrum plot config.yaml --xaxis dlambda --nbins 100 --range "-20,20"
| Option | Short | Default | Description |
|---|---|---|---|
--type |
-t |
original |
Photon type: input, peel, or original |
--global |
-g |
off | Use all photons (no aperture filter) |
--aperture |
-a |
Aperture radius in arcseconds | |
--center |
domain center | LOS center as 'x,y,z' |
|
--nbins |
-n |
50 |
Number of histogram bins |
--range |
-r |
auto | Histogram range as 'min,max' |
--xaxis |
-x |
x |
x (dimensionless frequency) or dlambda (Angstrom) |
--temperature |
-T |
2e4 |
Gas temperature [K] for x-axis conversion |
--compare-analytic |
Overlay analytic solution: sphere or slab (requires --tau0) |
||
--tau0 |
Line-center optical depth for analytic comparison | ||
--output |
-o |
Output directory for plots | |
--show/--no-show |
--no-show |
Show interactive plot | |
--save-data |
off | Save spectrum data as .npz |
Photon Traces
Traces are a debug feature: when enabled via mcrtsimulation.trace.blocksize in the config, the C++ kernel records each photon's position, cell, state, and frequency offset at every step to <outputpath>/traces/data.h5. The traces sub-commands analyze that file.
mcrt traces analyze
Visualize individual photon trajectories from trace output.
thor-tools mcrt traces analyze config.yaml --photon-id 42 --type 3d
thor-tools mcrt traces analyze config.yaml -p 0 -t all --save -o plots/
| Option | Short | Default | Description |
|---|---|---|---|
--photon-id |
-p |
0 |
Photon ID to analyze |
--type |
-t |
3d |
Plot type: 3d, 2d, state, sphere, or all |
--color-by |
-c |
dfreq |
Color field: dfreq, state, or none |
--output |
-o |
Output directory for plots | |
--format |
-f |
png |
Image format: png, pdf, or svg |
--show/--no-show |
--show |
Show interactive plot | |
--save/--no-save |
--no-save |
Save plots to files |
mcrt traces info
Display summary statistics for a traces dataset.
| Option | Short | Default | Description |
|---|---|---|---|
--photon-id |
-p |
Show info for a specific photon ID |
mcrt traces summary
Create a summary plot showing distributions across all traced photons.
| Option | Short | Default | Description |
|---|---|---|---|
--output |
-o |
Output file for summary plot | |
--format |
-f |
png |
Image format: png, pdf, or svg |
--show/--no-show |
--show |
Show interactive plot |
mcrt traces compare
Compare multiple photon traces in a single 3D plot.
| Option | Short | Default | Description |
|---|---|---|---|
--photon-ids |
-p |
0,1,2 |
Comma-separated list of photon IDs |
--output |
-o |
Output file for plot | |
--format |
-f |
png |
Image format: png, pdf, or svg |
--show/--no-show |
--show |
Show interactive plot |
Raytracer Commands
Operate on application directories containing .zr (Zarr) output files.
raytracer plot-frame
Plot a single frame from raytracer output.
thor-tools raytracer plot-frame ./my_sim/
thor-tools raytracer plot-frame ./my_sim/ --field temperature --frame 5
thor-tools raytracer plot-frame ./my_sim/ --list-fields
| Option | Short | Default | Description |
|---|---|---|---|
--field |
-f |
temperature |
Field to plot |
--frame |
0 |
Frame index | |
--output |
-o |
Output file path | |
--width |
Physical width in pkpc | ||
--show |
off | Show plot interactively instead of saving | |
--list-fields |
off | List available fields and exit | |
--config |
config.yaml |
Config file name in the app directory | |
--verbose |
-v |
off | Debug output |
raytracer render-movie
Render a movie from a frame sequence. Requires ffmpeg.
thor-tools raytracer render-movie ./my_sim/
thor-tools raytracer render-movie ./my_sim/ --field emissivity --fps 24 -j 8
| Option | Short | Default | Description |
|---|---|---|---|
--field |
-f |
first from config | Base field name |
--framerate |
--fps |
10 |
Video framerate |
--output |
-o |
Output movie filename | |
--width |
Physical width in pkpc | ||
--nworkers |
-j |
16 |
Parallel rendering workers |
--max-frame |
Maximum frame number to render (inclusive) | ||
--keep-frames |
off | Keep individual frame PNGs after movie creation | |
--overwrite |
off | Overwrite existing frames and movie | |
--watermark/--no-watermark |
--watermark |
Add version watermark | |
--list-fields |
off | List available fields and frame sequences | |
--config |
config.yaml |
Config file name | |
--verbose |
-v |
off | Debug output |
raytracer batch-parallel-render
Create parallel SLURM jobs for rendering by chunking frames.
thor-tools raytracer batch-parallel-render ./my_sim/ --njobs 8
thor-tools raytracer batch-parallel-render ./my_sim/ --njobs 4 --submit
| Option | Short | Default | Description |
|---|---|---|---|
--njobs |
-j |
4 |
Number of parallel jobs |
--template |
-t |
Path to custom SLURM job template file | |
--dry-run |
off | Show what would be created without executing | |
--submit |
off | Automatically submit SLURM jobs after creation | |
--overwrite |
off | Overwrite existing parallel job files |
raytracer merge-parallel-render
Merge projection outputs from parallel rendering jobs into a single Zarr store.
thor-tools raytracer merge-parallel-render ./my_sim/
thor-tools raytracer merge-parallel-render ./my_sim/ --force --verbose
| Option | Short | Default | Description |
|---|---|---|---|
--output |
-o |
app directory | Output directory for merged results |
--overwrite |
off | Overwrite existing merged output | |
--dry-run |
off | Show what would be merged without executing | |
--force |
off | Force merge even if some jobs haven't finished | |
--verbose |
-v |
off | Debug output |
raytracer interpolate-movie
Render a movie with AI frame interpolation (FILM). Requires tensorflow:
| Option | Short | Default | Description |
|---|---|---|---|
--field |
-f |
temperature |
Base field name |
--interpolation-factor |
1 |
Interpolated frames to insert between each pair | |
--framerate |
--fps |
10 |
Video framerate |
--output |
-o |
Output movie filename | |
--width |
Physical width in pkpc | ||
--nworkers |
-j |
4 |
Parallel rendering workers |
--batch-size |
3 |
Consecutive frames per batch | |
--keep-frames |
off | Keep individual frame PNGs | |
--overwrite |
on | Overwrite existing frames and movie | |
--watermark |
on | Add watermark | |
--verbose |
-v |
off | Debug output |