2.1. Migration of nublado.org

There were few (if any) viable options for migrating the entire project to a new host without significant manual intervention. That being the case, it was decided that this was an opportunity to migrate Cloudy to more modern and flexible version control and tooling. Trac¹ is rather dated at this point. It has not seen a significant update in many years, and it is built on Python 2.x, which is no longer being developed or supported. Subversion² (SVN) is still actively maintained, but many development projects have moved to using Git, which has a larger community of users and developers. After reviewing options for Git project hosting, it was ultimately decided to use GitLab³ hosted at UK for the Cloudy source code, issue tracker, and wiki. GitLab offers a free, open-source edition and provides free access to their licensed features and support services for opensource research software.

Migrating the existing data to GitLab in its entirety would be a difficult task. The existing SVN repository contained several decades of revision history, and the Trac interface held a large number of wiki articles and issue data. It was decided that the existing code revision history would not be migrated to Git. Instead, there would be an initial commit in the Git repository containing a reference to the Subversion repository for historical purposes. This greatly simplified the migration process. Issue data and wiki pages were migrated to GitLab using TracBoat⁴. This tool provided a very basic semi-automated migration but did not preserve all aspects of the content. In particular, wiki links were removed and had to be re-added manually.

The existing Trac site and Subversion repository were migrated to a new system at UK for historical reference purposes. They were configured as readonly, and the default destination for project links is redirected to the GitLab instance. Static files, including data sets, were also migrated and continue to be available and updated as needed.

2.2. User Forum Migration

A forum where Cloudy users can post questions or report problems has been available since June 2005. It had been hosted on yahoo.com until Fall 2019, when the company decided to withdraw support for groups. A key requirement for choosing a new host was to preserve the history of questions and answers posted on yahoo.com. groups.io met our needs, and the forum migrated to https://cloudyastrophysics.groups.io.

The new platform has allowed for more versatility. Our new setup now features a Main group, which preserves and extends our Q&A service. It also carries an Announcements group, where important announcements, e.g., about Cloudy workshops, are made; a Code group, where users can share scripts with other users; and finally a Results group, where users can share results obtained using Cloudy with the broader community. Users are encouraged to subscribe to all these groups.

3.1. Upgrade to Chianti Version 10

Cloudy has now adopted Chianti version 10.0.1. Previously, the code had been using version 7.1, released in 2013. The difficulty with upgrading earlier has been due to the changes the database format since v7.1. To remedy this, we developed a script to reprocess the version 10 data into the version 7 format. A detailed discussion of the script and changes to spectral line predictions as a result of the new database is presented in ^{Gunasekera et al. (2022a)}. The reprocessing script has been made open-source and is available at https://gitlab.nublado.org/arrack.

Due to the large number of additional atomic levels in version 10, the full reprocessed Chianti database is >15 times the size of version 7. Since many of these levels are above the ionization limit of the corresponding species, we have omitted all auto-ionizing levels from the default version utilized by Cloudy. Both the full reprocessed v10 database and the one without the auto-ionizing levels can be downloaded from http://data.nublado.org/chianti/.

3.2. Updates to the Stout Database

The format of the Stout (^{Lykins et al. 2015}) data files has been updated⁵. The most important change is that the spectroscopic information must now be enclosed in double quotes in the *.nrg files. This makes it easier for the code to extract this information, which is now included in the save line labels output. Also, the keywords in the *.coll files have been updated to make parsing easier. The new format is designated by the magic number “17 09 05”.

The Stout database now supports having multiple atomic or molecular datasets for a given species. This is necessary because it is not always possible to unequivocally decide which calculation is the better one. In such a case, one of these datasets will be designated as the default set, but the user has the option to switch to a different set using the new option to the species command. For example, in the command species “Fe+6” dataset=“alt”, alt is the nickname for the alternate dataset; Cloudy will use the data in the Fe 7 alt.* for this species.

Fe III collision strengths are updated to ^{Badnell & Ballance (2014)}. We had previously used data from ^{Zhang (1996)}. Energies are from NIST with missing levels taken from ^{Badnell & Ballance (2014)}. ^{Laha et al. (2017)} describe how the data were matched to experimental energies. Tests show that the total Fe III cooling increases by nearly 50%.

Certain “baseline” models (i.e., models without accurate collisions, see ^{Ferland et al. 2017}) in the Stout database have been updated to use collisional, transition probability, and energy data from the ADAS database. NIST energies are employed for the lowest excited levels, to permit the correct identification of spectral lines of astronomical interest. The species that have been updated include Mg⁺⁹ (^{Liang & Badnell 2011}), Al⁺² (^{Liang et al. 2009}), and S⁺⁴ (^{Fernández-Menchero et al. 2014}).

3.3. Fe II

The Fe ii ion has a complex structure with 25 electrons, and is a “grand challenge” problem in atomic physics. An accurate set of radiative and collisional atomic data is therefore needed to treat selective excitation, continuum pumping, and fluorescence, which are known to be crucial for the Fe II emission (e.g., ^{Verner et al. 2000}; ^{Baldwin et al. 2004}; ^{Bruhweiler & Verner 2008}; ^{Jin et al. 2012}; ^{Wang et al. 2016}; ^{Netzer 2020}). Uncertainties in the atomic data have been a longstanding limitation in interpreting line intensities.

Until recently, Cloudy shipped with the ^{Verner et al. (1999)} model, which has 371 levels that reach 11.6 eV, has about 68,000 transition probabilities, but uses the “g-bar” approximation for collision strengths. Due to its limitations, ^{Sarkar et al. (2021)} explored three other atomic models, that are now available with Cloudy; their energy levels are compared in Figure 1.

Fig. 1 Energy level structure of the Fe ii models available with Cloudy. From left to right, the atomic datasets are those of ^{Verner et al. (1999)}, ^{Bautista et al. (2015)}, ^{Tayal & Zatsarinny (2018)}, and ^{Smyth et al. (2019)}. The H I and Fe II ionization limits, the Lyα energy, an important source of photoexcitation for Fe II, and the thermal energy corresponding to 10⁴ K are also indicated. Adapted from ^{Sarkar et al. (2021)}. The color figure can be viewed online. 

Of relevance to the 2000-3000Å ultraviolet range are the datasets of ^{Tayal & Zatsarinny (2018)} and ^{Smyth et al. (2019)}. The ^{Tayal & Zatsarinny (2018)} model has 340 energy levels with the highest energy of ≈ 16.6 eV, that is, it goes above the ionization limit (16.2 eV). However, its density of states in highlying energy levels is low, as shown in Figure 1. Transitions between these energy levels produce about 58,000 emission lines with uncertainties in transition probabilities of ≲ 30% (in the 2200Å-7800Å). On the other hand, the ^{Smyth et al. (2019)} model includes 716 levels in the close coupling (scattering model) calculation, with the highest energy level reaching 26.4 eV. These levels produce about 256,000 emission lines. The ^{Smyth et al. (2019)} dataset also contains autoionizing levels, but its density of states in the high-lying energy states is larger than the ^{Tayal & Zatsarinny (2018)} dataset. Further details on these atomic models can be found in ^{Sarkar et al. (2021)}. Both models have been incorporated into Cloudy.

^{Sarkar et al. (2021)} showed that with the ^{Smyth et al. (2019)} dataset, Cloudy produces a spectrum that is in satisfactory agreement with the template spectrum of the I Zw 1 Seyfert galaxy (^{Vestergaard & Wilkes 2001}). Briefly, the better agreement of the Smyth dataset is due to the higher density of highly excited states, which enhance the effects of continuum fluorescence and lead to brighter emission lines at short wavelengths. Further details are described in the paper. Figure 2 illustrates the quality of that comparison.

Fig. 2 Comparison between the observed Fe II UV template of ^{Vestergaard & Wilkes (2001)} and the Cloudy predicted Fe II UV spectrum with V_turb = 100 km/s. The color figure can be viewed online. 

3.4. Kα Energies

We incorporated precise H-like Kα energies for elements between 6 ≤ Z ≤ 30 to match laboratory energies (^{Chakraborty et al. 2020a}). Figure 3 compares the difference in Kα energies between NIST (^{Kramida et al. 2018}) and Cloudy for the updated Cloudy energies and the old Cloudy energies appearing in C17.02. The revised Kα energies are ≈ 15-4000 times more precise than those of C17.02. This energy precision is also much superior to the energy accuracy of the current and future X-ray instruments like Chandra, XMM-Newton, XRISM, and Athena, as shown in Figure 3. The improved Cloudy energies will therefore be in excellent agreement with the future microcalorimeter observations.

Fig. 3 The absolute value of the difference between NIST and Cloudy Kα energies versus Kα energies for H-like ions of elements between 6 ≤ Z ≤ 30. Red triangles show the difference between energies in the current version (as of C17.03) of Cloudy and NIST, while green circles show the same difference for previous versions of Cloudy (from ≈2005 to C17.02). The color figure can be viewed online. 

3.5. Inner Shell Energies

We updated the fluorescence Kα energies of Si II-XI and S II-XIII used in Cloudy with the experimental data reported in ^{Hell et al. (2016)}. The energies of the lines in the past versions of Cloudy are mainly taken from Table 3 of ^{Kaastra & Mewe (1993)}, which contains the fluorescence yields, energies and Auger electron numbers for elements and ions from Be to Zn. Even though these values were in accordance with the theoretical calculations available at the time of the publication, today, this dataset is not accurate enough to model some already available high-resolution spectra (^{Amato et al. 2021}; ^{Camilloni et al. 2021}), and certainly for future X-ray spectra having eV resolution.

For this reason, we updated the energies from O-like to Be-like ions of Si and S (Si VII-XI and S IX-XIII) adopting the centroids for unresolved blends given in Table 3 of ^{Hell et al. (2016)}. Regarding the low-ionization lines, individual energies are taken from their Table 5, where the values of Si II-IV, Si V-VI, S II-VI and S VII-VIII are listed.

Kα ₁ and Kα ₂ are not experimentally resolved in ^{Hell et al. (2016)}, and their difference in energy is lower than the expected resolution of future X-ray microcalorimeters, so we assumed the same energy for both. ^{Camilloni et al. (2021)} provided a demonstration of the impact that such an update can have on the high-resolution spectra of the high mass X-ray binary Vela X-1 (see Figure 4).

Fig. 4 Visually co-added Chandra MEG ±1 order spectra of the HMXB Vela X-1 at the orbital phase ϕ _orb = 0.75 (see ^{Amato et al. 2021}). Top: Best fit model with Cloudy (grey solid line), using the improved energies for the Si fluorescence lines, available in C23. The specific contributions of each gas component are labeled (red dashed line and blue dot-dashed line), together with the best-fit parameters and 90% confidence level uncertainties (see ^{Camilloni et al. 2021}, for details). Bottom: As above, but with the previous version of Cloudy, C17. The low ionization component is here labeled in green, together with the adopted Si Kα lines (from ^{Kaastra & Mewe 1993}). For ease of comparison, the improved energies from ^{Hell et al. (2016)} are in blue, as in the top panel. Adapted from ^{Camilloni et al. (2021)}. The color figure can be viewed online. 

3.6. ℓ-changing Collisions

Momentum-changing collisions by protons were deeply revised in C17. An upgrade of the theory of ^{Pengelly & Seaton (1964, hereafter PS64)}, dubbed PS-M, was published by ^{Guzmán et al. (2017b)}, correcting the results at high density and low temperature of PS64 and getting a better agreement with the quantum-mechanical ab initio results from ^{Vrinceanu & Flannery (2001, hereafter VF01)}. The theory has been further refined by ^{Badnell et al. (2021)}, now called PS-M20. PS-M/PS-M20 results were in better agreement with the quantal calculations than the semi-classical calculations from ^{Vrinceanu et al. (2012)} (hereafter VOS12), which underestimate VF01 by a factor ≈ 6 (^{Guzmán et al. 2016}). Semi-classical rates were corrected by ^{Vrinceanu et al. (2017)} to get agreement with VF01 and PS-M. ^{Vrinceanu et al. (2019)} report in their Figure 2 a disagreement of PS-M rates with quantum mechanical rates for high n. However, we have confirmed that PS-M rates actually agree with the quantum mechanical ones for the results plotted in their figure. Their reported disagreement can be explained because they calculated the excitation ℓ → ℓ + 1 collisions incorrectly using the formula given by ^{Guzmán et al. (2017b)}, optimized for deexcitation collisions (ℓ → ℓ−1). If micro-reversibility is applied to the results of ^{Vrinceanu et al. (2019)} the obtained rates agree with the quantum ones for the entire range of the figure (^{Badnell et al. 2021}).

^{Guzmán et al. (2017a)} compared in their Tables 1 and 2 PS-M effective recombination rates to n = 2 levels of hydrogen with the ones quoted in Tables 4.10 and 4.11 of ^{Osterbrock & Ferland (2006)}, obtained from ^{Pengelly & Seaton (1964)}. PS-M produces effective recombination coefficients to 2s that are bigger in a ≈ 0.6% for Case A and a ≈ 0.1% for Case B, while recombination to 2p is smaller by ≈ 1−2%. Similarly, they found an agreement up to ≈ 5% for the emissivities of 2s2S→2p2P3/2o and up to a ≈ 0.5% for 2s2S→2p2P3/20→2p2P1/2o. We do not expect this to influence Lyα or the two-photon emission spectrum.

PS-M20 theory has been implemented in the latest versions of Cloudy for H-like and He-like ions. Cloudy selects PS-M20 theory by default if not specified. The command that selects the new PS-M20 results is:

for H-like collisions, and

for He-like systems.

3.6.1. The Importance of a Correct Number of Resolved Levels: Printing ℓ-changing Critical Densities

Accurate modeling of recombination lines for H-like and He-like ions requires a good description of the ion energy levels. Cloudy distinguishes between angular momentum ℓ-resolved levels and collapsed levels, for which ℓ-levels are populated according to their statistical weight (see ^{Ferland et al. 2013}, for more details).

Critical densities are defined as the density where collisional rates equal radiative de-excitation, n _e,c q _lu = τ _ul ⁻¹ (^{Pengelly & Seaton 1964}), where τ _ul is the half-life of radiative de-excitation between u and ℓ sub-shells, and q _lu is the effective coefficient of collisional excitation between ℓ and u sub-shells. Then averaging over ℓ we can obtain the critical density for the shell

for densities above n _e,c , collisions will be faster than radiative decay and dominate, ultimately bringing the n-shell to be statistically populated in its ℓ-sub-shells.

that can be used to print ℓ-changing critical densities for H-like and He-like ions in the output file. This command aims to help choose a physically-motivated number of resolved levels to employ in a simulation for each ion.

Optionally, H-like or He-like can be added together with an element name to specifically print the critical densities for an ion. For example, while the command line above prints critical densities for all resolved levels included in the simulations for all H-like and He-like ions, the more specific command,

In Figure 5 we have plotted the critical densities obtained with Cloudy using PS-M ℓ-changing theory versus the principal quantum number. Critical densities from Figure 4 of ^{Pengelly & Seaton (1964)} are also plotted for comparison. Complete agreement is shown in the figure. When densities are higher than the critical densities, collisions dominate and the ℓ quantum numbers redistribution is faster. At much higher densities the population of the ℓ-sub-shells will be statistical. Figure 5 can be used to determine the number of levels that should be treated as resolved in ℓ. As a rule of thumb, it is safe to add ten units to the principal quantum number for which the density is critical to ensure that collisions will statistically populate the levels treated as collapsed. For example, in a simulation of an H II region with density n _e = 10⁴ cm⁻³, the principal quantum number corresponding to that density would be n ≈ 15, according to Figure 5 (we can use the print critical density command to verify the critical densities for all resolved levels). A safe number of resolved levels to use is all levels n ≤ 25, that can be included in the simulations with the line (^{Ferland et al. 2017}):

Fig. 5 Comparison of critical densities from equation 1 with ℓ-changing collisions from PS-M20 with the results of Figure 4 of ^{Pengelly & Seaton (1964)}. We have chosen a pure hydrogen gas at electron temperature T = 10000K and electron density n _e = 10⁴ cm⁻³. The agreement is complete. The color figure can be viewed online. 

Note that different conditions of electron temperature and densities might cause the critical densities to vary, obeying the temperature dependence of the ℓ-changing cross sections, as well as their dependence on density due to the Debye cut-off of the collision probabilities (^{Pengelly & Seaton 1964}; ^{Guzmán et al. 2016}).

3.7. n-changing Collisions

Principal quantum number-changing electron collision data were analyzed by ^{Guzmán et al. (2019)}. C17 and previous versions used semiempirical data from ^{Vriens & Smeets (1980, hereafter VS80)}. ^{Guzmán et al. (2019)} suggested using the semiclassical straight trajectory Born approximation of ^{Lebedev & Beigman (1998, hereafter LB98)}. The latter is within a factor of ≈ 2 of VS80 collisions and has the same dependency on the high- and lowenergy range. Care must be taken when dealing with highly charged ions as the straight trajectory approximation would fail, especially at low energies, producing an underestimation of the rates. In that case, it would not be safer to use VS80, as this is intended only for atoms. Further theoretical work is needed for a better theory for highly charged ions.

While LB98 is the default theory for both H-like and He-like n-changing collisions, it is possible to choose between different theories in Cloudy using the command:

where H-like can be modified to He-like and the options are:

A comparison and analysis of these theories and application to different cases can be found at ^{Guzmán et al. (2019)}.

4.1. H ₂

A large model of molecular hydrogen was introduced by ^{Shaw et al. (2005)}. The level energies, which we use to derive line wavelengths, have been updated to ^{Komasa et al. (2011)}. This work incorporates many high-order effects in the H₂ wavefunctions, which result in ≈ 1 wavenumber changes in level energies. We derive line wavelengths from these energies, so small changes in wavelength result. The ^{Komasa et al. (2011)} energies are thought to be a significant improvement over previous data sets.

The previous version of Cloudy included the ^{Lique (2015)} H - H₂ collisional data as an option, although they were not used by default. We now use this as our preferred H - H₂ collision data set. Compared with previous calculations, these data extend to higher vibrational manifolds and include orthopara changing reactive collisions. Tests show that the H₂ 2.121 µm line intensity changes by roughly 50%, becoming stronger in some PDR sims.

4.2. Other Molecules

Molecular lines are sensitive to underlying physical conditions. Hence, they reveal physical conditions in various astrophysical environments when interpreted correctly. It is always our aim to predict more molecular lines with better precision. We do it in two ways. Firstly, by including more molecules in the Cloudy molecular network. Secondly, by updating the existing molecular network. Below, we mention such recent efforts.

^{Shaw et al. (2022)} have included the gas-phase energy levels, radiative and collisional rates for HF, CF⁺, HC₃N, ArH⁺, HCl, HCN, CN, CH, and CH₂ into Cloudy’s molecular network. The energy levels and collisional rate coefficients were taken from the upgraded LAMDA Database (^{van der Tak et al. 2020}). However, reaction rates stem from the UMIST Database for Astrochemistry (UDfA 2012; RATE12), specifically, ^{Roueff et al. (2014)}; ^{Schilke et al. (2014)}; ^{Priestley et al. (2017)}. As a result, Cloudy now predicts the line intensities and column densities of these molecules in addition to those included in the previous version. Figure 6 (^{Shaw et al. 2022}) shows the variation of densities of a few molecules as a function of A _V. The name of each molecule and the line representing its density are depicted in the same color. The solid lines represent simulations using this version, and the dashed lines represent simulations using the earlier version C17.

Fig. 6 Variation of densities of a few molecules as a function of A _V for an H II and PDR model (”h2₋orion₋hii₋pdr.in” from the Cloudy download under the directory tsuite). The name of each molecule and the line representing its density are depicted in the same color. The solid lines represent simulations using this version, and the dashed lines represent simulations using an earlier version C17. The color figure can be viewed online. 

Likewise, we have included the gas-phase chemical reactions, energy levels, and radiative and collisional rates of the SiS molecule (^{Shaw et al. 2023a}). The energy levels, Einstein’s radiation coefficients and collisional rate coefficients with H₂ molecules were taken from the upgraded LAMDA database. In addition, we have included collisions with H (^{Anusuri 2019}) and He (^{Vincent et al. 2007}; ^{Tobol a et al. 2008}). The chemical reaction rates were taken from various sources, UDfA, namely ^{Zanchet et al. (2018)}, ^{Willacy & Cherchneff (1998)}, ^{Doddipatla et al. (2021)}; and the Kinetic Database for Astrochemistry,⁶ respectively. Figure 7 (^{Shaw et al. 2023a}) demonstrates predicted intensities of various rotational lines of SiS for an H II and PDR model (“h2₋orion₋hii₋pdr.in”) from the Cloudy download under the directory tsuite.

Fig. 7 Panel 1: Variation of SiS density as a function of A _V for an H II and PDR model (“h2₋orion₋hii₋pdr.in” from the Cloudy download under the directory tsuite). Panel 2: Variation of temperature across the cloud. Panel 3: Model predicted intensities of various SiS rotational lines. The color figure can be viewed online. 

^{Shaw et al. (2023a)} included only rotational levels of SiS. However, we have now included the vibrotational levels (private communication with Ziwei Zhang).

Any species’ predicted column densities and line intensities depend on rate coefficients. We use mostly UDfA rate coefficients. In the UDfA, a two-body gas-phase chemical reaction rate coefficient k (cm³ s⁻¹) is given by the usual Arrhenius-type formula,

where T is the gas temperature. Reactions with γ < 0 will become unphysically large at low temperatures. ^{Röllig (2011)} has addressed the divergence of rate coefficients at low temperatures. A similar problem occurs for high temperatures encountered with CLOUDY. We apply a temperature cap T _cap for β >0 to avoid this. For T > T _cap , the rate coefficients retain the same values as at T _cap . Though ad hoc, we choose T _cap = 2500K (^{Shaw et al. 2023b}). This affects the warm, 5000K - 10000K, collisionally ionized clouds.

Cosmic-ray ionization rate plays an important role in ISM and is an active field of research. ^{Shaw & Ferland (2021)} demonstrated that the abundance of PAHs affects the free electron density, which changes the H⁺ ₃ density and hence the derived cosmic-ray ionization rate of hydrogen. We suggested that for the average Galactic PAH abundance, the cosmic-ray ionization rate of atomic hydrogen be 3.9 ± 1.9 × 10⁻¹⁶ s⁻¹ . The command

sets this rate. Furthermore, we showed that the cosmic-ray ionization rate of hydrogen derived using H⁺ ₃ is much higher when PAHs are absent.

Furthermore, ^{Shaw et al. (2020)} updated the mean kinetic energy of the secondary electrons (from 20eV to 36eV) produced by cosmic rays. This affects the cosmic-ray dissociation of molecular hydrogen and dense cloud chemistry.

5.1. New Refractive Index Files

New refractive index files have been added for astronomical silicate and graphite using the data described in ^{Draine (2003)}. These add much more structure to the inner-shell photoionization edges seen in the X-ray regime.

5.2. Interstellar Grain Absorption

We have introduced a new option to the metals deplete command to use the more selfconsistent depletion pattern described in ^{Jenkins (2009)}. An in-depth discussion on this depletion pattern and how it affects the predicted spectra is presented in ^{Gunasekera et al. (2022b}, ²⁰²³⁾. This new element-selective depletion option can be enabled with

command. The depletion parameters A _X , B _X , and z _X , specific for each element X, are read in from an external file called Jenkins09 ISM-Tab4.dep, and are used to compute the depletion scale factor D _x using the equation

where F _∗ represents the degree of depletion across all elements. This D _x factor then multiplies the reference abundance to produce the post-depletion gasphase abundances. By default, F _∗ = 0.5. However, its value may be adjusted with the command

An analysis of strong spectral-lines (log([O_III] λ5007/Hβ), log([N_II] λ6583/Hα), log([S_II] λλ6716,6731/Hα), and log([Oi] λ6300/Hα)) from a Cloudy model of a generalized H II region, based on SDSS-IV MaNGA observations (^{Bundy et al. 2015}; ^{Yan et al. 2016}), revealed that varying F _∗ affects the spectral line intensities and the thermal balance of the ionized cloud (^{Gunasekera et al. 2023}). The user must alter the grain abundance to match the degree of depletion (F _∗). To do this, compute the fraction of the total abundance of heavy elements locked in dust grains in the given F _∗ relative to the total abundance of heavy elements locked in dust grains at F _∗ = 0.5,

This fraction can then be given in the grains command to change the dust abundance self-consistently.

6.1. Microcalorimeters

Historically, Cloudy made X-ray predictions but was not designed for high-resolution spectral analysis. In preparation for the upcoming microcalorimeter missions XRISM and Athena, we have extended Cloudy to make it compatible with high-resolution spectral analysis in the X-ray regime. ^{Chakraborty et al. (2020b)} demonstrated the effects of Li-like iron on the Fe XXV Kα line intensities via resonant Auger destruction (RAD; e.g., ^{Ross et al. 1978}; ^{Matt et al. 1996}; ^{Liedahl 2005}). Although initially motivated by the Perseus cluster, this analysis was extended to include a wide range of column densities encountered in astronomy.

We also showed line-broadening effects produced by electron scattering. The command no scattering escape was introduced to ignore scattering of photons off of thermal electrons (^{Chakraborty et al. 2020b}). When line photons scatter off high-speed electrons, a fraction of them receive large Doppler shifts from their line center, creating super-broad Gaussian profiles. Such broad line profiles will not be detected in future high-resolution X-ray telescopes. The purpose of the above command is to model the unscattered photons that will be observed by these future X-ray missions. The command no absorption escape was introduced to ignore absorption by background opacities.

Comparing the observed spectra by Hitomi with Cloudy simulated spectra, ^{Chakraborty et al. (2020c)} presented a novel diagnostic for measuring column densities transitioning from optically thin (Case A) to optically thick (Case B) in H- and He-like iron. The effects of metallicity and turbulence on Fe XXV Kα line ratios were also demonstrated using the Perseus cluster as a reference.

We have also updated the collision strengths of the Fe Kα lines using recent calculations by ^{Si et al. (2017)}, replacing the old collision rates by ^{Zhang & Sampson (1987)}. The new rates are calculated based on the independent process and isolated resonance approximation using distorted waves (IPIRDW) technique. Updates to the collision rates resulted in significant differences in the estimated Fe Kα line ratios, as described in ^{Chakraborty et al. (2020c)}.

^{Chakraborty et al. (2021)} extended the classic Case A and Case B (^{Osterbrock & Ferland 2006}) to less familiar regimes Case C and Case D in the X-ray band. Previous works on these limits focused on the optical, ultraviolet, and infrared regimes (^{Menzel 1937}; ^{Baker & Menzel 1938}; ^{Chamberlain 1953}; Ferland 1999; ^{Peimbert et al. 2017}), but X-ray wavelengths were rarely studied. The net X-ray spectrum for all four cases within the energy range 0.1-10 keV was simulated at the resolving power of XRISM.

^{Chakraborty et al. (2022)} demonstrated atomic processes modifying soft X-ray spectra. This includes the enhancement in line intensities via continuum pumping in photoionized environments, and suppression in line intensities through photoelectric absorption and electron scattering in collisionallyionized and photoionized enviromnents. A hybrid of Cloudy simulated collisionally-ionized and photoionized model was used to fit the Chandra Medium Energy Grating (MEG) spectrum from V1223 Sgr, an intermediate polar. This was the first application of the new Cloudy interface compatible with highresolution spectral analysis in the X-ray regime.

We also increased the default number of levels in our default instance of the Fe¹⁶⁺ ion. The default limit to the number of its levels suppressed the 15.013 Å line, which is prominent in soft X-ray spectra. ^{Ferland et al. (2017)} has an extensive discussion of our choice of a default number of levels, the effects on a calculation, and how to change it.

Finally, we have improved the energy grid resolution of Cloudy’s coarse continuum to better suit it for tailoring models to the upcoming XRISM mission.

6.2. Inner Shell Ionization

The X-ray portion of most SEDs has little effect on the ionization of an ionized cloud, as discussed for AGN in the first appendix of ^{Temple et al. (2023)}. A more general discussion is presented here.

The photoionization rate for a given shell n is

where ν ₀ , σ _ν are the photoionization threshold of shell n [Ryd] and the cross section [cm⁻²], respectively, and ϕ _ν is the flux of ionizing photons [cm⁻² s⁻¹ Ryd⁻¹]. The total photoionization rate is the sum over all shells is

Consider the case of O²⁺, a common ion of the 3 ^rd most abundance element which produces the very strong O III lines. Three subshells, 1s ², 2s ², and 2p ², contribute to the total photoionization rate. We use the data fitted by (^{Verner et al. 1996}). The cross sections are shown in Figure 8. The K-shell cross sections are nearly one dex smaller than the valence shell.

Fig. 8 The total opacity of doubly ionized oxygen is shown. The K and L shell edges are marked. The color figure can be viewed online. 

The radiation field shape enters in equation 5. Figure 9 shows a power-law continuum, one with f _ν ∝ ν ⁻¹. This is an exceptionally hard SED with a large number of K-shell photons compared with L-shell. Even quasars, with their non-thermal continuum, are not this hard. This will overestimate the importance of K-shell photoionization. The upper panel of Figure 9 shows this SED as νf _ν .

Fig. 9 The upper panel shows the SED for an f _ν ∝ ν ⁻¹ SED, an exceptionally hard continuum. The lower panel gives the photon flux, ϕ _ν ∝ f _ν /hν ∝ ν ⁻². The hash marks indicate the locations of the K and L shells. The photon flux in the K shell is ≈ 2 dex smaller than the L shell. The color figure can be viewed online. 

The photon flux ϕ _ν enters in the photoionization rate. This is the ratio ϕ _ν ∝ f _ν /hν ∝ ν ⁻². This is shown in the lower panel. The flux of K-shell photons is about 150 times smaller than the flux of L shell photons.

Cloudy includes a command to report each shell’s photoionization rate Γ _n . We need this to treat Auger electron ejection and fluorescent emission properly. That rate is shown in the following Table 1.

The L shell rates are about 150 times larger than the K shell rates, due to the different photon fluxes, cross-sections, and energy ranges. The implication is that the K-shell rates are negligible compared with the valence shell rates. One result is that differences in the X-ray portion of a SED will have little impact on UV - IR emission.

There were several papers published in the 1970s that discussed inner shell processes at length. This physics is fully included in Cloudy. Many of those papers overstated the importance of inner shell physics on the ionization.

Although the inner shell physics has little effect on the ionization of the gas, it will be important for producing X-ray fluorescent emission lines as well as X-ray transmission spectroscopy. High-resolution X-ray observations of absorbing clouds in front of the X-ray continuum source could measure the features.

9.1. Migration to C++11

The code has been ported to C++11. This version of the C++ standard delivers significant new functionality and fixes many issues with the old C++98 standard we were using until now. Adopting the new standard enables writing more versatile code. Compilers with full support for the C++11 standard have been available since April 2013 (though some vendors only finalized their support later). By now, these compilers should be widely available, and this change should not impact the ability of our users to use Cloudy. Users now need a compiler with the following minimum requirements. For GNU g++ version 4.8.1 or later, for LLVM clang++ version 3.3 or later, for the Intel compiler version 15.0 or later, and for the Oracle Developer Studio compiler version 12.5 or later.

9.2. Executing the Code

Cloudy now supports the -e flag on the command line. After this flag, the user may enter one or more Cloudy commands separated by a semicolon. This averts the need to create an input file for very simple (test) models. It can also be useful when calling Cloudy from a shell script.

The executable now accepts the -s [ seed ] command line flag. This will set a fixed seed for the random number generator and is intended for debugging and testing purposes. The parameter is a 64-bit seed in hexadecimal form. If the seed is omitted, a default fixed value will be used. It is not recommended to use this flag in normal Cloudy runs.

The -a flag on the command line has been removed. This flag was only used in debugging and had been deprecated for some time.

The code has been enhanced to catch floating point exceptions and segmentation faults on supported platforms (this includes all major compilers on Linux and MacOS). This makes grid runs even more resilient against errors in one of the grid models, allowing the code to finish the grid despite these errors.

If some models in a grid fail, the save output for that grid point may be missing. As a workaround, the code now creates a stub file for the missing output by taking the correct output from another grid point and replacing all numbers by zeros.

In previous versions, when Cloudy aborted (e.g. due to too many convergence failures) it would try to soldier on and produce some (most likely wrong) output despite the failure. This is no longer done. The code now stops immediately after the abort.

Most compilers will now generate a backtrace of the call stack at the end of the output if an error occurs. This is useful for debugging purposes.

9.3. Reading and Writing Files

For several years Cloudy allowed the user to supply a custom search path for searching data files. The development of this feature has now been finalized. The code now uses a consistent policy for finding files that it needs to read. All commands will look in the local directory first, and then in the data directory (this is the standard search path). The user can alter the search path by defining the environment variable CLOUDY DATA PATH before the code is started up. This gives the user more freedom to choose where custom data files are stored. Setting this variable will no longer affect the compilation of the code (as was the case in C17 and before). The code will always write output in the local directory. This is now enforced.

9.4. Parser Changes

We have started modifying the parser to check the script’s syntax more strictly. The long-term goal is to check everything that is typed. In this release, we will start by fully checking the command name itself. Abbreviating the command is still allowed (as was already the case in previous releases) but all the typed characters will now be checked. We will enforce US spelling where relevant.

The input deck’s set of allowed comment characters has been significantly reduced. Since version C17.01, it is no longer allowed to use “c” or “C” to start a comment. In the current version, only comments starting with “#” or “##” are allowed. Comments of the first type will be echoed in the main output, while comments starting with “##” will not be echoed.

The parser now supports line disambiguation. The Cloudy line stack may contain seemingly duplicate entries with the same label and wavelength but which are actually different lines. This can create problems if you want to use such a line. One example is the H I 4.65247 µm line, which may be either the 7 → 5 or the 35 → 7 line. You can now optionally supply the lower and upper level index, or the energy of the lower level, to indicate which line you want. The save line labels output contains the necessary information to do this. This new syntax is supported by all commands that read line identifications. It is also supported by the subroutines cdLine, cdEmis, and cdGetLineList. This type of disambiguation is not possible for all lines on the line stack.

9.5. Numerical Methods

The old random number generators have been removed from Cloudy. These were based on the Mersenne twister algorithm and the Box-Muller method for generating random numbers with a normal (Gaussian) distribution. The new code uses a fully vectorized version of xoshiro256** (^{Blackman & Vigna 2021})⁸, while the random numbers with a normal distribution are now generated using the Ziggurat algorithm (^{Marsaglia & Tsang 2000}). Both methods are much faster than the old ones. An additional advantage is that the new code is fully aware of parallelization in the code, meaning that parallel ranks created with MPI or fork will automatically have a different sequence of random numbers. The code now generates a random seed at the start of execution by default (when available derived from /dev/urandom, otherwise using the system time), unless the -s command line parameter described above is used.

9.6. New, Modified, and Deleted Commands

Since C17.01 the save xspec command has a new option normalize. In versions prior to C17, the spectra would always have the same normalization as the save continuum output. This can be inconvenient for comparing spectra in grids where the normalization of the spectra can be vastly different. When using the normalize keyword, all spectra will be normalized to 1 photoncm⁻² s⁻¹ keV⁻¹ at a photon energy of 1 keV. The user can alter the latter value to a different photon energy.

Since C17.02, the save transmitted continuum command also works in luminosity mode, and the keyword last is implicitly assumed to avoid useless output. The format of the save transmitted continuum file has changed, so files from versions C17.01 and older will no longer be accepted. Spherical dilution will now be implicitly handled when the keyword scale is used, and the first and second models both set a radius.

The command database h-like keep fine structure has been added. This allows the finestructure components of the hydrogen-like lines to be reported on the line stack. Previous versions of the code already computed these components but did not report them. This behavior is still the default, but by including this command, the fine-structure lines will be added to the line stack.

The commands crash segfault, crash abort, crash grid, and crash bounds array have been added to emulate additional sources of errors. The crash bounds heap command has been removed as Cloudy no longer uses this method of allocating memory. The crash undefined commands have been reorganized and the only option left (without any additional keywords) is to test access to an undefined variable on the stack (this used to be called crash undefined stack | auto).

The set assert abort command has been removed. Its effect was identical to the -a command line flag, which was only used for debugging the code. The stop nTotalIoniz command has been removed. This was a debugging tool that was very rarely used. The drive family of commands have been removed. These were designed to test certain aspects of the code interactively. They have not been used in a long time and are obsolete. The state command has been removed. This was an unfinished experimental feature to save or restore the state of the code. This project has now been abandoned as it was too difficult to do. The plot family of commands has been removed (as was already announced in Hazy). This was obsolete code for producing ASCII plots on line printers.

The option to set the seed for the random number generator has been removed from the database H2 noise and database H-like | He-like error generation commands. Using a random seed is now the default, so the user is no longer needed to set the seed.

The table SED command now accepts the Flambda keyword in the SED data file. Fluxes in F _ν or νF _ν units were already accepted, now F _λ units can also be used.

The upper limit to the number of lines that can be supplied to the print line sum and save lines emissivity commands has been removed.

The command set blend has been added, allowing the user to define custom line blends. This command allowed us to move most of the blends that used to be hardwired into the code (e.g., Blnd 1909) to a new init file called blends.ini that is part of the data directory. This file is parsed automatically when starting up Cloudy, unless the no blends command is included in the script.

The abundances command has been modified. It is now mandatory to include an element symbol in front of the abundance, which will determine what element the abundance belongs to. This makes the command much safer. It also allows the user to put the elements in arbitrary order and removes the need to complete the list of abundances. The elements read command has been removed as it is no longer needed.

The database He-like FSM command has been removed. It was not working correctly, and moreover, ^{Bauman et al. (2005)} found that as a result of the principle of spectroscopic stability, it had very little impact on the predictions for the Hei spectrum. The situation is different, though, for highly charged ions, e.g. FeXXV. For such ions, the individual fine-structure components can be spectroscopically resolved and treating fine-structure mixing would be warranted. Implementing this will be postponed to a future release.

9.7. Storing SED Grids

The SED grids supported by Cloudy no longer need to be compiled into binary form. The code now directly reads the ASCII files to obtain the necessary information. Compiling the ASCII files is still supported, but now produces a completely different type of file that contains indices into the ASCII file. This step is optional but is strongly recommended for large grids to speed up the code. With this setup, recompiling stellar atmosphere grids is no longer necessary when the frequency mesh is changed. Compiling SEDs in an external format (such as Starburst99 or the Rauch stellar atmosphere grids) is still mandatory to obtain the ASCII files.