CLI Reference

The thor-tools command is the unified entry point for all THOR Python tools. Sub-commands are registered as plugins by individual packages.

thor-tools --help

MCRT Commands

Provided by thor-rt. All 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

Photon Traces

Traces are a debug feature of the MCRT simulation. When enabled via mcrtsimulation.trace.blocksize in the config, the C++ kernel records each photon's position, cell, state, and frequency offset at every propagation step. The output is written to <outputpath>/traces/data.h5. The traces subcommands analyze this HDF5 output.

`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.

thor-tools mcrt traces info config.yaml
thor-tools mcrt traces info config.yaml --photon-id 42

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.

thor-tools mcrt traces summary config.yaml -o summary.png

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.

thor-tools mcrt traces compare config.yaml --photon-ids 0,1,2,5

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

Provided by thor-rt. 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-based frame interpolation using Google's FILM model. Requires tensorflow:

uv pip install -e "python/thor-rt[interpolation]"

thor-tools raytracer interpolate-movie ./my_sim/ --field emissivity --interpolation-factor 3

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

Plugin System

The CLI uses Typer with an entry-point plugin system. Each package registers its commands via pyproject.toml:

[project.entry-points."thor_tools.plugins"]
mcrt = "thor.mcrt.commands:app"

At startup, thor-tools discovers all entry points in the thor_tools.plugins group and registers them as sub-commands.