Simulation Parameters

This page explains the options for configuring COLT simulations.

Configuration Files

COLT uses the yaml-cpp library to allow for flexible and convenient configuration of run-time parameters. We introduce the config.yaml file with the following example:

# COLT config file
--- !mcrt                     # Monte Carlo radiative transfer module

init_dir: ics                 # Initial conditions directory (default: "ics")
init_base: colt               # Initial conditions base name (optional)
output_dir: output            # Output directory name (default: "output")
output_base: Lya              # Output file base name (default: "colt")

cameras:                      # Add camera directions manually
  - [1,0,0]
  - [0,1,0]
  - [0,0,1]

... Additional run-time parameters

The format is essentially a human readable python dictionary of key: value pairs that allows #-style comments and complex specifications such as the above list of camera directions.

The YAML header --- !mcrt specifies which module to run, a convention that sets the module apart from more typical run-time parameters. The value is interpreted in the main file prior to instantiating the simulation to allow high level class polymorphism. By default the MCRT module is assumed in cases where the header line is not included.

Note

COLT configuration is design to be minimally verbose, transparent, and catch common unintended errors. In practice this means that only expected parameters are allowed and an error is raised for unexpected or repeated parameters. If a parameter is not specified then the default value will be assigned. Note that the default may depend on other parameters but this is determined by the code logic, i.e. the order of parameters does not matter. Only a few parameters are actually required, such as the initial conditions file naming scheme.

General Parameters

The following parameters are shared by most modules:

verbose – Verbose output for tests and debugging. [Default value: false]
init_file – Initial conditions file name. [Required if init_base is not specified]
init_dir – Initial conditions directory. [Optional]
init_subdir – Initial conditions subdirectory, e.g. allows ics/snap_000 organization. [Optional]
init_base – Initial conditions file base. [Optional]
init_ext – Initial conditions file extension. [Default value: hdf5]
output_dir – Output directory. [Default value: output]
output_subdir – Output subdirectory, e.g. allows output/snap_000 organization. [Optional]
output_base – Output file base. [Default value: colt]
output_ext – Output file extension. [Default value: hdf5]
snap_padding – Leading zeros for snapshot number formatting. [Default value: 3]
select_subhalo – Optional toggle for the command line subhalo/group specifier. If true then this is interpreted as a subhalo index, otherwise it is interpreted as a group index.

Note

In practice, an initial conditions file may be specified by the full name via init_file or the file pattern <init_dir>/<init_base>_<snapshot>.<init_ext>, which is then mirrored in the convention for output files, e.g. output/colt_000.hdf5.

Cosmological Parameters

The following parameters are related to the cosmology:

cosmological – Flag for cosmological simulations. Note: This is for cosmological vs. intrinsic observers, i.e. it changes the output units but not the physics. [Default value: false]
Omega0 – Matter density in units of the current critical density \(\rho_\text{crit,0}\). [Default value: 0.3111]
OmegaB – Baryon density in units of the current critical density \(\rho_\text{crit,0}\). [Default value: 0.04897]
h100 – Hubble constant in units of 100 km/s/Mpc. [Default value: 0.6766]

Note

Cosmological parameters are needed for calculating observed distances and other module specific quantities. The values are from the Planck mission (2018 results). For consistency, these parameters may also be read from the initial conditions file.

Gas Parameters

The following parameters are related to the gas environment:

constant_temperature – Enforce a constant temperature, \(T\). Note: This overrides automatically reading from the input file. [Optional | Units: K]
T_floor – Apply a temperature floor to all gas cells, \(T_\text{floor}\). [Optional | Units: K]
T_rtol – Relative tolerance for temperature changes, e.g. in photoionization equilibrium calculations. [Default value: 0.1]
electron_fraction – Enforce a constant electron fraction, \(x_e = n_e / n_\text{H}\). [Optional]
HI_fraction or neutral_fraction – Enforce a constant neutral fraction, \(x_\text{HI} = n_\text{HI} / n_\text{H}\). Note: In general, specifying an ionization state overrides automatically reading from the input file. If neither is present, we assume neutral gas compositions. [Optional]
HII_fraction or ionized_fraction – Enforce a constant ionized fraction, \(x_\text{HII} = n_\text{HII} / n_\text{H}\). [Optional]
H2_fraction or molecular_fraction – Enforce a constant molecular hydrogen fraction, \(x_\text{H2} = n_\text{H2} / n_\text{H}\). [Optional]
HeI_fraction – Enforce a constant HeI fraction, \(x_\text{HeI} = n_\text{HeI} / n_\text{He}\). [Optional]
HeII_fraction – Enforce a constant HeII fraction, \(x_\text{HeII} = n_\text{HeII} / n_\text{He}\). [Optional]
HeIII_fraction – Enforce a constant HeIII fraction, \(x_\text{HeIII} = n_\text{HeIII} / n_\text{He}\). [Optional]
CI_fraction – Enforce a constant CI fraction, \(x_\text{CI} = n_\text{CI} / n_\text{C}\). [Optional] Note: This is also available for CII, CIII, CIV, CV, CVI, and CVII.
NI_fraction – Enforce a constant NI fraction, \(x_\text{NI} = n_\text{NI} / n_\text{N}\). [Optional] Note: This is also available for NII, NIII, NIV, NV, NVI, NVII, and NVIII.
OI_fraction – Enforce a constant OI fraction, \(x_\text{OI} = n_\text{OI} / n_\text{O}\). [Optional] Note: This is also available for OII, OIII, OIV, OV, OVI, OVII, OVIII, and OIX.
NeI_fraction – Enforce a constant NeI fraction, \(x_\text{NeI} = n_\text{NeI} / n_\text{Ne}\). [Optional] Note: This is also available for NeII, NeIII, NeIV, NeV, NeVI, NeVII, NeVIII, and NeIX.
MgI_fraction – Enforce a constant MgI fraction, \(x_\text{MgI} = n_\text{MgI} / n_\text{Mg}\). [Optional] Note: This is also available for MgII, MgIII, MgIV, MgV, MgVI, MgVII, MgVIII, MgIX, MgX, and MgXI.
SiI_fraction – Enforce a constant SiI fraction, \(x_\text{SiI} = n_\text{SiI} / n_\text{Si}\). [Optional] Note: This is also available for SiII, SiIII, SiIV, SiV, SiVI, SiVII, SiVIII, SiIX, SiX, SiXI, SiXII, and SiXIII.
SI_fraction – Enforce a constant SI fraction, \(x_\text{SI} = n_\text{SI} / n_\text{S}\). [Optional] Note: This is also available for SII, SIII, SIV, SV, SVI, SVII, SVIII, SIX, SX, SXI, SXII, SXIII, SXIV, and SXV.
FeI_fraction – Enforce a constant FeI fraction, \(x_\text{FeI} = n_\text{FeI} / n_\text{Fe}\). [Optional] Note: This is also available for FeII, FeIII, FeIV, FeV, FeVI, FeVII, FeVIII, FeIX, FeX, FeXI, FeXII, FeXIII, FeXIV, FeXV, FeXVI, and FeXVII.
hydrogen_fraction – Enforce a constant hydrogen mass fraction. Overrides automatically reading \(X\) from the input file. If neither is present, we assume the primordial value of \(X = 0.76\). [Optional | Units: Mass fraction]
helium_fraction – Enforce a constant helium mass fraction. Overrides automatically reading \(Y\) from the input file. If neither is present, we assume the primordial value of \(Y = 1 - X\). [Optional | Units: Mass fraction]
metallicity – Enforce a constant metallicity. Overrides automatically reading \(Z\) from the input file. If neither is present, we assume solar metallicity. [Optional | Units: Mass fraction]
carbon_metallicity – Enforce a constant carbon metallicity, \(Z_\text{C}\). Note: In general, specifying an element specific metallicity overrides automatically reading from the input file. If neither is present, we assume solar scaled abundances, e.g. \(Z_\text{C} = Z_{\odot,\text{C}} (Z / Z_{\odot})\). [Optional | Units: Mass fraction]
nitrogen_metallicity – Enforce a constant nitrogen metallicity, \(Z_\text{N}\). [Optional | Units: Mass fraction]
oxygen_metallicity – Enforce a constant oxygen metallicity, \(Z_\text{O}\). [Optional | Units: Mass fraction]
neon_metallicity – Enforce a constant neon metallicity, \(Z_\text{Ne}\). [Optional | Units: Mass fraction]
magnesium_metallicity – Enforce a constant magnesium metallicity, \(Z_\text{Mg}\). [Optional | Units: Mass fraction]
silicon_metallicity – Enforce a constant silicon metallicity, \(Z_\text{Si}\). [Optional | Units: Mass fraction]
sulfer_metallicity – Enforce a constant sulfer metallicity, \(Z_\text{S}\). [Optional | Units: Mass fraction]
iron_metallicity – Enforce a constant iron metallicity, \(Z_\text{Fe}\). [Optional | Units: Mass fraction]
mass_weighted_metallicities – Adopt mass-weighted average metallicity values. [Default value: false]
dust_to_metal – Enforce a constant dust-to-metal ratio, \(\text{DTM} \equiv \rho_\text{dust} / \rho_Z\). [Optional | Units: Mass fraction]
dust_to_gas – Enforce a constant dust-to-gas ratio, \(\mathcal{D} \equiv \rho_\text{dust} / \rho\). [Optional | Units: Mass fraction]
dust_boost – Rescale the dust values by this boost factor. [Optional]
v_turb – Effective microturbulent velocity. [Default value: 0 | Units: cm/s]
v_turb_kms – Effective microturbulent velocity. [Default value: 0 | Units: km/s]
T_turb – Effective microturbulent temperature. [Default value: 0 | Units: K]
scaled_microturb – Scaled microturbulence model where high density gas is more turbulent. Specifically, \(T_\text{turb} = {\rm K\,km}^2 \rho / (\gamma k_\text{B})\) with an adiabatic index of \(\gamma = 5/3\). [Default value: false]

Note

The microturbulence parameter follows the standard treatment of adding Gaussian line broadening in quadrature: \(b = \sqrt{v_\text{th}^2 + v_\text{turb}^2}\). This acts as an effective temperature floor for line radiative transfer with \(v_\text{turb}^2 = 2 k_\text{B} T_\text{turb} / m_\text{carrier}\).

Camera Parameters

The following parameters are related to controlling cameras:

camera – Add a single camera direction manually in [1 0 0] format. [Optional]
cameras – Add a list of camera directions manually in [1 0 0] format. [Optional]
n_exp – Healpix exponent for camera directions, resulting in \(12 \times 4^{n_\text{exp}}\) directions in RING ordering. [Optional | Valid range: n_exp >= 0]
n_side – Healpix number of base pixel subdivisions for camera directions, resulting in \(12 \times n_\text{side}^2\) directions in RING ordering. [Overrides n_exp | Optional | Valid range: n_side >= 1]
n_rot – Number of rotation camera directions, which are evenly spaced in angle around a common axis, e.g. to make movies. [Optional | Valid range: n_rot > 0]
phi_start – Starting azimuthal angle for rotations. [Requires n_rot | Units: degrees]
phi_end – Ending azimuthal angle for rotations. [Requires n_rot | Units: degrees]
rotate_with_snaps – Flag to offset rotations by the snapshot number. [Requires n_rot | Default value: false]
rotation_axis – Axis for rotation camera directions in [0 0 1] format. [Requires n_rot | Default value: (0,0,1)]
camera_center – Camera target position in [0 0 0] format. [Default value: (0,0,0) | Units: cm]
camera_motion – Camera target velocity in [0 0 0] format. [Default value: (0,0,0) | Units: cm/s]
focus_cameras_on_emission – Focus the camera target position on the center of luminosity. [Default value: false]
shift_cameras_on_emission – Shift the camera target velocity on the center of luminosity. [Default value: false]
align_cameras_on_emission – Rotate the camera target direction to align camera_north with the angular momentum vector based on the center of luminosity. [Default value: false]
camera_north – Camera north orientation in [0 0 1] format. [Default value: (0,0,1)]
image_width – Image width defining a square aperture. Note: Similar setup for slit_width and cube_width. [Units: cm]
image_widths – Image \((x,y)\) widths defining a rectangular aperture. Note: Similar setup for cube_widths. [Units: cm]
image_radius – Image radius or half of the image width. Note: Similar setup for slit_radius and cube_radius. [Units: cm]
image_radii – Image \((x,y)\) radii or half of the image widths. Note: Similar setup for cube_radii. [Units: cm]
image_radius_bbox – Image radius or half of the image width. Note: Similar setup for slit_radius_bbox and cube_radius_bbox. [Units: bounding box]
image_radii_bbox – Image \((x,y)\) radii or half of the image widths. Note: Similar setup for cube_radii_bbox. [Units: bounding box]
n_pixels – Number of \((x,y)\) image pixels. Note: Similar setup for n_cube_pixels. [Default value: 100]
nx_pixels – Number of \(x\) image pixels, overriding n_pixels if both are specified. Note: Similar setup for nx_cube_pixels. [Default value: 100]
ny_pixels – Number of \(y\) image pixels, overriding n_pixels if both are specified. Note: Similar setup for ny_cube_pixels. [Default value: 100]
n_slit_pixels – Number of slit pixels in the spatially-resolved direction. [Default value: 100]
pixel_width – Intrinsic width of each image pixel. Note: Similar setup for slit_pixel_width and cube_pixel_width. [Units: cm]
pixel_widths – Intrinsic \((x,y)\) widths of each image pixel. Note: Similar setup for cube_pixel_widths. [Units: cm]
pixel_arcsec – Observed angular width of each image pixel. Note: Similar setup for slit_pixel_arcsec and cube_pixel_arcsec. [Units: arcseconds]
pixel_arcsecs – Observed angular \((x,y)\) widths of each image pixel. Note: Similar setup for cube_pixel_arcsecs. [Units: arcseconds]
pixel_arcsec2 – Observed angular area of each image pixel. Note: Similar setup for cube_pixel_arcsec2. [Units: arcseconds^2]
slit_aperture – Slit aperture width. [Units: cm]
slit_aperture_arcsec – Observed angular width of the slit aperture. [Units: arcseconds]
radial_image_radius – Radial image radius. Note: Similar setup for radial_cube_radius. [Units: cm]
radial_image_radius_bbox – Radial image radius. Note: Similar setup for radial_cube_radius_bbox. [Units: bounding box]
n_radial_pixels – Number of radial image pixels. Note: Similar setup for n_radial_cube_pixels. [Default value: 100]
radial_pixel_width – Intrinsic width of each radial image pixel. Note: Similar setup for radial_cube_pixel_width. [Units: cm]
radial_pixel_arcsec – Observed angular width of each radial image pixel. Note: Similar setup for radial_cube_pixel_arcsec. [Units: arcseconds]

Note

Some combinations of camera parameters are redundant but the configuration detects inconsistencies and gives sensible error messages to address these. If left unspecified, the cameras are set up to capture the entire domain as defined by the simulation bounding box.

Escape Parameters

The following parameters are related to controlling the conditions for escape:

spherical_escape – Flag to restrict ray-tracing a spherical region. [Default value: false]
escape_center – Center of the escape region in [0 0 0] format. [Default value: (0,0,0) | Units: cm]
escape_radius – Radius for the spherical escape region. [Units: cm]
escape_radius_bbox – Radius for the spherical escape region. [Units: bounding box]
emission_radius – Radius for the spherical emission region. [Units: cm]
emission_radius_bbox – Radius for the spherical emission region. [Units: bounding box]

Additional File Parameters

The following parameters are related to specific additional I/O files:

save_connections – Save the Voronoi connections to a file. [Default value: true]
save_circulators – Save the Voronoi circulators to a file. [Default value: true]
avoid_edges – Avoid ray-tracing through edge cells. [Default value: true]
inner_edges – Flag to also treat inner neighbors of edge cells as edges. [Default value: false]
output_inner_edges – Flag to output inner edge cells (for tracking purposes). [Default value: true]
cgal_file – CGAL connectivity file (optional). [Default value: init_file]
cgal_dir – CGAL connectivity directory (optional). [Default value: init_dir]
cgal_subdir – CGAL connectivity subdirectory, e.g. allows ics/snap_000 organization. [Default value: cgal_dir]
cgal_base – CGAL connectivity file base (optional). [Default value: init_base]
cgal_ext – CGAL connectivity file extension (optional). [Default value: init_ext]

Note

The CGAL connectivity is usually saved to the original initial conditions file for future use. Here we allow the option of either not saving the connections or writing them to a different file.

abundances_file – Abundances initial conditions file (optional). [Default value: init_file]
abundances_dir – Abundances initial conditions directory (optional). [Default value: init_dir]
abundances_subdir – Abundances initial conditions subdirectory, e.g. allows ics/snap_000 organization. [Default value: abundances_dir]
abundances_base – Abundances initial conditions file base (optional). [Default value: init_base]
abundances_ext – Abundances initial conditions file extension (optional). [Default value: init_ext]
abundances_output_file – Abundances output file (optional). [Default value: abundances_file]
abundances_output_dir – Abundances output directory (optional). [Default value: abundances_dir]
abundances_output_subdir – Abundances output subdirectory, e.g. allows ics/snap_000 organization. [Default value: abundances_output_dir]
abundances_output_base – Abundances output file base (optional). [Default value: abundances_base]
abundances_output_ext – Abundances output file extension (optional). [Default value: abundances_ext]

Note

The abundances are usually read/saved to the original initial conditions file for future use. Here we allow the option of reading/writing them to a different file.

Advanced Parameters

The following parameters are related to advanced options:

set_density_from_mass – Set the density by reading the mass and dividing by volume (m expecting units of g). Note: This can be useful for applying density-like analyses methods, e.g. ray-based projections, to point-like data types such as SPH data, star particles, or dark matter. [Default value: false]
read_density_as_mass – Similar to set_density_from_mass but reads the density as a mass-like field before dividing by volume (rho expecting units of g/cm^3). [Default value: false]
use_internal_energy – Set the temperature by reading the (mass) specific internal energy (e_int expecting units of cm^2/s^2). Note: When activated this overrides reading the temperature directly. When the temperature is not present in the initial conditions file and constant_temperature is not set, the default for this flag will update to true. [Default value: false]