Cloudy & Associates

Skip to content
GitLab
Commit 3b4a833a authored by Chatzikos, Marios's avatar Chatzikos, Marios
Browse files

Merge branch 'readmes' into 'master' 

Convert all REAME files to Markdown

See merge request !52
parents 7df8be33 beceb545
Hide whitespace changes
Inline Side-by-side
README.md
View file @ 3b4a833a
......@@ -32,11 +32,46 @@ as well as tarballs on our
[release folder](https://data.nublado.org/cloudy_releases).
# Directory structure
There are seven directories below this one containing the:
1. atomic, molecular, grains data, as well as SEDs (```data/```);
1. documentation (```docs/```);
1. doxygen setup files (```doxygen/```);
1. a unit test library (```library/```);
1. some helpful scripts (```scripts/```);
1. the source (```source/```);
1. and test suite (```tsuite/```).
The test suite directory, tsuite, has a number of directories below it,
each exercising different aspects of Cloudy.
These directories contain all files needed to build and execute Cloudy.
Each directory has a readme file giving more information on its contents.
It is important to maintain this directory structure when the download is
opened on your computer.
# Building Cloudy
Instructions for building the code on various platforms are available on
[the wiki](https://gitlab.nublado.org/cloudy/cloudy/-/wikis/CompileCode).
Makefiles are provided for most popular compilers (see ```source/sys_*```).
# Documentation
The ```docs``` directory contains Hazy, Cloudy's documentation.
# API
Cloudy's API is described with [Doxygen](https://doxygen.nl), and is available
Cloudy's API is described with [Doxygen](https://doxygen.nl).
A precompiled version is available
[online](https://data.nublado.org/doxygen/c22.00).
If you wish to produce a local instance, please follow the instructions in
the ```doxygen/``` directory.
# Contact us
......
data/readme_LineList_dat.txt → data/README_LineLists.md
View file @ 3b4a833a
# 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.
data/README_data.md 0 → 100644
View file @ 3b4a833a
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.
The commands
```
database [chianti|stout|lamda]
```
are provided to manipulate each database en masse, while the command
```
species "Fe+" [dataset="Tayal18"]
```
is provided for refined control of individual model ions.
Notice that the keyword ```dataset``` may be used to select between various
datasets, as in the Fe+ example above.
* * *
Compiling ancillary 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.
The script ```make_data.sh``` may be used to construct ancillary files used
by Cloudy.
Some of them, relating to grains, are discussed below.
### (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
data/SED/ReadMe.txt → data/SED/README.md
View file @ 3b4a833a
## Notes
This specifies optional SEDs. One of these files will be used if the command
table SED "filename.sed"
appears.
......@@ -18,7 +20,7 @@ appears then the flux can be given in relative nu f_nu units.
Comments begin with "#" and can occur anywhere in the file.
The list of energies and fluxes are concluded with a field of stars,
for example, *****.
for example, \*\*\*\*\*.
Everything after the field of stars is ignored, so can be used to document the
SED.
......@@ -29,7 +31,7 @@ part of the SED to the low-energy limit of the code using a power law.
The following SED files are now included;
AGN_Jin*.sed
AGN_Jin\*.sed
These are the SEDs summarized in 2020MNRAS.494.5917F and derived by
2012MNRAS.420.1825J and 2017MNRAS.471..706J
......
data/SED/Trapezium/README.md 0 → 100644
View file @ 3b4a833a
## Notes
Trapezium cluster massive stars
stellar types listed in Table 1 of Ferland+12
http://adsabs.harvard.edu/abs/2012ApJ...757...79F
That paper used TLusty stellar atmospheres.
Trapezium_Tlusty shows this
Wagle+ in preparation claim that WMbasic gives better fit to [Ne III] lines.
Trapezium_WMbasic shows this
Veusz file and pdf compare these two.
* * *
The original form came from Will Henney in email of
2012 Dec 5. His notes follow:
> Stellar parameters for C, A, D are from Simón-Díaz \cite{2006A&A…448..351S}
> I originally had th1B as a B2V star, which should be cooler than what Gary had (28kK and 10**4.4 Lsun), but I can't find the provenance of this
> actually th1B (BM Ori) is a quintuple system: see SIMBAD record
> SIMBAD says primary is B1V citing \cite{Close:2003}, but that paper does not mention spectral types at all. I suspect this is a confusion with B1, B2, etc being the designations of the quintuple components
> \cite{Weigelt:1999} find a B3 spectral type for the primary (B1) with log L = 3.25 and T = 18000
> B2, B3, and B4 are all lower mass, but B5 has mass similar to B1 accoding to \cite{Weigelt:1999}. However, this must be a mistake: according to \cite{Abt:1991}, who detect B1 and B5 as an eclipsing spectroscopic binary, the mass ratio is 0.3, implying that B5 has a mass of only 2 Msun..
> th1C is a triple system \cite{Lehmann:2010a}
> \cite{Schertl:2003} have broad constraints on the parameters of C2 (dark gray line in their Fig 4). If we take the middle of this range, we get a giantish B3IV star: log L = 3.8, T = 17000, M = 9 Msun, age much less than 1 Myr.
> We can work out the surface gravity:
> g = G M / R2 = G M 4 pi sigma T4 / L = 6.673e-8 9 1.989e33 4 pi 5.6703e-5 17000**4 / 10**3.8 3.82e33 = 2950 cm/s2 => log g = 3.5
> [X] We should check these parameters against \cite{Lehmann:2010a}, who say 12 Msun in their abstract. The article itself is not freely available -grab it when I get back to work
> If we use the same evo tracks as in \cite{Schertl:2003}, then this would imply B2IV with log L = 4.0, T = 21000
> So, after checking out the Lehman article, it seems the 12 Msun is robust, since it is based on orbital solution. The translation to luminosity and Teff is rather more speculative.
> In fact, according to \cite{Kraus:2007}, the companion is O9.5V with Teff = 32000, log L = 4.68. This is also consistent with the Schertl tracks, but it is assuming 15.5 Msun.
> If we instead use 12 Msun as the best mass estimate \cite{Lehmann:2010a}, then we would get log L = 4.2, Teff = 25,000
> Recalculate surface gravity for new parameters
> g = G M / R2 = G M 4 pi sigma T4 / L = 6.673e-8 12 1.989e33 4 pi 5.6703e-5 25000**4 / 10**4.2 3.82e33 = 7322 cm/s2 => log g = 3.86
>
> 2014 May 06, changed some tlusty stars to WMBasic - had used tlusty for all stars originally. WMBasic produces better agreement with H II region optical emission, especially [Ne III]
> Using this new solution for th1C2 changes the broadband ratios by about 5%.
> th1A is a double system
>
> stars = dict(
> th1C = dict(T=39000., g=4.1, L=5.31),
> th1A = dict(T=30000., g=4.0, L=4.45),
> th1D = dict(T=32000., g=4.2, L=4.47),
> th1B = dict(T=18000., g=4.1, L=3.25),
> th1C2 = dict(T=25000., g=3.86, L=4.2),
> )
data/SED/Trapezium/readme.txt deleted 100644 → 0
View file @ 7df8be33
Trapezium cluster massive stars
stellar types listed in Table 1 of Ferland+12
http://adsabs.harvard.edu/abs/2012ApJ...757...79F
That paper used TLusty stellar atmospheres.
Trapezium_Tlusty shows this
Wagle+ in preparation claim that WMbasic gives better fit to [Ne III] lines.
Trapezium_WMbasic shows this
Veusz file and pdf compare these two.
***************************
The original form came from Will Henney in email of
2012 Dec 5. His notes follow:
Stellar parameters for C, A, D are from Simón-Díaz \cite{2006A&A…448..351S}
I originally had th1B as a B2V star, which should be cooler than what Gary had (28kK and 10**4.4 Lsun), but I can't find the provenance of this
actually th1B (BM Ori) is a quintuple system: see SIMBAD record
SIMBAD says primary is B1V citing \cite{Close:2003}, but that paper does not mention spectral types at all. I suspect this is a confusion with B1, B2, etc being the designations of the quintuple components
\cite{Weigelt:1999} find a B3 spectral type for the primary (B1) with log L = 3.25 and T = 18000
B2, B3, and B4 are all lower mass, but B5 has mass similar to B1 accoding to \cite{Weigelt:1999}. However, this must be a mistake: according to \cite{Abt:1991}, who detect B1 and B5 as an eclipsing spectroscopic binary, the mass ratio is 0.3, implying that B5 has a mass of only 2 Msun..
th1C is a triple system \cite{Lehmann:2010a}
\cite{Schertl:2003} have broad constraints on the parameters of C2 (dark gray line in their Fig 4). If we take the middle of this range, we get a giantish B3IV star: log L = 3.8, T = 17000, M = 9 Msun, age much less than 1 Myr.
We can work out the surface gravity:
g = G M / R2 = G M 4 pi sigma T4 / L = 6.673e-8 9 1.989e33 4 pi 5.6703e-5 17000**4 / 10**3.8 3.82e33 = 2950 cm/s2 => log g = 3.5
[X] We should check these parameters against \cite{Lehmann:2010a}, who say 12 Msun in their abstract. The article itself is not freely available -grab it when I get back to work
If we use the same evo tracks as in \cite{Schertl:2003}, then this would imply B2IV with log L = 4.0, T = 21000
So, after checking out the Lehman article, it seems the 12 Msun is robust, since it is based on orbital solution. The translation to luminosity and Teff is rather more speculative.
In fact, according to \cite{Kraus:2007}, the companion is O9.5V with Teff = 32000, log L = 4.68. This is also consistent with the Schertl tracks, but it is assuming 15.5 Msun.
If we instead use 12 Msun as the best mass estimate \cite{Lehmann:2010a}, then we would get log L = 4.2, Teff = 25,000
Recalculate surface gravity for new parameters
g = G M / R2 = G M 4 pi sigma T4 / L = 6.673e-8 12 1.989e33 4 pi 5.6703e-5 25000**4 / 10**4.2 3.82e33 = 7322 cm/s2 => log g = 3.86
2014 May 06, changed some tlusty stars to WMBasic - had used tlusty for all stars originally. WMBasic produces better agreement with H II region optical emission, especially [Ne III]
Using this new solution for th1C2 changes the broadband ratios by about 5%.
th1A is a double system
stars = dict(
th1C = dict(T=39000., g=4.1, L=5.31),
th1A = dict(T=30000., g=4.0, L=4.45),
th1D = dict(T=32000., g=4.2, L=4.47),
th1B = dict(T=18000., g=4.1, L=3.25),
th1C2 = dict(T=25000., g=3.86, L=4.2),
)
data/UTA/readme.txt → data/UTA/README.md
View file @ 3b4a833a
UTA data sets from several papers, cited in *.dat files
UTA_Gu06.dat
UTA_Kisielius.dat
## Notes
UTA data sets from several papers, cited in \*.dat files:
* UTA\_Gu06.dat
* UTA\_Kisielius.dat
------------------
NOTATION FOR THE OPACITY PROJECT DATA, nrb00*
These sets of inner shell transitions are from Nigel Badnell's web site
http://amdpp.phys.strath.ac.uk/tamoc/DATA/PE/
### NOTATION FOR THE OPACITY PROJECT DATA, nrb00\*
These sets of inner shell transitions are from Nigel Badnell's
[web site](http://amdpp.phys.strath.ac.uk/tamoc/DATA/PE).
Badnell et al. (2005) describe the methods.
ADS URL : http://adsabs.harvard.edu/abs/2005MNRAS.360..458B
They were generated as part of the Seaton/Opacity Project and follow their convention.
[Badnell et al. (2005)](https://adsabs.harvard.edu/abs/2005MNRAS.360..458B)
describe the methods.
They were generated as part of the Seaton/Opacity Project and follow their
convention.
The names designate the electron target because the R-matrix
radiative data is generated from an electron collision problem,
taken down to bound states.
The names begin with nrb00 then the isoelectronic sequence of the next higher ion,
followed by the element. The number after the element is related to the charge,
but think of the number
The names begin with ```nrb00```, followed by the isoelectronic sequence of
the next higher ion, followed by the element.
The number after the element is related to the charge, but think of the number
as Roman since target electron charge = Roman recombined.
So, in this convention, data for O VI, which is Li-sequence, would be He since
that is the parent ion, followed by o6. So,
O VI == he_o6ic1-2.dat
```O VI == he_o6ic1-2.dat```.
Data within the file:
IRSL are the (non-energy-order) levels in
```
INDX IRSL CODE S L WJ WNR
```
The first column here is lower level, second upper level.
```
IRSL IRSL N L DEL(RYD) B(SEC) R(SEC) A(SEC): 1
```
B is Einstein up, R is down and A is Auger.
see
http://www.adas.ac.uk/man/appxa-38.pdf
see [here](https://www.adas.ac.uk/man/appxa-38.pdf)
for the rest of the file spec.
The full BibTeX record of that paper is:
```
@ARTICLE{2005MNRAS.360..458B,
author = {{Badnell}, N.~R. and {Bautista}, M.~A. and {Butler}, K. and
{Delahaye}, F. and {Mendoza}, C. and {Palmeri}, P. and {Zeippen}, C.~J. and
......@@ -55,4 +62,4 @@ for the rest of the file spec.
adsurl = {http://adsabs.harvard.edu/abs/2005MNRAS.360..458B},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
```
data/abundances/README.md 0 → 100644
View file @ 3b4a833a
## Notes
The files in this directory specify standard chemical compositions and,
optionally, grains.
One of these files will be used if the command
```
abundances "filename.abn"
```
appears.
These ```.abn``` files may also specify grains, although grains are not
included by default.
```default.abn``` specifies our default composition.
```default-reference.abn``` is a copy of that file.
The ```\*.dpl``` files specify depletion factors that account for the elements
that are used to build grains.
These may be parsed by the
```
metals deplete "filename.dpl"
```
or
```
metals deplete Jenkins 2009 Fstar=0.5 "filename.dpl"
```
commands.
The default file, described below, will be used if no file appears between the quotes.
* * *
### Specifying abundances
The default is the "solar" composition in ```default.abn```.
It is used if no others are specified.
```default-backup.abn``` is a backup of this file, used to reestablish default
if you change it.
This is a fairly old set of "solar" abundances that we maintain for backwards
compatibility.
To change the default abundance set, copy one of the abundance files (e.g.,
```default.abn``` or ```solar84.abn```) in your working directory, preferrably
with a custom name, edit it at will, and use it with the command
```
abundances "mycustom.abn"
```
#### Available files
* solar84.abn - abundances used by "old solar" option, used in versions 84-94
of the code.
* Other .abn files - see the comments within the file for more details.
The file name gives a good indication of its contents
* * *
### Default depletion files
The command
```
metals deplete
```