New in Next Release

This page summarizes all major changes and improvements to Cloudy that will be included in the next release. You may also view the HotFixes and KnownProblems pages, or return to the main RevisionHistory page.


The code has been ported to C++11. This implies that you need a compiler with full support for C++11. For g++ that means 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 Studio compiler version 12.5 or later.

The He-like iso sequence has been altered. One of the changes is that helium triplet lines connecting to the 1s.2p 3P states are now J-resolved, with an additional Blnd entry for the entire multiplet. In c17 and earlier only the multiplet line was stored. This can fool existing scripts. As an example, we will discuss the well-known He I line at 587.6 nm. In c17 only the multiplet existed as "He 1" 5875.64A. In the current release there are three J-resolved lines: "He 1" 5875.61A, 5875.64A, and 5875.98A, while the multiplet is now called "Blnd" 5875.66A. So the line "He 1" 5875.64A still exists, but has a different meaning than in c17! See the save line labels output for detailed information about other helium lines.

All TABLE STAR commands now work directly on the ascii file. This means that you now need to have the *.ascii versions of the SED grid files in your data search path and can remove the compiled *.mod files. Compiling *.ascii files is still supported (though it is now optional) using the same commands as in previous Cloudy versions. This command now produces index files with names ending in *.idx. These files help speed up reading the ascii file and are strongly recommended for large grids. Note that despite the simple appearance of these files, they are (in principle) still platform dependent. The big advantage of this setup is that there is no longer a dependence on the frequency mesh, so you do not need to recompile the ascii grids when you change the frequency mesh. Compiling grids that are not in the standard Cloudy format (e.g. Starburst99 output) is still mandatory.

To fix compiler warnings with g++ 8, the state file of the phymir optimizer has been altered. This implies that state files from older versions of the code are no longer accepted. Continuing an optimization run with a different version of Cloudy is not recommended in any case.

The code now catches OS signals like FP exceptions and segmentation faults on supported platforms. These are then rethrown into C++ exceptions that need to be caught by the main program. This allows a grid run to continue despite such an error. When the code aborts (e.g. due to excessive convergence failures) this now also generates a C++ exception. In order to be fully compliant with these changes, programs that call Cloudy as a subroutine need to update the main program to catch the new exceptions. See tsuite/programs/template.cpp for an example of the new code.

In this release we have made a start with modifications of the parser that are aimed at making it stricter in checking the syntax of the script. We realize that the loose syntax that was in use until C17 can have advantages (e.g., we could largely dodge the issue of US vs. UK spelling). But we have also received multiple complaints from users where it turned out that something they typed in their script was silently interpreted as something completely different by the parser. This is dangerous, and in the most extreme case can lead to wrong results being published. The long-term goal is to check everything that is typed in the script (apart from comments of course). In this release we will start by fully checking the command name itself. Abbreviating the command is still allowed (as long as it is unambiguous with a minimum of 4 characters) but all the characters that are typed will be checked. Where there are differences, we will choose US spelling. This can break existing scripts if they contain typos or use alternate spelling. In such a case, the code will now make a suggestion for the correction (unless the command is garbled too much).

Parser and related changes

See also the Caveats section above.

In c17.01 using comment characters other than '#' and '##' was deprecated. These have now been removed.

The implementation of the search path for finding input files has been finalized. This implies that the code now uses a consistent policy for finding files that it needs to read. All commands will now look in the local directory first, and then in the data directory. The user can alter the search path by defining the environment variable CLOUDY_DATA_PATH before the code is started up. See the new sections "Reading and Writing Files" and "The Search Path for Input Files" in Hazy 1 for a more detailed explanation.

Setting the search path in the file path.h was deprecated. This file has now been removed.

Setting the search path as a command line parameter during compilation was deprecated. This option has now been removed.

Saving files to a destination outside the local directory, e.g. using

save continuum "subdir/"

was never intended to be supported. This is now checked and the code will abort when this is attempted. The reason for this change is that saving files outside the local directory does not work in grid runs.

The restriction to NKRD (4000) input lines has been removed. Also the restriction on the input line length (was 2000 characters) has been removed. The code now accepts an arbitrary number of input lines of arbitrary length.

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 in a command like save line list. One example is the H I 4.65247 micron 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 the save lines emissivity, save line list, set blend, print line sum, table lines, monitor line, and optimize lines commands. 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. See Hazy for further information. The code will print a warning when you use a line that is ambiguous.

Changed commands or options

The executable now accepts the -e option which allows you to supply Cloudy commands directly on the command line, e.g.

cloudy.exe -e test

to execute the smoke test. See RunCode for details.

The command species "Fe+6" dataset="alt" has been added. This allows multiple Stout datasets for a given species to be supported.

Critical densities for l-changing collisions for H-like and He-like iso-sequences can be printed now, e.g.

print critical densities h-like helium

This line will print a column with the main quantum number n (starting with n=3) and another with the critical densities for H-like helium. If no element is specified, then the entire iso-sequence (for all elements included in the simulation) will be printed.

A new command database h-like keep fine structure has been added that allows the fine-structure components of the hydrogenic lines to be reported on 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 executable no longer accepts the -a option on the command line. This option was deprecated and has now been removed. This was used for debugging only and caused a failed assert to abort rather than emit a C++ exception.

The set assert abort command has been removed. This had the same effect as the -a command line option described above.

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 interactively test certain aspects of the code. They have not been used in a long time and were obsolete.

The state command has been removed. This was an experimental feature that never worked. This project has now been abandoned.

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 (assuming you are old enough to remember what a line printer is...!).

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.

The executable now accepts the -s [hex seed] option on the command line. This will set a fixed seed for the random number generator (see also below) and is intended for debugging and testing purposes. It is not recommended to use this in normal Cloudy runs.

The table SED command now accepts the keyword Flambda in the SED file. Fluxes in Fnu or nuFnu units were already accepted, now Flambda 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.

Two new commands have been created allowing the user to manage blends in Cloudy. The command set blend allows the user to define new line blends, while the no blends command tells the code not to create the standard blends. See also the next section for further information.

The table ks18 command has been renamed to table ks19. This was necessary because the paper that described the data took a long time to review and was only accepted in 2019, long after we added the grids.

The abundances command has been modified. It is now mandatory to include an element symbol in front of the abundance and this 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 for the list of abundances to be complete. The elements read command has been removed as it is no longer needed. An example of the new syntax is shown below

abundances he=-1 C=-3.523 N=-4. O=-3.222 ne=-3.824 mg=-4.523 
continue si=-4.523 s=-4.824 cl=-7 ar=-10 fe=-10 

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 He I spectrum. The situation is different though for highly charged ions, e.g. Fe XXV. 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.

The atomic, molecular, and grain database

The molecular hydrogen level energies, which we use to derive line wavelengths, have been updated to Komasa (2011). This results in ~1 wavenumber changes in level energies.

We now use the Lique 2015 H - H2 collisional data by default. Compared with previous calculations, these data extend to higher vibrational manifolds and include ortho-para changing reactive collisions. Tests show that the 2.121 micron line intensity changes by roughly 50%, becoming stronger in some PDR sims.

Fe III collision strengths are updated to Badnell and Balance 2014. We had previously used data from Zhang 1996. Tests show that the total Fe III cooling increases by nearly 50%.

In c17.02 a bug had been fixed that could lead to a failed sanity check when running with a very high resolution frequency mesh. As a result the photoionization thresholds got a slightly different energy. In this release also the radiative recombination continuum entries on the line stack have a slightly different wavelength to make them consistent with the new threshold values.

The refractive index data for astronomical silicate and graphite from Draine, 2003, ApJ, 598, 1026 have been added. These can be found in the files sdraine03.rfi and gdraine03.rfi.

In order to fix a bug where many blends were not predicted on the emergent line stack, the requirements for adding lines to a blend have been tightened. Blend components now have to be transmitted lines (i.e. have type 't', see the save line labels output) that are associated to a database transition. As a result many blend components have been removed, mostly predictions for the recombination contribution to a given line. These predictions are based on ad hoc theories that are not valid over the entire parameter range that Cloudy covers. The components that have been removed are still available as separate entries on the line stack. Below are the details.

Six blends had no valid components left after the operation and have been removed:

removed blend removed components
Inwd 1549 Inwd 1548.19, Inwd 1550.78
Inwd 1240 Inwd 1238.82, Inwd 1242.80
Inwd 1035 Inwd 1031.91, Inwd 1037.62
Blnd 4341 O 2P 4341, O 2R 4341
Blnd 3736 O 2P 3736, O 2R 3736
Blnd 5592 O 3 5592, O 3C 5592

Seven blends only had one valid component left and have also been removed. The table below gives the lines they should be replaced with:

removed blend replacement removed components
Blnd 977 C 3 977.020 C 3R 977
Blnd 5755 N 2 5754.61 N 2T 5755, N 2R 5755
Blnd 765 N 4 765.147 N 4R 765
Blnd 3726 O 2 3726.03
Blnd 3729 O 2 3728.81
Blnd 4363 O 3 4363.21 O 3C 4363, O 3R 4363
Blnd 630 O 5 629.732 O 5R 630

The following remaining blends had components removed:

blend removed components
Blnd 1657 C 1R 1656
Blnd 9850 C 1R 9850
Blnd 1335 C 2R 1335
Blnd 2326 C 2H 2326
Blnd 6580 C 2R 6580, C 2P 6580
Blnd 1176 C 3R 1175
Blnd 1909 C 3R 1909, C 3H 1909
Blnd 1549 C 4R 1549
Blnd 5199 N 1R 5199, N 1C 5199, N 1T 5199
Blnd 1085 N 2R 1085
Blnd 990 N 3R 990
Blnd 2471 O 2R 2471
Blnd 3727 O 2R 3726, O 2R 3729, O 2H 3727
Blnd 7323 O 2R 7323
Blnd 7332 O 2R 7332
Blnd 7325 O 2R 7323, O 2R 7332
Blnd 835 O 3R 835
Blnd 1666 O 3H 1665, O 3A 1665
Blnd 789 O 4R 789
Blnd 1402 O 4H 1401

Most line blends have been moved into an external init file. Cloudy versions up to C17 contained various line blends (e.g. Blnd 1909) that were hardwired into the source code. These have been moved to an init file blends.ini that is part of the data directory and which is read automatically when the code starts up (unless the new command no blends is entered). This file uses the set blend command to define the blends. This approach creates a more transparent way of setting up the blends. Users can now use the blends.ini file as a template to set up their own collection of custom blends.

Two abundance tables have been extracted from “Palme, H.; Lodders, K.; Jones, A.”, table 1. There are named “palme14-Sol.abn” and “palme14-Met.abn” . The earlier includes Solar photospheric abundances and the latter includes meteorite abundances.

Two new blends are added to blend.ini file. Blend 1650 is related to He II+OIII] line and blend 1400 is for Si IV+O IV] line.

Improved physics and numerical methods

Masers are allowed by default in iso-sequences. To turn off masers in H-like hydrogen use the command database h-like hydrogen maser off.

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**, while the random numbers with a normal distribution are now generated using the Ziggurat algorithm. Both methods are much faster than the old ones. An additional advantage is that the new code is fully aware of parallellization 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 (usually derived from /dev/urandom), unless the -s command line parameter described above is used.

Other changes

The labels for collisional heating and cooling of the gas by grains have been renamed to GrCH and GrCC, resp. Before they were both called GrGC.

The label for the inward component of continuum bands has been changed to InwdBnd. Before they were called Inwd. This led to ambiguities with individual Fe II lines when the big Fe II model was used.

A well-known problem is that the output of grid runs could be incomplete when certain sims in the grid failed. A workaround has now been implemented that replaces missing or empty output files with stub files that are generated by taking a correct file and replacing all the numbers by zeros. This should give plotting programs a fighting chance to produce meaningful output. Note that partial output will not be replaced by a stub file.

On supported platforms the code will now generate a backtrace when an error is encountered.

The code now uses the 2018 CODATA adjustment for the fundamental physical constants.

Return to the RevisionHistory page.

Return to the StepByStep instructions.

Return to main wiki page

Last modified 17 months ago Last modified on 2019-07-10T17:01:38Z