Configuration Reference

Thor uses YAML configuration files. This page documents all available options.

File Structure

# Global settings
## Required
dataset_type: 'shellmodel'
driver_type: 'mcrtsimulation'

## Optional
device: "cpu"          # options: "cpu", "cpu-openmp", "gpu", "multigpu"
log_level: info        # options: trace, debug, info, warn, error
log_dir: "./logs"

# Dataset section (name must match dataset_type)
shellmodel:
  # ...

Global Settings

Device Options

Dataset Types

• shellmodel - Spherical shell
• powerlaw_shellmodel - Power-law shell profiles
• unigrid - Uniform Cartesian grid
• infiniteslab - Infinite slab
• pointcloud_voronoi - Voronoi tessellation (experimental)
• pointcloud_voronoi_tree - Tree-accelerated Voronoi (incomplete)
• pointcloud_sph - SPH interpolation (incomplete)

Driver Types

• mcrtsimulation - Monte Carlo Radiative Transfer
• raytracer - Forward ray tracing (projections, absorption spectra, tracers, etc)

MCRT Simulation Settings

mcrtsimulation:
  outputpath: output
  overwrite: true
  linename: Lya

  # Photon control
  nphotons_max: 100000
  nphotons_step_max: 100000
  nsteps_per_photon_max: 10000000

  # Physics
  xcrit: 3.0
  acc_scheme: Smith15
  interactor: ResonantWithDustInteractor

  # Stepping
  max_step: 1.0
  min_step: 0.0

  # Boundary conditions
  pbc: false
  hubble_flow: 300.0       # km/s/Mpc (for cosmological simulations)

  # Peeling
  use_peeling: true
  peeling:
    dist_max: 0.6
    tau_max: 100.0

  # Emission model
  emissionmodel:
    # ...

  # Output processors
  outputprocessors:
    # ...

MCRT Parameters

Line Names

The linename selects the resonant line to simulate. It determines the scattering cross-section, the ion density field that drives opacity, and which Cloudy emission/absorption fields to load. Use one of the following abbreviations:

Acceleration Schemes

Only use values other than none with Lyman-alpha.

Interactors

Debug Settings

Optional settings for diagnosing photons that may be stuck in infinite loops:

mcrtsimulation:
  debug:
    stuck_photon_print: true
    stuck_photon_finish: false

A photon is flagged as "potentially stuck" when it exceeds nsteps_per_photon_max steps within a single kernel invocation. This is a heuristic, not a definitive indicator—in high-density regions, a photon may legitimately undergo many scatterings before escaping. The flag simply identifies photons that have taken an unusually high number of steps.

Actual stuck photons are typically caused by geometric edge cases (e.g., photons trapped at cell boundaries or tangent to spherical shells) or numerical precision issues where the photon makes near-zero progress per step.

When stuck_photon_print is enabled, the simulation logs:

• The number of potentially stuck photons
• Position and direction of the first flagged photon

Peeling Settings

When use_peeling: true, peeling photons are generated at each scattering event and propagated towards the observer:

mcrtsimulation:
  use_peeling: true
  peeling:
    dist_max: 0.6       # maximum observer distance (box widths)
    tau_max: 100.0       # maximum optical depth before discarding peel

Emission Models

Single Source

emissionmodel:
  mode: "singlesource"
  singlesource:
    nphotons: 1000
    lum_total: 1e42
    position: [0.5, 0.5, 0.5]
    forced_weight: 1.0  # optional

List Source

emissionmodel:
  mode: "listsource"
  listsource:
    loader: gadget
    nphotons_per_source_min: 1
    nphotons_per_source_max: 1000

Dataset Source

emissionmodel:
  mode: "datasetsource"
  datasetsource:
    # Uses emission field from dataset loader

Output Processors

We allow for different raw and processed outputs. The most commonly used output format for now is the raw Monte Carlo photon output.

Each processor entry supports the following common parameters:

Stream Filtering

THOR runs up to three photon streams: original (escaped photons), peel (peeling-off photons), and input (initial photon state). By default, each output processor is active for all streams. The streams parameter restricts a processor to specific streams:

outputprocessors:
  - type: "photon"
    active: true

  - type: "sbmap"
    streams: ["peel"]        # only process peeling photons (default for sbmap)
    nbins_x: 64
    nbins_y: 64
    left_x: 0.0
    right_x: 1.0
    left_y: 0.0
    right_y: 1.0
    weight: "weight"

  - type: "histogram1d"
    # no streams → active for all streams
    field: "dlambda"
    weight: "weight"
    left: -1.5
    right: 1.5
    nbins: 30
    assess_convergence: true
    convergence_threshold: 0.1

Some processors have built-in defaults: sbmap defaults to streams: ["peel"] since it infers the line of sight from the photon direction, which is only well-defined for peeling photons.

Photon Output

Writes escaped photon data to HDF5.

Histogram 1D

Bins photon field values into a histogram (e.g., spectrum).

Surface Brightness Map (sbmap)

Projects photon positions onto a 2D image plane perpendicular to the line of sight. Produces an HDF5 dataset at /sbmap/image.

The image frame is computed from the line of sight direction and the north hint vector. By default, the LOS is inferred from the first photon's direction, which is correct for peeling photons (all share the same direction). For non-peel streams, provide an explicit line_of_sight and override streams.

Dataset-Specific Configuration

See Datasets for detailed configuration of each dataset type.