Cloudy & Associates

Commit 7e38b820 authored by Chatzikos, Marios's avatar Chatzikos, Marios
Browse files

Convert READMEs in data to markdown

parent 3ed30643
Read me for Cloudy data files
=============================
last reviewed November 3, 2022
* * *
Overview
--------
This documents the data files included in the Cloudy data distribution.
The instructions for setting up the code are on the
[web site](https://www.nublado.org).
Three types of files are present in this (top) directory:
* **_\*.ini_** These are files that are used to set up Cloudy.
You can change these files to alter the default behavior of the code.
These can, for instance, change the continuum resolution or add new entries
into the main emission-line output.
* **_\*.dat_** These are the foundation atomic/molecular data files that are
needed for the code to operate.
Do not change these files.
* **_\*.in_** These are input scripts that are used to compile various helper
files such as stellar atmospheres or types of grains. 
* * *
Database atomic/molecular models
--------------------------------
Cloudy draws the majority of its atomic and molecular data from external
databases, namely:
* the _Chianti_ database (v10.0.1),
[Del Zanna et al. 2021 ApJ, 909, 38](https://ui.adsabs.harvard.edu/abs/2021ApJ...909...38D)
* the _Stout_ database,
[Lykins et al. 2015 ApJ, 807, 118](https://ui.adsabs.harvard.edu/abs/2015ApJ...807..118L)
* the LAMDA database,
[van der Tak et al. 2020, Atoms, 8, 15](https://ui.adsabs.harvard.edu/abs/2020Atoms...8...15V)
See the respective papers for details.
* * *
Compiling ancillary files with the \*.in input files
----------------------------------------------------
The download includes all the files you will need to get Cloudy running.
The download does not include the stellar continua file that are needed for
the table stars command to work.
The web site describes how to set up these continua and this only needs to be
done if you want to use the table stars command.
Several input files (names like compile\*.in) are examples of compiling some
of the stellar continua.
### (Possibly) compiling the size-distributed grains
It is easy to create new grain tipes.
Compiled opacities are already included in the data files (the \*.opc files),
so nothing need be done if you are happy with the default setup.
They would need to be recompiled if you change the energy grid of the code,
or wish to use a different grain refractive index or size distribution.
Distributed grains are new in C96 and were added in collaboration with
Peter van Hoof and Peter G. Martin.
These use optical properties for each grain material (the \*.rfi files) and
size distribution files (the \*.szd files) to create grain opacities
(the \*.opc files) that are a function of grain material and size.
The code can then do a more realistic simulation of the grain emission and
physics.
### The grain properties files, \*.szd, \*.rfi, \*.opc
These files specify the size distribution (\*.szd) and refractive indices
(\*.rfi) for the new treatment of grain physics that is used with the
```compile grains``` command.
The \*.opc files give the actual opacities used by the code.
For details, see Appendix A in Hazy 1.
* * *
User-defined files that change code behavior
--------------------------------------------
### The \*.ini files
These are a series of files that add commands to the input stream when you run
a model.
They are added by including an **init** command that names one of the following
files.
* **c84.ini** - makes code behave more like version 84
* **fast.ini** - this includes several commands that make the code run faster,
at the expense of a less accurate simulation
* **honly.ini** - hydrogen only init file
* **hheonly.ini** - init file for H, He only
* **ism.ini** - turns off level 2 lines and only includes prominent elements
for depleted mixture.
_**NB**_ This does not add grains to the mix even though many elements are
strongly depleted.
This is not consistent, and so grains should be added separately.
* **pdr\_leiden.ini** and **pdr\_leiden\_hack.ini** are used to compute the
PDR models given in Roellig et al.
### FeII bands in the output
The data file _FeII\_bands.ini_ is used to specify a series of FeII bands that
are entered into the main emission line output.
These bands are described further in the dat file and in the part of Hazy where
FeII is discussed.
### Continuum bands in the output
The data file _continuum\_bands.ini_ is used to define a series of wavelength
bands.
Each band has a lower and upper wavelength and the code will integrate all
emission over these bands.
The total luminosity or intensity is entered into the main emission line output.
### Emission line lists for cdGetLineList
These are the default lists of emission lines that can be read into arrays of
emission lines by calling cdGetLineList.
This is useful when the code is being called as a subroutine of other larger
codes, as a way to obtain a list of emission lines whose intensities are to
be extracted from the calculation.
This process is described in the section of a later part of Hazy on calling
Cloudy as a subroutine.
These files are meant to be changed by the user. 
The files have names LineList\*.dat and the end of the filename indicates the
purpose.
At present the lists are the following:
* **LineList\_BLR.dat** - lines seen in the spectra of BLR of AGN
* **LineList\_NLR.dat** - lines seen in the spectra of NLR of AGN
* **LineList\_HII.dat** - lines for HII Regions
* **LineList\_strong.dat** - a minimarl list of emission lines
* **LineList\_PDR.dat** - a list of PDR lines
* **LineList\_PDR\_H2.dat** - a PDR line list with many H2 lines from the large
molecule
* **LineList\_HeH.dat** - a set of H and He emission lines
* **LineList\_He\_like.dat** - lines for the He-like iso sequence
Some line wavelengths may change over time as the accuracy of energy levels
improve.
The ```table lines "name.dat"``` command is used to check that that the lines
in the file name.dat are still correct.
Any line list file that is included here in the data director should also be
included in an one of the test cases in the test suite.
### The resolution of the continuum mesh
The file _continuum\_mesh.ini_ contains data the defines the continuum mesh
used during a calculation.
It is possible to make the continuum have any resolution at all by changing
this file.
The continuum resolution largely sets the execution time so be careful.
The file contains documentation of its use.
* * *
Hummer and Storey Case B data files
-----------------------------------
The files HS\_e1b.dat through HS\_e8b.dat, and HS\_e1a.dat through HS\_e8a.dat
are from
[Storey P.J., Hummer D.G. 1995, MNRAS 272, 41](https://ui.adsabs.harvard.edu/abs/1995MNRAS.272...41S).
* * *
Mewe files
----------
The files mewe\_fluor.dat and mewe\_nelectron.dat are tables 2 and 3 of the
atomic data from
[Kaastra, J.S., & Mewe, R., 1993, A&AS, 97, 443](https://ui.adsabs.harvard.edu/abs/1993A%26AS...97..443K).
The file mewe\_gbar.dat  is the Mewe data files for g-bar collision strengths.
* * *
Molecular hydrogen files
------------------------
Files related to the structure of the H2 molecule are contained within the
_h2/_ directory.
File names reflect their contents, so that files:
* *energy_?.dat* contain the energy structure of the molecule in various
configurations
* *transprob_?.dat* contain transition probabilities
* *coll_rates_?.dat* contain collision strengths for impact by a variety of
projectiles striking H2
* *dissprob_?.dat* contain dissociation probabilities for various electronic
configurations of H2
* *hminus_deposit.dat* distribution functions for populating levels of H2
following formation from H\-
* * *
UTA data file
-------------
All UTA data are stored in the _UTA/_ directory.
There are two files with names UTA\*.dat, the following:
* UTA\_Gu06.dat - from Gu et al. ApJ, 641, 1227.  These are now the default for Fe0 through Fe+12.
* UTA\_Kisielius.dat - from Kisielius et al. MNRAS 344, 696, used for Fe+13 - Fe+15.
All other files (303 in total) are taken from the Opacity Project.
For details, see README.md therein.
* * *
Level 1 and Level 2 data files
------------------------------
* level1.dat, the main set of level 1 lines, this file is designed to be edited by humans.
* level2.dat, the level 2 lines, do not edit this file!
* * *
Miscellaneous directories
-------------------------
Other directories exist with useful information:
* _abundances/_ defines elemental and isotopic abundances used by Cloudy
* _SED/_ contains the Spectral Energy Distributions of various sources
* * *
Visit [www.nublado.org](https://www.nublado.org) for more details and the latest updates.
Good luck!
Gary J. Ferland
# Line Lists -- Overview
When the code is called as a subroutine of other, larger codes,
it is possible to obtain a list of emission lines by calling cdGetLineList.
The argument to that routine is the name of a file that has a list of the emission
......@@ -18,29 +20,34 @@ The wavelength is in Angstroms unless the line ends with
the character 'c' (centimeters) or 'm' (microns). If the value is
in Angstroms and it is less than 1000A then the number is a 4-digit
floating point number. If it is in microns or cm,
the wavelength is a 4-digit floating point number followed by 'm' or 'c'
the wavelength is a 6-digit floating point number followed by 'm' or 'c'
immediately after the number. This is the same format as the emission
line printout at the end of a calculation. A list of line labels can be
generated by running the code with the "print line lables" command.
comments can appear after the wavelength
DANGER!
Many different lines can have the same wavelength - make sure you get the right line!
The punch line labels command can generate a complete list of all
lines perdicted by the code. Its output includes the line index,
a number giving the order of the line in the large stack of emision lines.
There are a vast number of emission lines predicted by the code,
and many lines will have the same wavelength. The line label can
usually be used to distinguish between various lines with
the same wavelength. This is seldom the case for contributions
to the line however. For instance, the label "inwd" is applied to the inward
contribution to all lines, so there are almost certainly many
lines with this label and the same wavelength. The line index
can be used to break this degeneracy in cases where you want to
obtain a line's intensity with a call to a routine. Routine cdLine_ip
uses this index to find the relative intensity and luminosity of a
line with a particular index. But note that this index is not
a constant - it will always be the same for a particular set of
input conditions, but it depends on the sizes of various atoms
generated by running the code with the "print line labels" command.
Comments can appear after the wavelength.
## DANGER!
Many different lines can have the same wavelength - make sure you get the right
line!
The ```save line labels``` command can generate a complete list of all
lines perdicted by the code (the file _docs/LineLabels.txt_ shows the default
list of lines).
Its output includes the line index, a number giving the order of the line in
the large stack of emision lines.
There are a vast number of emission lines predicted by the code, and many lines
will have the same wavelength.
The line label can usually be used to distinguish between various lines with
the same wavelength.
This is seldom the case for contributions to the line however.
For instance, the label "inwd" is applied to the inward contribution to all
lines, so there are almost certainly many lines with this label and the same
wavelength.
The line index can be used to break this degeneracy in cases where you want to
obtain the intensity of a lines with a call to a routine.
Routine ```cdLine_ip``` uses this index to find the relative intensity and
luminosity of a line with a particular index.
But note that this index is not a constant - it will always be the same for a
particular set of input conditions, but it depends on the sizes of various atoms
and which elements are turned on.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment