Version 22 (modified by peter, 2 weeks ago) (diff)

Mention changed behavior of environment variable after C17.

Setting the path

The skinny on editing the path If you are using a Linux computer, a Mac, or a Windows machine with Cygwin, you can use a makefile to build the code. You do not need to do the steps on this page and you can go on to the next step, CompileCode.

There are vast amounts of atomic data that the code must reference in order to compute a model. These are the files that live in the data directory. The code must be able to find these data files. Their location is stored in the code. This information needs to be updated so that it gives the location of the data on your machine.

Setting the path to the data files is done automatically when compiling the code with make. You can modify the default path generated by make by using the first method. The second method is to add an extra parameter to the compiler options when compiling from the command line, and the third method is to edit the file path.h in the source directory (the last two methods are deprecated since version C17).

Method 1: Supplying the path at runtime

Since Cloudy version C06.02, compiling the code with make will automatically set the search path for the data files. The method described below is only needed if you want to modify the default path generated by make. The latter should suffice for the needs of most users. If you are not sure what the explanations below mean, simply compile the code with make and skip the rest of this page.

Since Cloudy version C08 you can set the path to the data files at runtime before you start up Cloudy by setting the environment variable CLOUDY_DATA_PATH. This setting will always override any settings generated by make. On Unix platforms the method for setting the environment variable depends on the shell you are using. For csh/tcsh use:

setenv CLOUDY_DATA_PATH "/usr/gary/cloudy/data"  (double quotes are optional)

For bash/sh/ksh/etc... you should use:

export CLOUDY_DATA_PATH="/usr/gary/cloudy/data"  (no spaces around the '='!)

In windows you would use:

set CLOUDY_DATA_PATH=c:\cloudy\trunk\data  (no spaces around the '=', no double quotes around the directory name!)

If the environment variable is defined during compilation, it will override the default setting generated by make and this path will be stored in the executable. If the environment variable is defined during execution, it will always override the path stored in the executable. This behavior will be changed in the first major release after C17. From then on the environment variable will only affect the code during execution, but will not affect compilation of the code.

The environment value CLOUDY_DATA_PATH supports a search path with multiple components, similar to the search paths used in UNIX. You can supply multiple directory paths, separated by a colon (':') on UNIX and Mac systems, or separated by a semicolon (';') on Windows systems. When Cloudy searches for a file, it will search in each of the component directories until it finds the file. An example (for UNIX) would be

export CLOUDY_DATA_PATH="/usr/gary/cloudy/data:/usr/gary/local_data"

When Cloudy looks for a data file, it will first look in the directory /usr/gary/cloudy/data. If it doesn't find the file there, it will look in /usr/gary/local_data instead. The latter is convenient for storing locally generated data such as grain opacity or stellar atmosphere files. Storing them in /usr/gary/local_data avoids having to move them around every time you switch to a new Cloudy version.

Starting with Cloudy version C17, the search path will also support the special path component "+" which will be expanded to the default search path that make would have generated for that release. This makes it even more convenient to maintain locally generated data files by using

export CLOUDY_DATA_PATH="+:/usr/gary/local_data"

This way you don't have to worry what the correct path would be to the standard data files that are distributed with Cloudy! The special path component "+" is only supported when you use make to compile the code.

Method 2: Setting the path with a compiler option

This method is deprecated and will be removed in a future release.

In Cloudy version C07.02 and before there were two names for the data path, CLOUDY_DATA_PATH and LOCAL_DATA_PATH. In Cloudy version C08 there is only one, CLOUDY_DATA_PATH. Use CLOUDY_DATA_PATH where LOCAL_DATA_PATH appears below for version C08 and later.

Robin Williams added a macro, LOCAL_DATA_PATH, that allows the path to be specified by the value of the macro. To use this you should add the following parameter to the compiler options:


(for Unix) or


(for Windows). So the complete line could e.g. be (this depends on the platform and compiler you are using, see CompileCode for more details):

g++ -ansi -c -O3 -Wall -DLOCAL_DATA_PATH=\"/usr/gary/cloudy/data/\" *.cpp

In Visual Studio you would go to Project / properties / Configuration Properties / C/C++ / Preprocessor and set the following within the Preprocessor Definitions line:


Method 3: Setting the path by editing path.h

This method is deprecated and will be removed in a future release.

Edit the file path.h (located in the source directory) and locate the variable CLOUDY_DATA_PATH. There are two instances, one for windows and another for unix. If you are using Cygwin on Windows you should set the unix path. You need to edit the correct one for your operating system. Change the string within the double quotes so that it gives the location of the data on your computer.

The path would be a string within double quotes. On a Unix machine the result should look like this:

 * Specify a search path to data directories here.
 * This is for Unix variants.  You can specify a search path for one or several
 * data directories using the standard colon-separated list of Unix paths. You
 * can enter as many paths as you like. One example could be: */

#define CLOUDY_DATA_PATH "/usr/local/cloudy/data:/home/user/cloudy/data"

On a Windows machine the result should look like this:

/* The following example shows the format for Windows. You can
 * specify a search path for one or several data directories using a list separated
 * by semi-colon signs ";". The path must be enclosed between double quotes.
 * NB - note that the backslash "\" always needs to be typed twice, as shown below: */

#define CLOUDY_DATA_PATH "c:\\projects\\cloudy\\data;c:\\users\\gary\\data"

The double backslash is needed on Windows systems to prevent the character following the slash from being interpreted as an escape sequence.

The string giving the path MUST have the proper directory mark as the last character before the second quote. This would be a "/" in Unix, a "
" in Windows, and a "]" in VMS.

C++ syntax for the newcomer There must be two double-quotes. The path is the series of characters between them. The line must end with a semicolon. Lines that start with are comments. One of the paths will be commented out.

If the path is longer than FILENAME_PATH_LENGTH characters then increase the size of FILENAME_PATH_LENGTH in cddefines.h and recompile the entire code. Remember that in C++ a string must have one extra byte for storing the end-of-string sentinel.

If you store your *.ini initialization files in the data directory then the ini files will be automatically found by the code.

Next step: CompileCode - compile the code.

Return to StepByStep instructions

Return to