User Tools

Site Tools


Ramses Hands-On Session

In this tutorial, we explore the Kevin-Helmholtz instability with the CFD code Ramses. To get going, you can either download a prepared virtual machine, or install Ramses yourself. After you've done either, proceed to Test Driving Ramses.


You can either (i) download a virtual machine (VM) image that comes preloaded with all necessities, or (ii) install Ramses, Pymses, the post-processing scripts, and all dependencies from scratch. Unless you know what you're doing, we suggest you go with the VM.

Download VirtualBox, Virtual Machine Image

For this exercise, we have prepared a virtual machine image in which you can run Ramses and the post-processing scripts. To make this work, you will need to download

  1. Oracle VirtualBox (
  2. The virtual machine image ( :!: 2.3GB

Download VirtualBox for the platform you're running (Windows/OSX/Linux) and install it. Then download the virtual machine image provided. Launch VirtualBox, click File, then Import Appliance. Then click “Open Appliance”, navigate to the file you downloaded, hit Open, then Continue, and finally Import.

Select the virtual machine KM Ramses in the left pane, and click Start in the menu bar. This will launch you into a Linux session. Click the Terminal icon on the Desktop to get going.

:!: If you run an older version of OSX (10.6 or 10.7), you may need to download VirtualBox 4.1 instead of the current 4.2 release. You can get it via

Set Up Ramses Yourself

Hereafter, we will use the paths/directories as in the virtual machine image provided.

For Ramses, you will need a Fortran compiler such as GFortran. If you want to run Ramses on >1 core, you will need an MPI stack such as OpenMPI. For post-processing, there are many options. We suggest you use the excellent Pymses stack, which provides both a GUI viewer for the data as well as access to the data structures in a nice Pythonic way. To generate and play back videos from output images, you should get mencoder and mplayer. We also need git to download some additonal scripts.

Assuming you're running a Debian based Linux (such as Debian, Ubuntu or Mint), the following package manager invocation should download and install all the dependencies you will need.

$ apt-get install build-essential gfortran openmpi-dev openmpi-bin ipython python-numpy python-scipy python-matplotlib python-tables python-wxgtk2.8 mplayer mencoder git

To install Pymses, do

$ cd ~/Source
$ tar xfvz pymses_3.1.0.tar.gz
$ cd pymses_3.1.0
$ make

You will also need to install some further post-processing scripts, i.e.

$ cd ~/Source
$ git clone

To add the Pymses libraries, the Pymses viewer binary, and the additional scripts to your paths, do

$ cd ~
$ vim .bash_aliases

export PATH=~/Source/pymses_3.1.0/bin:$PATH
export PYTHONPATH=~/Source/pymses_3.1.0:$PYTHONPATH
export PYTHONPATH=~/Source/km2013-handson-post:$PYTHONPATH

You may need to log out and back in again.

To download and install Ramses, do

$ cd ~/Source
$ wget
$ tar xfvz ramses.tar.gz

To prepare the installation directory, do

$ cd ~
$ mkdir Simulations

Test Driving Ramses

Firstly, we will compile Ramses with a custom patch that sets the initial conditions for the Kevin-Helmholtz instability. Type the following

$ cd ~/Source/ramses
$ cd bin
$ vim Makefile

The default Makefile is fine, EXCEPT that you need to find and change the following lines to

NDIM = 2
PATCH = ../patch/insta

Now compile Ramses by typing

$ make

:!: DO NOT be tempted to do something like make -j2 even if you have >1 core available. This might cause different modules to be compiled out of order, causing the compilation to fail.

Now create a new directory at a location of your choice. Here, we will store raw and post-processed simulation outputs. Once done, let's run Ramses!

$ cd ~/Simulations
$ ~/Source/ramses/bin/ramses2d ~/Source/ramses/patch/insta/kh.nml

This will launch Ramses and you should see something like

_/_/_/       _/_/     _/    _/    _/_/_/   _/_/_/_/    _/_/_/  
 _/    _/    _/  _/    _/_/_/_/   _/    _/  _/         _/    _/ 
 _/    _/   _/    _/   _/ _/ _/   _/        _/         _/       
 _/_/_/     _/_/_/_/   _/    _/     _/_/    _/_/_/       _/_/   
 _/    _/   _/    _/   _/    _/         _/  _/               _/ 
 _/    _/   _/    _/   _/    _/   _/    _/  _/         _/    _/ 
 _/    _/   _/    _/   _/    _/    _/_/_/   _/_/_/_/    _/_/_/  
                         Version 3.0                            
        written by Romain Teyssier (CEA/DSM/IRFU/SAP)           
                      (c) CEA 1999-2007                         
 Working with nproc =    1 for ndim = 2
 Building initial AMR grid
 Initial mesh structure
 Level  1 has          1 grids (       1,       1,       1,)
 Level  2 has          4 grids (       4,       4,       4,)
 Level  3 has         16 grids (      16,      16,      16,)
 Level  4 has         64 grids (      64,      64,      64,)
 Level  5 has        128 grids (     128,     128,     128,)
 Level  6 has        256 grids (     256,     256,     256,)
 Level  7 has        512 grids (     512,     512,     512,)
 Level  8 has       1024 grids (    1024,    1024,    1024,)
 Level  9 has       1536 grids (    1536,    1536,    1536,)
 Level 10 has       2048 grids (    2048,    2048,    2048,)
 Starting time integration
 Fine step=     0 t= 0.00000E+00 dt= 9.103E-05 a= 1.000E+00 mem= 7.0% 
 Mesh structure
 Level  1 has          1 grids (       1,       1,       1,)
 Level  2 has          4 grids (       4,       4,       4,)
 Level  3 has         16 grids (      16,      16,      16,)
 Level  4 has         64 grids (      64,      64,      64,)
 Level  5 has        128 grids (     128,     128,     128,)
 Level  6 has        256 grids (     256,     256,     256,)
 Level  7 has        512 grids (     512,     512,     512,)
 Level  8 has       1024 grids (    1024,    1024,    1024,)
 Level  9 has       2048 grids (    2048,    2048,    2048,)
 Level 10 has       3072 grids (    3072,    3072,    3072,)
 Main step=     1 mcons= 0.00E+00 econs= 0.00E+00 epot= 0.00E+00 ekin= 2.58E+01
 Fine step=     1 t= 9.10290E-05 dt= 9.105E-05 a= 1.000E+00 mem= 8.9% 

Wait something like 30 seconds, then hit CTRL+C to cancel the job. Check what files we have in the directory, i.e. do

$ ls -lisa

which should reveal something like

3329   0 drwxr-xr-x 1 volker volker    204 May 22 10:51 output_00001
3330   0 drwxr-xr-x 1 volker volker    204 May 22 10:51 output_00002
3331   0 drwxr-xr-x 1 volker volker    204 May 22 10:51 output_00003

In this example, we have generated 3 output directories. You may have more or less at this stage. Inside the directories (take a look if you want) you can find some Fortran binary files (these are the raw simulation data) and some text files (these are header files). Since the simulation employs a complicated data structure, we need to use Pymses and some additional scripts to extract meaningful data from them. If you type

$ python ~/Source/km2013-handson-post/ 1 1 --show

Pymses will read the first output, extract the density, and {x,y}-velocity, compute the vorticity, average the vorticity along Y, and then show plots thereof.

Actual Simulation

We now want to run the simulation much longer than in the previous example (where you cancelled the job after 30 seconds). Depending on the power of you machine, this can take a while (10-25 minutes). Before launching the job, we need to edit the namelist file of the simulation, where relevant simulation parameters (how long to run job, how much memory to allocate, how big a box to simulate, etc) are set.

Open to file in an editor as

$ vim ~/Source/ramses/patch/insta/kh.nml

Have a look a the file and maybe take a look at the Ramses manual (~/Source/ramses/doc/ramses_ug.pdf) to see what some of the parameters do. Either way, then locate the lines containing tout=1.0 and ngridmax=20000 and change them to


This prevents Ramses from allocating too little memory for the duration of run we're aiming at.

Now, navigate back to your simulation directory, and relaunch Ramses with

$ cd ~/Simulations
$ ~/Source/ramses/bin/ramses2d ~/Source/ramses/patch/insta/kh.nml

and get some coffee. This will take somewhere between 10 and 25 minutes, depending on your processing power.

While the code is running, open a new terminal and take a look in the file that sets the initial conditions for the simulation to see how exactly we set up the flow.

$ cd ~/Source/ramses/patch/insta
$ vim condinit.f90

Post-Processing, Exercise Sheet

Once the simulation is done, again type

$ ls -lisa

you should see a large number of output directories (56).

We now wish to generate a video of how density, {x,y}-velocity, and vorticity evolve during the simulation run. To post-process all outputs, and save images of them, type

$ python ~/Source/km2013-handson-post/ 1 56 --save

This will generate 5 * 56 files of the form


You can now use mencoder to generate videos, i.e.

$ mencoder mf://Density*.png -mf w=800:h=600:fps=5:type=png -ovc lavc -lavcopts vcodec=mpeg4:mbd=2:trell -oac copy -o Density.avi
$ mencoder mf://X-Velocity*.png -mf w=800:h=600:fps=5:type=png -ovc lavc -lavcopts vcodec=mpeg4:mbd=2:trell -oac copy -o X-Velocity.avi
$ mencoder mf://Y-Velocity*.png -mf w=800:h=600:fps=5:type=png -ovc lavc -lavcopts vcodec=mpeg4:mbd=2:trell -oac copy -o Y-Velocity.avi
$ mencoder mf://Vorticity*.png -mf w=800:h=600:fps=5:type=png -ovc lavc -lavcopts vcodec=mpeg4:mbd=2:trell -oac copy -o Vorticity.avi
$ mencoder mf://Y-Vorticity*.png -mf w=800:h=600:fps=5:type=png -ovc lavc -lavcopts vcodec=mpeg4:mbd=2:trell -oac copy -o Y-Vorticity.avi

and watch them with

$ mplayer Density.avi
$ mplayer X-Velocity.avi
$ mplayer Y-Velocity.avi
$ mplayer Vorticity.avi
$ mplayer Y-Vorticity.avi

Now take a look at the exercise sheet for some questions.

ramses.txt · Last modified: 2013/07/10 07:02 (external edit)