Frequently asked Questions about Cloudy
How should the code be referenced in publications?
How it should not be cited I keep track of publications that use the code for documentation to funding agencies. Before the advent of ADS the preferred reference was a citation to Hazy, the code's documentation. However, ADS does not automatically keep track of citations to publications like Hazy. The Web of Science does track Hazy, but unlike ADS, it is not free. Please do not cite Hazy.
How it should be cited: Cloudy is a research project that involves the creative efforts of many people. It should be cited as follows: "Calculations were performed with version yy.mm.vr of Cloudy, last described by Ferland et al. (1998)." The citation is the following review paper in PASP:
Ferland, G. J. Korista, K.T. Verner, D.A. Ferguson, J.W. Kingdon, J.B. Verner, & E.M. 1998, PASP, 110, 761 here on the ADS
The citation should explicitly mention the version "yy.mm.vr" of the code since some predictions do changes as the atomic data and treatment of physical processes improve. A typical version will be 07.02.01. Old versions of the code are never deleted from this web site so it is possible to recover a version that produced a given result.
An update to the PASP review article is in the works, but is not the highest priority.
My code/analytical results do not get the Cloudy results. What is different?
The book Astrophysics of Gaseous Nebulae (Second edition, described here) goes into most of the underlying physics. The output options given below will isolate which processes are important.
The print arrays command will produce a detailed list of physical processes that affect the ionization of the gas. The photoionization rates may be substantially faster than what you would expect from the continuum alone. That is usually due to photoionization by trapped emission lines. The punch ionizing continuum command will identify contributors to the photo rates.
The punch heating and punch cooling commands will list heating and cooling agents.
These provide enough information to fully understand the ionization and temperature of the gas.
How can I drive a C++ program like Cloudy from Fortran?
It is possible to drive the current version of Cloudy, which is a C++ code, from existing Fortran programs without too much effort. A good approach is to use the cfortran.h header file described here.
Is it really necessary to read all of Hazy to find out which commands changed between versions Cxx and Cyy??
No. There is a list of changes between Cxx and Cyy are listed in the RevisionHistory page.
Many of the commands shown in Hazy have an underscore before or after a keyword. Why?
The underscore indicates a required space. The underscore should not be included. This is discussed in the chapter Introduction to Commands in Part 1 of Hazy.
What are all the assert commands in the test cases?
All of the test cases that are part of the distribution include many "assert" commands. These have nothing to do with the simulation or the astrophysics. Instead, they provide a way for the code to validate itself automatically. Assert commands are described towards the end of Part I of Hazy, and tell the code what answer it predicted in the past. If it does not obtain this answer it will print a comment. Here in Lexington the entire test suite is recomputed every night, and the assert commands provide a way to discover whether any changes have affected predictions. The assert commands can be safely removed or ignored. In fact the test suite includes a perl script, tests_remove_asserts.pl, which will remove them automatically.
What is the name of the code?
It's Cloudy, not CLOUDY. The tradition of capitalizing names of programs goes back to FORTRAN 77 and its predecessors. The ANSI/ISO standard required that source code be in capital letters. Modern languages allow mixed case. It's Cloudy.
Line intensities in the output from the punch continuum command
All lines are included in the punch output, but there are several tricky points. The basic problem is that the code knows what the intensity or luminosity of the line is, but it does not know over what frequency or wavelength range that energy is spread.
The line to continuum contrast is a linear function of the assumed line width. The intensity of a line in the continuum output file will only be equal to the predicted intensity if the line width is set to the speed of light. This is discussed in Part 1 of Hazy where the punch continuum command is described, see the subsection on line to continuum contrast. The set PunchLWidth command, described there and later in Hazy, allows you to change the line width to the appropriate value.
All lines include contributions from continuum pumping. This component may or may not be a net contributor to the observed line, depending on whether the continuum source is in the beam. The pumped part of the line is not included in the punch continuum output for this reason. Direct continuum excitation will generally be very important for clouds that are optically thin in the lines. The pumped contribution can be printed out separately.
Where are the emission lines identified?
See the Chapter The Emission Lines in Part 3 of Hazy.
You can produce a file with all the line labels and wavelengths with the punch line labels command. This output is produced by the func_lines.in test case in the auto directory of the test suite.
What are the spectral features in the punch continuum output?
Both lines and continua are present in the punch continuum output. The description of the command in Hazy 1 explains the various columns.
The first column gives the photon energy. Labels for a line and continuum at that energy are given after the total intensity. More than one line may occur within a particular continuum cell. The line label gives the label of the first line that was placed in that cell, not the strongest line. The continuum label is placed at the threshold for a continuum process. The last column gives an indication of the number of lines within a particular cell.
The print line cell xx command can be used to print the label for all lines that fall within a particular cell. You can look at the main output file to see which line is the strongest contributor.
A low-density cloud with solar (or higher) abundances seemed to crash or stop unexpectedly. What happened?
The first thing to do in any calculation is understand why the code stopped. In most cases it stops because the kinetic temperature falls below 4000K. This limit can be reset with the stop temperature command. For classical nebulae the gas grows this cool only in neutral regions beyond the H+ - H0 ionization front, so the effect is to stop the calculation near this ionization front.
If the gas has solar or higher abundances, and the density is 1,000 cm-3 or lower, the ionized part of the cloud can equilibrate at temperatures well below 1000K despite the high ionization and photoelectric heating. This is discussed, among other places, in Ferland et al. (1984; ApJ 281, 194, the test case nova_dqher.in illustrates the phenomenon) and for H II regions by Shields and Kennicutt (1995, ApJ 454, 807).
This is not a problem, and it should occur in real nebulae. It is not understood why pure recombination line H II regions are not observed. Cloudy stopped because the gas was too cool. To compute the full ionization structure you should lower the lowest electron temperature with the stop temperature command, say to something like stop temperature 100. But be aware that thermal instabilities can occur around 1000K where the cooling curve has a maximum due to fine structure cooling.
Predicted intensities of hydrogen and helium lines
Hydrogen line intensities can be predicted with great precision when Case B applies. Ferguson and Ferland (1997) describe Cloudy’s hydrogen atom. It gives good results for levels below n = 10 in the code’s default state, which uses a 26 level atom. The number of levels can be increased by using the atom H-like levels command, and this gives better results at the expense of more compute time. The larger atom should give results accurate to better than 5% for lines arising from below principal quantum number 10, and 10% accuracy for lines with upper levels between 10 and 15. All levels except for 2s and 2p are assumed to be well l-mixed. So no attempt to resolve the n levels into l levels is made for n > 2. This approximation is nearly exact at medium to high densities (nH > 106 cm-3) but is approximate (but certainly better than 10%) at low densities, as Ferguson and Ferland (1997) describe.
The accuracy of Cloudy’s H I line emissivities is limited by the size of the model hydrogen atom that can be computed on the fly. The definitive calculation for hydrogen recombination is that of Hummer & Storey (1987) and Storey & Hummer (1995), who used a 1000 level atom with all l-states explicitly considered (that works out to something like a million levels!). The code interpolates on their tables and includes their Case A and Case B predictions within the main emission-line list. These predictions are more accurate than Cloudy’s in cases where the Case A or Case B approximation is valid.
The Hummer & Storey (1987) calculation is for Case B conditions, which assume that many processes are unimportant (see Ferguson & Ferland 1997 and AGN3). Neglected processes include collisional excitation from the ground or first excited states, induced processes where the incident continuum causes the atom to fluoresce, and line transfer in all non-Lyman lines. Case B is often an excellent assumption for galactic nebulae such as planetary nebulae or H II regions. Case B is not valid for gas densities greater than 106 cm-3 or when X-rays are present. When any of these processes are important the hydrogen spectrum is far more model dependent and the results of Cloudy’s model atom are more realistic than Case B predictions.
The code includes a model of the He0 atom that is applied all along the helium iso-electronic sequence (Porter et al 2005, ApJL, 622L, 73, here. The model can have an arbitrarily large number of levels. The predictions become more exact as the number of levels is increased but the calculations become slower.
Return to main wiki page
Return to nublado.org
