Anmhd (short for anelastic magnetohydrodynamic solver) solves the
three-dimensional system of magnetohydrodynamic equations in the anelastic
approximation using a streamfunction formalism.  The system is solved on
a uniform Cartesian mesh.  For a description of the numerical techniques,
and the anelastic formalism in general, see 

* Fan Y., Zweibel, E. G., Linton, M. G., & Fisher, G. H., 1999, ApJ, 521, 460  
* Abbett, W. P., Fisher, G. H., & Fan, Y., 2001, ApJ, 546, 1194 

and references therein.

Anmhd-1.0.2 can be downloaded from 
http://solarmuri.ssl.berkeley.edu/public/software/Anmhd/

--------------------
Contact information:
--------------------
Dave Bercik <bercik@ssl.berkeley.edu>
Bill Abbett <abbett@ssl.berkeley.edu>

------------------------------------
To install the Anmhd-1.0.2 software:
------------------------------------

1)  Unpack the compressed tarball in the directory where you want it to reside.

    tar -zxvf Anmhd-1.0.2.tar.gz

2)  The software will be installed under the directory Anmhd-1.0.2.  In the 
    Anmhd-1.0.2 directory there are five subdirectories:  
      prog      - the main source directory 
      run       - the main run directory
      init      - the initial state source directory 
      initrun   - the initial state run directory
      idl       - a directory with some example IDL I/O procedures
      utilities - unformatted fortran to sdf conversion tools

3)  There are a few external code dependencies. First, an external FFT program
    must be linked in when compiling.  A few common routines on different 
    platforms can be set with pre-processor directives as described below. 

    A second external dependency is that lapack and blas packages must be 
    linked in when compiling.  Many platforms have these packages available in 
    a standard install, but optimized vendor versions can be used as well.

    If you wish to use "Simple Data Format" (SDF) for the binary file i/o 
    for anmhd, then this package must be linked in when compiling as well.  
    If not, the code will use unformatted fortran for binary i/o.  SDF files
    have the advantage of being platform independent, so that they can be
    easily moved to other systems for further analysis.  Fortran unformatted
    files differ between compilers and platforms and can be endian-dependent,
    but on the other hand, fortran unformatted file i/o is probably faster.  
    The SDF source code and installation instructions can be obtained from:
    http://solarmuri.ssl.berkeley.edu/~fisher/public/software/SDF .  
    Get version 0.74 (or more recent).

    Pre-processor flags:
    -------------------

    CRAY - use scfft2d/csfft2d for FFT, use shared-memory multitasking

    FFTW2 - support for FFTW2 libraries (not compatible with CRAY, IBM, SGI)

    FFTW3 - support for FFTW3 libraries (not compatible with CRAY, IBM, SGI)
 
    IBM - use drcft2/dcrft2 for FFT
   
    INTEL - set for x86 and x86-64 platforms

    OPENMP - support for OpenMP parallel libraries (not compatible with 
             CRAY, IBM, INTEL)
    PPIV - use LAPACK genral banded matrix solver with partial pivoting
           instead of default pentadiagonal matrix solver

    SGI - use dzfft2du/zdfft2du for FFT

    SINGLE - set for systems where default precision is double precision
             (not compatible with CRAY)

    SDF - use sdf format for binary file i/o instead of unf. fortran i/o

-------------------
To use Anmhd-1.0.2:
-------------------

1)  First, you need to make an initial state, which needs to be named 
    fatmos.dat (or fatmos.sdf if using SDF).  There are some example 
    initialization routines in the init directory.  You should modify one of 
    the examples to suit your needs.  Make sure that your file is 
    symbolically linked to the file init.F.  The example initialization 
    routines are as follows:


    init_scratch_hd.F - a purely hydrodynamic starting state with random
                        entropy fluctuations

    init_rfatmos.F - generates a fresh starting state from a restart Fourier-
                     variables data file

    init_rfatmos_addB.F - generates a fresh starting state from a restart 
                          Fourier-variables data file and adds random magnetic 
                          field fluctuations

    init_rpatmos.F - generates a fresh starting state from a physical-variables
                     data file

2)  Edit the files paramt.h and paramz.h in the include subdirectory to 
    indicate the desired grid size for the simulation.  Note that n1=nx, 
    n2=ny and n3=nz

3)  Edit the appropriate makefile for your architecture in the makefiles 
    subdirectory.  Make sure that the C pre-processor definition CPP
    is consistent with its location on your system.
    Make sure you have set pre-processor flags for any of the
    desired software libraries, as noted above.  This is done by editing
    the CPPFLAGS variable in the Makefile, using -D<option>, 
    where <option> can be e.g. FFTW3, INTEL, SDF, etc.  Then, make sure
    that the variables LIBFFT, LIBLIN, and LIBMISC contains all the necessary 
    information about where each desired library is installed and the name 
    of the library to be linked so that the compiler can find the libraries.  

    Then, Link this file to Makefile in the init directory.  
    To compile just type

    make init.x

4)  To create the binary file fatmos.dat (or fatmos.sdf file if you are using 
    SDF), change directories to initrun.  If you are 
    creating a fresh state from an existing data file (Fourier or physical), 
    link the existing data file to rstrt.dat (rstrt.sdf if using SDF).  
    The init.x from the init directory should be pre-linked here 
    (if it is not, link it) Now run the initialization routine by typing

    ./init.x

5)  Copy or link fatmos.dat (or fatmos.sdf) to the run directory.

6)  Once you have an initial state, you can compile the main procedure.  
    Change to the prog directory.  As was done in the init directory, modify 
    the proper makefile in the makefiles directory and link it to Makefile in 
    the prog directory.  Compile the program by typing  

    make anmhd.x

7)  Change to the run directory.  The executable anmhd.x sould be pre-linked 
    here from the prog directory (if not, link it).  Make sure that there is 
    an fatmos.dat (or fatmos.sdf) file present if starting a new run, or 
    a "_rstrt.dat" (or "_rstrt.sdf") file if you are continuing a run.

8)  Edit the param.dat file and enter appropriate values.  See the file for
    an explanation of the input parameters.  Note that the first uncommented 
    line is the title of your run and will be used as the root string for your
    data files.  For example, if you input "my_run" you will get data files
    such as "my_run_pvar_0001.dat" (or "my_run_pvar_0001.sdf") and 
    "my_run_rstrt.dat" (or "my_run_rstrt.sdf").  

9)   Run the program by typing

    ./anmhd.x

10)  Besides the physical variable and Fourier variable restart data files, 
     there are a number of other output text files generated by anmhd.x.  These
     are briefly described below.

     energies.dat - text output file containing domain-integrated energies 
  
     joblog.dat - text file that gives a run termination message, 
                  either "normal end" or an error message

     out.dat - text file with extra debugging output some of which is 
               not found in other data

     tstep.dat - text file with timestep data

11)  If you use IDL to analyze or display your output data, a number of 
     sample procedures are in the idl directory which extract arrays from 
     the output files.  For example, rdpvar_uf.pro will read and extract
     variables in physical space from the _pvar_nnnn.dat files, and 
     rd_rstrt_uf.pro will read Fourier data from the restart files.  If SDF
     is being used, the procedure rddata_sdf.pro can be used to read data from
     any of the binary output files, such as the _pvar_nnnn.sdf files or 
     the _rstrt.sdf file, the fatmos.sdf file, or _fvar_nnnn.sdf file.
     These IDL procedures are self-documenting, in that typing the name of
     the procedure will return its expected calling sequence.

12)  In the util subdirectory is the source code for a utility
     that provides some low-level diagnostics for the unformatted fortran i/o
     files (f77udiag), and utilities that convert the binary files 
     between unformatted fortran and sdf formats.  The utilities pvuf2sdf
     and pvsdf2uf convert _pvar files between unformatted fortran and sdf
     formats, and the utilities rsuf2sdf and rssdf2uf convert _rstrt, fatmos,
     and _fvar files back and forth between unformatted fortran and sdf file
     formats.  All of these utilities require the SDF library to be installed.
     The executables take their input from the command-line and
     the command-line arguments can be found by just typing the names of
     the diagnostics.  To compile these diagnostics, change into the util
     directory, edit Makefile to make sure the choice of compilers will work
     on your system, and then type "make".  The fortran compiler needed to
     compile pvuf2sdf, pvsdf2uf, rsuf2sdf, and rssdf2uf must be able to
     compile fortran 90 source code, and preferably should be the same
     compiler used to compile Anmhd itself, or at least use a compatible
     version of unformatted fortran i/o.