RATRAN

TODO: Not sure if this can still work. Needs to be checked and updated if we want to keep it.

RATRAN is a computer code, developed by Michiel Hogerheijde & Floris van der Tak, to calculate the radiative transfer and excitation of molecular lines, see https://sronpersonalpages.nl/~vdtak/ratran/frames.html for details.

Note: since revision a6a757b8, ProDiMo has in-build line transfer, see ProDiMo_Line_Transfer. With this new module, we achieve better stability & performance as compared to RATRAN/SKY, because the in-build line transfer resolves the inner disk regions much better, using a different ray setup with logarithmically spaced concentric rings around the star in the image plane. Therefore, it is generally recommended to use ProDiMo's in-build line transfer. However, the in-build line transfer relies on the resulting level populations obtained with escape probability treatment as calculated for the heating/cooling. Using RATRAN instead is still a valid option e.g. to study the effects of proper non-LTE treatment on the line formation. However, it is recommended to use RATRAN only for lines that originate from a larger disk volume, e.g. sub-mm and radio lines. If you use RATRAN on lines that form in very specific and small areas of the disk, RATRAN/AMC will still work fine, but RATRAN/SKY will have problems to spatially resolve these lines.

ProDiMo produces output files that can be used as input for the 2D version of RATRAN. You can download two different modified versions of RATRAN from this repository, but be warned!

2D RATRAN is not free - you must give Michiel Hogerheijde co-author right if you want to publish results about disks obtained with RATRAN see https://sronpersonalpages.nl/~vdtak/ratran/frames.html. If you want to checkout 2D RATRAN from this repository, please let Michiel know about it and ask for his permission first michiel@strw.leidenuniv.nl.

Checkout RATRAN

There are two modified versions of Ratran in this repository, one called RatranPW modified by me (Peter Woitke), and a version called RatranWFT modified by Wing-Fai Thi - you have to make your choice.

Both versions use so-called scrambled quasi randon numbers instead of pseudo random numbers as used in the original dirstribution. We observe a large acceleration, typical a facor of 10. RatranPW uses in principle the same algorithm as the original RATRAN with a FIXSET and a RANDOM phase. I have modified the algorithm slightly though, e.g. putting in a NG-iteration in FIXSET phase.

RatranWFT uses more aggressive changes, and is even faster. Wing-Fai has completely re-written the algorithm how to choose and eventually to fix the ray directions. However, we observed some weaknesses during tests for optically thick non-LTE cases with H2O. Thus, RatranWFT is still experimental. Only RatranPW is coupled to the dust opacity used in ProDiMo so far.

> mkdir /path/to/Ratran
> cd /path/to/Ratran
> svn checkout --username AlbertEinstein https://forge.roe.ac.uk/svn/ProDiMo/RatranPW .

Install and update RATRAN

There are some problems with RATRAN and svn, because we want to use, checkout, update and commit changes from different machines, but RATRAN is a complicated package which usually needs to be configured in a different way for each machine, setting paths etc. Here is a way, though, that should work ...

First, DO NOT USE THE CONFIGURE SCRIPT. Instead, copy and modify an init file and source it, whenever you want to use RATRAN:

> cd RATRAN
> cp init@tummel init@mymachine
> ln -s init@mymachine init
> emacs init
> svn add init@mymachine
> source init

Second, there is a binary, i.e. a machine-dependent file in RATRAN/bin called readmol.lnx which needs to be compiled. I changed this file to a link to RATRAN/molec/a.out which is not part of the repository. Simply compile readmol.f in RATRAN/molec, which creates the target a.out, as

> cd RATRAN/molec
> ifort readmol.f

Third, the Makefiles for amc and sky, amc.make.lnx and sky.make.lnx, are machine-dependent. To solve that problem, I have changed them into links to "Makefile" which is not part of the repository. Follow the following procedure:

> cd RATRAN/amc
> cp Makefile@tummel Makefile@mymachine
> ln -s Makefile@mymachine MakeFile
> emacs Makefile
> svn add Makefile@mymachine
> cd ../sky
> cp Makefile@tummel Makefile@mymachine
> ln -s Makefile@mymachine MakeFile
> emacs Makefile
> svn add Makefile@mymachine

This way, if you commit changes via svn next, only your variants of Makefiles and init are added without disturbing other users.

How to use RATRAN

Ratran uses two seperate codes, amc and sky, to do the non-LTE calculations and the formal solution to simulate observations, respectively. Both programs require fits-libraries. I use a package called cfitsio3060 that needs to be installed. Look at http://www.sron.rug.nl/~vdtak/ratran/frames.html] for details.

ProDiMo offers two ways to use Ratran.

Possibility 1

The easiest way to use RATRAN is to trust ProDiMo's non-LTE calculations of atomic and molecular population numbers with escape probability, which includes the continuous irradiation from the star and from the disk (provided that you have run a ProDiMo model with radtrans=.true.). If you run ProDiMo with parameter write_pop=.true, output files will be created that contain the necessary input data for sky concerning cells and population numbers

> cd /path/to/ProDiMo/TWHya
> ls pop*
pop_LTE_CII.out  pop_LTE_CO.out  pop_LTE_oH2O.out  pop_LTE_OI.out  pop_LTE_pH2O.out
pop_PRO_CII.out  pop_PRO_CO.out  pop_PRO_oH2O.out  pop_PRO_OI.out  pop_PRO_pH2O.out

The files with PRO in the middle are ProDiMo's results with escape probability. LTE contains the same data for Boltzman population according to the local gas temperature.

Next, create an input file for sky, let's call it sky_OI.inp

source=pop_PRO_OI.out
format=fits
outfile=line_PRO_OI
trans=1,3
pix=94,0.08,32,2
chan=100,0.20
distance=140.0
incl=75.0
units=Wm2Hzsr
;
q

Learn more about the sky parameters at https://sronpersonalpages.nl/~vdtak/ratran/frames.html. Sky will automatically use dust opacity tables created by ProDiMo, called dust_opac.out, but note that there is no scattering in amc/sky, nor direct light from the star, which currently limits the applicability of amc to the far IR - mm wavelegth range.

You furthermore need to specify the 3D-velocity field as function of x and z, all in SI units(!). Here is an example of velo_ProDiMo.f, assuming circular Kelperian orbits. You probably want to change the stellar mass.

      SUBROUTINE velo(id,x,z,v)

      IMPLICIT NONE
      INTEGER id
      DOUBLE PRECISION x,z,r,v(3)
      DOUBLE PRECISION ggravi,msol,mass
      PARAMETER (ggravi = 6.6725985d-11, msol=1.9891d30)
      PARAMETER (mass = 1.0)

      r = dsqrt(x**2+z**2)
      v(1) = 0.d0
      v(2) = 0.d0
      v(3) = dsqrt ( ggravi * mass * msol * x**2/r**3 )  ! NOTE: m/s !!!

      return
      end

Now, we are ready to run sky

> source /path/to/Ratran/init
> sky sky_OI.inp

The result will be fits-files with the 3D line-data, here called line_PRO_OI_001.fits and line_PRO_OI_003.fits, which contain a cube of intensities(pixel,pixel,velo-interval). These output data can be analysed with various tools, e.g. gaia. But I prefer to use idl with self developed macros, see e.g. /path/to/ProDiMo/idl/GASPS.pro

> ln -s /path/to/Ratran/idl/GASPS.pro .
> emacs GASPS.pro
> idl
IDL> .r GASPS

Remark 1: idl needs to be able to read fits-files. I use the astrolib-package via a setenv command

> setenv IDL_PATH ${IDL_DIR}:${IDL_DIR}/lib:${IDL_DIR}/products/astrolib/pro

As far as I know, the astrolib-package is free. You will find it probably on the net.

Remark 2: be aware that GASPS.pro reads the sky input file to obtain pixel, channel, distance and inclination information. So make sure it is consistent with the one that you used to generate the fits file!

Possibility 2

If you want to use the Monte-Carlo program amc, we first have to create an input file for amc that contains cells, temperatures, species and collision partner densities. This is done by a seperate program called transform_v4

> cd /path/to/ProDiMo/ratran_interface
> emacs makefile
> make

Now, cd back to your working directory, link the executable, and run it. It reads ProDiMo's output file ProDiMo.out.

> ln -s ../ratran_interface/transform_v4 .
> transform_v4

Enter your favourite gas species and grid size. Typical grid sizes are 10x10 to 40x40. The result is a file called Ratran.input. You can have a look on the results with the idl-macro showgrid.pro in /path/to/ProDiMo/idl.

Next, we need to create an amc control file, let's call it amc_OI.inp

source=Ratran.input
outfile=pop_AMC_OI.out
molfile=oatom_my.dat
snr=10
nphot=31
kappa=prodimo.f
velo=velo_ProDiMo.f
seed=4711
fixset=1.e-4
trace=off
;
q

Again, learn more about the amc parameters at https://sronpersonalpages.nl/~vdtak/ratran/frames.html.

NOTE: there are especially "good" numbers nphot for the quasi-random sobol sequences, namely 2n-1 (i.e. 1,3,7,15,31,63,127,...). You can use other numbers, but the performance is slightly better with these.

Now, you are ready to run the 2D non-LTE simulation. Type

> source /path/to/Ratran/init
> amc amc_OI.inp

After some minutes, or some hours, amc should finish by creating an output file called pop_AMC_OI.out. This is analogous to pop_PRO_OI.out and pop_LTE_OI.out. Note, however, that the cells are different and have been "filled" in a different way. Follow now the procedure to apply sky next as described under Possibility 1.