GitLab

1 Where do I ask questions?

At the code's user group. We were one of the early adopters of Yahoo groups and moved to this user group when Yahoo discontinued their service. All of the old posts were also moved to the new site. If you encounter an old link to the Cloudy Yahoo! discussion board you should search for its content on the new group.

2 How should the code be referenced in publications?

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.vr of Cloudy, last described by Ferland et al. (xxxx)." The citation should be the most recent review paper:

For Cloudy versions up to and including C10.vr:

G. J. Ferland, K. T. Korista, D. A. Verner, J. W. Ferguson, J. B. Kingdon, and E. M. Verner. CLOUDY 90: Numerical Simulation of Plasmas and Their Spectra. PASP, 110:761-778, 1998.

For Cloudy versions C13.vr:

G. J. Ferland, R. L. Porter, P. A. M. van Hoof, R. J. R. Williams, N. P. Abel, M. L. Lykins, Gargi Shaw, W. J. Henney, and P. C. Stancil. The 2013 Release of Cloudy. Revista Mexicana de Astronomia y Astrofisica, 49:1–27, 2013.

For Cloudy versions C17.vr:

G. J. Ferland, M. Chatzikos, F. Guzmán, M. L. Lykins, P. A. M. van Hoof, R. J. R. Williams, N. P. Abel, N. R. Badnell, F. P. Keenan, R. L. Porter, and P. C. Stancil. The 2017 Release Cloudy. Revista Mexicana de Astronomia y Astrofisica, 53:385-438, 2017.

The citation should explicitly mention the version "yy.vr" of the code since some predictions do change as the atomic data and treatment of physical processes improve. A typical version will be 17.00. 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.

A more complete version of the citation can be generated by running the code with the command print citation.
This will include the full bibtex reference.

3 I added up all the energy in the emission line printout, or in the save continuuum output, and it is less than the energy in the incident spectrum. What happened to the missing energy?

Chapter 3 of AGN3 (Osterbrock & Ferland 2006) goes over heating and cooling in a photoionized nebula. Much of the incident photon energy goes into ionizing or dissociating a species and the rest is shared with free electrons. The energy shared with the free electrons is converted into emission of one kind or another and this conversion of kinetic energy into radiation is referred to as cooling. The energy that originally went into ionizing the species is converted into recombination lines or continua during the recombination process.

For most radiation fields the majority of the photon energy goes into ionization energy and is converted into recombination lines.

For the sum of the incident field to equal the sum of the emission we would have to compute the intensities of all recombination lines. The model atoms include a finite number of levels. Recombination lines produced by these levels are explicitly included in the spectrum. The energy emitted by levels higher than the model atoms is included in the energy conservation but not in the emitted spectrum.

The amount of energy that is emitted by levels higher than the highest levels in the model atoms and so not included in the spectrum is typically about 20%-40% for a hydrogen-rich gas ionized by starlight. The amount is larger for softer SEDs since a larger fraction of the incident photon energy is converted into recombination lines. The amount even larger for gas where the heavy elements are strongly enhanced since the number of levels included in models of intermediate ionization heavy elements is relatively small.

So, the recombination lines produced by levels higher than our model atoms are included in the energy equation but are not included in the emitted spectrum.

4 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 _save ionizing continuum_ command will identify contributors to the photo rates.

The _save heating_ and _save cooling_ commands will list heating and cooling agents.

These provide enough information to fully understand the ionization and temperature of the gas.

5 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.

6 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.

7 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.

8 What are all the assert commands in the test cases (Versions C08 and before)?

8 What are all the monitor commands in the test cases (Versions C10 and later)?

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 in 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.

The assert command was renamed to monitor in version C10 to avoid confusion over the C++ assert macro.

9 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.

10 Line intensities in the output from the save continuum command

All lines are included in the save 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 save 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 save 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.

11 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 save line labels command. This output is produced by the func_lines.in test case in the auto directory of the test suite.

12 What are the spectral features in the _save continuum_ output?

Both lines and continua are present in the _save 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.

13 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 to 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^+^ - H^0^ 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.

14 The output from a punch command is not really described in Hazy (C08 and before)

14 The output from a save command is not really described in Hazy (C10 and later)

Many of the save commands are there for debugging and their output changes to suit circumstances. The documentation in Hazy is vague for these cases to minimize the workload and maximize accuracy. But it is easy to see what is being produced.

First, locate the point in parse_save.cpp where the command is parsed. Usually, the capitalized first four characters of the start of the command's keyword will be there. As an example this is the point where the save continuum command is parsed;

	/* the save continuum command, with many options,
	 * the first 3 char of the chSave flag will always be "CON" 
	 * with the last indicating which one */
	else if( p.nMatch("CONT") && !p.nMatch("XSPE") )
	{

You will find a key that tells the code what to do. Here is where save emitted continuum is parsed;

			/* continuum emitted by cloud */
			strcpy( save.chSave[save.nsave], "CONE" );

To see what the output means, search over the entire code for the string that is copied into save.chSave - in this case it is "CONE". We see that this string is used in save_do.cpp at line 734 (in my working copy of the code). Examine the code starting with the string to see what is output. The code looks like

			else if( strcmp(save.chSave[ipPun],"CONE") == 0 )
			{
				/* save emitted continuum */
				/* set pointer for possible change in units of energy in continuum
				 * AnuUnit will give anu in whatever units were set with save units */

This process will reveal anything ambiguous about the save commands.

15 Predicted intensities of hydrogen and helium lines in version c08 and before

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 2_s_ and 2_p_ 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 (n,,H,, > 10^6^ 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 10^6^ 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 He^0^ 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.

16 What are the difference between the intrinsic and emergent line intensities in the main output?

See Hazy 1, Chapter Grains, section Line intensities with grains, and Hazy 2, Chapter Observed Quantities, section Line intensities in a dusty cloud.

17 A simulation with a power-law density law extends to a very large radius and small density, and there may be convergence problems

See Hazy 1, Chapter "Density laws", section "Clouds extending to infinity"

18 I want to save some quantity X as a function of depth, but there is no save command to do this. Is it OK to stop the simulation at various depths and combine the information?

In general, no. Stopping the sim at various depths will not do the right thing. Stopping the model early will change the optical depth to the outer edge of the sim, which will affect physical conditions further in because the escape probability of the radiation is different. In short, stopping early will usually affect quantity X and you will often get the wrong answer that way. This is frequently asked in connection with saving the continuum. Note that there is a keyword EVERY to save the output of the SAVE CONTINUUM command in every zone. Otherwise, the best course of action is to post your problem to the discussion board (see point 1 above).

Go home