Friday, September 18, 2009

Athena Magnetohydrodynamics (MHD) Code

Some of you (one of you) requested a little more information about the hydrodynamics code that I mentioned in a previous post. The code written in C is called Athena after the Greek goddess. The best basic overview of the code comes from the authors themselves:

"Athena is a grid-based code for astrophysical gas dynamics, based on higher-order Godunov methods, with nested and adaptive mesh capabilities. The original development efforts were supported by the NSF Information Technology Research (ITR) program. As part of the project, Athena will be made freely available to the astrophysics community, along with complete documentation and web-based training material.

The current version of the code (v3.1) implements algorithms for:

  • compressible hydrodynamics and ideal MHD in one-, two-, or three-spatial dimensions,
  • ideal gas equation of state with arbitrary γ (including γ = 1, an isothermal EOS).
  • first-, second- or third-order characteristic interpolation in the primitive variables,
  • numerical fluxes computed using a variety of approximate and/or linearized Riemann solvers,
  • source terms due to a static gravitational potential,
  • self-gravity computed using FFTs,
  • an arbitrary number of passive scalars advected with the flow,
  • parallelization using domain decomposition with MPI.
The code is being developed by Jim Stone (Princeton University), Tom Gardiner (Cray Research), Peter Teuben (University of Maryland), and John Hawley (University of Virginia). Code development began in 2000, and is on-going.

The primary motivations for developing Athena are to (1) adapt higher-order Godunov schemes for astrophysical MHD, (2) use a single-step Eulerian update so the solver can be used with adaptive mesh refinement, (3) optimize and parallelize the implementation on modern, distributed memory processors, and (4) distribute the code to the astrophysics community with documentation and web-based training tools. The first three motivations are driven by our own research needs, the last is done in the hope the community will find the resulting code useful for their own research."

So that is how the authors of the code describe the it and now onto my opinion of the code. I found it very easy to pick up and learn how to use. For those who download the code it comes with several preworked examples that demonstrate different aspects of the code. The examples include several standard test problems (spherical blast wave, linear waves and others with more obscure names, usually after the people who first published a paper on that problem). The code comes with a user's guide which contains most of what is needed to get the code up and running. I think that it took me less than a week from when I downloaded the code to when I got the first examples running. Keep in mind that I had also just bought a laptop two days before I downloaded the code and I was in the process of making a Linux partition and making sure that I also had all of the necessary libraries and compilers necessary to run the code. So I was not just dealing with getting the code up and running but also getting my computer up and running for that first week. After that it was a matter of working through some of the examples, changing the inputs and figuring out how it all worked.

On a basic level the code is very simple to run. It only takes three commands to make it run and in some cases it only takes one. For example if I wanted to run my particular problem that I wrote, which I named Starburst, from the command line I would type:

configure --with-problem=starburst --with-gas=hydro

make all

./athena -i ../tst/2D-hydro/starburst.c

The first line sets up the problem and in general has the form: "configure [--enable-feature] [--disable-feature] [--with-package=choice]". The second compiles the code (and does a few more things). The last line actually runs the code and calls the input file "starburst.c". The individual problem files include all of the code needed to make the initial conditions (density, pressure etc.) as well as functions to include a gravitational potential, and functions to update certain cells every cycle (to be used, for example, to inject matter and energy into the center of a galaxy), along with several more useful functions designed for other specific purposes to control output etc.

The code is very versatile and can run on many processors (or just one like my laptop). The individual features available which are used with the configure command are given in the user's manual (snapshot shown below, the bold options are the defaults, click to see a larger and easier to read version):

As you may notice it includes an MHD option which is what makes Athena so powerful, and well known. Most people I have talked to about Athena view it a primarily an MHD code though it is also used for normal hydro stuff. Right now I am using it as a hydro code, but the plan is to eventually use it with MHD.

So overall the code is very easy to learn how to use and to get working. It is another matter (haha) to make it do something different, new and useful (preferably all three), and above all publishable. I would recommend using this code if you are looking into using a standard, ready to run out of the box code for hydrodynamics or MHD. I will now take questions.


  1. Ryan, that code sounds interesting. I wonder if it is related to the MHD code I used at Los Alamos: Zeus-MP.

    I just find it interesting they are both MHD codes and Athena is the daughter of Zeus. (I wonder if there is a parent/offspring aspect to these two MHD codes.)

  2. "The code is being developed by... and John Hawley (University of Virginia)."

    That is too funny given what I said about Zeus-MP.

    I met John Hawley when he visited Los Amalmos. He wanted to speak to Dan Whalen and myself, since we were doing stuff that interested him, and one of the only things I remember about the meeting was he went on about how the maintainer of the Zeus-MP code has made horrible decisions and comes across as if he thinks he's God.

    Oh yeah, we had dinner with him too. He was nice, just criticized Zeus-MP.

  3. That makes me think that I want to try to do a simulation of my system on a computer, but not on my own.

  4. But may be I will need a new code, as a name it could be something like "Energize the World".

  5. Ryan,

    Just a couple of technical questions. Does Athena have any explicit diffusion? If not, I would assume it is designed for low density environments. Also, how does Athena enforce div(B) = 0? Finally, what kind of problems have been done with Athena?

  6. To Joseph : "Los Alamos" it makes me think about the book : "Chaos" by James Gleick.


To add a link to text:
<a href="URL">Text</a>