How to run Cloudy C15

If you are new to UNIX/Linux/Cygwin it may be useful to familiarize yourself first with some of the basics of using the command prompt. A good introduction can be found in  this tutorial. The code can be run directly from the command prompt or as a subroutine of larger programs. The first sections describe the command-prompt approach.

This page discusses running on a single processor. Running in parallel is discussed on the MpiParallel page.

Running from the command prompt

Create an input script

By default, the code reads from standard input and writes to standard output. The input file contains all the commands that control the code. A typical input file contains the series of commands written one per line and might look something like the following:

title typical input stream
blackbody 1.2e5 K
luminosity 37
radius 17
hden 4
save overview "script.ovr"

Enter this into a file with a name like

Create a run script

This is the best way to run the code. Create a shell script named "run" which includes the path to the cloudy executable. If you place the run script in a directory that is on your path then you can run the code from any directory on the computer.

Linux and other UNIX variants (like OS X or Cygwin)

The run file contains the following:

/path/to/cloudy.exe -r $1

where /path/to/cloudy.exe is the path to the cloudy executable. On your system this may be something like /users/gary/cloudy/source/sys_gcc/cloudy.exe. Make the script executable by typing

chmod +x run


Create a shell script named "run.bat" that contains the following:

set CLOUDY_DATA_PATH=c:\cloudy\trunk\data
c:\path\to\cloudy.exe -r %1

Put this in a directory. I called mine gary\bin

Put that directory on the search path so that you can use it in other directories. To modify the search path in Windows 7

  • From the desktop, right-click My Computer and click Properties.
  • In the System Properties window, click on the Advanced tab.
  • In the Advanced section, click the Environment Variables button.
  • Finally, in the Environment Variables window (as shown below), highlight the Path variable in the Systems Variable section and click the Edit button. Add or modify the path lines with the paths you wish the computer to access. Each different directory is separated with a semicolon.

Running the code

If you type the following at the command prompt:

run script

Cloudy will read the input from the file and write the output to the file script.out. The overview file will be saved to script.ovr. Notice that this style adds an implicit .in to the end of the input file name. So you should not include the .in extension in the command above! This will work with all Cloudy scripts.

For this to work, the run script should be located in a directory that is included in your search path. Otherwise you need to include the full path in the command, e.g.,

./run script


/path/to/run script

where /path/to is the actual path to the directory where the run script resides.

Other command-line options

Execute the code with the -h option to get a full list of command line options:

./cloudy.exe -h

The -p option on cloudy.exe

This behaves like the previous option, it adds an implicit .in at the end of the file name, but it also controls the name of the save output files. Suppose the input script contains:

title typical input stream
blackbody 1.2e5 K
luminosity 37
radius 17
hden 4
save overview ".ovr"
save heating ".het"

Then the run script, written as,

/path/to/cloudy.exe -p $1

and executed as

run script

will read commands from the file and write results to the file script.out. It will also add the string "script" to the beginning of all save file names. The files script.ovr and script.het will be created. (Had the save command been written as save overview "script.ovr" the output file scriptscript.ovr would be created.) This will work with all Cloudy scripts.

cloudy.exe with no options

This requires that the input file end in .in and adds a prefix to the save output file names. Create a run script containing

/path/to/cloudy.exe $1

and then run the code as


It tells the code to expect input from the file and to write to the file script.out. The prefix script is added to all save output. This will work with all Cloudy scripts.

Explicit input and output files

An alternative way to execute Cloudy is to type:

/path/to/cloudy.exe < input_file > output_file

(This was the preferred manner in C10 and before.) In this example commands would be read in from the file input_file and results are sent to the file output_file. This way of running the code will not work for all Cloudy scripts, in particular it will not work for the grid or optimizer options, so it is better to use the syntax shown earlier.

To run Cloudy as a subprogram of other, larger, codes

Often the most insight is gained from producing a large number of models with various input parameters changing, to see how predicted quantities change. To do this you want to write your own main program, and delete the one that comes with the distribution. There are examples of doing this in the tsuite/programs directory of the download you obtain from the web site.

Delete the old main program:

The file maincl.cpp is in the source distribution. Delete this file (or rename it to something like maincl.old) and also delete maincl.o if you compiled the entire distribution.

Compile the new main program and link it with the rest of Cloudy.

Starting with version C08, Cloudy can generate C++ exceptions that need to be caught. This needs to be done in the main program. If they are not caught your program will crash on an unhandled exception and part of your output may be lost! The solution is to surround the code in your current main program with a try / catch clause. A template showing how this can be done is included in the tsuite/programs directory of your distribution and is called template.cpp. See also the chapter on Cloudy as a subroutine in Hazy 3.

Compile the main program with the options described on the compile page. You will need to compile the rest of the code, generating *.o files, then compile the new main program, and link it all together. Note that in C++ the main program must be called main, but it can live in a file with any name. The header files and routines you will need to access are declared in the header files cddefines.h and cddrive.h. Include these files in your main program. Comments in the headers describe how the various driving routines should be called.

A few simple main programs showing how to call the code as a routine are in the programs directory that is located in the main test suite directory.

Exit codes

We obey standard unix conventions and return 0 upon successful completion of a run. The file source / cddefines.h contains a list of other exit codes. Search for the variable exit_type.

Next step, CompileStars, is to compile the optional stellar atmospheres

Return to StepByStep instructions

Return to