Version 2 (modified by Gary J. Ferland, 12 years ago) (diff)


How to run Cloudy

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.

The code is designed to be autonomous and self-aware. It should explain if something goes wrong. There are generally two sources of problems - the path does not properly point to the data directory or the code was compiled with aggressive optimization. You should run the test suite (described next) to confirm that the code was compiled correctly.

Run a smoke test

First run a smoke test to see if anything works. Execute the code with the single command "test". To do this, if the executable is called "cloudy.exe" and a carriage return is "<cr>", type

cloudy.exe <cr>
test <cr>

You could also create a file ("") and enter the word "test" as the first and only line in the file. Then execute the code by typing

cloudy.exe < > test.out <cr>

Have a look at the output. It is described in detail in a chapter in Part 3 of Hazy. This test passed if the last line of output says the following:

 [Stop in maincl, Cloudy exited OK]

If the smoke test goes up in flames There are two reasons the test could fail, the path has not been set properly and compiler bugs.

If the path has not been set properly then the code will not be able to find its data files. It will say so, and explain what path was used. Review the instructions for setting the path (see the page EditPath), fix it, recompile the code, and try again.

It is also possible that the compiler did not produce correct code. Cloudy is designed to be autonomous and self aware. If it fails any of its internal sanity checks then it will exit with an error condition, most likely a thrown assert. For serious compiler bugs there may be a hardware exception (computer-ese for, "it crashes"). This is almost always caused by compiler bugs. Turn down the level of optimization, recompile the code, and try again. See the CompileCode page for more on aggressive optimization.

Check that it crashes on errors

It would be good if the code crashed on divide by zero, overflow, using NaN, and (for the debug compile) a failed assert. Run the following four tests to check that the code does crash.

title confirm it crashes on overflow
crash overflow

title confirm it crashes on divide by zero
crash zero

title confirm it crashes when using NaN (not a number)
crash NaN

title confirm it crashes with a failed assert
crash assert

This uses the crash command, which is implemented in routine CrashDo, to confirm that the code will crash on division by zero, overflow, use of NaN, the C assert macro, and array bounds checking.

In some compilers the routine CrashDo? will not work properly unless this module is compiled without optimization since the compiler may detect that the results of the unsafe code are not used elsewhere in Cloudy, and simply not do the evaluation. With icc and the native SGI compiler you need to explicitly include the -O0 command line option to achieve this since optimization is the default. This could also apply to other compilers that we haven't tested. This is only to confirm that the crash will occur with the crash command, with these compilers safe code (code that will crash after a floating point error) is still produced with higher optimization, but the crash command itself will be optimized away.

Crash assert is a special case. It might only fail when the code is compiled in debug mode since asserts may not exist in optimized code. If the code is compiled correctly and the asserts are working, then the calculation will end with statements saying that something bad has happened. This is the normal termination for a crash due to a failed assert and means that everything is fine.

If the code does not crash on each of these tests then your system is quite happy with bad floating point math or failed asserts. It is quite possible that you will not be able to get your system to crash on floating point errors. (This seems to get harder every year.) This is not a major problem but is something that should be kept in mind.

To execute the code as a stand-alone program:

The following outlines several ways to run the code. Method 2 is the most commonly used one. It uses a "script" to run the model. If you place the script in a directory that is on your path then you can run the code from any directory on the computer.

Method 1

The code reads from standard input and writes to standard output. From the command line the code would be executed as follows, if the executable is called cloudy.exe:

cloudy.exe < input_file > output_file

In this example commands would be read in from the file "input_file" and results are sent to the file "output_file" A typical input file contains the series of commands written one per line:

title typical input stream
blackbody 120,000K
luminosity 37
radius 17
hden 4

Method 2 - linux

This is how I run the code in linux. I created a shell script named "run" that contains the following:

cloudy.exe < $ > $1.out

Make the script executable by typing

chmod ugo+x run

then execute the code as follows:

run input

This will read commands from the file and write results to the file input.out.

Method 2 - Windows

This is how I run the code in windows. I created a shell script named "run.bat" that contains the following:

cloudy.exe < > %1.out

Execute the code as follows:

run input

This will read commands from the file and write results to the file input.out.

Method 3

Robin Williams added a command line "-p" option that allows the input to be specified:

cloudy.exe -p input

This will read commands from the file and write results to the file input.out. It will also add the string "input" to the beginning of all punch file names.

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. Delete the old main program:

The file maincl.c 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.

This is done with the compile 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 cddefine.h and cddrive.h. Include these files in your main program. Comments in the headers describe how the various driving routines should be called.

I have created a few simple main programs to show how to call the code as a routine. These are in the file programs* in the test suite directory here .

Next step, compile the optional stellar atmospheres