MCRT Ionization Equilibrium

This page explains the options for ionization equilibrium Monte Carlo radiative transfer (MCRT) simulations. The Ionization module produces self-consistent ionization states that can be used as initial conditions for emission lines with the MCRT module.

General Parameters

The following parameters are important module parameters:

n_photons – Number of photon packets used in the simulation. [Default value: 1]
n_photons_per_star – Number of photon packets per star particle. [Optional]
n_photons_max – Maximum number of photon packets allowed when n_photons_per_star is used. [Optional]
max_iter – Maximum number of iterations for the radiative transfer and ionization solver. [Default value: 10 | Valid range: 1 < max_iter < 100]
max_error – Relative error tolerance for convergence in the ionization solver. Note: Convergence is based on the global rate of hydrogen recombinations: \(\int \alpha_\text{B}(T) n_e n_\text{HII} \text{d}V\). [Default value: 0.01 | Valid range: 0 < max_error < 1]
max_error_pre – Relative error tolerance for convergence in the pre-conditioning step of the ionization solver. [Default value: 0.01 | Valid range: max_error <= max_error_pre < 1]
n_photons_pre – Number of pre-conditioning photon packets used in the simulation. [Default value: n_photons]
precondition – Convenience factor to simultaneously decrease the number of photons and increase the max error used in the pre-conditioning step. If set to N, then n_photons_pre = n_photons / N and max_error_pre = max_error * N. [Default value: 1 | Recommended value: 10]

Note

The solver will stop if the relative error is less than max_error or if the maximum number of iterations is reached. To prevent updating the ionization states, set max_iter to 1. Experience shows that the ionization states converge faster when using precondition = 10, which works well for most cases.

charge_exchange – Include charge exchange processes. [Default value: false]
dialectric_recombination – Include dielectric recombination processes. [Default value: false]
output_abundances – Flag to output ionization abundances for each cell, e.g., \(x_\text{HII} = n_\text{HII} / n_\text{H}\)). [Default value: true]
output_iterations – Flag to write intermediate ionization results after each iteration of the radiative transfer solver. [Default value: false]
n_skip_iterations – Number of iterations to skip between writing intermediate ionization results. [Default value: 1 | Valid range: n_skip_iterations >= 1]
output_photons – Flag to output escaped and absorbed photon packets. [Default value: true]
photon_file – Output a separate photon file with this base name, e.g. “photons”. [Optional]
output_n_scat – Flag to output the number of scattering events for photon packets. [Compile-time parameter | Default value: false]
output_absorption_distance – Flag to output the distance traveled until undergoing absorption. [Default value: false]
output_source_position – Flag to output the emission position for photon packets. [Default value: false]
output_{atom}_absorption – Flag to output the absorption due to a specific atom over all ionization species for photon packets. [Default value: false]
output_{ion}_absorption – Flag to output the absorption due to a specific ion for photon packets. [Default value: false]

Note

The {atom} placeholder should be replaced with the atom name, which can be any of the following: hydrogen, helium, carbon, nitrogen, oxygen, neon, magnesium, silicon, sulfer, and iron. The {ion} placeholder should be replaced with the ion name, which can be any of the following: HI, HeI, HeII, CI, CII, CIII, etc.

Ionization Parameters

These parameters control which ions are included in the simulation:

ion_max_eV – Maximum ionization threshold energy to include. [Default value: 100 | Units: eV]
helium_ions – Flag to include all helium ions. [Default value: true]
HeI_ion and HeII_ion – Include HeI and HeII ionization. [Default value: helium_ions]
metal_ions – Flag to include metal ions, i.e. C, N, O, Ne, Mg, Si, S, and Fe. [Default value: false]
{atom}_ions – Flag to include all ions for a specific atom, e.g., silicon_ions for all silicon ions up to ion_max_eV. [Default value: metal_ions]
{ion}_ion – Flag to include a specific ion, e.g., SiIV for all ions up to SiIV.
[Default value: {atom}_ions]
ion_bins – Include frequency bin edges corresponding to ionization thresholds of all ions. [Default value: false]
metal_bins – Include frequency bin edges corresponding to ionization thresholds of all metal ions. [Default value: false | Overrides ion_bins]
{atom}_bins – Include frequency bin edges corresponding to ionization thresholds of all ions for a specific atom. [Default value: false | Overrides ion_bins and metal_bins]
{ion}_bin – Include a frequency bin edge corresponding to the ionization threshold of a specific ion. [Default value: false | Overrides {atom}_bins]
min_bin_eV – Lower limit of the lowest energy bin. [Optional | Units: eV]
min_bin_angstrom – Lower limit of the lowest energy bin in angstroms. [Optional | Units: angstrom]
max_bin_eV – Upper limit of the highest energy bin. [Default value: Corresponds to 1 angstrom | Units: eV]
max_bin_angstrom – Upper limit of the highest energy bin in angstroms. [Optional | Units: angstrom]
max_bin_dex – Maximum frequency bin width in dex (logarithmic scale). [Optional | Valid range: > 0]

Dust Parameters

These parameters define the dust properties in the simulation:

dust_model – Dust model for the radiative transfer setting the dust opacity, albedo, and anisotropy parameters. [Options: SMC, MW, LAURSEN_SMC, filename]
kappa_HI, kappa_HeI, kappa_HeII – Dust opacity in the HI, HeI, and HeII ionizing frequency bins, scaling the absorption coefficient by the dust mass: \(k_\text{dust} = \kappa_\text{dust} \rho_\text{dust}\). [Default value: Based on dust_model | Units: cm^2/g of dust]
albedo_HI, albedo_HeI, albedo_HeII – Dust scattering albedo in the HI, HeI, and HeII ionizing frequency bins, defined as \(A = k_\text{scat} / (k_\text{abs} + k_\text{scat})\). [Default value: Based on dust_model and line | Valid range: 0 < albedo < 1]
cosine_HI, cosine_HeI, cosine_HeII – Anisotropy parameter \(\langle \mu \rangle\) for dust scattering in the HI, HeI, and HeII ionizing frequency bins. [Default value: Based on dust_model and line | Valid range: -1 < cosine < 1]

Radiation Source Parameters

These parameters define the radiation sources in the simulation:

source_file_Z_age – File containing source spectra tabulated as functions of metallicity and age. :dv:[Optional]
source_model – Model for the stellar sources, most of which are predefined for HI, HeI, and HeII. [Default value: “” | Options: GMC, MRT, BC03-IMF-SOLAR, BC03-IMF-HALF-SOLAR, BC03-IMF, BPASS-IMF-135-100, BPASS-CHAB-100, custom]
f_esc_stars – Escape fraction from stellar birth clouds (only applies to 13.6 eV and above). [Default value: 1 | Valid range: 0 < f_esc_stars < 1]
j_exp – Luminosity boosting exponent for power-law emission biasing, i.e. probabilities are rescaled according to \(\propto \mathcal{L}_\text{cell}^{j_\text{exp}}\) such that \(j_\text{exp} < 1\) can better sample lower emissivity regions. [Default value: 1 | Valid range: 0 < j_exp < 1]
V_exp – Volume boosting exponent for power-law emission biasing, i.e. probabilities are rescaled according to \(\propto V_\text{cell}^{V_\text{exp}}\) such that \(V_\text{exp} < 1\) can better sample smaller volume regions. [Default value: 1]
nu_exp – Frequency boosting exponent for power-law emission biasing, i.e. probabilities are rescaled according to \(\propto \nu^{nu_\text{exp}}\) such that \(nu_\text{exp} > 1\) can better sample higher frequency bands. [Default value: 1]
HI_bias – Additional frequency boost factor for HI ionizing photons above the minimum energy threshold (13.6 eV). [Default value: 1 | Valid range: >=1]

Gas Emission Parameters

These parameters control gas emission processes:

free_free – Include free-free continuum emission. [Default value: false]
free_bound – Include free-bound continuum emission. [Default value: false]
two_photon – Include two-photon continuum emission. [Default value: false]

AGN Source Parameters

These parameters define the AGN sources in the simulation:

AGN_model – Model for the AGN source. [Optional | Options: Stalevski12, Lusso15]
Lbol_AGN – Bolometric luminosity of the AGN. Can also be specified in solar luminosities. [Default value: 1e11 Lsun | Units: erg/s]

Point Source Parameters

These parameters define point sources in the simulation:

point – Point source position in [x y z] format. [Optional | Units: cm]
x_point, y_point, z_point – Point source \((x, y, z)\) coordinates. [Optional | Units: cm]
T_point – Temperature of the point source blackbody spectrum. [Required if point_source is true | Units: K]
Lbol_point – Bolometric luminosity of the point source. [Optional | Units: erg/s]
L_point – Luminosity of the point source in the specified energy range. [Optional | Units: erg/s]
Ndot_point – Photon rate of the point source. [Optional | Units: photons/s]
kappa_point – Dust opacity for the point source. [Default value: Based on dust_model | Units: cm^2/g of dust]
albedo_point – Dust scattering albedo for the point source. [Default value: Based on dust_model | Valid range: 0 < albedo < 1]
cosine_point – Dust scattering anisotropy parameter for the point source. [Default value: Based on dust_model | Valid range: -1 < cosine < 1]

Plane Source Parameters

These parameters define plane sources in the simulation:

plane_direction – Direction of the plane source. [Options: ‘+x’, ‘-x’, ‘+y’, ‘-y’, ‘+z’, ‘-z’]
T_plane – Temperature of the plane source blackbody spectrum. [Required if plane_source is true and source_file_Z_age is not specified | Units: K]
Sbol_plane – Plane bolometric surface flux. [Optional | Units: erg/s/cm^2]
Lbol_plane – Plane bolometric luminosity. [Optional | Units: erg/s]
L_plane – Luminosity of the plane source in the specified energy range. [Optional | Units: erg/s]
Ndot_plane – Photon rate of the plane source. [Optional | Units: photons/s]
plane_beam – Use an ellipsoidal beam instead of a rectangular plane. [Default value: false]
plane_center_x_bbox, plane_center_y_bbox, plane_center_z_bbox – Center of the plane source in bounding box units. [Valid range: 0 < value < 1]
plane_radius_x_bbox, plane_radius_y_bbox, plane_radius_z_bbox – Radii of the plane source in bounding box units. [Valid range: > 0]
kappa_plane – Dust opacity for the plane source. [Default value: Based on dust_model | Units: cm^2/g of dust]
albedo_plane – Dust scattering albedo for the plane source. [Default value: Based on dust_model | Valid range: 0 < albedo < 1]
cosine_plane – Dust scattering anisotropy parameter for the plane source. [Default value: Based on dust_model | Valid range: -1 < cosine < 1]

UV Background Parameters

These parameters control the inclusion of a UV background:

UVB_model – UV background model to use. [Optional | Options: FG11, etc.]
self_shielding – Include UV background self-shielding in dense regions. [Default value: false]

Probe Output Parameters

These parameters control various probe output options:

output_stars – Flag to output the emission and escape data for each star. [Default value: false]
output_cells – Flag to output the emission and escape data for each cell. [Default value: false]
output_cells_UVB_HI – Output cell UV background ionization for HI. [Default value: false | Units: photons/s]
output_cells_rec_{ion} – Output cell recombination rates for a specific ion. [Default value: false | Units: photons/s]
output_cells_col_{ion} – Output cell collisional ionization rates for a specific ion. [Default value: false | Units: photons/s]
output_cells_phot_{ion} – Output cell photoionization rates for a specific ion. [Default value: false | Units: photons/s]
output_cells_cx_{ion} – Output cell charge exchange rates for a specific ion. [Default value: false | Units: photons/s]
output_photoionization – Flag to output species photoionization rate integrals for each cell. [Default value: false | Units: photons/s/carrier]
output_photoheating – Flag to output the total photoheating rate for each cell. [Default value: false | Units: erg/s]
output_photon_density – Flag to output the photon density for each cell and frequency bin. [Default value: false | Units: photons/cm^3]

Observed Output Parameters

This section describes the output options for MCRT simulations, including angle-averages, peel-off cameras, and directional binning parameters.

Angle-averaged Parameters

The following parameters are related to angular-averaged escape options:

output_radial_avg – Output angle-averaged radial surface brightness. [Default value: false]
output_bin_radial_avg – Output angle-averaged bin radial surface brightness. [Default value: false]

Camera Parameters

The following parameters are related to cameras options:

output_escape_fractions – Output camera escape fractions. [Default value: true | Dimensions: (n_cameras)]
output_bin_escape_fractions – Output bin escape fractions. [Default value: false | Dimensions: (n_cameras, n_bins)]
output_images – Output surface brightness images. [Default value: true | Dimensions: (n_cameras, nx_pixels, ny_pixels) | Output units: photons/s/cm^2]
output_bin_images – Output bin surface brightness images. [Default value: false | Dimensions: (n_cameras, nx_pixels, ny_pixels, n_bins) | Output units: photons/s/cm^2]
output_radial_images – Output radial surface brightness images. [Default value: false | Dimensions: (n_cameras, n_radial_pixels) | Output units: photons/s/cm^2]
output_bin_radial_images – Output bin radial surface brightness images. [Default value: false | Dimensions: (n_cameras, n_radial_pixels, n_bins) | Output units: photons/s/cm^2]
output_mcrt_emission – Output intrinsic emission without transport based on MCRT sampling (also works for radial images). [Default value: false | Dimensions: (n_cameras, nx_pixels, ny_pixels) | Output units: photons/s/cm^2]
output_mcrt_attenuation – Output attenuated emission without scattering based on MCRT sampling (also works for radial images). [Default value: false | Dimensions: (n_cameras, nx_pixels, ny_pixels) | Output units: photons/s/cm^2]

Healpix Binning Parameters

The following parameters are related to line-of-sight healpix binning options:

n_exp_map – Healpix exponent for the line-of-sight map, resulting in \(12 \times 4^{n_\text{exp,map}}\) directions. Note: Similar setup for n_exp_flux, n_exp_radial, and n_exp_cube. [Default value: 2 | Valid range: n_exp_map >= 0]
n_side_map – Healpix number of base pixel subdivisions for the line-of-sight map, resulting in \(12 \times n_\text{side,map}^2\) directions. Note: Similar setup for n_side_flux, n_side_radial, and n_side_cube. [Overrides n_exp_map | Default value: 4 | Valid range: n_side_map >= 1]
map_radius – Radius for the line-of-sight healpix map of radial surface brightness images. Note: Similar setup for cube_map_radius. [Units: cm]
map_radius_bbox – Radius for the line-of-sight healpix map of radial surface brightness images in units of the bounding box radius \(R_{\rm box}\). Note: Similar setup for cube_map_radius_bbox. [Units: bounding box]
map_radius_Rvir – Radius for the line-of-sight healpix map of radial surface brightness images in units of the selected halo virial radius \(R_{\rm vir}\). Note: Similar setup for cube_map_radius_Rvir. [Units: Virial radius]
n_map_pixels – Number of radial pixels for the line-of-sight healpix map of radial surface brightness images. Note: Similar setup for n_cube_map_pixels. [Default value: 100]
map_pixel_width – Intrinsic width of each radial pixel for the line-of-sight healpix map of radial surface brightness images. Note: Similar setup for cube_map_pixel_width. [Units: cm]
map_pixel_arcsec – Observed angular width of each radial pixel for the line-of-sight healpix map of radial surface brightness images. Note: Similar setup for cube_map_pixel_arcsec. [Units: arcseconds]
output_map – Output a line-of-sight healpix map of escape fractions. [Default value: false | Dimensions: (12 * n_side_map^2)]
output_map2 – Output a statistical moment line-of-sight healpix map, e.g. to estimate convergence statistics as the relative error is approximately \(\sqrt{\text{map2}} / \text{map}\). [Default value: false | Dimensions: (12 * n_side_map^2)]
output_radial_map – Output a line-of-sight healpix map of radial surface brightness images. [Default value: false | Dimensions: (12 * n_side_radial^2, n_map_pixels) | Output units: photons/s/cm^2]
output_bin_radial_map – Output a line-of-sight healpix map of radial spectral data cubes. [Default value: false | Dimensions: (12 * n_side_cube^2, n_cube_map_pixels, n_bins) | Output units: photons/s/cm^2]

Advanced Parameters

These parameters are for advanced outputs and configurations:

output_ion_stats – Flag to output ionization statistics for all active ions. [Default value: false]
output_ion_stats_{atom} – Output ionization statistics for a specific atom. [Default value: false | Overrides output_ion_stats]
output_ion_stats_{ion} – Output ionization statistics for a specific ion. [Default value: false | Overrides output_ion_stats_{atom}]
output_ion_stats_gas – Output total ionization statistics for all active ions. [Default value: false]
output_ion_stats_dust – Output dust absorption statistics. [Default value: false]
output_ion_stats_tot – Output total ionization and absorption statistics (gas + dust). [Default value: false]

Spatial Statistics Parameters

The following parameters are compile-time options and need to be set in the defines.yaml file:

output_ion_cell_age_freq – Output the rate of absorptions by cell, age, and frequency. [Compile-time parameter | Default value: false | Units: photons/s]
output_ion_radial_age_freq – Output the rate of absorptions by radial bin, age, and frequency. [Compile-time parameter | Default value: false | Units: photons/s]
output_ion_distance_age_freq – Output the rate of absorptions by distance bin, age, and frequency. [Compile-time parameter | Default value: false | Units: photons/s]

Radial Flow Parameters

The radial flow data is a 3D probe of the radiation field. The output data is in the radial_flow group with attributes n_radial_bins and n_freq_bins and fields radial_edges [cm] (radial bin edges), freq_edges (frequency bin edge indices), freq_names (frequency bin edge names), freq_edges_eV [eV] (frequency bin edges in eV), Ndot_src (emission as a function of source radii and frequency bin), Ndot_esc (escape as a function of source radii and frequency bin), Ndot_{ion} (ionization and absorption statistics as a function of absorption radii and frequency bin), Ndot_pass (first passage by source radii and shell boundaries and frequency bin), and Ndot_flow (net flux by source radii and shell boundaries and frequency bin).