Code description

Here, I'll try to provide some high-level guidance when reading the Sunrise source code. As always, the ultimate documentation is the code itself, so for this to make sense, you should probably open up the Doxygen class hierarchy in another window and keep them side by side.

This description will mostly pertain to the mcrx code. The code in sfrhist is neither that interesting nor as complicated as the radiation transfer code.

Basic code structure

The basic idea behind the Sunrise code was to subdivide the functionality needed for the radiation transfer calculation into distinct parts that are as independent as possible and that can be substituted if different behavior is needed.

Many of these classes are templated on any of three template parameters, the "chromatic policy" which determines whether it should have mono- or polychromatic functionality, the "rng_policy" which determines how the random numbers are drawn (whether there is a global or thread-local RNG), and the "sampling policy" which determines how sampling of a distribution of discrete items should take place (using either rejection sampling or the cumulative distribution). In practice, it's the polychromatic policy, the thread-local RNGs, and sampling from the cumulative distribution that's used.

The fundamental components are:

• Sources -- The radiation in the calculation needs to come from somewhere. There are a number of classes inheriting from emission that create rays based on some distribution. There is everything from point sources to collimated beams, "fuzzy particles" (the star particles in SPH simulations), emission from the cells in the grid itself (used for the dust emission), and uniform external illumination.

• The grid -- The geometry of the dust is defined with a grid class, adaptive_grid, which is subclassed into concrete classes depending on the exact application. These concrete classes (full_sed_grid, ir_grid, aux_grid) that implement the specific way of loading and saving the contents of the grid.

The grid supplies a few crucial methods used in the ray tracing, so should (in principle) be easy to substitute with a different class, for example for spherical coordinates or unstructured meshes, though this has so far never been done. The operations the grid/cell classes need to provide are essentially finding intersections between rays and cell boundaries and calculating the column density along a given ray.

Behind the scenes, the grid is implemented with the classes grid_base which provides the basic functionality of a Cartesian grid, dynamic_grid which is a dynamically allocated Cartesian grid of arbitrary dimensions, and octogrid which is a 2 cubed grid. The class grid_cell represents a cell in a grid, and this cell can contain either data (an arbitrary class) or a subgrid. The way the grid is set up, the base grid is a dynamic_grid, and all subgrids are cells that contain an octogrid.

• The data in the grid cells -- The content of the grid cells are an absorber object, that keeps the density of the scattering species and the intensity of the radiation field in the grid cell.

• The cameras -- The images of the outgoing radiation is handled by an emergence object, which in turn holds one or more camera objects. There are a number of concrete subclasses of emergence (full_sed_emergence, aux_emergence) that know how to interpret the content of the cameras and save them to the output file.

• The ray -- The ray class implements a ray propagating with some (arbitrary) content.

• The radiation transfer object -- Finally, the class responsible for putting it all together is xfer. The xfer object does the actual transfer of radiation. It calls the emission object to create rays, propagates them through the grid while adding their radiation intensity to the absorber, and adds the rays that leave the volume to the emergence. By calling the shoot() method, one ray is emitted, propagated through the volume (potentially scattering), and registered with the cameras. All details of the radiation transfer are contained in this class.