README FILE ------------------------------------------------------------------------------- HARTRATE - an ionization code (c) Christopher W. Churchill (NMSU) in collaboration with Elizabeth Klimek (NMSU) Jacob Vander Vliet (NMSU) ------------------------------------------------------------------------------- This file explains: (1) code download (2) code install and execution (3) code tutorial (4) code limitations (5) acknowledgements ------------------------------------------------------------------------------- Code Download The code and all supporting files are in the gzipped tar file 'hartrate.tar.gz' which can be downloaded by clicking on the link with that hyper-link tag. ------------------------------------------------------------------------------- Code Install and Execution (1) Unpacking files Save the gzipped tar file to a desired directory. To unzip the tar file type 'gunzip hartrate.tar.gz' on the command line. To unpack the tar file type 'tar -xvf hartrate.tar' on the command line. The 'v' (verbose) will list the files as they are unpacked. This list can be compared the list of files in the 'Contents' file provided on the web page. In the 'Contents' file, a brief description of the role of each file is provided. The files will unpack into a subdirectory called 'hartrate/'. Four subdirectories to the 'heartrate/' subdirectory are also created: 'hartrate/Iondata/' - contains files with fitting coefficients 'hartrate/UVBspectrum/' - contains the UVB SEDs library for z=0-5 'hartrate/Sb99Spectrum/' - contains Starburst99 stellar SED library 'hartrate/Output/' - contains example output file from the code See the 'Contents' file for additional details. (2) Compiling the code and executing The code is written in Fortran. It is fully compatible with f95 compilers on Linux platforms. There is a 'Makefile' included in the download. In the 'hartrate/' subdirectory, simply type 'make' on the command line. If the compilation is successful, the code is ready for execution. The executable file is called 'rates' and it is executed by simply typing 'rates' on the command line while your PWD is 'heartrate/'. Alternatively, one can modify their path command or employ a symbolic link in order to be able to work in any arbitrary PWD. There are no command line inputs for RATES. Different compilers can complain (warnings )about different bits of coding. The code is certainly not perfect in all syntax and it is possible that some f95 compilers may generate warnings or even errors. Hopefully, anything that comes up can be easily fixed, but if there are intractable problems, please email cwc@nmsu.edu for assistance. There is a good chance that the code will compile with f77 or f90 as well, but this has not been tested. ------------------------------------------------------------------------------- Code Tutorial This stand alone version of HARTRATE is called RATES, since it is independent of the hydroART cosmological simulations for which HARTRATE was designed. There are some slight differences between RATES and HARTRATE as the latter was described in the paper Churchill+ (2014, ApJ, submitted). RATES outputs the equilibrium ionization fractions and number densities for all included ions (from H to Zn) for a given cloud model. The gas component of a cloud model is defined by three quantities nH = the hydrogen number density T = the equilibrium temperature Z = the metallicity in solar units The ionizing SEDs can be the Haardt & Madau (HM) UVB and/or a single stellar population. To specify the HM UVB, the redshift, z, is specified. To specify the stellar population, the population mass, age, metallicity (in solar) and distance from the cloud model are specified. RATES provides for the combined HM UVB + stellar population SED to be used. RATES can be in used in three different modes. MODE=1 generate a single cloud model MODE=2 generate a series if cloud models with fixed nH over a range of T MODE=3 generate a grid of cloud models over ranges of nH and T Currently, RATES can solve clouds only at a single redshift and a single metallicity. Redshift and/or metallicity can be added to a grid by systematically running RATES in MODE=3 for various redshifts and metallicities. All input for RATES is contained in the the file 'rates.inp'. And example of this file is provided on the web page for perusal. DO NOT MODIFY THE FILE FORMAT OF 'rates.inp', OR RATES WILL CRASH. In some cases, not all input parameters are utilized, but values must always be present in each field of the 'rates.inp' file. For example, if photoionization is turned "off" for a collisional ionization only model, then the redshift of the cloud model is not required, but a redshift value must still be present in the proper field for that parameter or the code will crash. The 'rates.'inp' file is segregated into 9 segments. Each input parameter and its allowed range are briefly described in the 'rates.inp' file. Here, we elaborate a bit further... 1. RUN MODE - here is where the run MODE is specified (1,2,3) and the choice of ionizing SED. Inclusion of the HM UVB requires a redshift is specified under "UVB IONIZING SPECTRUM PARAMETERS" (see below). Inclusion of stellar ionizing spectrum requires the properties of the stellar population under 'STELLAR IONIZING SPECTRUM PARAMETERS' (see below). If running MODE=2, the range of log(T), from log(Tmin) to log(Tmax) in intervals dlogT is specified. If running MODE=3, the range of log(nH), from log(nHmin) to log(nHmax) in intervals dlognH is also specified. IF running MODE=1, the single cloud properties are provided under SINGLE CLOUD PARAMETERS. Note that the cloud model metallicity is specified under SINGLE CLOUD PARAMETERS for all MODES. 2. LSF MODE - just leave this as is 3. REPORTING MODE - RATES creates several output files(*) per user directive. Options are: the ion number densities, which have the file names 'X.nkjT', where X is the elemental species (i.e, H, He, Mg); the ionization fractions, which have file names 'X.fkjT'; the rates and rate coefficients for each ion, which have the file names 'X.Rphot_kjT' for the photoionization rates, 'X.arec_kjT' for the recombination rate coefficients, and 'X.acoll_kjT' for the collisional ionization rate coefficients. Finally, the ionizing spectrum can be output in the files 'sed-UVB.dat', 'sed-SB99.dat', and 'sed-full.dat', where the latter is the combined SED. * The downloaded files in 'hartrate/Output/' provide example output from the code (these file do not serve any other function, and can be deleted at any time without affecting code operations). 4. SINGLE CLOUD PARAMETERS - if using MODE=1, this is where the cloud nH, T, and Z (solar units) are specified. Note that the values are *not* log10 quantities, but linear values. If running MODE=2 or MODE=3, the metallicity of the cloud model is still specified here. 5. PHYSICS MODE - the various ionization processes can be included or excluded. Photo recombination must always be included, but dielectronic recombination can be turned "off" or "on". 6. UVB IONIZING SPECTRUM PARAMETERS - if photoionization is included in PHYSICS MODE and if the UVB ionizing spectrum is specified in RUN MODE, this is where the redshift of the cloud model is specified for interpolating the library of HM UVB SEDs 7. STELLAR IONIZING SPECTRUM PARAMETERS - if photoionization is included in PHYSICS MODE and if the stellar ionizing spectrum is specified in RUN MODE, then this is where the mass (in log10 solar masses) of the stellar population is specified, the age in Myr, the metallicity in solar units (not log10, but linear), and the distance to the population in kiloparsecs. 8. METALS TO INCLUDE - this is where the chemical mixture of the cloud model is specified. Note that the current version or RATES assumes a solar abundance pattern. Those elements with QUALITY CODE 'C' should be avoided if possible, for there are some of these which crash the code. 9. DIRECTORIES OF INPUT DATA FILES - three directory paths are listed here. The first line is the directory where the fitting coefficients data files live. These are the 'tab*.dat' files that have been distributed in the subdirectory 'hartrate/Iondata/'. The second line is the directory where the HM UVB SED library files live. These are the 'HM*.cont' files that have been distributed in the subdirectory 'hartrate/UVBspectrum/'. The third line is the directory where the Starburst99 99 SED library files live. These are the 'Ms*.stb99' files that have been distributed in the subdirectory 'hartrate/Sb99pectrum/'. The output of rates is to the PWD. In addition to the output files described above (see REPORTING MODE), a file called 'rates.runlog' is output. This file contains all information that was streamed to screen during program execution. ------------------------------------------------------------------------------- Code Limitations 1. RATES handles only optically thin gas, see Churchill+ (2014, Apj, submitted) for definition of optically thin. As such, there is no ionization structure in the cloud model and therefore no information on cloud depth scale. 2. RATES handles a solar abundance pattern only. This can easily be modified in the code, but the distributed version accounts for a solar pattern only. 3. RATES handles only a single stellar population when including stellar radiation for photoionization. ------------------------------------------------------------------------------- Acknowledgements The reference for RATES is Churchill+ (2014, ApJ, submitted). Please refer to the code as RATES* , where the footnote is * http://astronomy.nmsu.edu/cwc/Software/Ioncode/ ------------------------------------------------------------------------------- eof