amun-code/README.md
Grzegorz Kowal a1b47ab1e1 README: Update features and add CMake compilation steps.
Signed-off-by: Grzegorz Kowal <grzegorz@amuncode.org>
2020-08-13 16:35:39 -03:00

162 lines
6.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# **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 OrnsteinUhlenbeck 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>)`.