amun-code/README.md

# **The AMUN Code**
## Copyright (C) 2008-2020 Grzegorz Kowal

AMUN is a parallel code to perform numerical simulations in fluid approximation
on uniform or non-uniform (adaptive) meshes. The goal in developing this code is
to create a solid framework for simulations with support for number of numerical
methods which can be selected in an easy way through a parameter file. The
following features are already implemented:

* hydrodynamic and magnetohydrodynamic set of equations (HD and MHD),
* both classical and special relativity cases for the above equations,
* Cartesian coordinate system,
* uniform and adaptive mesh generation and update,
* 2nd to 4th order time integration using Strong Stability Preserving
  Runge-Kutta methods,
* 2nd order TVD interpolation with number of limiters and higher order
  reconstructions,
* Riemann solvers of Roe- and HLL-types (HLL, HLLC, and HLLD),
* standard boundary conditions: periodic, open, reflective, hydrostatic, etc.
* turbulence driving using Alvelius or Ornstein–Uhlenbeck methods,
* viscous and resistive source terms,
* support for passive scalars (up to 100),
* data stored in internal XML+binary or HDF5 format,
* support for Zstandard, LZ4, and LZMA compression in XML+binary format,
* Python interface to read snapshots in both formats,
* MPI parallelization,
* completely written in Fortran 2008,
* simple Makefile or CMake for executable building,
* minimum requirements, only Fortran compiler and Python are required to
  prepare, run, and analyze your simulations.

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.


Developers
==========

 - Grzegorz Kowal <grzegorz@amuncode.org>


Requirements
============

* Fortran 2003 compiler, tested compilers include:
    - [GNU Fortran](https://gcc.gnu.org/fortran/) version 4.5 or newer,
    - [PGI Community Edition](https://www.pgroup.com/products/community.htm),
      version 18.10 or newer,
    - [Intel Fortran](https://software.intel.com/en-us/fortran-compilers)
      compiler version 9.0 or newer.
* Optional, but recommended, [OpenMPI](https://www.open-mpi.org/) for parallel
  runs, tested with version 1.8 or newer.
* Optional [HDF5 libraries](https://www.hdfgroup.org/solutions/hdf5/), tested
  with version 1.10 or newer. The code now uses the new XML-binary snapshot
  format. However, if you still want to use older HDF5 snapshot format, you
  will need these libraries.
* Optional [CMake](https://cmake.org) version 3.16 or newer, for managing the
  build process.


Environment Variables
=====================

If you need to use the HDF5 libraries and they are not installed in the default
location, i.e. in the system directory **/usr**, make sure that the environment
variable _HDF5DIR_ is set in your **~/.bashrc** (or **~/.cshrc**) and pointing
to the location where the HDF5 libraries have been installed.


Recommended compilation (using CMake)
=====================================

1. Clone the AMUN source code:
  - from Bitbucket:
    `git clone https://grzegorz_kowal@bitbucket.org/amunteam/amun-code.git`,
  - from GitLab:
    `git clone https://gitlab.com/gkowal/amun-code.git`
  - or unpack the archive downloaded from page
   [Downloads](https://bitbucket.org/amunteam/amun-code/downloads/).
2. Create a directory for compilation in any location,
   e.g. `mkdir cmake-build && cmake-build`.
3. Call `ccmake <path to amun-code>`, e.g. `ccmake ..`, and press 'c' once.
   Configure available options. Press 'c' once again, and 'g' to
   generate makefiles. Alternatively, just call `ccmake <path to amun-code>`
   for default options.
4. Compile the code using `make`. The executable file **amun.x** should be
   created.


Alternative compilation (using `make.conf`)
===========================================

1. Clone the AMUN source code:
  - from Bitbucket:
    `git clone https://grzegorz_kowal@bitbucket.org/amunteam/amun-code.git`,
  - from GitLab:
    `git clone https://gitlab.com/gkowal/amun-code.git`
  - or unpack the archive downloaded from page
   [Downloads](https://bitbucket.org/amunteam/amun-code/downloads/).
2. Go to directory **build/hosts/** and copy file **default** to a new file named
   exactly as your host name, i.e. `cp default $HOSTNAME`.
3. Customize your compiler and compilation options in your new host file.
4. Go up to directory **build/** and copy file **make.default** to **make.config**.
5. Customize compilation time options in **make.config**.
6. Compile sources by typing `make` in directory **build/**. The executable file
   **amun.x** should be created there.


Usage
=====

In order to run some test problems you can simply copy the problem parameter
file from directory **problems/** to the location where you wish to run your
test. Copy the executable file **amun.x** from the **build/** directory compiled
earlier. If you provide option _-i <parameter_file>_, the code will know that
parameters have to be read from file _<parameter_file>_. If you don't provide
this option, the code assumes that the parameters are stored in file
**params.in** in the same director.

In order to run serial version, just type in your terminal:
  `./amun.x -i ./params.in`.

In order to run parallel version (after compiling the code with MPI support),
type in your terminal:
  `mpirun -n N ./amun.x -i ./params.in`,
where N is the number of processors to use.


Reading data
============

By default, the code uses new XML+binary snapshot data format. It can also be
forced by setting parameter **snapshot_format** to **xml**.

In order to read produced data in this format, you will need to install the
provided Python module. Simply change to **python/** directory and run
  `python setup.py install --user`
to install the module in your home directory.

Import the module in your python script using
  `from amunpy import *`,
and then initiate the interface using
  `snapshot = AmunXML(<path to the snapshot directory>)`
and read desired variable using
  `var = snapshot.dataset(<variable>)`.

The function **dataset()** returns rescaled uniform mesh variable as NumPy
array.

If you want to read data from HDF5 snapshot, just use
  `var = amun_dataset(<snapshot HDF5 file>, <variable>)`.