cloudy_slug: An Automated Interface to cloudy

SLUG stochastically generates stellar spectra, and it includes an approximate computation of the nebular lines produced when those photons interact with the interstellar medium. However, this approximation ignores a number of potentially important effects, and does not properly account for the stochastic nature of the stellar spectra. To perform a much more accurate calculation, SLUG includes an automated interface to cloudy (Ferland et al., 2013, RMxAA, 49, 137). This can be used to post-process the output of a SLUG run in order to compute nebular emission.

cloudy_slug Basics

The basic steps (described in greater detail below) are as follows:

  1. Get cloudy installed and compiled, following the directions on the cloudy website.

  2. Set the environment variable $CLOUDY_DIR to the directory where the cloudy executable cloudy.exe is located. If you are using a bash-like shell, the syntax for this is:

    export CLOUDY_DIR = /path/to/cloudy
    

    while for a csh-like shell, it is:

    setenv CLOUDY_DIR /path/to/cloudy
    
  3. If you desire, edit the cloudy input template cloudy_slug/cloudy.in_template and the line list cloudy_slug/LineList_HII.dat. There are the template input files that will be used for all the cloudy runs, and their syntax follows the standard cloudy syntax. They control things like the density and element abundances in the nebula – see The cloudy_slug Input Template for more details.

  4. Perform the desired SLUG simulation. The SLUG simulation outputs must include spectra and photometry, and one of the photometric bands output must be QH0 (see Photometric Filter Keywords). Depending on whether one is running in integrated or cluster mode (see Integrated versus Cluster Spectra), either integrated specta and photometry or cluster spectra and photometry are required.

  5. Invoke the cloudy_slug interface script via:

    python cloudy_slug/cloudy_slug.py SLUG_MODEL_NAME
    

    where SLUG_MODEL_NAME is the name of the SLUG run to be processed. See The cloudy_slug Physical Model for more information on the underlying physical model assumed in the calculation, and The cloudy_slug Interface Script for more details on the python script and its options.

  6. The output will be stored as a series of additional output files of with names of the form SLUG_MODEL_NAME_*cloudy*.ext, where the extension is .txt, .bin, or .fits, depending on the format in which the orignal SLUG output was stored. These files can be processed automatically by the slugpy helper routines (see slugpy – The Python Helper Library). See Full Description of cloudy_slug Output for a description of the outputs.

Note that some care is required in selecting the conditions passed to cloudy to ensure that the results are physically sensible. Users are strongly encouraged to read The cloudy_slug Physical Model to understand exactly what physical assumptions are being made, and to ensure that they are reasonable.

The cloudy_slug Physical Model

The cloudy_slug code computes emission from a spherical HII region surrounding a stellar population. The stellar population comes from SLUG, and the emission calculation is performed with cloudy. Combining the two requires some physical assumptions and inputs, which are explained in this section.

Integrated versus Cluster Spectra

SLUG outputs both integrated spectra for all the stars in a galaxy, and spectra for individual clusters. Both the integrated spectra and the individual cluster spectra can be processed by cloudy. However, it is important to understand the implicit physical assumptions that one is making while doing so. If one has a galaxy where all stars are in clusters (i.e., cluster formation fraction is unity and there is no cluster disruption), then the integrated starlight spectrum is just the sum of the individual cluster spectra. For nebular emission, however, this is not the case: nebular emission does not, in general, add linearly.

For this reason, if one processes the integrated spectrum through cloudy, the implicit physical assumption is that the entire galaxy is a single giant HII region being ionized by the starlight of all the clusters present. If one processes the individual cluster spectra instead, the implicit physical picture is that there is no overlap whatsoever between the HII regions surrounding different star clusters. Reality almost certainly lies somewhere between these two extremes, but it is important to understand physically what assumption one is making by adopting one or the other. We refer to processing the integrated spectrum as integrated mode, and to processing the individual cluster spectra as cluster mode. Note that cluster mode can be very computationally intensive if there are many clusters present, and that in cluster mode there is no processing of nebular emission produced by field stars.

In either mode, the spectrum that is used to compute the nebular emission will be the unextincted, non-redshifted spectrum computed by SLUG.

Nebular Properties

Computing the nebular emission requires specifying the physical properties of the interstellar gas into which the photons propagate. Codes like cloudy require that the HII region be described by an inner radius \(r_0\) and a number density \(n_{0}\) of hydrogen nuclei at that radius. One option for cloudy_slug is that these parameters can be set in the cloudy inputs as they would be for a normal cloudy run. However, these parameters are not necessarily the most convenient or descriptive ones with which to describe HII regions. For this reason, cloudy_slug allows users to specify HII region properties in a number of other more convneient ways.

The basic assumptions made in cloudy_slug’s parameterization is that the HII region is isobaric and isothermal, at all points hydrogen is fully ionized and helium is singly ionized, and that radiation pressure is negligible. The HII region occupies a spherical shell bounded by an inner radius \(r_0\) and an outer radius \(r_1\). The inner radius is set by the presence of a bubble of shocked stellar wind material at a temperature \(\sim 10^6\) K, which is assumed to be optically thick to ionizing photons. The outer radius is set by the location where all the ionizing photons have been absorbed.

Under these assumptions, the inner density \(n_0\) is simply the (uniform) density \(n_{\mathrm{II}}\) throughout the ionized region, and the ionizing photon luminosity passing through a shell of material at a distance \(r\) from the stars is

\[Q(r) = Q(\mathrm{H}^0) \left[1 - \left(\frac{r}{r_S}\right)^3 + \left(\frac{r_0}{r_S}\right)^3\right],\]

where \(Q(\mathrm{H}^0)\) is the hydrogen-ionizing luminosity of the source and \(r_S\) is the Stromgren radius, given by

\[r_S = \left(\frac{3 Q(\mathrm{H}^0)}{4\pi \alpha_B f_e n_{\mathrm{II}}^2}\right)^{1/3}.\]

Here \(\alpha_B\) is the case B recombination coefficient and \(f_e\) is the abundance of electrons per H nucleus. For the purposes of cloudy_slug, we take these two quantities to have the fixed values \(\alpha_B = 2.59\times 10^{-13}\;\mathrm{cm}^3\;\mathrm{s}^{-1}\), appropriate for a temperature of \(10^4\) K, and \(f_e = 1.1\), appropriate for a region where He is singly ionized.

From this setup one can define some useful dimensionless numbers. One is the wind parameter \(\Omega\) introduced by Yeh & Matnzer (2012, ApJ, 757, 108), which under the simple assumptions made in cloudy_slug is given by

\[\Omega = \frac{r_0^3}{r_1^3-r_0^3}\]

i.e., it is just the ratio of the volume occupied by the wind gas to that occupied by the photoionized gas. The value of \(\Omega\) determines whether winds are important (\(\Omega \gg 1\)) or unimportant (\(\Omega \ll 1\)) for the dynamics of the HII region. The second dimensionless parameter is the volume-averaged ionization parameter

\[\mathcal{U} = \frac{3}{4\pi (r_1^3-r_0^3)} \int_{r_0}^{r_1} \left(\frac{Q(r)}{4\pi r^2 c f_i n_{\mathrm{II}}}\right) 4\pi r^2 \, dr.\]

Here \(f_i\) is the number of free ions per H nucleus, and is equal to \(f_i = 1.1\) under the assumption that He is singly ionized. The quantity in parentheses is the ratio of the ionizing photon to ion number densities at radius \(r\). The value of \(\mathcal{U}\) is, together with \(n_{\mathrm{II}}\), the most important factor in determining the output spectrum. A third useful dimensionless parameter is the ionization parameter at the inner radius,

\[\mathcal{U}_0 = \frac{Q(\mathrm{H}^0)} {4\pi r_0^2 f_i n_{\mathrm{II}} c}.\]

The various quantities are not unrelated. It is straightforward to show that they are constrained by the following relationships:

\[ \begin{align}\begin{aligned}\begin{split}r_0 & = \Omega^{1/3} r_S \\\end{split}\\\begin{split}r_1 & = \left(1 + \Omega\right)^{1/3} r_S \\\end{split}\\\begin{split}\mathcal{U} & = \left[\frac{81 \alpha_B^2 n_{\mathrm{II}} Q(\mathrm{H}^0)}{256 \pi c^3 f_e}\right]^{1/3} \left[\left(1 + \Omega\right)^{4/3} - \Omega^{1/3} \left(\frac{4}{3}+\Omega\right)\right] \\\end{split}\\\begin{split}& = \left[\frac{81 \alpha_B Q(\mathrm{H}^0)} {64 \pi c^2 f_e r_S}\right]^{1/2} \left[\left(1 + \Omega\right)^{4/3} - \Omega^{1/3} \left(\frac{4}{3}+\Omega\right)\right] \\\end{split}\\\begin{split}\mathcal{U}_0 &= \left[ \frac{\alpha_B^2 n_{\mathrm{II}} Q(\mathrm{H}^0)} {36 \pi c^3 f_e}\right]^{1/3} \frac{1}{\Omega^{2/3}} \\\end{split}\\\begin{split}&= \frac{4}{9}\Omega^{-2/3} \left[(1+\Omega)^{4/3} - \Omega^{1/3}\left(\frac{4}{3}+\Omega\right)\right]^{-1} \mathcal{U} \\\end{split}\end{aligned}\end{align} \]

These relations may be used to compute any four of the quantities \(n_{\mathrm{II}}\), \(r_0\), \(r_1\), \(\mathcal{U}\), \(\mathcal{U}_0\) and \(\Omega\) given the other two. slugpy – The Python Helper Library provides a class hiiregparam that can be used to perform such a computation.

Given this background, cloudy_slug allows the user to specify the physical properties of the HII region by setting any two of the following six quantities:

  1. The photoionized gas density \(n_{\mathrm{II}}\).
  2. The inner radius \(r_0\).
  3. The outer radius \(r_1\).
  4. The volume-averaged ionization parameter \(\mathcal{U}\).
  5. The inner radius ionization parameter \(\mathcal{U}_0\).
  6. The wind parameter \(\Omega\).

The two quantities chosen can be specified exactly, or can be drawn from a specified PDF. One final option, which is only available in cluster mode, is to obtain the required quantities from a dynamical model – see Dynamical Mode.

A few caveats are in order at this point.

  1. Not all combinations of values are realizable. In addition to the obvious constraints (e.g., \(r_1 > r_0\)), there are some subtle ones. For example, for any given ionizing luminosity \(Q(\mathrm{H}^0)\) and density \(n_{\mathrm{II}}\), the value of \(\mathcal{U}\) is bounded from above. Increasing the wind parameter \(\Omega\) can allow arbitrarily small values of \(\mathcal{U}\), but not arbitrarily large ones. If the user requests a physically impossible combination of parameters, cloudy_slug will correct the parameters to the allowed range and run, while issuing a warning.
  2. Even for parameters that are not physically impossible, the results may not be sensible, and may cause cloudy to crash in extreme cases. For example, if one sets \(\Omega = 0\) and \(\mathcal{U} = 10^{-4}\), then for an ionizing lumnosity of \(Q(\mathrm{H}^0) = 10^{50}\) photons/s (typical for a cluster of \(\sim 10^4M_\odot\)), the corresponding density is \(n_{\mathrm{II}} \approx 10^{-5}\mbox{ cm}^{-3}\)! As this density the gas will be fully ionized by cosmic rays and the extragalactic background, and it makes no sense to think of it as an HII region. Caution is required.
  3. The parameter combinations \((r_0,\mathcal{U})\) and \((r_1,\mathcal{U}_0)\) not allowed because they do not define a unique solution for the other parameters (the resulting equations have multiple physically-valid solutions).
  4. The relations given above are only valid if radiation pressure is not dynamically significant. If it is, then there are no known analytic relations between the various quantities. The cloudy_slug code will still run, and will use the relations above, but the actual HII region properties may be markedly different from those requested. In cases where radiation pressure is important, it is generally advisable to save the HII region physical conditions output by cloudy to compute quatities from them directly. The cloudy_slug script will issue a warning if radiation pressure is expected to be significant for the HII region being computed. As a rule of thumb, radiation pressure is significant if
\[\zeta \equiv \frac{r_{\mathrm{ch}}}{r_1} > 1\]

where \(r_{\mathrm{ch}}\) is the characteristic radius defined by Krumholz & Matzner (2009, ApJ, 703, 1352) as

\[\begin{split}r_{\mathrm{ch}} & = \frac{\alpha_B}{12 \pi \phi} \left(\frac{\epsilon_0}{2 f_e k_B T_{\mathrm{II}}}\right)^2 f_{\mathrm{trap}}^2 \frac{\psi^2 Q(\mathrm{H}^0)}{c^2} \\\end{split}\]

Here \(\phi = 0.73\) is the fraction of ionizing photons absorbed by hydrogen atoms rather than dust, \(\epsilon_0 = 13.6\;\mathrm{eV}\) is the hydrogen ionization potential, \(T_{\mathrm{II}} = 10^4\;\mathrm{K}\) is the temperature inside the HII region, \(f_{\mathrm{trap}} = 2\) is the trapping factor that accounts for stellar wind and trapped infrared radiation pressure, and \(\psi = 3.2\) is the mean photon energy in Rydberg for a fully sampled IMF at zero age.

Dynamical Mode

In cluster mode, cloudy_slug allows an additional option to derive the physical properties of the HII region. They can be computed from a dynamical model of HII region expansion, taken from Krumholz & Matzner (2009, ApJ, 703, 1352). In this model, the radius of an HII region can be computed as a function of the ionizing luminosity \(Q(\mathrm{H}^0)\), ambient hydrogen number density \(n_{\mathrm{H}}\), and star cluster age \(t\) as

\[ \begin{align}\begin{aligned}\begin{split}r_1 & = r_{\mathrm{ch}} \left(x_{\mathrm{rad}}^{7/2} + x_{\mathrm{gas}}^{7/2}\right)^{2/7} \\\end{split}\\\begin{split}x_{\mathrm{rad}} &= (2\tau^2)^{1/4} \\\end{split}\\\begin{split}x_{\mathrm{gas}} &= (49\tau^2/36)^{2/7} \\\end{split}\\\begin{split}\tau &= t/t_{\mathrm{ch}} \\\end{split}\\\begin{split}t_{\mathrm{ch}} & = \left(\frac{4\pi \mu m_{\mathrm{H}} n_{\mathrm{H}} c r_{\mathrm{ch}}^4}{3 f_{\mathrm{trap}} Q(\mathrm{H}^0) \psi \epsilon_0}\right)^{1/2} \\\end{split}\end{aligned}\end{align} \]

Definitions of various quantities appearing in these equations are given above. The quantity \(\mu = 1.4\) is the mean mass per hydrogen nucleus for gas of the standard cosmic composition.

We refer to this method of computing HII region properties as dynamical mode. In this mode, a user can specify the properties of the nebula in terms of an ambient density \(n_{\mathrm{H}}\) and a wind parameter \(\Omega\). All other quantities are derived from these two and from the ionizing luminosity \(Q(\mathrm{H}^0)\) and age \(t\) of each cluster. Dynamical mode can only be used in combination with cluster mode, not integrated mode, because composite stellar populations do not have well-defined ages.

The cloudy_slug Input Template

The cloudy_slug interface operates by reading SLUG output spectra and using them as inputs to a cloudy calculation. However, cloudy obviously requires many input parameters beyond simply the spectrum of the input radiation field. These parameters are normally provided by an input file whose format is as described in the cloudy documentation. The cloudy_slug interface works by reading a template input file that specifies all these parameter, and which will be used as a basis for the final cloudy input files that will contain the SLUG spectra.

In general the template input file looks just like an ordinary cloudy input file, subject to the following restrictions:

  1. The input file must not contain any commands that specify the luminosity, intensity, or the spectral shape. These will be inserted automatically by the cloudy_slug script.
  2. The input file may contain a radius command specifying the inner radius of the HII region. If it does not, then the user must specify the radius in another way, by setting 2 of the 6 inputs described in Nebular Properties (for simulations not done in dynamic mode) or by setting an ambient density and wind parameters in Dynamical Mode. If the user does set these quantities, any radius command in the template file will be ignored, and a warning message will be issued if one is found. Finally, note that cluster_slug will only compute derived parameters correctly from a radius in the template file if the radius is specified in cloudy’s default format, by giving a log of the radius in cm; the keywords “linear” and “parsecs” are not currently supported.
  3. The input file may contain a hydrogen density command specifying the starting hydrogen density. The rules for this are the same as for the radius command.
  4. Any outputs to be written (specified using the save or punch keywords) must give file names containing the string $OUTPUT_FILENAME. This string will be replaced by the cloudy_slug script to generate a unique file name for each cloudy run, and to read back these outputs for post-processing.
  5. The cloudy_slug output will contain output spectra only if the cloudy input file contains a save last continuum command. See Full Description of cloudy_slug Output.
  6. The cloudy_slug output will contain output line luminosities only if the cloudy input file contains a save last line list emergent absolute column command. See Full Description of cloudy_slug Output.
  7. The cloudy_slug output will contain output physical conditions and dimensionless values only if the cloudy input file contains a save last hydrogen conditions command. See Full Description of cloudy_slug Output.
  8. If any other outputs are produced by the input file, they will neither be processed nor moved, deleted, or otherwise changed by the cloudy_slug script.
  9. Running cloudy in grid mode is not currently supported.

An example cloudy input file with reasonable parameter choices is provided as cloudy_slug/cloudy_in.template in the main directory of the SLUG repository.

In addition to the input file, the default template makes use of a cloudy line list file to specify which line luminosities should be output (see the cloudy documentation for details). The template points to the file cloudy_slug/LineList_HII.data (which is identical to cloudy’s default line list for HII regions), but any other valid cloudy line list file would work as well.

The cloudy_slug Interface Script

The cloudy_slug.py script provides the interface between SLUG and cloudy. Usage for this script is as follows:

cloudy_slug.py [-h] [-a AGEMAX] [--cloudypath CLOUDYPATH]
               [--cloudytemplate CLOUDYTEMPLATE] [-cm]
               [-cf COVERINGFAC] [-d] [-hd HDEN] [-ip IONPARAM]
               [-ip0 IONPARAM0] [-ipm IONPARAMMAX]
               [--ionparammin IONPARAMMIN] [-nl NICELEVEL]
               [-n NPROC] [-ps PARAMSAFETY] [-qm QH0MIN] [-r0 R0]
               [-r1 R1] [-s] [--slugformat SLUGFORMAT]
               [--slugpath SLUGPATH] [-t TMPDIR] [-v] [-wp WINDPARAM]
               [-wr]
               slug_model_name [start_spec] [end_spec]

The positional arguments are as follows:

  • slug_model_name: this is the name of the SLUG output to be used as a basis for the cloudy calculation. This should be the same as the model_name parameter used in the SLUG simulation, with the optional addition of a path specification in front.
  • start_spec: default behavior is to run cloudy on all the integrated spectra or cluster spectra (see Integrated versus Cluster Spectra). If this argument is set, cloudy will only be run in spectra starting with the specified trial number or cluster number; numbers are 0-offset, so the first trial/cluster is 0, the next is 1, etc.
  • end_spec: same as start_spec, but specifying the last cluster to be processed. Per standard python convention, the spectra processed will go up to but not include end_spec.

The following optional arguments control paths and file locations:

  • --cloudypath CLOUDYPATH: path to the cloudy executable; default is $CLOUDY_DIR/cloudy.exe
  • --cloudytemplate CLOUDYTEMPLATE: cloudy input file template (see The cloudy_slug Input Template); default is $SLUG_DIR/cloudy_slug/cloudy.in_template
  • --slugformat SLUGFORMAT: the format of slug output data to use; valid values are ascii, bin, binary, and fits. By default cloudy_slug checks for any output whose name and path match the model name and search path, regardless of format.
  • --slugpath SLUGPATH: path to the SLUG output data. If not set, cloudy_slug searches for an appropriately-named set of output files first in the current working directory, and next in $SLUG_DIR/output
  • -t TMPDIR, --tmpdir TMPDIR: location of the temporary directory where temporary files should be stored; defaults to ./cloudy_tmp_MODEL_NAME.

The following arguments control how HII regions are processed:

  • -a AGEMAX, --agemax AGEMAX: maximum cluster age in Myr for cloudy computation. Cloudy will not be run on clusters older than this value, and the predicted nebular emission for such clusters will be recorded as zero. Default value is 10 Myr. This argument only has an effect if running in cluster mode (see Integrated versus Cluster Spectra); otherwise it is ignored.
  • -cf COVERINGFRAC, --coveringfrac COVERINGFRAC: this sets the covering fraction of the HII region, i.e., the fraction of ionizing photons that are assumed to produce nebular emission; the output luminosity is decreased by a factor of the covering fraction
  • -cm, --clustermode: if this argument is set, then cloudy_slug will process cluster spectra; the default behavior is to process integrated spectra
  • --ionparammax IONPARAMMAX: maximum value for the inner radius ionization parameter \(\mathcal{U}_0\). If the value falls outside this range, the behavior is controlled by the setting of the paramsafety option (see below).
  • --ionparammmin IONPARAMMIN: same as ionparammax, but sets a minimum instead of a maximum.
  • -qm QH0MIN, --qH0min QH0MIN: minimum ionizing luminosity for which to run cloudy (default = 0). As with --agemax, for clusters / times where cloudy is not run, that case will still appear in the output, but the nebular spectra and nebular line luminosities will all be set to zero.

The following parameters specify the physical properties of HII regions, as explained in Nebular Properties. Parameters can be set to either fixed values, or to the names of PDF files. Any numerical value given is interpreted as a fixed constant, while non-numerical values are interpreted as the names of PDF files that specify a PDF from which the corresponding parameter is to be drawn. See Probability Distribution Functions for details on PDF file formats.

  • -hd HDEN, --hden HDEN: hydrogen density in HII region, \(n_{\mathrm{II}}\)
  • -ip IONPARAM, --ionparam IONPARAM: volume-averaged ionization parameter, \(\mathcal{U}\)
  • -ip0 IONPARAM, --ionparam0 IONPARAM0: ionization parameter at HII region inner edge, \(\mathcal{U}_0\)
  • -r0 R0: inner radius of the HII region
  • -r1 R1: outer radius of the HII region
  • -wp WINDPARAM, --windparam WINDPARAM: wind parameter, \(\Omega\)

The following arguments control general code behavior:

  • -h, --help: prints a help message and then exits
  • -nl NICELEVEL, --nicelevel NICELEVEL: if this is set, then the cloudy processes launched by the script will be run at this nice level. If it is not set, they will not be nice’d. Note that this option will only work correctly on platforms that support nice.
  • -n NPROC, --nproc NPROC: number of simultaneous cloudy processes to run; default is the number of cores available on the system
  • --ps PARAMSAFETY, --paramsafety PARAMSAFETY: specifies how to handle situations where the combination of input HII region parameters is not physically allowed, or falls outside the bounds set by ionparammin and ionparammax. Available options are:
    • warn: one of the input parameters is adjusted to bring it to a physically-allowed value, and a warning is issued; the run continues. This is the default behaviour.
    • skip: runs with unphysical parameter choices are skipped; the parameters that were chosen are recorded in the output file, but the output spectrum, all line luminosities, and all other parameters are set to 0, and cloudy is not run.
    • halt: if a forbidden parameter combination is found, the entire cloudy_slug run is halted.
    • redraw: if a forbidden parameter combination is found, and one or more parameters are being drawn from a PDF, a new set of parameters will be drawn from the PDF. Redrawing will continue up to 100 times until a physically-allowed parameter combination is found. If no valid parameter combination is found after 100 attempts, revert to skip.
  • -s, --save: by default, cloudy_slug will extract line and spectral data from the cloudy outputs and store them as described in Full Description of cloudy_slug Output, then delete the cloudy output files. If this option is set, the cloudy output files will NOT be deleted, and will be left in place, in sub-directory of the working directory called cloudy_tmp_MODEL_NAME where MODEL_NAME is the SLUG model name. WARNING: cloudy’s outputs are written in ASCII and are quite voluminous, so choose this option only if you are running cloudy on a small number of SLUG spectra and/or you are prepared to store hundreds of GB or more. The data that cloudy_slug extract are much, much smaller, and (if you do not use ASCII format) are stored in a much more compact form.
  • -v, --verbose: if this option is set, cloudy_slug produces verbose output as it runs
  • -wr, --writeparams: if set, this option causes cloudy_slug to write out a file beginning with cloudy_slug.param for each cloudy run. This file is written in the same directory used by the save command, and it contains an ASCII printout of the various parameters. This option is only applied if --save is also set.

Full Description of cloudy_slug Output

The cloudy_slug script will automatically process the cloudy output and produce a series of new output files, which will be written to the same directory where the input SLUG files are located, and using the same output mode (ASCII text, raw binary, or FITS – see Output Files and Format). If cloudy_slug is called to process integrated spectra, the four output files will be MODEL_NAME_integrated_cloudyparams.ext, MODEL_NAME_integrated_cloudylines.ext, MODEL_NAME_integrated_cloudyphot.ext, and MODEL_NAME_integrated_cloudyspec.ext, where the extension .ext is one of .txt, .bin, or .fits, depending on the output_mode. If cloudy_slug is run on cluster spectra, the four output files will be MODEL_NAME_cluster_cloudyparams.ext, MODEL_NAME_cluster_cloudylines.ext, MODEL_NAME_cluster_cloudyphot.ext, and MODEL_NAME_cluster_cloudyspec.ext. All of these output files will be read and processed automatically if the outputs are read using read_integrated or read_cluster in the slugpy – The Python Helper Library library.

The format of these files is described below.

The integrated_cloudyparams File

This file contains the input parameters for the cloudy runs, and quantities derived from them. All parameters are as defined in Nebular Properties. The output file consists of a series of entries containin the following fields:

  • Trial: which trial these data are from
  • Time: evolution time at which the output is produced
  • Hden: number density of hydrogen nuclei at the inner edge of the HII region, in H/cm^3
  • R0: radius of the inner edge of the HII region, in cm
  • R1: radius of the outer edge of the HII region, in cm
  • QH0: ionizing luminosity input to cloudy, in photons/s
  • CovFac: covering factor used
  • U: volume-averaged ionization parameter \(\mathcal{U}\)
  • U0: inner edge ionization parameter \(\mathcal{U}_0\)
  • Omega: wind parameter \(\Omega\)
  • zeta: radiation pressure parameter \(\zeta\)

It will also contain the following fields if the cloudy template file includes a save last hydrogen conditions command:

  • Hden_out: mean H number density for the HII region structure computed by cloudy, in H/cm^3; the average is weighted by the ionized volume, i.e., it is weighted by \(x\, dV\), where \(x\) is the hydrogen ionization fraction.
  • R1_out: HII region outer radius returned by cloudy
  • Omega_out: wind parameter \(\Omega\), computed using R1_out instead of R1
  • zeta_out: radiation pressure parameter \(\zeta\), computing using R1_out instead of R1

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, the data are written in a FITS file containing a binary table extension. The table contains one column whose name corresponds to the list of fields above.

If the SLUG data input to cloudy_slug were writtin in binary mode, these data are written in a raw binary file that is formatted as follows. First, there are four bytes specifying if the optional fields are included:

  • Hden_out_set (byte): 0 if the data do not include Hden_out, 1 if they do include it
  • R1_out_set (byte): 0 if the data do not include R1_out, 1 if they do include it
  • Omega_out_set (byte): 0 if the data do not include Omega_out, 1 if they do include it
  • zeta_out_set (byte): 0 if the data do not include zeta_out, 1 if they do include it

This is followed by a series of records containing the following fields:

  • Trial (numpy uint64)
  • Time (numpy float64)
  • Hden (numpy float64)
  • R0 (numpy float64)
  • R1 (numpy float64)
  • QH0 (numpy float64)
  • covFac (numpy float64)
  • U (numpy float64)
  • U0 (numpy float64)
  • Omega (numpy float64)
  • zeta (numpy float64)
  • Hden_out (numpy float64; optional, only if the relevant byte in the header is set to )
  • R1_out (numpy float64; optional, only if the relevant byte in the header is set to )
  • Omega_out (numpy float64; optional, only if the relevant byte in the header is set to )
  • zeta_out (numpy float64; optional, only if the relevant byte in the header is set to 1)

There is one such record for each output time, with different trials ordered sequentially, so that all the times for one trial are output before the first time for the next trial.

The integrated_cloudylines File

This file contains data on the nebular line emission produced by the interaction of the stellar radiation field with the ISM. It consists of a series of entries containing the following fields:

  • Time: evolution time at which the output is produced
  • LineLabel: four letter code labeling each line. These codes are the codes used by cloudy (see the cloudy documentation)
  • Wavelength: wavelength of the line, in Angstrom. Note that default cloudy behavior is to round wavelengths to the nearest Angstrom.
  • Luminosity: line luminosity, in erg/s

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, the data are written in a FITS file containing two binary table extensions. The first extension contains two fields, Line_label and Wavelength, giving the four-letter cloudy line codes and central wavelengths. The second extension contains three columns, giving the trial number, time, and line luminosity for each line at each time in each trial.

If the SLUG data input to cloudy_slug were written in binary mode, the data are written in a raw binary file. The file starts with a header consisting of

  • NLine (python int, equivalent to C long): number of lines
  • LineLabel (NLine entries stored as ASCII text): line labels listed in ASCII, one label per line

This is followed by a series of entries of the form

  • Trial (numpy uint64)
  • Time (numpy float64)
  • LineLum (NLine entries of type numpy float64)

There is one such record for each output time, with different trials ordered sequentially, so that all the times for one trial are output before the first time for the next trial.

The integrated_cloudyspec File

This file contains data on the spectrum produced by interaction between the stellar radiation field and the nebula. Each entry in the output file contains the folling fields:

  • Trial: which trial these data are from
  • Time: evolution time at which the output is produced
  • Wavelength: the wavelength at which the spectrum is evaluated, in Angstrom
  • Incident: specific luminosity in erg/s/Angstrom at the specified wavelength. In cloudy’s terminology, this is the incident spectrum, i.e., the stellar radiation field entering the nebula. It should be the same as the spectrum contained in the SLUG integrated_spec file for the corresponding time and trial, except interpolated onto the wavelength grid used by cloudy.
  • Transmitted: specific luminosity in erg/s/Angstrom at the specified wavelength. In cloudy’s terminology, this is the transmitted spectrum, i.e., the stellar spectrum exiting the HII region, not including any emission produced within the nebula. This is what would be detected by an observing aperture that included only the stars, and none of the nebula.
  • Emitted: specific luminosity in erg/s/Angstrom at the specified wavelength. In cloudy’s terminology, this is the emitted spectrum, i.e., the spectrum emitted by the diffuse gas in the HII region, excluding any light from the stars themselves. This is what would be seen by an observer whose aperture covered the nebula, but masked the stars.
  • Transmitted_plus_emitted: this is just the sum of Transmitted and Emitted. It represents what would be observed in an aperture including both the stars and the HII region.

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, these data are written in a FITS file containing two binary table extensions. The first extension contains one field, Wavelength, which gives the wavelengths of the spectra in Angstrom. The second extension contains six fields: Trial, Time, Incident_spectrum, Transmitted_spectrum, Emitted_spectrum, and Transmitted_plus_emitted_spectrum. The first two of these give the trial number and time, and the remaining four give the incident, transmitted, emitted, and transmitted plus emitted spectra for the corresponding time and trial.

If the SLUG data input to cloudy_slug were written in binary mode, these data are written in a raw binary file that is formatted as follows. The file begins with a header consisting of

  • NWavelength (numpy int64): number of wavelengths
  • Wavelength (NWavelength entries of numpy float64)

and then contains a series of records of the form

  • Trial (numpy uint64)
  • Time (numpy float64)
  • Incident (NWavelength entries of numpy float64)
  • Transmitted (NWavelength entries of numpy float64)
  • Emitted (NWavelength entries of numpy float64)
  • Transmitted_plus_emitted (NWavelength entries of numpy float64)

There is one such record for each output time, with different trials ordered sequentially, so that all the times for one trial are output before the first time for the next trial.

The integrated_cloudyphot File

This file contains photometric data computed for the spectra produced by the interaction between the stellar radiation field and the HII region. The file consists of a series of entries containing the following fields:

  • Trial: which trial these data are from
  • Time: evolution time at which the output is computed
  • PhotFilter1_trans: photometric value for the Transmitted radiation field through filter 1, where filter 1 here is the same as filter 1 in The integrated_phot File; units are also the same as in that file.
  • PhotFilter1_emit: photometric value for the Emitted radiation field through filter 1
  • PhotFilter1_trans_emit: photometric value for the Transmitted_plus_emitted radiation field through filter 1
  • PhotFilter2_trans
  • PhotFilter2_emit
  • PhotFilter2_trans_emit
  • ...

For distinctions between the Transmitted, Emitted, and Transmitted_plus_emitted radiation fields, see The integrated_cloudyspec File, or the cloudy documentaiton. Note that we do not record photometry for the incident spectrum, since that would be, up to the accuracy of the numerical integration, identical to the photometry already recorded in the The integrated_phot File.

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, these data are written in a FITS file containing one binary table extension, consisting of a series of columns. The columns are Trial, Time, Filter1_Transmitted, Filter1_Emitted, Filter1_Transmitted_plus_emitted, .... The first two columns give the trial number and the time, and the remainder give the photometric values for the transmitted, emitted, and transmitted plus emitted spectra in each filter.

If the SLUG data input to cloudy_slug were written in binary mode, these data are written to a raw binary file that is formatted as follows. The file starts with an ASCII header consisting of the following, each on a separate line:

  • NFilter (stored as ASCII text): number of filters used
  • FilterName FilterUnit (NFilter entries stored as ASCII text): the name and units for each filter are listed in ASCII, one filter-unit pair per line

This is followed by a series of entries of the form:

  • PhotFilter_Transmitted (NFilter entries of numpy float64), giving the transmitted photometry in each filter
  • PhotFilter_Emitted (NFilter entries of numpy float64), giving the emitted photometry in each filter
  • PhotFilter_Transmitted_plus_emitted (NFilter entries of numpy float64), giving the transmitted plus emitted photometry in each filter

There is one such record for each output time, with different trials ordered sequentially, so that all the times for one trial are output before the first time for the next trial.

The cluster_cloudyparams File

This file contains the input parameters for the cloudy runs, and quantities derived from them. It consists of a series of entries containin the following fields:

  • UniqueID: a unique identifier number for each cluster that is preserved across times and output files
  • Time: evolution time at which the output is produced
  • Hden: number density of hydrogen nuclei at the inner edge of the HII region whose structure cloudy computes, in H/cm^3
  • R0: radius of the inner edge of the HII region, in cm
  • R1: radius of the outer edge of the HII region, cm
  • QH0: ionizing luminosity input to cloudy, in photons/s
  • CovFac: covering factor used
  • U: volume-averaged ionization parameter \(\mathcal{U}\)
  • U0: inner edge ionization parameter \(\mathcal{U}_0\)
  • Omega: wind parameter \(\Omega\)
  • zeta: radiation pressure parameter \(\zeta\)

It will also contain the following fields if the cloudy template file includes a save last hydrogen conditions command:

  • Hden_out: mean H number density for the HII region structure computed by cloudy, in H/cm^3; the average is weighted by the ionized volume, i.e., it is weighted by \(x\, dV\), where \(x\) is the hydrogen ionization fraction.
  • R1_out: HII region outer radius returned by cloudy
  • Omega_out: wind parameter \(\Omega\), computed using R1_out instead of R1
  • zeta_out: radiation pressure parameter \(\zeta\), computing using R1_out instead of R1

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, the data are written in a FITS file containing a binary table extension. The table contains one column whose name corresponds to the list of fields above.

If the SLUG data input to cloudy_slug were writtin in binary mode, these data are written in a raw binary file that is formatted as follows. First, there are four bytes specifying if the optional fields are included:

  • Hden_out_set (byte): 0 if the data do not include Hden_out, 1 if they do include it
  • R1_out_set (byte): 0 if the data do not include R1_out, 1 if they do include it
  • Omega_out_set (byte): 0 if the data do not include Omega_out, 1 if they do include it
  • zeta_out_set (byte): 0 if the data do not include zeta_out, 1 if they do include it

Next there are a series of records, one for each output time, with different trials ordered sequentially, so that all the times for one trial are output before the first time for the next trial. Each record consists of a header containing

  • Time (double)
  • NCluster (std::vector<double>::size_type, usually unsigned long long): number of non-disrupted clusters present at this time

This is followed by NCluster entries of the following form:

  • UniqueID (numpy uint64)
  • Time (numpy float64)
  • Hden (numpy float64)
  • R0 (numpy float64)
  • R1 (numpy float64)
  • QH0 (numpy float64)
  • covFac (numpy float64)
  • U (numpy float64)
  • U0 (numpy float64)
  • Omega (numpy float64)
  • zeta (numpy float64)
  • Hden_out (numpy float64; optional, only if the relevant byte in the header is set to )
  • R1_out (numpy float64; optional, only if the relevant byte in the header is set to )
  • Omega_out (numpy float64; optional, only if the relevant byte in the header is set to )
  • zeta_out (numpy float64; optional, only if the relevant byte in the header is set to 1)

The cluster_cloudylines File

This file contains data on the nebular line emission produced by the interaction of the stellar radiation field with the ISM around each cluster. It consists of a series of entries containing the following fields:

  • UniqueID: a unique identifier number for each cluster that is preserved across times and output files
  • Time: evolution time at which the output is produced
  • LineLabel: four letter code labeling each line. These codes are the codes used by cloudy (see the cloudy documentation)
  • `` Wavelength``: wavelength of the line, in Angstrom. Note that default cloudy behavior is to round wavelengths to the nearest Angstrom.
  • Luminosity: line luminosity, in erg/s

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, the data are written in a FITS file containing two binary table extensions. The first extension contains two fields, Line_label and Wavelength, giving the four-letter cloudy line codes and central wavelengths. The second extension contains four columns, giving the unique ID, trial number, time, and line luminosity for each line at each time in each trial.

If the SLUG data input to cloudy_slug were written in binary mode, the data are written in a raw binary file. The file starts with a header consisting of

  • NLine (python int, equivalent to C long): number of lines
  • LineLabel (NLine entries stored as ASCII text): line labels listed in ASCII, one label per line

This is followed by a series of records, one for each output time, with different trials ordered sequentially, so that all the times for one trial are output before the first time for the next trial. Each record consists of a header containing

  • Time (double)
  • NCluster (std::vector<double>::size_type, usually unsigned long long): number of non-disrupted clusters present at this time

This is followed by NCluster entries of the following form:

  • UniqueID (numpy uint64)
  • LineLum (NLine entries of numpy float64)

The cluster_cloudyspec File

This file contains data on the spectra produced by the interaction of the stellar radiation field with the ISM around each cluster. It consists of a series of entries containing the following fields:

  • UniqueID: a unique identifier number for each cluster that is preserved across times and output files
  • Time: evolution time at which the output is produced
  • Wavelength: observed frame wavelength at which the spectrum is evaluated
  • Incident: specific luminosity in erg/s/Angstrom at the specified wavelength for the incident radiation field
  • Transmitted: specific luminosity in erg/s/Angstrom at the specified wavelength for the transmitted radiation field
  • Emitted: specific luminosity in erg/s/Angstrom at the specified wavelength for the emitted radiation field
  • Transmitted_plus_emitted: specific luminosity in erg/s/Angstrom at the specified wavelength for the transmitted plus emitted radiation field

For explanations of the distinction between the incident, transmitted, emitted, and transmitted plus emitted radiation fields, see The integrated_cloudyspec File.

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, these data are written in a FITS file containing two binary table extensions. The first table contains a column Wavelength listing the wavelengths at which the spectra are given. The second table consists of seven columns: Trial, UniqueID, Time, Incident_spectrum, Transmitted_spectrum, Emitted_spectrum, and Transmitted_plus_emitted_spectrum. The first three of these give the trial number, unique ID of the cluster, and the time. The remaining four give the incident, transmitted, emitted, and transmitted plus emitted spectra for the corresponding cluster.

If the SLUG data input to cloudy_slug were written in binary mode, these data are written to a raw binary file formatted as follows. The file starts with

  • NWavelength (numpy int64): the number of wavelength entries in the spectra
  • Wavelength (NWavelength entries of type double)

and then contains a series of records, one for each output time, with different trials ordered sequentially, so that all the times for one trial are output before the first time for the next trial. Each record consists of a header containing

  • Time (double)
  • NCluster (python int): number of non-disrupted clusters present at this time

This is followed by NCluster entries of the following form:

  • UniqueID (unsigned long)
  • Incident (NWavelength entries of numpy float64)
  • Transmitted (NWavelength entries of numpy float64)
  • Emitted (NWavelength entries of numpy float64)
  • Transmitted_plus_emitted (NWavelength entries of numpy float64)

The cluster_cloudyphot File

This file contains data on the photometry of the spectra produced by the interaction of the stellar radiation field with the ISM around each cluster. It consists of a series of entries containing the following fields:

  • UniqueID: a unique identifier number for each cluster that is preserved across times and output files
  • Time: evolution time at which the output is produced
  • PhotFilter1_trans: photometric value for the Transmitted radiation field through filter 1, where filter 1 here is the same as filter 1 in The integrated_phot File; units are also the same as in that file.
  • PhotFilter1_emit: photometric value for the Emitted radiation field through filter 1
  • PhotFilter1_trans_emit: photometric value for the Transmitted_plus_emitted radiation field through filter 1
  • PhotFilter2_trans
  • PhotFilter2_emit
  • PhotFilter2_trans_emit
  • ...

For distinctions between the Transmitted, Emitted, and Transmitted_plus_emitted radiation fields, see The integrated_cloudyspec File, or the cloudy documentaiton. Note that we do not record photometry for the incident spectrum, since that would be, up to the accuracy of the numerical integration, identical to the photometry already recorded in the The cluster_phot File.

If the SLUG data input to cloudy_slug were written in ascii mode, these data are output as a text file containing a series of columns, with different trials separated by lines of dashes.

If the SLUG data input to cloudy_slug were written in fits mode, these data are written in a FITS file containing one binary table extension. The columns in this FITS file are Trial, UniqueID, Time, Filter1_Transmitted, Filter1_Emitted, Filter1_Transmitted_plus_emitted, .... The first three columns give the trial number, cluster unique ID, and the time, and the remainder give the photometric values for the transmitted, emitted, and transmitted plus emitted spectra in each filter.

If the SLUG data input to cloudy_slug were written in binary mode, these data are written in a raw binary file that is formatted as follows. The file starts with an ASCII text header consisting of the following, each on a separate line:

  • NFilter (stored as ASCII text): number of filters used
  • FilterName FilterUnit (NFilter entries stored as ASCII text): the name and units for each filter are listed in ASCII, one filter-unit pair per line

This is followed by a series of entries of that each begin with a header

  • Time (double)
  • NCluster (std::vector<double>::size_type, usually unsigned long long): number of non-disrupted clusters present at this time

This is followed by NCluster entries of the following form:

  • UniqueID (unsigned long)
  • PhotFilter_Transmitted (NFilter entries of numpy float64), giving the transmitted photometry in each filter
  • PhotFilter_Emitted (NFilter entries of numpy float64), giving the emitted photometry in each filter
  • PhotFilter_Transmitted_plus_emitted (NFilter entries of numpy float64), giving the transmitted plus emitted photometry in each filter

Full Documentation of slugpy.cloudy

slugpy.cloudy.read_cloudy_continuum(filename, r0=None)[source]

Reads a cloudy continuum output, produced by save last continuum

Parameters
filename : string
name of the file to be read
r0 : float
inner radius, in cm; if included, the quantities returned will be total energies instead of energy emission rates instead of rates per unit area
Returns

A namedtuple containing the following fields:

wl : array
wavelengths in Angstrom
incident : array
incident radiation field intensity
slugpy.cloudy.read_cloudy_hcon(hcon_file, r0=0.0)[source]

Reads cloudy outputs produce by the ‘save last hydrogen conditions’ and ‘save last hydrogen ionization’ file, and uses these to return various HII region diagnostic parameters.

Parameters
hcon_file : str
Name of hydrogen conditions file to be read
r0 : float
Inner radius for the calculation
Returns
r1 : float
outer radius, in cm
nII : float
average number density of H nuclei
Omega : float
wind parameter, defined as r0^3 / (r1^3 - r0^3)
Notes
All averages are averages over the ionized volume, i.e., the average is taken with a weighting factor 4 pi r^2 (n_H+/n_H) dV.
slugpy.cloudy.read_cloudy_linelist(filename)[source]

Reads a cloudy line list output, produced by save last line list

Parameters
filename : string
name of the file to be read
Returns

A namedtuple containing the following fields:

labels : array, dtype ‘S4’
list of line labels
wl : array
array of line wavelengths, in Angstrom
lum : array
array of line luminosities; this will be in whatever units the cloudy output is in
slugpy.cloudy.read_cluster_cloudyparams(model_name, output_dir=None, fmt=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 cluster_cloudyparams file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : ‘txt’ | ‘ascii’ | ‘bin’ | ‘binary’ | ‘fits’ | ‘fits2’
Format for the file to be read. If one of these is set, the function will only attempt to open ASCII-(‘txt’ or ‘ascii’), binary (‘bin’ or ‘binary’), or FITS (‘fits’ or ‘fits2’) formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

id : array, dtype uint
unique ID of cluster
trial: array, dtype uint
which trial was this cluster part of
time : array
time at which cluster’s properties are being evaluated
cloudy_hden : array
number density of H nuclei at the inner edge of the ionized region simulated by cloudy
cloudy_r0 : array
inner radius of the ionized region simulated by cloudy
cloudy_r1 : array
outer radius of the ionized region simulated by cloudy (approximate!)
cloudy_QH0 : array
ionizing luminosity used in the cloudy computation
cloudy_covFac : array
covering factor assumed in the cloudy computation; only a fraction covFac of the ionizing photons are assumed to produce emission within the HII region, while the remainder are assumed to escape
cloudy_U : array
volume-averaged ionization parameter of the HII region simulated by cloudy
cloudy_U0 : array
ionization parameter of the HII reegion at its inner edge
cloudy_Omega : array
Yeh & Matzner (2012) wind parameter for the HII region simulated by cloudy
cloudy_zeta : array
Krumholz & Matzner (2009) radiation pressure parameter for the HII region, again approximate; values of zeta >~1 indicate that radiation pressure is dynamically important

The following fields may or may not be present, depending on what is found in the output file:

cloudy_hden_out : array
volume-averaged number density produced by the cloudy calculation
cloudy_r1_out : array
HII region outer radius produced by cloudy
cloudy_Omega_out : array
value of Omega computed using cloudy_r1_out
cloudy_zeta_out : array
value of zeta computed using cloudy_r1_out

Notes

The relationships between U, U0, Omega, r0, r1, hden, and QH0 used in deriving various parameters are valid only in the limit of negligible radiation pressure. They may be significantly off if radiation pressure is significant, i.e., if zeta >~ 1.
slugpy.cloudy.read_cluster_cloudyphot(model_name, output_dir=None, fmt=None, nofilterdata=False, photsystem=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 cluster_cloudyphot file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the SLUG2 output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : string
Format for the file to be read. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’. If one of these is set, the code will only attempt to open ASCII-, binary-, or FITS-formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
nofilterdata : bool
If True, the routine does not attempt to read the filter response data from the standard location
photsystem : None or string
If photsystem is None, the data will be returned in the same photometric system in which they were read. Alternately, if it is a string, the data will be converted to the specified photometric system. Allowable values are ‘L_nu’, ‘L_lambda’, ‘AB’, ‘STMAG’, and ‘Vega’, corresponding to the options defined in the SLUG code. If this is set and the conversion requested involves a conversion from a wavelength-based system to a frequency-based one, nofilterdata must be False so that the central wavelength of the photometric filters is available.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

id : array, dtype uint
unique ID of cluster
trial: array, dtype uint
which trial was this cluster part of
time : array
times at which cluster spectra are output, in yr
cloudy_filter_names : list of string
a list giving the name for each filter
cloudy_filter_units : list of string
a list giving the units for each filter
cloudy_filter_wl_eff : list
effective wavelength of each filter; this is set to None for the filters Lbol, QH0, QHe0, and QHe1; omitted if nofilterdata is True
cloudy_filter_wl : list of arrays
a list giving the wavelength table for each filter; this is None for the filters Lbol, QH0, QHe0, and QHe1; omitted if nofilterdata is True
cloudy_filter_response : list of arrays
a list giving the photon response function for each filter; this is None for the filters Lbol, QH0, QHe0, and QHe1; omitted if nofilterdata is True
cloudy_filter_beta : list
powerlaw index beta for each filter; used to normalize the photometry
cloudy_filter_wl_c : list
pivot wavelength for each filter; used to normalize the photometry
cloudy_phot_trans : array, shape (N_cluster, N_filter)
photometric value for each cluster in each filter for the transmitted light (i.e., the starlight remaining after it has passed through the HII region); units are as indicated in the units field
cloudy_phot_emit : array, shape (N_cluster, N_filter)
photometric value for each cluster in each filter for the emitted light (i.e., the diffuse light emitted by the HII region); units are as indicated in the units field
cloudy_phot_trans_emit : array, shape (N_cluster, N_filter)
photometric value in each filter for each cluster for the transmitted plus emitted light (i.e., the light coming directly from the stars after absorption by the HII region, plus the diffuse light emitted by the HII region); units are as indicated in the units field
Raises
IOError, if no photometry file can be opened; ValueError, if photsystem is set to an unknown value
slugpy.cloudy.read_cluster_cloudylines(model_name, output_dir=None, fmt=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 cluster_cloudylines file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the SLUG2 output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : string
Format for the file to be read. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’. If one of these is set, the code will only attempt to open ASCII-, binary-, or FITS-formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

id : array, dtype uint
unique ID of cluster
trial: array, dtype uint
which trial was this cluster part of
time : array
times at which cluster spectra are output, in yr
cloudy_linelabel : array, dtype=’S4’, shape (N_lines)
labels for the lines, following cloudy’s 4 character line label notation
cloudy_linewl : array, shape (N_lines)
rest wavelength for each line, in Angstrom
cloudy_linelum : array, shape (N_cluster, N_lines)
luminosity of each line at each time for each trial, in erg/s
slugpy.cloudy.read_cluster_cloudyspec(model_name, output_dir=None, fmt=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 cluster_cloudyspec file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the SLUG2 output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : string
Format for the file to be read. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’. If one of these is set, the code will only attempt to open ASCII-, binary-, or FITS-formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

id : array, dtype uint
unique ID of cluster
trial: array, dtype uint
which trial was this cluster part of
time : array
times at which cluster spectra are output, in yr
cloudy_wl : array
wavelength, in Angstrom
cloudy_inc : array, shape (N_cluster, N_wavelength)
specific luminosity of the cluster’s stellar radiation field at each wavelength, in erg/s/A
cloudy_trans : array, shape (N_cluster, N_wavelength)
specific luminosity of the stellar radiation field after it has passed through the HII region, at each wavelength, in erg/s/A
cloudy_emit : array, shape (N_cluster, N_wavelength)
specific luminosity of the radiation field emitted by the HII region, at each wavelength, in erg/s/A
cloudy_trans_emit : array, shape (N_cluster, N_wavelength)
the sum of the emitted and transmitted fields; this is what would be seen by an observer looking at both the star cluster and its nebula
Raises
IOError, if no spectrum file can be opened
slugpy.cloudy.read_integrated_cloudylines(model_name, output_dir=None, fmt=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 integrated_cloudylines file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the SLUG2 output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : string
Format for the file to be read. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’. If one of these is set, the code will only attempt to open ASCII-, binary-, or FITS-formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

time : array, shape (N_times) or shape (N_trials)
Times at which data are output; shape is either N_times (if the run was done with fixed output times) or N_trials (if the run was done with random output times)
cloudy_linelabel : array, dtype=’S4’, shape (N_lines)
labels for the lines, following cloudy’s 4 character line label notation
cloudy_linewl : array, shape (N_lines)
rest wavelength for each line, in Angstrom
cloudy_linelum : array, shape (N_lines, N_times, N_trials)
luminosity of each line at each time for each trial, in erg/s
slugpy.cloudy.read_integrated_cloudyparams(model_name, output_dir=None, fmt=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 integrated_cloudyparams file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the SLUG2 output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : string
Format for the file to be read. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’. If one of these is set, the code will only attempt to open ASCII-, binary-, or FITS-formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

time : array, shape (N_times) or shape (N_trials)
Times at which data are output; shape is either N_times (if the run was done with fixed output times) or N_trials (if the run was done with random output times)
cloudy_hden : array
number density of H nuclei at the inner edge of the ionized region simulated by cloudy
cloudy_r0 : array
inner radius of the ionized region simulated by cloudy
cloudy_r1 : array
outer radius of the ionized region simulated by cloudy (approximate!)
cloudy_QH0 : array
ionizing luminosity used in the cloudy computation
cloudy_covFac : array
covering factor assumed in the cloudy computation; only a fraction covFac of the ionizing photons are assumed to produce emission within the HII region, while the remainder are assumed to escape
cloudy_U : array
volume-averaged ionization parameter of the HII region simulated by cloudy
cloudy_U0 : array
ionization parameter of the HII reegion at its inner edge
cloudy_Omega : array
Yeh & Matzner (2012) wind parameter for the HII region simulated by cloudy
cloudy_zeta : array
Krumholz & Matzner (2009) radiation pressure parameter for the HII region, again approximate; values of zeta >~1 indicate that radiation pressure is dynamically important

The following fields may or may not be present, depending on what is found in the output file:

cloudy_hden_out : array
volume-averaged number density produced by the cloudy calculation
cloudy_r1_out : array
HII region outer radius produced by cloudy
cloudy_Omega_out : array
value of Omega computed using cloudy_r1_out
cloudy_zeta_out : array
value of zeta computed using cloudy_r1_out

Notes

The relationships between U, U0, Omega, r0, r1, hden, and QH0 used in deriving various parameters are valid only in the limit of negligible radiation pressure. They may be significantly off if radiation pressure is significant, i.e., if zeta >~ 1.
slugpy.cloudy.read_integrated_cloudyphot(model_name, output_dir=None, fmt=None, nofilterdata=False, photsystem=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 integrated_cloudyphot file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the SLUG2 output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : string
Format for the file to be read. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’. If one of these is set, the code will only attempt to open ASCII-, binary-, or FITS-formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
nofilterdata : bool
If True, the routine does not attempt to read the filter response data from the standard location
photsystem : None or string
If photsystem is None, the data will be returned in the same photometric system in which they were read. Alternately, if it is a string, the data will be converted to the specified photometric system. Allowable values are ‘L_nu’, ‘L_lambda’, ‘AB’, ‘STMAG’, and ‘Vega’, corresponding to the options defined in the SLUG code. If this is set and the conversion requested involves a conversion from a wavelength-based system to a frequency-based one, nofilterdata must be False so that the central wavelength of the photometric filters is available.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

time : array, shape (N_times) or shape (N_trials)
Times at which data are output; shape is either N_times (if the run was done with fixed output times) or N_trials (if the run was done with random output times)
cloudy_filter_names : list of string
a list giving the name for each filter
cloudy_filter_units : list of string
a list giving the units for each filter
cloudy_filter_wl_eff : list
effective wavelength of each filter; this is set to None for the filters Lbol, QH0, QHe0, and QHe1; omitted if nofilterdata is True
cloudy_filter_wl : list of arrays
a list giving the wavelength table for each filter; this is None for the filters Lbol, QH0, QHe0, and QHe1; omitted if nofilterdata is True
cloudy_filter_response : list of arrays
a list giving the photon response function for each filter; this is None for the filters Lbol, QH0, QHe0, and QHe1; omitted if nofilterdata is True
cloudy_filter_beta : list
powerlaw index beta for each filter; used to normalize the photometry
cloudy_filter_wl_c : list
pivot wavelength for each filter; used to normalize the photometry
cloudy_phot_trans : array, shape (N_filter, N_times, N_trials)
photometric value in each filter at each time in each trial for the transmitted light (i.e., the starlight remaining after it has passed through the HII region); units are as indicated in the units field
cloudy_phot_emit : array, shape (N_filter, N_times, N_trials)
photometric value in each filter at each time in each trial for the emitted light (i.e., the diffuse light emitted by the HII region); units are as indicated in the units field
cloudy_phot_trans_emit : array, shape (N_filter, N_times, N_trials)
photometric value in each filter at each time in each trial for the transmitted plus emitted light (i.e., the light coming directly from the stars after absorption by the HII region, plus the diffuse light emitted by the HII region); units are as indicated in the units field
Raises
IOError, if no photometry file can be opened; ValueError, if photsystem is set to an unknown value
slugpy.cloudy.read_integrated_cloudyspec(model_name, output_dir=None, fmt=None, verbose=False, read_info=None)[source]

Function to read a SLUG2 integrated_cloudyspec file.

Parameters
model_name : string
The name of the model to be read
output_dir : string
The directory where the SLUG2 output is located; if set to None, the current directory is searched, followed by the SLUG_DIR directory if that environment variable is set
fmt : string
Format for the file to be read. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’. If one of these is set, the code will only attempt to open ASCII-, binary-, or FITS-formatted output, ending in .txt., .bin, or .fits, respectively. If set to None, the code will try to open ASCII files first, then if it fails try binary files, and if it fails again try FITS files.
verbose : bool
If True, verbose output is printed as code runs
read_info : dict
On return, this dict will contain the keys ‘fname’ and ‘format’, giving the name of the file read and the format it was in; ‘format’ will be one of ‘ascii’, ‘binary’, or ‘fits’
Returns

A namedtuple containing the following fields:

time : array, shape (N_times) or shape (N_trials)
Times at which data are output; shape is either N_times (if the run was done with fixed output times) or N_trials (if the run was done with random output times)
cloudy_wl : array
wavelength, in Angstrom
cloudy_inc : array, shape (N_wavelength, N_times, N_trials)
specific luminosity of the stellar radiation field at each wavelength and each time for each trial, in erg/s/A
cloudy_trans : array, shape (N_wavelength, N_times, N_trials)
specific luminosity of the stellar radiation field after it has passed through the HII region, at each wavelength and each time for each trial, in erg/s/A
cloudy_emit : array, shape (N_wavelength, N_times, N_trials)
specific luminosity of the radiation field emitted by the HII region, at each wavelength and each time for each trial, in erg/s/A
cloudy_trans_emit : array, shape (N_wavelength, N_times, N_trials)
the sum of emitted and transmitted; this is what would be seen by an observer looking at both the star cluster and its nebula
slugpy.cloudy.write_cluster_cloudyparams(data, model_name, fmt)[source]

Write out photometry for nebular emission computed by cloudy on a slug spectrum for a series of clusters

Parameters
data : namedtuple
Cluster cloudy parameter data; a namedtuple containing the fields id, trial, time, cloudy_hden, cloudy_r0, cloudy_r1, cloudy_QH0, cloudy_covFac, cloudy_U, cloudy_U0, cloudy_Omega, and cloudy_zeta; may also optionally contain the fields cloudy_r1_out, cloudy_hden_out, cloudy_Omega_out, and cloudy_zeta_out
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing
slugpy.cloudy.write_cluster_cloudyphot(data, model_name, fmt)[source]

Write out photometry for nebular emission computed by cloudy on a slug spectrum for a series of clusters

Parameters
data : namedtuple
Cluster cloudy photometry data to be written; a namedtuple containing the fields id, time, cloudy_filter_names, cloudy_filter_units, cloudy_phot_trans, cloudy_phot_emit, and cloudy_phot_trans_emit
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing
slugpy.cloudy.write_cluster_cloudylines(data, model_name, fmt)[source]

Write out data computed by cloudy on a slug spectrum

Parameters
data : namedtuple
Cloudy spectral data for clusters to be written; a namedtuple containing the fields time, cloudy_linelist, cloudy_linewl, cloudy_linelum
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing
slugpy.cloudy.write_cluster_cloudyspec(data, model_name, fmt)[source]

Write out data computed by cloudy on a slug spectrum

Parameters
data : namedtuple
Cloudy spectral data for clusters to be written; a namedtuple containing the fields id, time, cloudy_wl, cloudy_inc, cloudy_trans, cloudy_emit, and cloudy_trans_emit
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing
slugpy.cloudy.write_integrated_cloudyparams(data, model_name, fmt)[source]

Write out photometry for nebular emission computed by cloudy on a slug spectrum for a series of clusters

Parameters
data : namedtuple
Cluster cloudy parameter data; a namedtuple containing the fields time, cloudy_hden, cloudy_r0, cloudy_r1, cloudy_QH0, cloudy_covFac, cloudy_U, cloudy_U0, cloudy_Omega, and cloudy_zeta; may also optionally contain the fields cloudy_r1_out, cloudy_hden_out, cloudy_Omega_out, and cloudy_zeta_out
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing
slugpy.cloudy.write_integrated_cloudylines(data, model_name, fmt)[source]

Write out line luminosities computed by cloudy on a slug spectrum

Parameters
data : namedtuple
Integrated cloudy line data to be written; a namedtuple containing the fields time, cloudy_linelist, cloudy_linewl, cloudy_linelum
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing
slugpy.cloudy.write_integrated_cloudyphot(data, model_name, fmt)[source]

Write out photometry for nebular emission computed by cloudy on a slug spectrum

Parameters
data : namedtuple
Integrated cloudy photometry data to be written; a namedtuple containing the fields time, cloudy_filter_names, cloudy_filter_units, cloudy_phot_trans, cloudy_phot_emit, and cloudy_phot_trans_emit
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing
slugpy.cloudy.write_integrated_cloudyspec(data, model_name, fmt)[source]

Write out data computed by cloudy on a slug spectrum

Parameters
data : namedtuple
Integrated cloudy spectral data to be written; a namedtuple containing the field time, cloudy_wl, cloudy_inc, cloudy_trans, cloudy_emit, and cloudy_trans_emit
model_name : string
Base file name to give the model to be written. Can include a directory specification if desired.
fmt : string
Format for the output file. Allowed values are ‘ascii’, ‘bin’ or ‘binary, and ‘fits’.
Returns
Nothing