# **The AMUN Code** ## Copyright (C) 2008-2021 Grzegorz Kowal [![Build Status](https://ampere-orbis.nsupdate.info/api/badges/gkowal/amun-code/status.svg)](https://ampere-orbis.nsupdate.info/gkowal/amun-code) 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 so far, * uniform and adaptive mesh generation and update, * a number of time integration methods, from 2nd to 5th order Runge-Kutta methods: Strong Stability Preserving and Embedded (with the error control), * high order reconstructions: from 2nd to 9th order WENO and MP, both explicit and compact methods, the 2nd order TVD interpolation has a number of limiters supported, * 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, * data stored in an internal XML+binary or the HDF5 format, * data integrity of the XML+binary format guaranteed by the XXH64 or XXH3 hashes; * support for Zstandard, LZ4, and LZMA compressions in the XML+binary format, * support for Deflate, SZIP, Zstandard, and ZFP compressions in the HDF5 format, * easy and consistend Python interface to read snapshots in both formats, * MPI parallelization, * completely written in Fortran 2008, * simple Makefile or CMake for building the code executable, * 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 . Developers ========== - Grzegorz Kowal 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. - [NVIDIA HPC](https://developer.nvidia.com/hpc-sdk) compiler version 21.9. Warning: I could not make it run with the included MPI libraries. * Recommended, although optional, [OpenMPI](https://www.open-mpi.org/) for parallel runs, tested with version 1.8 or newer. * Optional [CMake](https://cmake.org) version 3.16 or newer, for advanced compilation option selection. * Optionally, the XML-binary format compression requires: [LZ4 library](https://lz4.github.io), [Zstandard library](http://facebook.github.io/zstd/), or [LZMA library](https://tukaani.org/xz/) [XXHASH library](http://www.xxhash.com/). * 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. * Deflate compression is natively supported in HDF5 libraries, however, optionally these compression formats are supported through filters: [SZIP](https://support.hdfgroup.org/doc_resource/SZIP/) [HDF5Plugin-Zstandard](https://github.com/gkowal/HDF5Plugin-Zstandard), [H5Z-ZFP](https://github.com/LLNL/H5Z-ZFP). Recommended compilation (using CMake) ===================================== 1. Clone the AMUN source code: - from GitLab: `git clone https://gitlab.com/gkowal/amun-code.git` - from Bitbucket: `git clone https://grzegorz_kowal@bitbucket.org/amunteam/amun-code.git`, - or unpack the archive downloaded from page [Downloads](https://bitbucket.org/amunteam/amun-code/downloads/). 2. Create the build directory, e.g. `mkdir amun-build && cd amun-build`. 3. Call `ccmake `, e.g. `ccmake ..`, and press 'c' once. Set available options, if necessary. Press 'c' once again, and 'g' to generate makefiles. 4. Compile the code using `make`. The executable file **amun.x** should be available in a few moments. Alternative compilation (using `make`) =========================================== 1. Clone the AMUN source code: - from GitLab: `git clone https://gitlab.com/gkowal/amun-code.git` - from Bitbucket: `git clone https://grzegorz_kowal@bitbucket.org/amunteam/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 the 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 _, the code will know that parameters have to be read from 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 the new XML+binary snapshot data format. Parameter **snapshot_format** set to either **xml** or **h5** controls which file format is used. In order to read the data produced in this format, you will need to install the Python module AmunPy included in subdirectory **python/amunpy**. Simply go to this 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 to the XML+binary snapshots using `snapshot = AmunXML()` or to the HDF5 files using `snapshot = AmunH5()` and read desired variables using function `var = snapshot.dataset()`. The function **dataset()** returns the requested variable mapped on the uniform mesh as a NumPy array.