The MPI - Adaptive Mesh Refinement - Versatile Advection Code (development version)
Adding a physics module to MPI-AMRVAC

This document explains how you can add a new physics module to MPI-AMRVAC.

Where to place files, and which makefiles to edit

MPI-AMRVAC is organized in a library, which in essence only differs according to the dimensionality of the problem: the library part of the code will be compiled in the


directory, if you indicated the setup to be 2D, and used the default architecture settings, i.e. when your problem used $AMRVAC_DIR/ -d=2. What is contained in this library version is controlled by the makefile called


and this file controls which physics modules are contained in the library. To add a new physics module called 'myphys', add myphys to the line SRC_DIRS := ...:

SRC_DIRS := . modules amrvacio physics rho hd mhd particle nonlinear myphys

The files for your physics module should then be placed in a newly created subdirectory


You can put all the required routines in a single file called mod_myphys.t, or use multiple files, for example like this:

  1. mod_myphys.t: Top level module, which will include the other modules of 'myphys'
  2. mod_myphys_phys.t: Contains the basic data and routines for your physics (which variables are required, how to compute fluxes, etc.)
  3. mod_myphys_roe.t: Contains methods for the Roe solver
  4. makefile: A makefile which lists the relevant source files

It is probably best to look at existing physics modules to see which routines are required. The makefile will specify which extra Fortran files the subdirectory contains, and hence would read

FOBJECTS += mod_myphys_phys.t mod_myphys.t mod_myphys_roe.t

It is important to correspondingly update the module dependencies in the makefile found at


You can either do this by hand, but a typo-proof manner to do so is to run the script


This produces a dependency list, which is intended to replace the part in


which follows the line mentioning

Dependencies of FOBJECTS (generated by

Hence, you first edit the $AMRVAC_DIR/src/makefile, delete all lines below this line, and then execute in $AMRVAC_DIR/src the command >> makefile

Note: the actual makefile you use for a specific application is in general composed of parts collected from

  1. $AMRVAC_DIR/src/makefile
  2. $AMRVAC_DIR/arch/amrvac.make
  3. $AMRVAC_DIR/arch/lib.make
  4. $AMRVAC_DIR/arch/default.defs [overruled by $AMRVAC_DIR/ -arch=debug which uses debug.defs instead]
  5. $AMRVAC_DIR/arch/rules.make

Physics module bare essentials

The file


must specify the way to activate your physics module. At the very least, it will tell the code to use the corresponding


which contains info on initialization of the variables, controls the addition of new parameters and corresponding entries in the namelists. This is done by subroutine myphys_phys_init().

Furthermore, mod_myphys_phys.t provides all info on fluxes, (geometric) source terms, etc. See especially the examples provided by


Adding scheme-specific info, source terms, etc

It is possible to use basic schemes like TVDLF or HLL as soon as the


contains the corresponding subroutines to identify the maximal and minimal characteristic wave speeds, the fluxes, and the (geometric) source terms. You are also required to specify the way to convert conservative to primitive variables, and back [if relevant for your module]. It is imperative that you use the LASY syntax to ensure that your physics module can be compiled meaningfully in any dimensionality.

Schemes like HLLC, Roe, etc, which require more info on the characteristic decomposition can be added as well, following the examples provided for rho, hd, mhd modules. The same is true for source terms. The roe solver needs to be organized in the file