The NDSPMHD Dusty Smoothed Particle Magnetohydrodynamics code

Installing/compiling the NDSPMHD code

System requirements

The basic requirements for compiling and running ndspmhd are simply a reasonably modern Fortran compiler. The instructions below assume a unix-based operating system (e.g., Linux or Mac OS/X). There is no reason in principle why ndspmhd should not run under Windows, but I can offer no support in this regard (likewise for SPLASH).

Getting a Fortran compiler

As NDSPMHD is written in Fortran 90, you will need to have a modern Fortran compiler installed. Options include:

• gfortran, the free Gnu Fortran Compiler, download binary version here.
• ifort, one of the most widely available commercial compilers (and is very good).

Compiling the code

Uncompress the tar file:

tar xvfz ndspmhd-v2.0.tar.gz

and enter the directory

cd ndspmhd

Compile the code by typing "make" whilst specifying the number of spatial dimensions, e.g.

make 1D

which gives the following error

make: WARNING: value of SYSTEM =  not recognised...
=>set the environment variable SYSTEM to one listed
  in the Makefile and try again

I suggest one of the following, based on detected Fortran compilers...

make SYSTEM=gfortran
(end of possible selections)

settings for different SYSTEMs are listed in src/Makefile. Either choose one suggested above or add your own customised setup in src/Makefile. Compile for your chosen system using (e.g.)

make SYSTEM=gfortran 2D

or by setting SYSTEM as an environment variable, e.g. in bash:

export SYSTEM=gfortran;
make 2D

Compiling the code will produce a binary called either 1DSPMHD, 2DSPMHD or 3DSPMHD in the root-level ndspmhd directory.

Running the exercises...

Once the code has compiled successfully, you should proceed to running the examples.

Running the NDSPMHD examples

Preliminaries

After unpacking the tar file:

tar xvfz ndspmhd-examples.tar.gz

and entering the examples directory,

cd ndspmhd-examples/

you will see three subdirectories for hydrodynamical, MHD (both ideal and non-ideal) and dusty-gas tests:

$ ls
DUST/	HYDRO/	MHD/  MHD-NONIDEAL/

For hydrodynamics (in the HYDRO directory), there are 7 tests:

test1-2Drandom-settling/	test3.1-2Dsodshock/		test6-2Dkhinstability/
test2-2Dpairing-instability/	test4-1Drarefaction/		test7-3Dsedov-blast-wave/
test3-1Dsodshock/		test5-1Dblastwave/

Whilst for MHD there are 7:

test1-1.5Dbriowu-shock/		test3-1.5Dtoth-strong-mhdshock/	test5-2Dmhdrotor/		test7-2Dcurrent-loop-advection/
test2-1.75Dmhd-shock/		test4-2.5Dalfvenwave/		test6-2Dorszag-tang-vortex/

and for dust-gas (in the DUST directory) there are 5:

test1_dustybox/		test2_dustywave/	test3_dustyshock/	test4_dustdiffusion/	test5_dustsettle/

These are all standard test problems in the computational astrophysics literature and appropriate references can be found along side these tests in my papers on SPH and SPMHD algorithms. The reference list gives the most useful of these.

Running the tests

It is preferable to go through the examples in the order given. For each test there is a README-blah.txt file in the subdirectory describing how to run the code step-by-step, so things are fairly self-explanatory.

For example, entering the first test directory

cd test1-2Drandom-settling/

you will find the following files:

$ ls
Makefile		random.in		rpsph.in		splash.limits
README-settling.txt	randomav.in		splash.defaults

...so simply follow the instructions in the README-settling.txt file...

$ more README-settling.txt
This is a test showing how a random particle distribution will relax to an
ordered arrangement because of the Hamiltonian nature of SPH.

Type "make clean" and "make" to re-compile the 2DSPMHD binary.

Run the code using ./2DSPMHD random.in
Or with output to a file: ./2DSPMHD random.in >& random.out &

Plot the results using "nsplash random_0*.dat"
...

Note that you will need to have SPLASH installed to view the code output.

Next steps...

After running a few of the examples, you will have a rough idea of how the code works and what the important input options are. From there you can proceed to explore the tests further or continue towards setting up your own problem...

Running your own setups

Creating a new run directory

Compiling the code will produce a binary called either 1DSPMHD, 2DSPMHD or 3DSPMHD in the root-level ndspmhd directory. The procedure I use for starting a calculation is generally as follows:

Create a new directory and enter it:

mkdir test-run
cd test-run

Use the script in the ndspmhd/scripts directory to write a local Makefile:

~/where-I-put-it/ndspmhd/scripts/writemake.sh 1D > Makefile

then, after setting the location of the code via the NDSPMHD_DIR environment variable (best to set this permanently by putting it in your .bash_profile or equivalent)

export NDSPMHD_DIR=~/where-I-put-it/ndspmhd

Now you can simply type

make

which should compile the code and copy the binary to the current directory. A directory listing shows the binary and the local Makefile:

$ ls
1DSPMHD*	Makefile

Creating an input file

Create an input file with default options by running the code with the name of an input file as the argument:

$ ./1DSPMHD test.in
 number of runs =  1
 run =  1  runname = test.in
 input file test.in              not found
  would you like to create one with default options?
y
 input file test.in              created successfully
STOP exiting...

Editing the particle setup / initial conditions

When run with an input file as the argument, the code runs from scratch with the particle setup specified by the SETUP1D, SETUP2D or SETUP3D variable in src/Makefile. To edit the currently compiled setup, use

make edit

which will load the relevant file into your favourite editor (requires setting the EDITOR environment variable to be your favourite text editor). Alternatively you can make a new setup_blah.f90 file and specify this using SETUP1D=setup_blah.f90 in the Makefile. Then

make

to rebuild the code in the local directory with the edited file.

You can also specify the setup in the local Makefile by giving an extra argument to the writemake script, i.e.,

~/where-I-put-it/ndspmhd/scripts/writemake.sh 1D setup_blah.f90 > Makefile

Then when you type "make" the code will always build using setup_blah.f90 as the initial conditions. This is how the Makefiles in the examples directories have been written.

Running parameter sweeps

With more than one input file on the command line, e.g.

./1DSPMHD test1.in test2.in test3.in

the code will run each test concurrently (provided the previous test finishes normally). This is a convenient way of performing parameter sweeps (in serial) without any scripting.

Restarting the code

It is possible to restart the code from the position of any binary dump file by simply giving the name of the file instead of the input file on the command line, e.g.

./1DSPMHD test_00020.dat

which will look for input options in a file called test.in.

Papers describing algorithms in NDSPMHD

See the main NDSPMHD page for details about the code.

Reference list