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:

\[ P(x,y) = \int_0^L q(s) \cdot w(s) \, ds \]

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

Parameter	Type	Default	Description
`dist_max`	float	-	Maximum ray distance (in box widths)
`max_step`	float	`1.0`	Maximum step length along the ray
`min_step`	float	`0`	Minimum step length
`outputpath`	string	required	Output file path
`overwrite`	bool	`false`	Overwrite existing output
`linename`	string	-	Spectral line name (required for line-specific fields)
`populate`	dict	-	Maps derived field names to dataset field names
`kernel_stats`	bool	`false`	Compute kernel execution statistics

VolumeRenderOperator

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

TracerOperator

Traces rays and records field values at each cell traversal, producing per-ray profiles.

Projection Parameters

Parameter	Type	Default	Description
`mode`	string	required	Camera mode (see below)
`view`	string	`"orthogonal"`	Projection type (see below)
`fields`	list	required	Fields to project
`npixels`	list	`[128, 128]`	Resolution as `[width, height]`
`widths`	list	-	Field of view `[x, y]` in box units
`position`	list	`[0.5, 0.5, 0.5]`	Camera position `[x, y, z]` in normalized coords
`direction`	list	-	View direction `[x, y, z]` (unit vector)
`up`	list	`[0, 1, 0]`	Up vector `[x, y, z]` (unit vector)
`nframes`	int	`1`	Number of frames (for `rotate`/`traverse` modes)
`use_weighting`	bool	`true`	Weight projections by density field
`perform_averaging`	bool	`true`	Normalize by total weight (density-weighted average)
`invert`	bool	`false`	Invert ray direction

View Types

Value	Description
`"orthogonal"`	Parallel projection (default)
`"perspective"`	Perspective projection with field of view
`"equirectangular"`	360° equirectangular projection
`"healpix"`	Equal-area all-sky map in HEALPix RING ordering

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:

Parameter	Type	Default	Description
`nside`	int	required	HEALPix resolution; must be a positive power of two.
`ordering`	string	`"ring"`	RING ordering only (NESTED not yet supported).

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]
  fields: [Density, Temperature]

stereoscopic is not supported in healpix mode.

Camera Modes

The mode parameter controls how rays are generated across frames:

Mode	Description
`manual`	Explicit position, direction, and up vectors
`rotate`	Rotate camera around a `center` point over `nframes`
`traverse`	Move camera along `direction` by `travel_distance` over `nframes`

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.