Mara: astrophysics gas and plasma dynamics code
===============================================

Author: Jonathan Zrake

New York University (2009 - 2013)
Stanford University (2013 - 2017)
Columbia University (2017 - present)




What is Mara?
-----------------------------------------------

Mara is a multidimensional Godunov-type code that solves the equations of
compressible gasdynamics and magnetohydrodynamics (MHD).




Checking out
-----------------------------------------------

Copy and paste the following commands into a terminal window:

git clone --recursive https://github.com/jzrake/Mara2 Mara
cd Mara
touch Makefile.in
cd Cow
ln -s ../Makefile.in .
./configure
cd ..




Building
-----------------------------------------------

1. Make sure you have a working installation of MPI and HDF5.

2. Open the file called Makefile.in, in the Mara root directory, and copy the
following lines into it:

    CXX = mpicxx
    H5I = -I/usr/include
    H5L = -L/usr/lib -lhdf5

3. Modify these values to indicate your HDF5 installation directory, and name
of your MPI C++ compiler. Provide the full path of the executable if it's not
in your system PATH or your system has more than one.

4. Type make.




Basic usage
-----------------------------------------------

mara command [key=val] [key=val]

The first argument `command` is the name of a sub-program, which runs a
particular solver and physics configuration. Most of the sub-program source
code can be found in the src/Problems directory. To see a list of available
commands type `mara` without any arguments.

The list of key-value pairs on the command line will be passed to the sub-
problem as parameters. Don't use dashes before them.




Code base
-----------------------------------------------

# Overview

Mara's source code is written in C++, with some limited usage of C++11
features: lambda functions, auto keyword, std::shared_ptr, and move semantics.
The root directory contains source files that provide physics solvers and the
application logic. These classes depend on lower-level facilities provided in
the Cow (stands for "cube of wonder") library. Cow contains physics agnostic
classes for things like multidimensional arrays, data formats (HDF5, VTK), and
distributed memory parallelism (through a thin MPI wrapper). Having this layer
helps in the "separation of concerns"; physics solvers delegate menial tasks
like array allocation and interprocess communication to facilities in the Cow
namespace, which keeps the solver code clean and expressive.


# Standards and style

Mara uses a very consistent (though maybe idiosyncratic) coding standard
throughout the code base. I have adopted it from the JUCE toolkit, which I
believe is exemplary when it comes to quality of C++ code development. The
coding standards I use are outlined here:

https://www.juce.com/learn/coding-standards

You may find some of these annoying or superficial, but if you are contributing
code, at least please make an effort to conform to them.


# Git commits

For git commits, please try to format your commit messages like the following
(without the leading spaces of course):

    Fix typo in the README file

    This commit also adds some links to potentially relevant URL's.
    All tests are passing.

First word is a present tense verb, is capitalized, there is no period at the
end, and the whole first line should be less than 50 characters. More detail
should follow on a paragraph below, separated by a newline. Good git
conventions and their rationale are outlined here:

https://chris.beams.io/posts/git-commit




Data visualization
-----------------------------------------------

Mara provides output data in HDF5 and VTK formats. ParaView is recommended for
2D and 3D visualization tasks.

Notes:
- To use Python "programmable source" code in ParaView, the h5py module must
  be available to ParaView. One way to do this is to copy your h5py
  installation directory to the Python directory used by ParaView. For exmaple,
  on OSX, run

  cp -r ~/Your/h5py-2.x/lib/python2.7/site-packages/h5py /Applications/ParaView.app/Contents/Python

- More to come...