* COMPILE contains information on compiling the code.
* VERSION discusses some of the code's structure, capabilities, and updates over time.
* THIS README FILE contains a quick HOW-TO for running the code.
o Quick basics:
* The main arrays over the computational volume are given ordered
ARRAY(JMAX2,KMAX2,LMAX) for JMAX=Max R zones, KMAX= Max Z zones
and LMAX=Max azimuthal zones. JMAX2=JMAX+2, etc., which takes
into account ghost cells. J=2 is the first radial cell and
JMAX1 (JMAX+1) is the last radial cell on the computational volume.
J=1 and JMAX2 are boundary ghost cells. Likewise for K.
* S = radial momentum density
* T = vertical momentum density
* A = angular momentum density
* rho = mass volume density
* eps = internal energy volume density
* S,T are face-centered. A,rho,eps are all cell-centered.
* U,W,OMEGA are the radial, vertical, and azimuthal velocity components,
where OMEGA is the azimuthal speed. They have the same centering as the
corresponding momenta.
* R,Z = face-zeroed quantities. R(2) = 0, and R(3) = rof3n, where rof3n
and zof3n are the radial and vertical cell sizes.
* rhf and zhf are the cell-centered radial and vertical quantities.
rhf(2)= half*rof3n
* Loops are ordered L,K,J. J is the fastest iterator as a result, which
is optimal for FORTRAN arrays (column-major).
* Source gives force and dissipation/cooling terms.
* Flux takes care of the advective terms.
* Evolution: 1/2 source -> 1/2 Flux -> full Flux with updated values
-> Potential update -> 1/2 source with updated values.
o The header files, along with pre-compiler options, control the functionality of the code.
* units.h contains the cooling switches, equation of state options, data files names,
and definitions of constants.
* globals.h declares global variables and common blocks. In an updated version of the code,
modules will be used instead. For now, common blocks will need to suffice.
* hydroparams.h contains the size of the arrays, defining JMAX,KMAX, and LMAX. POT3JMAX and
POT3KMAX are also defined for the potential solver. The potential grid need not be the
same size as the rest of the grid, but it cannot be smaller than JMAX,KMAX. Usually, they
are set to the same size. A large potential volume may be desired for some problems to
minimize boundary value problems. JMIN sets the inner boundary of the system. If JMIN=2,
the entire grid is active. For JMIN>2, radii with J<JMIN are not included in the calculation.
Any mass that flows through the inner grid is either added to the central potential or
simply discarded. The default is to assume a central potential is used and to add that mass
to the potential. The rest of the values in hydroparams.h should not be changed.
o Upon compiling the code, the executable (default 'chymera-omp') will be in the run directory.
This directory also contains all dat files for table reads, and will need to contain the
files fort.5 and fort.7.
* fort.5 is the basic readin file. It controls the code output and simulation steps. This
will be changed to a user-friendly namelist readin formation, but as of now, we need to
deal with an input file based on coding during code antiquity. The top of the file is
shown below.
### CODE ###
1.0E0 1.5E0
1.666666666666667E0
000000 010000 001000 000003 000001 000001 010000 000000
9.0e0 0.0e0
THE DATA AREIN THIS ORDER:
KONST PINDEX
GAMMA
ITSTRT,ITSTOP,IDIAG,ISOADL,ITYPE,NMODL,ISTOR,IGRID,
NPRIME (=9 for ISO)
### END CODE ###
Some description is given in the fort.5 file. The main things to note are the following:
o KCONST (p=KCONST rho^(1+1/n)) and the polytropic index n.
o GAMMA = 1+1/n = adiabatic index
o Iteration start, iteration stop, diagnostic output, ISOADL=3 (do not change),
initial model type, NMODL=1 (do not change), output store, IGRID=0 (do not change).
o Last line is obsolete, but keep it in until the readin has been updated. Do not change.
Iteration start is the first iteration the code will take, and the stop is the last iteration.
This is just for any given stretch. Diagnostic writes will be made every IDIAG, including
density and temperature dumps. Restart files and very large files for complete diagnostics
will be dumped every ISTOR. Be careful with the selection of ISTOR, as too frequent dumps
can lead to excessive data demands.
ITYPE describes the model readin. ITYPE=1 is used for a restart without any modification.
ITYPE=98 reads in the file, but then adds a random density perturbation with an amplitude
given by amp0 set in units.h (headers directory). ITYPE=99 reads in an LMAX=8 model and
expands it to the LMAX given in hydroparams.h.
* fort.7 is the restart file. Output from the code saved.* can be copied to fort.7 as a new
readin. When the input controls are converted to namelist files, the user will have the
option of giving a name for the restart file to avoid the copying hastle. Copying is in
place for now, though.
o ANALYSIS DIRECTORY
* A variety of analysis tools are available for streamlining images and movie production. All
fortran code can usually be compiled with gfortran -o blah blah.f90 -frecord-marker=4.
Be sure to mind the endianness, as well as what the compiler is actually doing with record
marker length.
o sigplot.f90 makes surface density plots from code output. Run ./sigplot to get instructions
how to run the code. For example:
### TERMINAL SESSION ###
cfe2.aboley 74> ./sigplot
A CHYMTOOL SPONSORED EVENT
sigplot v 1. 11.10.2007. Nora Bolig
SIGPLOT USAGE: sigplot {stepbegin} {stepend} {stepskip}
{jmax} {kmax} {lmax} {torp} {dz}
{cell-to-size unit conversion }
{min surface density background}
{code to cgs surfden conversion}
{filein prefix} {fileout prefix}
Calling Cthulu...(run)
### END TERMINAL ###
For AU units, i.e., the default with G=1, AU=1, and Msun=1, torp = 0.159 to convert code
output to years. Any value can be given for torp, for example, the ORP conversion.
dz = cell-to-size unit conversion for AU units, but could be different for other units.
The code will work in log units and give output in surface density cgs log10. For min
surface density, give a small number in log10 (e.g., -18.). For AU units, cgs surfden
conversion is about 8.9e6. Filein should be a rho3d file. An example of correct syntax is
### TERMINAL SESSION ###
./sigplot 100000 100001 10 256 64 512 0.159 0.1 0.1 -18. 8.9e6 ../run/rho3d. sig.
### END TERMINAL ###
where the cell sizes are 0.1 AU. The output file sig.100000 will have X, Y, and
V, where V is log10(surface density). These can be plotted with python scripts
or most simply with gunplot
### GNUPLOT SESSION ###
gnuplot>f="sig.100000"
gnuplot>plot f w image
### END GNUPLOT ###
Many files can be made at once using makesig.sh. This is just a template, and may need some
modification for limits, etc., for any given use. makeimage.py is likely more understandable,
but makesig.sh works with just gnuplot and tcsh.
* midplot.f90 plots midplane density or temperature values, and is used analogously to sigplot.f90.
Many of the other tools follow similar patterns. The scale is linear for midplot.
* Many other tools are available. Many of them are given with the current distribution, but
documentation is still being made. When all else fails, look at the source code. Most tools give
some hint how to use them by running them without any command line input.
o Your first disk simulation.
* Simulation ICs are available for users through github. For your first run, consider the ICs in
CHYMERA-CODE-IC-1. Do the following, assuming PWD=$CHYMERA_HOME, where CHYMERA_HOME is the directory
where you can see bin, run, radhydro, etc. I'm also assuming the CHYMERA-CODE-IC-1 is available in
the $HOME directory, but this can be anywhere of the user's choosing.
1). Copy $HOME/CHYMERA-CODE-IC-1/ic.dat to run/fort.7
2). Copy $HOME/CHYMERA-CODE-IC-1/fort.5 to run/.
3). Copy $HOME/CHYMERA-CODE-IC-1/units.h to headers/.
-> Note that placing header files in the patch directory will not work at the moment. I'm
aware fo the issue and working on it.
4). Copy $HOME/CHYMERA-CODE-IC-1/hydroparam.h to headers/.
5). Copy $HOME/CHYMERA-CODE-IC-1/Makefile.DEFS to bin/.
6). cd bin
7). make
-> The code fort.7 file is binary, little endian. If you have a big endian machine, before
running the code type
export GFORTRAN_CONVERT_UNIT="little_endian"
for bash.
-> If you are using a compiler other than gcc, adjustments will need to be made.
8). cd ../run
9). ./chymera-omp
10). When finished, you will have files to analyze.
11). cd ../analyze
12). Make sure sigplot and midplot have been compiled.
13). ./midplot 10 11 10 512 64 256 0.159 0.167 0.167 3. 1. ../run/temperat3d. tk_
14). ./sigplot 10 11 10 512 64 256 0.159 0.167 0.167 -18. 8.9e6 ../run/rho3d. sig_
15). python makeimage.py
16). xv png/sig_000010.png
17). Make edits in makeimage.py to analyze temperature next, and look at the tk image
along with time sig image.
* A few notes on image files:
1). rslts.* contain lots of output regarding the simulation. It is in ascii format.
2). gamma1.* contain the adiabatic index. This is only needed for variable gamma sims.
3). coolheat_full.* big file containing output regarding heating terms and optical depths
4). saved.* restart files.
5). massflow.* files tracking mass flow on and off the grid, as well as accretion onto a
central object if used.
6). rho3d.* volume density output
7). temperat3d.* temperature output
8). There are other files. Some are uesful, others are not. I am trying to clean this up.
* Known issues
1). Mind the stack size limits. If the code has an immediate segfault, the stack size might
be too small. Increase using the commands "ulimit" in bash and "limit" in (t)csh.
Contact me if you have questions.