cloudy-agn/README

Generally, the software is intended to be run by a single command in while working in a directory that contains several cloudy grid output files in subdirectories. This command is the script "scripts/meta/process_gridoutputs.sh". The output files must be named "mpi_grid.out". For instance, the structure I used looks like this:
.
├── magdziarz
│   ├── grids
│   │   ├── halfsolar
│   │   │   └── 4thdex
│   │   │       ├── cldn_22.00
│   │   │       ├── cldn_23.00
│   │   │       ├── cldn_24.00
│   │   │       └── nonitrogen
│   │   └── solar
│   │       └── 4thdex
│   │           ├── cldn_22.00
│   │           ├── cldn_22.50
│   │           ├── cldn_23.00
│   │           ├── cldn_23.50
│   │           └── cldn_24.00
│   └── points
│       ├── collapsed_default
│       ├── collapsed_doubled
│       ├── coll_def
│       ├── coll_doub
│       ├── conv_test_1
│       ├── conv_test_2
│       └── test
└── mehdipour
    ├── grids
    │   └── solar
    │       └── 4thdex
    │           ├── cldn_22.00
    │           ├── cldn_22.50
    │           ├── cldn_23.00
    │           ├── cldn_23.50
    │           ├── cldn_24.00
    │           └── newcldn22.59

where each directory "cldn_##.##" contains a file called "mpi_grid.out".

If I ran the primary script here, it would find all mpi_grid.out files in this structure, and would attempt to produce tables from each using the line list contained in "linelist.c17" in the "reference" directory. It will archive them into .tar.gz files by using the directory structure to create the filenames, but it ignores directories named "grids", so this would produce, for example, "fortfiles_mehdipour.solar.4thdex.cldn_24.00.tar.gz", and so on.

As of the first version of c17, this approach works quite well. New cloudy versions often produce changes in the output file, so this approach will become less reliable as time goes on. Ultimately, it would be more reliable to use the internal workings of cloudy to produce what we want, and moving forward I will attempt to do that. As it stands, the tables are collated from the intrinsic line list, and the emergent line list is ignored. The last entry found in the emission line output is used for any particular emission line, to avoid conflicts with default continuum bins.


The Line List
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Currently, the software reads the line list from a file called "linelist.c17" in the directory called "reference". The program ignores comment lines beginning with # and blank lines, but otherwise will interpret the line as containing an emission line identifier that should be read from the cloudy output file. The identifier can be copied and pasted directly from the cloudy output file or from a line label file output during a cloudy run. The program knows to only look at the relevant number of characters, so anything after that on the line can be interpretted as a user comment. For example,

FeKa      1.78000A              total intensity of K-alpha line

tells the program to compile a flux table for the emission line identified by "FeKa      1.78000A", and the fact that it is the total intensity of the K-alpha line is just information meant for the user.



explanations of files
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

scripts
──────────────────────────────────────────────────────────────────────────
all files found under subdiretories of "scripts" 
scripts/
├── analysis
├── cloudy
├── meta
├── operations
├── thor
├── util
└── xmgrace

subdirs
─────────────
"meta" contains scripts that are intended to be run by the user

"cloudy" contains the input scripts used for our grid runs

"thor" contains scripts used to submit jobs to thor with the torque scheduling system

"util" contains scripts that run procedures used by other scripts and are not intended to be run by the user

"xmgrace" contains parameter scripts for plotting various quantities

"operations" contains scripts that operate on various files, such as tables stored in fortfiles or a cloudy output file. Generally, these scripts aren't intented to be run by the user directly, but are setup this way for troubleshooting. Most of these are obsolete now and will probably get removed, soon, because they've been baked into my primary c++ program.

"analysis" give information about emission lines and the continuum, but these are not updated for c17, yet.


process_gridoutputs.sh
─────────────
in scripts/meta

This is the main script for creating fort files from cloudy grid output files. The use of this script is described at the beginning of the document. Go to a directory that contains at least one subdirectory with a file called "mpi_grid.out". It will attempt to compile flux tables and save them as a set of fort files. The syntax requires no command line arguments, just cd to the appropriate directory, then run the script from its location in the scripts/meta directory.


package_tables.sh
─────────────
in scripts/operations

This is the script that packages fortfiles for a particular cloudy grid output file. This isn't intended for the user to run directly, but sometimes I use it directly when troubleshooting. The syntax is:

package_tables.sh <dir>

where <dir> is a directory containing a cloudy grid output file called "mpi_grid.out".

The script will create a directory called "fortfiles" under which it will put "raw" fortfiles and "interpolated" fort files, after calling the interpolation c++ program from the "bin" directory, if it exists. The raw files have been sufficient since c17, because most of the convergence issues have been solved, it seems.



source files
──────────────────────────────────────────────────────────────────────────
all files found under "src". A standard GCC c++ compiler should be sufficient to compile all of these programs. All of these programs have debugging output that is toggled by changing the "debug" booleans at the top of agn.hpp before compiling. Sorry, I know that's terrible, but it was quick and easy!

To build one of these programs, cd to the "src" directory and use the "build" script, e.g.,

> cd src
> ./build create_fort_files

This will compile create_fort_files.cpp and move the binary to the "bin" directory, where the various scripts look for binaries.

agn.hpp
─────────────
The primary header for the project. This file defines containers and methods for storing cloudy grid results. The routine for reading the cloudy file is defined here, read_cloudy_grid(), and it's a mess. This is because the most efficient approach was to read the entire grid at once, collating lines as we go. This iapproach increased efficiency but it's ugly and I'm not sure when I'll have time to rewrite it. This may turn out to be a detriment to troubleshooting.


spectral_lines.hpp
─────────────
This header contains definitions and utilities for storing and operating on emission lines and flux tables. The bulk of the code run by "create_fort_files.cpp" is included in this file, besides reading the cloudy file itself.


create_fort_files.cpp
─────────────
The operational program for creating fort files from a cloudy grid output file. The syntax is:

./create_fort_files <cloudy output file> <line list file>

This reads the line list from the line list file, then compiles tables for each line from the cloudy output file. The fort files will be created in your current working directory. This program is rarely intended to be run on its own, and is called by the "scripts/operations/package_tables.sh" script, which is turn called by the "scripts/meta/process_outputs.sh" script.


interpolation_fix.cpp
─────────────
This program runs a cubic spline-based smoothing operation along lines in constant hydrogen density over a flux table file. It returns another table with the fixed values. The syntax is:

interpolation_fix <input file> <output file>


subtract_fortfiles.cpp
─────────────
This program takes two flux tables and returns a new table of their difference to standard output, which can be streamed to a file. The syntax is:

subtract_fortfiles <file1> <file2> <4 char header>

where the difference will be file1 - file2, and the new table's header will start with the 4 characters in the third command line argument.


convert_sed_ryd_to_ev.cpp
─────────────
OLD. A simple program for converting SEDs in rydbergs to ev. Cloudy can do this on its own, so this program is redundant.

save_table2d_slice.cpp
─────────────
OLD. Used to extract slices along constant hden or phi from a flux table, mostly for examination during debugging. Lots of easy ways to do this in graphing software and what have you. This may not even work anymore and I'll probably remove it soon.

sed/*
─────────────
OLD. These were routines created to produce spectral energy distributions. We don't take this approach anymore, since it's not necessary to create the SED more than once. SEDs are stored in tables in the directory "reference", instead, and the "sed" subdirectory will probably be removed soon.