rdramses

Description of the code

rdramses is used to extract information from an output of the RAMSES code by Romain Teyssier. It is based on Romain's amr2map and part2map that you can find in the utils/f90 directory of the RAMSES package. The purpose of rdramses is to provide a fast yet efficient way of extracting data about hydrodynamics, gravity and particles. Some basic computations are included in the code, but most of the scientific analysis must be done in additional steps.

Dimensions and units: The code has been designed to work with hydrodynamical 3D simulations of galaxies (i.e. no cosmo). It does not work for 1D or 2D runs. The units (input and/or output) can be changed to better fit your needs by modifying the source code of rdramses (search "scale_" in rdramses.f90).

Disclaimer: rdramses is a 'live' code which I constantly modify according to my day-to-day science needs. Feel free to modify it to fit your own purposes but in any case,use the code at your own risks!

Download

Download the source (.f90) from GitHub.

Optional Makefile and a namelist template (with all options commented out) are also available, for convenience.

Optional libraries:
cfitsio (to generate FITS output. Optional but highly recommended!)
FFTW (to compute the PSD)
MPI libraries (to split the volume of analysis. Check the MPI implementation on your supercomputer)

rdramses general syntax

(Text in green is example values.)

rdramses syntax always contains the input directory, which is an output directory from RAMSES. rdramses -inp output_00001

All others parameters/keywords listed below are optionals

On top of this, choose one (only one at a time) of the modes [hydro | random | gravity | pdf | psd | fits | part | id | sfr] to get the data.

All the options of rdramses (except the input directory and the MPI commands) can be set using a namelist and setting the nml option: rdramses -inp output_00001 -nml namelist This is useful when repeating the same treatment (e.g. on several snapshots). If options are added to the command line, they overwrite their equivalent in the namelist.

All files produced by rdramses starts with rdr_ followed by the snapshot number, and some keywords about the options used. You can add a suffix to the filenames generated with the option -out foo In any case, the filenames end with the "extension" (.hydro, .rand, .grav, .q, .fits, .part, .partid or .sfr). All files, excepts fits, are in ascii format.

Volume selection

By default, the full computational domain is considered. To select a smaller volume within your simulation cube, you can use one of the following syntaxes:

Parallelepiped. The limit are defined in term of fraction of boxlen with 0,0,0 being the corner of the box. -xmin 0.1 -xmax 0.9 -ymin 0.1 -ymax 0.9 -zmin 0.4 -zmax 0.5

Parallelepiped. The limit are defined in kpc, with 0,0,0 being the center of the box. -kpc -xmin -10 -xmax 10 -ymin -10 -ymax 10 -zmin -2 -zmax 2

Cube of 10 kpc centered on 2 kpc, 3 kpc, 4 kpc from the center of the box. -cube 10 -xcen 2 -ycen 3 -zcen 4

Parallelepiped of 10 kpc * 20 kpc * 30 kpc centered on 2 kpc, 3 kpc, 4 kpc from the center of the box. -d 10 20 30 -xcen 2 -ycen 3 -zcen 4 To use option -d in a namelist, define cubex, cubey and cubez for the 3 sizes.

Grid data (hydro or gravity)

For all grid data, you can choose the maximum (finest) AMR level to consider: -lmax 15

Then, choose one of the following modes.

Hydro mode

Ouput an ascii file with one line per leaf cell in the selection (format = x, y, z, vx, vy, vz, rho, level, mass, temperature. In kpc, km/s, cm-3, Msun and K) -hydro

Select only cells with density between 0.1 and 100 cm-3. -rhomin 0.1 -rhomax 100

Center the coordinates on the center of the selection -cen

Random mode

Replace each leaf cell with randomly positioned particles of 0.1 Msun each and output their positions in an ascii file: -rand 0.1 This is used to generate many particles per cell for 3D rendering of structures (shows "where the matter is").

Select only cells with density between 0.1 and 100 cm-3: -rhomin 0.1 -rhomax 100

Center the coordinates on the center of the selection -cen

Gravity mode

Output the same as hydro mode (see above) but with the 3 components of the gravitational force in addition: -grav

Select only cells with density between 0.1 and 100 cm-3: -rhomin 0.1 -rhomax 100

Center the coordinates on the center of the selection -cen

PDF mode

Compute the probability distribution function (PDF) of the density of gas and output the histogram in an ascii file: -pdf 100 for the PDF on 100 log-spaced bins. The output file contains 2 columns: the minimum density in each bin (in cm-3), and the gas mass (in Msun).

Set the minimum and maximum of the PDF to 0.1 and 100 cm-3: -rhomin 0.1 -rhomax 100

Fits mode

This mode requires to compile rdramses with the pre-processor flag FITS, and to include the cfitsio library.

This mode produces a 2D fits image. The number of pixel in the image depends on the AMR grid and the maximum refinement level of the volume considered. By default, the projection along the third dimension is made by computing the volume-density-weighted average of the quantity plotted. For another behavior, one can use -maxval, -maxrho or -sum (see below).

Projection along the x axis (default is z). -dir x If used in a namelist, don't forget to add the quotes: 'x'

The value of the map is the maximum value along the line-of-sight -maxval

The value of the map is the value along the line-of-sight where the volume density is maximum -maxrho

The value of the map is the sum of all values along the line-of-sight. (Since version 1.4, the total is conserved.) -sum

Quantity to extract -typ 1 -1 = cpu number
0 = ref. level
1 = gas volume density [cm-3] (default)
2 = X velocity [km/s]
3 = Y velocity [km/s]
4 = Z velocity [km/s]
5 = gas pressure []
6 = passive scalar
7 = gas temperature [K]
8 = sound speed [km/s]
9 = Jeans length [pc]
10 = velocity dispersion [km/s]
11 = 2D-velocity [km/s]
12 = 3D-velocity [km/s]
13 = 2D-gravitational acceleration [kpc/Myr^2]
14 = 3D-gravitational acceleration [kpc/Myr^2]
15 = x-gravitational acceleration [kpc/Myr^2]
16 = y-gravitational acceleration [kpc/Myr^2]
17 = z-gravitational acceleration [kpc/Myr^2]
18 = tidal acceleration (along its main axis) [Myr^-2]
19 = tidal acceleration normalized to gravity
20 = shear [Myr^-1]
21 = shear as a centrifugal acceleration normalized to self-gravity (warning: not total gravity)
22 = compressive turbulence [km/s/pc]
23 = solenoidal turbulence [km/s/pc]
24 = gas mass [Msun]

q mode

Ouput an ascii file with one line per leaf cell in the selection (format = x, y, z, typ) -q -typ 1 typ defines a additional physical quantity (see the list in the Section on Fits mode, above)

Select only cells with density between 0.1 and 100 H/cc. -rhomin 0.1 -rhomax 100

Center the coordinates on the center of the selection -cen

PSD mode

This mode requires to compile rdramses with the pre-processor flag FFTW, and to include the FFTW library.

Compute the power spectrum density (PSD) on a map made with the options of the Fits mode, and output it in an ascii file -psd (the fits file is not produced). The output file contains 3 columns: the wavenumber (in pc-1), the power and the inverse of the wavenumber (in pc).

Same as -psd, but without computing the average over the number of elements carrying each frequencies -psdm This is used to combine multiple PSDs computed independently. The average must be done manually, independently from rdramses. If run with MPI, the output file only contains the power column, and the wavenumber (in pc-1) and its inverse (in pc) are output in a separate file.

Particles data

In particle mode, all hydro and AMR data is ignored. Only the part files are read.

For efficient reading of the data, the size of buffer arrays has been defined using a pre-processor constant NPARTMAX. If the code runs into errors, increase NPARTMAX at the begining of the source code in the rdramses.f90 file, at the line
integer,parameter::NPARTMAX=60000000
and recompile.

In particle mode, you can use the volume selection. In addition, you can use the options

Consider one particle out of 10 -pstep 10

Mass selection (min and/or max), in solar masses -pmmin 1e3 -pmmax 2e5

Then, you can choose one of the following modes:

Particle fits mode

This mode requires to compile rdramses with the pre-processor flag FITS, and to include the cfitsio library.

Generate a 2D fits image of the surface density of the particles -p

Set the number of pixels of the fits image along the x-axis (the other axe will be scaled accordingly) -pix 256 (default is 512 pixels)

Particle ascii mode

Ouput an ascii file with one line per particle in the selection (format = x, y, z, vx, vy, vz, mass. In kpc, km/s, and Msun) -part

Center the coordinates on the center of the selection -cen

New star mode

Ouput an ascii file with one line per stellar particle formed during the simulation in the selection (format = x, y, z, vx, vy, vz, mass, age. In kpc, km/s, Msun and Myr) -ns

Age selection (min and/or max), in Myr -pamin 2.0 -pamax 10.0

Center the coordinates on the center of the selection -cen

SFR mode

Compute SFR as a mass-weighted histogram of the birthdate of the new stars, in bins of 2 Myr. Output is the histogram in ascii format. -sfr 2.0 The output file contains 2 columns: the minimum age in each bin (in Myr), and the SFR (in Msun/yr)

Correct SFR for stellar mass loss -eta_sn 0.2 -f_w 0 Because of the mass loss of new stars via supernova feedback, the parameters of the feedback must be passed. As in the RAMSES namelist, eta_sn is the fraction of the IMF producing SNe (default is eta_sn=0, i.e. no feedback correction), and f_w is the loading factor. (f_w = 0 for thermal SNe, f_w > 0 for kinetic SNe). We assume the stars younger than 10 Myr have not lost mass.

Particle ID mode

Output an ascii file with one line (one column only) per particle in the selection -id This ID can be used to track particles over several snapshots.

MPI

The code can be run in parallel. This is useful when treating a huge volume at high resolution. The volume is then split in equal-size sub-volumes and the rdramses treatment is done independently for each sub-volumes and the results from one CPU are never used by another.

Spread the volume into 4 columns (i.e. along the x-axis) and 6 rows (along the y-axis)
-ncol 4 -nrow 6 rdramses has to be compiled with the MPIMODE pre-processor flag, and run with the appropriate mpirun command (here for 4*6 = 24 CPUs).

Quick how-to

A few examples of useful commands.

Make the density map of gas in the center of the box: rdramses -inp output_00001 -lmax 12 -cube 10

Make the density map of a disk-like structure: rdramses -inp output_00001 -lmax 12 -d 100 100 10 -dir y

Make the density map of stars in the center of the box: rdramses -inp output_00001 -p -cube 10

Make the map of the 2D velocity field rdramses -inp output_00001 -lmax 12 -typ 11

Compute the SFR of a run with thermal SN feedback rdramses -inp output_00001 -sfr 1.0 -eta_sn 0.2 -f_w 0.0

Compute the PDF rdramses -inp output_00001 -pdf 100 -rhomin 1e-3 -rhomax 1e5

Help, feedback

Questions, bug reports, comments and suggestions are most welcome: florent.renaud<at>gmail.com

Florent Renaud - last update: 16 August 2017