Ray Tracer Driver

The RayTracer driver follows deterministic ray paths through the simulation domain (vs. the MCRT driver's stochastic photon transport). Use it for:

• Projections: column density maps, temperature-weighted projections
• Volume rendering: 3D visualization with transfer functions
• Line tracers: quantities along specific sight lines

Architecture

flowchart TD
    subgraph RayTracer["RayTracer Driver"]
        init[Initialize] --> run[run]
        run --> proj[run_projections]
        run --> trace[run_tracers]
        run --> abs[run_absorptiongrids]
    end

    subgraph Operators["Operators"]
        proj --> ProjOp[ProjectionOperator]
        proj --> VolOp[VolumeRenderOperator]
        trace --> TracerOp[TracerOperator]
        abs --> AbsOp[OpticalDepthGridOperator]
    end

    subgraph Kernel["SYCL Kernel"]
        ProjOp --> kernel[evolve_step]
        VolOp --> kernel
        TracerOp --> kernel
        AbsOp --> kernel
        kernel --> field[Field Access]
    end

    field --> smart[SmartFieldAccessor]
    field --> dynamic[DynamicFieldAccessor]

Operators

ProjectionOperator

Computes 2D projections by integrating field values along rays:

Where:

• \(q(s)\) is the quantity being projected (e.g., Temperature)
• \(w(s)\) is the weight field (typically Density)
• \(L\) is the path length through the domain

Configuration example:

raytracer:
  dist_max: 0.7              # maximum ray distance (box widths)
  max_step: 1e-2             # maximum step length
  outputpath: output.zr
  overwrite: true
  linename: FeXXV            # required for line-specific fields
  populate:                   # map derived fields to loaded dataset fields
    Emissivity: "cloudyemission_Fe25 1.85040A"

  operators:
    projections:
      mode: manual
      view: orthogonal        # orthogonal, perspective, or equirectangular
      position: [0.5, 0.5, 0.0]
      direction: [0.0, 0.0, 1.0]
      up: [0.0, 1.0, 0.0]
      npixels: [512, 512]     # [width, height] in pixels
      widths: [1.0, 1.0]      # field of view [x, y] in box units
      fields:
        - Temperature
        - Density
      use_weighting: true      # weight projections by density
      perform_averaging: true  # normalize by total weight (density-weighted average)

Ray Tracer Parameters

Ray Sources

Most raytracer examples put camera keys (mode, view, position, direction, npixels, ...) directly under an operator block. Operators can also use a ray_source: block, which selects a named ray generator and makes the ray layout explicit.

Supported ray_source.type values:

The camera_* sources are the ray_source: spelling of the manual camera path: type determines the camera view, so mode/view are not needed inside the block. Camera animation modes (rotate, traverse, nframes, and explicit frame lists) remain on the legacy inline camera configuration. stereoscopic is rejected under ray_source: because non-image operators size their buffers from the mono ray layout.

Random uniform rays

random_uniform emits n_rays rays with start positions

x, y, z ~ Uniform([0, 1))

in normalized box coordinates. It sets each ray origin to the sampled position. The output layout is Scatter, so rays have no pixel, image, or HEALPix ordering.

Example with random positions and isotropic random directions:

raytracer:
  operators:
    tracers:
      ray_source:
        type: random_uniform
        n_rays: 10000
        direction_distribution: isotropic
        seed: 12345
      fields: [Density]

Example with random positions and a shared fixed direction:

raytracer:
  operators:
    tracers:
      ray_source:
        type: random_uniform
        n_rays: 10000
        direction_distribution: fixed
        direction: [0.0, 0.0, 1.0]
        seed: 12345
      fields: [Density]

Uniform-grid cell centers

grid_centers puts one ray at the center of each cell of a uniform N³ (or [nx, ny, nz]) lattice — a repeatable, volume-uniform seeding of the box.

Dataset point centers

dataset_points seeds one ray per dataset cell — for a Voronoi mesh, the cell-generating sites — or a random count subsample (0 = all, reproducible from seed). Where the grid is volume-uniform, this samples per cell, so rays concentrate where the cells are smallest, i.e. in the dense gas. Needs a dataset with per-cell positions (Voronoi/particle); others report no points and stop.

Scatter layout is currently useful for TracerOperator on one MPI rank. Multi-rank tracer runs reject Scatter sources because distributed skewer merging needs a meaningful camera depth order. Structured-output operators also reject Scatter: ProjectionOperator requires Grid2D or Healpix, while VolumeRenderOperator, OpticalDepthGridOperator, and CoherenceLengthOperator require Grid2D.

VolumeRenderOperator

Performs volume rendering with density-weighted field values for 3D visualization.

TracerOperator

Records a per-ray profile along each sight line: instead of collapsing the ray to a single pixel (as ProjectionOperator does), it stores an ordered list of segments with, for each, the segment's path length and an accumulated quantity (e.g. the mean field value over that segment). Output is therefore a ragged, per-ray structure ("skewers"), not a 2D image — so it accepts any ray layout (Grid2D, Healpix, or Scatter ray sources).

The operator is built from four orthogonal, JIT-specialized choices:

1. What ends a segment — the close rule.
2. What is accumulated within a segment — the accumulator.
3. How the ray itself propagates — the propagation mode (straight, or field-aligned / curved).
4. What ends the whole ray — the stop rule (in addition to the always-on dist_max / domain-exit / stuck-ray terminators).

Segment model: close rule + accumulator

Only these (close_rule, accumulator) pairs are supported; any other combination terminates at startup:

Curved-ray propagation

By default rays travel straight. Setting propagation_mode: field_aligned makes each ray follow a vector field (direction_field) cell-by-cell — it becomes a streamline. The ray source then only seeds the field-line entry points; the path is determined by the field. This is the same DirectionFunctor abstraction the CoherenceLengthOperator uses, so a field-aligned tracer measures, e.g., the coherence length of a magnetic field line and the mean |B| along it in one pass.

Ray-stop rule

The close rule decides where a segment ends; the stop rule decides where the whole ray ends. They are orthogonal. By default (stop_rule: never) a ray runs until one of the always-on terminators fires — raytracer.dist_max, leaving the domain, or the stuck-ray guard. stop_rule: angle_threshold adds an early termination: the ray ends when direction_field bends past stop_angle_threshold.

stop_angle_reference chooses what the rotation is measured against, exactly like angle_reference does for the close rule:

• continuous (default) — compares each cell to the previous one, so the ray stops at the first adjacent cell-to-cell bend exceeding the threshold.
• cumulative — compares each cell to the ray's seed direction, so the ray stops once the field has drifted past the threshold relative to where it started (there is no re-seed — a stop ends the ray).

The angle is measured on the raw field direction — the stop does not apply flip_anti_parallel. A ~180° reversal of the field between cells therefore exceeds any sub-180° threshold and terminates the ray (a field reversal is treated as a genuine coherence break). This matches the close rule's angle convention; note it differs from propagation_mode: field_aligned, which does flip so the ray keeps heading forward through a reversal — so a field-aligned ray can coast through a reversal while the stop rule ends it there.

The canonical pairing is close_rule: every_cell + stop_rule: angle_threshold: it logs every cell (full per-cell fidelity) but only until the field bends, giving a bounded, physically meaningful per-ray length. That bound is what keeps a per-cell trace tractable at full resolution — an unbounded every_cell trace runs to dist_max and emits orders of magnitude more entries.

Configuration

The camera-grid keys (mode, view, position, direction, up, npixels, widths, …) are shared with the projection operators — see Projection Parameters, View Types, and Camera Modes. The tracer-specific keys:

Output

Written under the tracers/<field>/ zarr group as flat arrays indexed by a per-ray offsets table. The written arrays are compacted: ray i's entries occupy [offsets[i], offsets[i+1]) exactly (last ray runs to the end of the array), so its segment count is offsets[i+1] - offsets[i] — no padding. Naming note: the array called lengths is not a segment count: under weighted_mean it holds the per-segment path lengths (in normalized box units); under length_only it stays zero and the segment length is written to contributions instead (see the table).

Distributed (MPI) support

TracerOperator has MPI support for the legacy/default tracer mode: close_rule: every_cell, accumulator: weighted_mean, propagation_mode: straight, and stop_rule: never. This path is covered by the tracer_mpi, tracer_mpi_pbc, and tracer_mpi_pbc_offaxis regression tests, which compare multi-rank output against a one-rank baseline.

The newer tracer modes are single-rank only. propagation_mode: field_aligned, close_rule: angle_threshold, and stop_rule: angle_threshold terminate at startup under MPI: field-aligned rays bend away from the precomputed per-rank segment table, angle-threshold segmentation would over-split at every rank boundary, and the angle stop's per-ray reference cannot follow a ray across a rank handoff. Scatter ray sources (e.g. random_uniform) are likewise single-rank because they have no meaningful camera depth axis to merge.

Examples

Classic per-cell skewer (default), Density along an orthographic grid:

raytracer:
  operators:
    tracers:
      mode: manual
      view: orthogonal
      position: [0.01, 0.5, 0.5]
      direction: [1.0, 0.0, 0.0]
      npixels: [256, 256]
      widths: [0.98, 0.98]
      fields: [Density]
      # close_rule: every_cell, accumulator: weighted_mean, weight: density (defaults)

Magnetic field-line coherence length and mean |B| per segment (curved ray):

raytracer:
  dist_max: 1.1          # REQUIRED for field_aligned; max path length to trace
  operators:
    tracers:
      mode: manual
      view: orthogonal
      position: [0.01, 0.5, 0.5]
      direction: [1.0, 0.0, 0.0]   # seeds entry pixels only; path follows B
      npixels: [640, 640]
      widths: [0.98, 0.98]
      fields: [MagneticFieldMagnitude]
      close_rule: angle_threshold
      accumulator: weighted_mean
      weight: none                 # path-length-weighted (spatial) mean |B|
      angle_threshold: 90.0
      min_segment_length: 2.71e-8  # ~1 pc: drop sub-resolution micro-segments
      propagation_mode: field_aligned
      direction_field: MagneticField
      flip_anti_parallel: true     # required for magnetic (sign-agnostic) fields
      min_field_magnitude: 1.0e-20

Log every cell of a magnetic field line until it kinks (per-cell trajectory dump with a bounded, physically meaningful length — tractable at full resolution because each ray stops at its first bend rather than running to dist_max):

raytracer:
  dist_max: 1.1          # REQUIRED for field_aligned; max path length to trace
  operators:
    tracers:
      mode: manual
      view: orthogonal
      position: [0.01, 0.5, 0.5]
      direction: [1.0, 0.0, 0.0]
      npixels: [640, 640]
      widths: [0.98, 0.98]
      fields: [PositionX, PositionY, PositionZ, MagneticFieldMagnitude]
      close_rule: every_cell       # one entry per cell (full per-cell path)
      accumulator: weighted_mean
      weight: none
      propagation_mode: field_aligned
      direction_field: MagneticField
      flip_anti_parallel: true
      stop_rule: angle_threshold   # end the ray at the first bend...
      stop_angle_threshold: 30.0
      stop_angle_reference: continuous   # ...measured cell-to-cell

Projection Parameters

View Types

For perspective view, an additional fov_up parameter (in degrees, default 90) controls the vertical field of view.

For healpix, a single camera position emits one ray per HEALPix pixel; the output is a 1D zarr array of length 12 * nside² (RING ordering). Required extra keys:

The angular frame is box z-up: theta is measured from +z, phi increases from +x toward +y, regardless of camera basis. The dataset carries a healpix attribute block (nside, ordering, frame, npix) in its zarr attributes; downstream Python code can call healpy.pix2ang(nside, ipix) directly on the index. Example:

projections:
  mode: manual
  view: healpix
  nside: 16             # 12 * 16² = 3072 pixels (Smith+19 convention)
  position: [0.5, 0.5, 0.5]
  start_dist: 0.005     # optional: skip inner 0.005 box-units (e.g. central SFR core)
  fields: [Density, Temperature]

stereoscopic is not supported in healpix mode.

Camera Modes

The mode parameter controls how rays are generated across frames:

Mode-specific parameters:

• rotate: requires center (point to orbit around)
• traverse: requires travel_distance (total distance to travel along direction)

Field Access

Fields are selected at runtime; see JIT Field Access for the dispatch mechanism.

Output

Results are written to a Zarr store (.zr directory):

• Projections: 2D arrays of shape (npixels_y, npixels_x)
• Volume renders: RGB(A) images
• Tracers: per-ray field profiles

See Raytracer Postprocessing for reading the output.