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.
------
# To execute the code as a stand-alone program:
The following outlines several ways to run the code.
The run command is the one I use most often.
It uses a "script" to run the model.
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.
----
## cloudy.exe at the command prompt
This is the most basic way to run the code.
By default, the code reads from standard input and writes to standard output. So we need to tell the code
where to read its input.
From the command line there are several ways to do this, if the executable is called cloudy.exe:
```
cloudy.exe -r script
```
This will read the input from the file `script.in` and write the output to the file `script.out`. Note that the file name extension `.in` is not included in the command! An alternative way to execute Cloudy is to type:
```
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`. This way of running the code will not work for all Cloudy scripts, so it is better to use the `-r` syntax shown earlier. A typical input file contains the series of commands written one per line:
```
title typical input stream
blackbody 120000K
luminosity 37
radius 17
hden 4
```
Both methods have the disadvantage that you must execute the
code from the directory where `cloudy.exe` lives. This is inconvenient.
----
## The run command
This is the best way to run the code.
Create a shell script named "run" which contains the following:
### all shells in linux and other UNIX variants
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
```
=== windows ===
Create a shell script named "run.bat" that contains the following:
```
set CLOUDY_DATA_PATH=c:\cloudy\trunk\data
cloudy.exe -r %1
```
----
In all cases you would execute the code as follows:
```
run input
```
This reads commands from the file `input.in` and writes results to the file `input.out`.
Each of these run commands sets the data path as an environment variable before calling the code.
This makes it possible to have more than one version of Cloudy since each version
must know how to find its data.
----
## The -p option on cloudy.exe
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 input.in and write results to the file `input.out`.
It will also add the string "input" to the beginning of all save file names. Just like the `-r` flag described earlier, it will work with all Cloudy scripts.
------
# 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.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.
------
Next step, CompileStars, is to compile the optional stellar atmospheres
