Ray Tracer Driver

The RayTracer driver performs deterministic ray tracing through volumetric data, supporting projections, volume rendering, and line-of-sight tracing operations.

Overview

Unlike the Monte Carlo Radiative Transfer (MCRT) driver which simulates stochastic photon transport, the RayTracer follows deterministic ray paths through the simulation domain. This makes it ideal for:

Projections: Column density maps, temperature-weighted projections
Volume rendering: 3D visualization with transfer functions
Line tracers: Extracting 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

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

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

The RayTracer uses runtime field selection, allowing the quantity to project to be specified at runtime rather than compile time. See JIT Field Access for implementation details.

Output

Results are saved as HDF5 datasets:

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

Performance Considerations

Use Release builds for production runs (10-100x faster than Debug)
The number of rays equals npixels_x * npixels_y
Memory scales with ray count and maximum path length