Compiling the code
Ancillary files
Corrections, Hot Fixes, and
the Cloudy Mailing List
Comments or Suggestions?
The following outlines a method that generally works.
Hot fixes are described below, and are a set of corrections that must be made to the distributed source. They are listed on the hot fixes page of the web site, http://www.pa.uky.edu/~gary/cloudy .
Compile everything with a command something like the following (which works on a
Sparc):
f77 -Nx10000 -fast -fnonstd -c *.f
and linking with
f77 -o -fast c90.exe *.o
thus creating the executable c90.exe. These options allow for
speed optimization and larger numbers of external names for a Sparc.
The code generates very large numbers of underflows during a typical calculation. This is an inevitable result of any calculation that attenuates a beam of light. Some operating systems, by default, will generate signals when an underflow occurs. This slows down the works by something like an order of magnitude. The environment should be set to allow underflows to generate zero with no signal.
You can tell whether the system is loosing time to underflow trapping by running one of the sample input files. The parispn.in is a good one, and both the input and output are included with the source distribution. Use the Unix time command to track execution time. If the environment is set up to trap underflows about half of the wall clock time will simply disappear, and 90% of the tracked time will go to system rather than user. Things are probably ok if user gets most of the time.
It should be safe to compile the entire code with the fastest options (except on an alpha - below). There are a few routines that are quite long, and some compilers may have trouble with them. Actually the code spends most of its time in only a few routines, phfit, gamk, opacin, level2, ColStrGBar, DimaCool, and bnfun, and the code will run fairly fast if only these are fully optimized. These are also the routines to think about if parallel or vector optimization is a possibility.
Usually you want to ask for a 'fast' compilation, meaning slow compile time but fast execution time. It may also be necessary to ask the compiler to extend the number of allowed continuation lines, or the increase the number of symbols. The following are the options I used on each of the machines for which I have tested the code:
g77 is the GNU native Fortran 77 compiler but did not work on our attempts (the resulting executable crashed). This example does a f2c conversion to C, followed by compilation with the GNU C compiler.
The fnonstd tells the CPU not to trap some exceptions, and will make the code run faster. It is not necessary to use the -Nx2000 option on recent versions of the compiler. On other compilers it may be necessary to set an option to extend the number of continuation statements. If you leave out the fast option on the second (link) step the link will fail on some Sparcs.
Use the -fpe0 option when compiling and linking in OSF configuration. The environment must not trap underflow; our machine does so by default, but -fpe0 will ensure this.
NB The Fortran on this machine is the buggiest I have ever seen - make sure you have the most recent version of the compiler. I used version 3.8 on OSF/1 AXP. One of the reasons this machine is so fast is that the compiler plays tricks with the source. Often this results in code being executed that is actually protected by an if statement. In other cases the order of parenthesis is ignored, in violation of the Fortran 77 standard. These cases can only be identified and corrected after a crash occurs. Please let me know about them.
One fix that usually seems to work is to not use the -fast option. There are a handful of routines that do not seem to compile well with the fast option, because of bugs in the system's fast function library. These include linefit.f, hcolst.f, he1col.f, and he2col.f. These routines should be compiled with the -fpe0 option alone if problems are encountered.
Henrik Spoon writes that, in VMS configuration, the options "/float=ieee/check=nounderflow" are the equivalent of the "-fpe0" compiler options in OSF configuration. I have never run the current version of the code in VMS.
The HP Fortran 77 compiler has a bug in the file open statement. The result is that if you create punch output, the system opens the file as as scratch file, which disappears when the code completes. See the discussion below. There is a special command, set exemplar, which sets a flag to get around the bug.
The -lfpe option loads the floating point library designed to ignore underflow. You should also set the environment to ignore underflow with the setenv command. This worked on one SGI I had access to, but not with others. Please let me know if you figure out how to ignore underflow.
A problem can arise when running Cloudy on a VAX, and this makes the use of the /g_floating option on the DEC Fortran compiler necessary. Several portions of Cloudy having to do with determining the ionization balance of the elements are written in double precision. The neutral fraction can become very small when the gas is highly ionized, and it is necessary to have exponents that extend beyond the conventional 10± 38 range of these machines. This portion of the code is written in double precision, which by the IEEE convention also has an increased exponent size. A VAX does not obey this convention (they were developed before it was) unless the /g_floating option is used on the compile step. Cloudy checks to see that the double precision is working correctly and will print a note if it is not. On some VAXs the g_floating option brings a severe time penalty. If this is the case, then it is not necessary to use the g_floating option, but Cloudy will not work for many conditions. Floating-point overflow may or may not occur if /g_floating is not specified.
Version 90 of Cloudy has not been tested on a VAX
Some compilers need well over 100 meg of swap space to compile the large block data containing the emission line atomic data, blckwind.f. We have increased our swap space here to allow compilations without problems. Another way to compile the block data is to use the option -temp=dir flag on the Fortran compiler to tell it to use the local disk for the temp files.
These do not occur. All compile-time errors I have heard about were due to older compilers, by default, being unable to handle large numbers of continuation statements, or to the large temp space mentioned above. There are some do loops that will not be executed (see Katya Verner's Model FeII atom below) and this may be flagged as a warning. This is normal.
There are several large common blocks which extend through many dozens of continuation lines. Most current Fortran compilers can handle this, but some older compilers may need to have an option turned on, allowing larger numbers of continuation statements. If you obtain compile-time Fortran errors, view the compiler's man page and check for options to allow many more continuation statements.
This is not included in C90 since it is an area of great activity and development, and so not stable. The compiler may flag several do loops as never being executed as a result. All will be in routines with 'fe2' somewhere in the name. This is normal.
Cloudy can produce ancillary output by entering "punch" commands. On most
machines the system will open a new file with a name like fort.11, without interaction
from the user. On others (the Microsoft PowerStation is an example) a name must be
provided, even though this does not appear to be ANSI standard Fortran 77. In other cases
(our HP Exemplar is an example) an opened file may be defined as scratch by default, and
it is necessary to change the open command to get another (keep) status. If the
status is not changed the punch output will simply disappear when the calculation is
complete.
In cases where the punch command does not produce the expected files, it will probably be
necessary to alter the syntax on the open command. These occur in routine
GetPunch near line 140. Two open commands occur, one with the
file name specified on the punch command, the other with the default file name. One or
both of these commands may need to be changed for the punch command to work properly if
your system is off the standard.
A problem arises if the routines are compiled and placed into a library. The code stores many values in block data statements. Compilers will allow you to put a block data into a library and the Fortran 77 standard says that these preset values should be used at link / load time. Most compilers will not load the block data values from the library, in violation of the Fortran standard. This is a documented problem in several compilers. If you wish to build a library you should leave the block data out, and explicitly link them at load time.
This file c84.ini contains a series of commands that will make C90 behave more like C84. Initialization files are new to C90. The contents of c84.ini will be entered into the command stream when the command init file=c84.ini is entered. This is described in Part I of Hazy. This file can be placed anywhere on the system if the path is set with the set path command.
A sample input stream parispn.in, the Meudon 1985 planetary nebula, is also included. The Lexington Meeting also uses this as one of the benchmarks (see Ferland et al 1995, in Analysis of Emission Lines, CUP, also on the Cloudy reprints page). Output from several platforms is also included.
This is the Unix script I use for computing a single model. You will need to edit the file and explicitly indicate the location of the executable file. To run the planetary nebula model you would enter the command run parispn and end up with a file parispn.out. If you enter the command run parispn test.out the output file will be called test.out instead.
Five sets of stellar atmospheres can be automatically accessed by the code. Subsets of the Mihalas (1972) and Kurucz (1979) grids are contained within the code in data statements. These are accessed with the table star Kurucz or table star Mihalas commands. Three sets of more modern atmospheres, subsets of the Kurucz (1991), Rauch (1997; A&A 320, 237) and Werner and Heber (1991), are also available. These are far too large to store within the code and are accessed as ancillary files. These should be obtained from the Web site and compiled, as described in a subsection of the MISCELLANEOUS COMMANDS section of Hazy I.
This is maintained in the web site. This is a complete history of changes to the active version of the code.
These are short changes to the code that fix specific problems. Hot Fixes are placed on the web site as soon as a problem is identified and corrected. These changes will be included in the next rev of the code, which may be some time away. The current set of hot fixes has not been incorporated into the source on the web site. The first step in setting up the code is to incorporate the hot fixes.
To be placed on the Cloudy mailing list and be notified of updates to the code, please send a request to garyl@cloud9.pa.uky.edu The Cloudy home page http://www.pa.uky.edu/~gary/cloudy also has an option to place yourself on the mailing list. It is important to be on this list and that the current version of the code, with hot fixes included, be used. Anything as complex as Cloudy must contain bugs. These are fixed as soon as they are found.
Please send comments or suggestions to Gary Ferland at gary@cloud9.pa.uky.edu