Installation of RADMC-3D

Although the RADMC-3D package contains a lot of different software, the main code is located in the src/ directory, and is written in Fortran-90. The executable is radmc3d. Here we explain how to compile the fortran-90 source codes and create the executable radmc3d.

Compiling the code with ‘make’

To compile the code, enter the src/ directory in your shell. You now may need to edit the Makefile in this directory using your favorite text editor and replace the line

FF = gfortran -fopenmp

with a line specifying your own compiler (and possibly OpenMP directive, if available). If, of course, you use gfortran, you can keep this line. But if you use, e.g., ifort, then replace the above line by

FF = ifort -openmp

(note the slightly different OpenMP directive here, too). If you save this file, and you are back in the shell, you can compile the radmc3d code by typing

make

in the shell. If all goes well, you have now created a file called radmc3d in the src/ directory.

If, for whatever reason, the OpenMP compilation does not work, you can also compile the code in serial mode. Simply remove the -fopenmp directive.

The install.perl script

If instead of typing just make you type

make install

(or you first type make and then make install, it is the same), then in addition to creating the executable, it also automatically executes a perl script called install.perl (located also in the src/ directory). This PERL script installs the code in such a way that it can be conveniently used in any directory. What it does is:

  • It checks if a bin/ directory is present in your home directory (i.e. a $HOME/bin/ directory). If not, it asks if you want it to automatically make one.

  • It checks if the $HOME/bin/ directory is in the path of the currently used shell. This is important to allow the computer to look for the program radmc3d in the $HOME/bin/ directory. If you use a bash shell, then you can add the following line to your $HOME/.bashrc:

    export PATH=/myhomedirectory/bin:$PATH

  • It creates a file radmc3d in this $HOME/bin/ directory with the correct executable permissions. This file is merely a dummy executable, that simply redirects everything to the true radmc3d executable located in your current src/ directory. When you now open a new shell, the path contains the $HOME/bin/ directory, and the command radmc3d is recognized. You can also type source $HOME/.bashrc followed by rehash. This also makes sure that your shell recognizes the radmc3d command.

  • It checks if a python/ subdirectory exists in the above mentioned bin/ directory, i.e.a $HOME/bin/python/ directory. If not, it asks if you want it to automatically create one.

  • If yes, then it will copy all the files ending with .py in the python/radmc3d_tools/ directory of the distribution to that $HOME/bin/python/radmc3d_tools/ directory. This is useful to allow you to make an PYTHONPATH entry to allow python to find these python scripts automatically.

Note that this perl script installs the code only for the user that installs it. A system-wide installation is not useful, because the code package is not very big and it should remain in the control of the user which version of the code he/she uses for each particular problem.

If all went well, then the perl.install script described here is called automatically once you type make install following the procedure in Section Compiling the code with ‘make’.

Before the installation is recognized by your shell, you must now either type rehash in the shell or simply open a new shell.

How do you know that all went OK? If you type radmc3d in the shell the RADMC-3D code should now be executed and give some comments. It should write:

================================================================
     WELCOME TO RADMC-3D: A 3-D CONTINUUM AND LINE RT SOLVER

                         VERSION 2.0

               (c) 2008-2020 Cornelis Dullemond

      Please feel free to ask questions. Also please report
       bugs and/or suspicious behavior without hestitation.
     The reliability of this code depends on your vigilance!
                   dullemond@uni-heidelberg.de

  To keep up-to-date with bug-alarms and bugfixes, register to
                    the RADMC-3D forum:
           http://radmc3d.ita.uni-heidelberg.de/phpbb/

             Please visit the RADMC-3D home page at
 http://www.ita.uni-heidelberg.de/~dullemond/software/radmc-3d/
================================================================

Nothing to do... Use command line options to generate action:
  mctherm        : Do Monte Carlo simul of thermal radiation
  mcmono         : Do Monte Carlo simul only for computing mean intensity
  spectrum       : Make continuum spectrum
  image          : Make continuum image

on the screen (or for newer versions of RADMC-3D perhaps some more or different text). This should also work from any other directory.

What to do if this all does not work?

In case the above compilation and installation does not work, here is a proposed procedure to do problem hunting:

  1. First, answer the following questions:

    • Did you type make install in the src/ directory? I mean, did you not forget the install part?

    • Did you put $HOME/bin/ in your path (see above)?

    • If you just added $HOME/bin/ to your path, did you follow the rest of the procedure (either closing the current shell and opening a new shell or typing the source and rehash commands as described above)?

    If this does not help, then continue:

  2. Close the shell, open a new shell.

  3. Go to the RADMC-3D src/ directory.

  4. Type ./radmc3d. This should give the above message. If not, then make sure that the compilation went right in the first place:

  5. Type rm -f radmc3d, to make sure that any old executable is not still present.

  6. Type make clean. This should return the sentence OBJECT and MODULE files removed.

  7. In case the problem lies with the OpenMP parallellization, you could do cp Makefile_normal Makefile, which switches off the OpenMP compilation.

  8. Then type make. This should produce a set of lines, each representing a compilation of a module, e.g. gfortran -c -O2 ./amr_module.f90 -o amr_module.o, etc. The final line should be something like gfortran -O2 main.o ..... gascontinuum_module.o -o radmc3d. If instead there is an error message, then do the following:

    • Check if the compiler used (by default gfortran) is available on your computer system.

    • If you use an other compiler, check if the compiler options used are recognized by your compiler.

    • Check if the executable radmc3d is now indeed present. If it is not present, then something must have gone wrong with the compilation. So then please check the compilation and linking stage again carefully.

    If you followed all these procedures, but you still cannot get even the executable in the src/ directory to run by typing (in the src/ directory) ./radmc3d (don’t forget the dot slash!), then please contact the author.

  9. At this point we assume that the previous point worked. Now go to another directory (any one), and type radmc3d. This should also give the above message. If not, but the radmc3d executable was present, then apparently the shell path settings are wrong. Do this:

    • Check if, in the current directory (which is now not src/) there is by some accident another copy of the executable radmc3d. If yes, please remove it.

    • Type which radmc3d to find out if it is recognized at all, and if yes, to which location it points.

    • Did you make sure that the shell path includes the $HOME/bin/ directory, as it should? Otherwise the shell does not know where to find the $HOME/bin/radmc3d executable (which is a perl link to the src/radmc3d executable).

    • Does the file $HOME/bin/radmc3d perl file exist in the first place? If no, check why not.

    • Type less $HOME/bin/radmc3d and you should see a text with first line being #!/usr/bin/perl and the second line being someting like system("/Users/user1/radmc-3d/version_2.0/src/radmc3d @ARGV"); where the /Users/user1 should of course be the path to your home directory, in fact to the directory in which you installed RADMC-3D.

If this all brings you no further, please first ask your system administrators if they can help. If not, then please contact the author.

Installing the simple Python analysis tools

RADMC-3D offers (in addition to the model setup scripts in the examples/ subdirectories) two Python support libraries:

  1. python/radmc3d_tools/

    This library contains only some bare-bones small Python scripts.

  2. python/radmc3dPy/

    This library is a sophisticated stand-alone library developed by Attila Juhasz, and further maintained together with the RADMC-3D main author.

How to install and use the python/radmc3d_tools/

The installation of the python/radmc3d_tools should be automatic when you type make install in the src/ code directory (see above). It will copy the files to the bin/python/radmc3d_tools/ directory in your home directory. If this directory does not exist, you will be asked if you want it to be created. If you confirm (typing ‘y’), then the files from the python/radmc3d_tools/ directory will be copied into the $HOME/bin/python/radmc3d_tools/ directory.

Now you need to make sure that Python knows that these tools are there. In Python here are two ways how you can make sure that Python automatically finds these scripts:

  1. Under Unix/Linux/MacOSX you can set the PYTHONPATH directly in your .bashrc file. For example: in .bashrc (if you use the bash shell) you can write:

    export PYTHONPATH=$HOME/bin/python:$PYTHONPATH

(where $HOME is your home directory name).

  1. Alternatively you can set the PYTHONPATH directly from within Python with the python command:

    import os
import sys
home = os.environ["HOME"]
sys.path.append(home+'/bin/python')

If all goes well, if you now start Python you should be able to have access to the basic Python tools of RADMC-3D directly. To test this, try typing from radmc3d_tools.simpleread import * in Python. If this gives an error message that simpleread.py cannot be found, then please ask your system administrators how to solve this.

You may ask why first copy these files to $HOME/bin/python/radmc3d_tools/ and not point PYTHONPATH directly to the python/radmc3d_tools in your RADMC-3D distribution? The reason is that if you have multiple versions of RADMC-3D on your computer system, you always are assured that Python finds the python routines belonging to the latest installation of RADMC-3D (note: only assured if that latest compilation was done with make install).

Now you should be ready to use the tools. The most important one would be the simpleread.py tool, which contains a set of functions for reading typical RADMC-3D input and output files (though only for regular model grid, not for octree grids). In a Python command line interface you can import them by:

from radmc3d_tools import simpleread

And you can then, for instance, read the dust density file with:

d = simpleread.read_dustdens()

Here, d is now an object containing a d.grid subobject (which contain information about the grid) and the dust density array d.rhodust. Have a look at the various functions in simpleread, to see what is available.

How to install and use the python/radmc3dPy library

The installation of the python/radmc3dPy package is described in the python/radmc3dPy/README file. In short, by going into the python/radmc3dPy/ directory and typing in the shell:

python setup.py install --user

it should install itself right into your Python distribution. For instance, if you have anaconda3 on a Mac, it would copy the files into the directory

$HOME/.local/lib/python3.7/site-packages/radmc3dPy/

Python knows where to find it there.

Now you should be ready to use radmc3dPy, by importing it:

import radmc3dPy

radmc3dPy consists of several sub libraries such as radmc3dPy.analyze and radmc3dPy.image. For instance, to read the dust density distribution, you could do this:

from radmc3dPy import analyze
d = analyze.readData(ddens=True)

The d.rhodust array now contains the dust density.

For more information, please consult the radmc3dPy documentation in the python/radmc3dPy/doc/ directory.

Making special-purpose modified versions of RADMC-3D (optional)

For most purposes it should be fine to simply compile the latest version of RADMC-3D once-and-for-all, and simply use the resulting radmc3d executable for all models you make. Normally there is no reason to have to modify the code, because models can be defined quite flexibly by preparing the various input files for RADMC-3D to your needs. So if you are an average user, you can skip to the next subsection without problem.

But sometimes there is a good reason to want to modify the code. For instance to allow special behavior for a particular model. Or for a model setup that is simply easier made internally in the code rather than by preparing large input files. One can imagine some analytic model setup that might be easier to create internally, so that one can make use of the full AMR machinery to automatically refine the grid where needed. Having to do so externally from the code would require you to set up your own AMR machinery, which would be a waste of time.

The problem is that if the user would modify the central code for each special purpose, one would quickly lose track of which modification of the code is installed right now.

Here is how this problem is solved in RADMC-3D:

  • For most purposes you can achieve your goals by only editing the file userdef_module.f90. This is a set of standard subroutines that the main code calls at special points in the code, and the user can put anything he/she wants into those subroutines. See Chapter Modifying RADMC-3D: Internal setup and user-specified radiative processes for more information about these standard subroutines. This method is the safest way to create special-purpose codes. It means (a) that you know that your modification cannot do much harm unless you make really big blunders, because these subroutines are meant to be modified, and (b) you have all your modifications only in one single file, leaving the rest of the code untouched.

  • You can create a local version of the code, without touching the main code. Suppose you have a model directory run_mymodel and for this model you want to make a special-purpose version of the code. This is what you do:

    1. Copy the Makefile from the src/ directory into run_mymodel.

    2. Copy the .f90 file(s) you want to modify from the src/ directory into run_mymodel. Usually you only want to modify the userdef_module.f90 file, but you can also copy any other file if you want.

    3. In the run_mymodel/Makefile replace the SRC = . line with SRC = XXXXXX, where XXXXXX should be the full path to the src/ directory. An example line is given in the Makefile, but is commented out.

    4. In the run_mymodel/Makefile make sure that all the .f90 files that should remain as they are have a $(SRC)/ in front of the name, and all the .f90 files that you want to modify (and which now have a copy in the run_mymodel directory) have a ./ in front of the name. By default all .f90 files have $(SRC)/ in front of the name, except the userdef_module.f90 file, which has a ./ in front of the name because that is the file that is usually the one that is going to be edited by you.

    5. Now edit the local .f90 files in the run_mymodel directory in the way you want. See Chapter Modifying RADMC-3D: Internal setup and user-specified radiative processes for more details.

    6. Now inside the run_mymodel directory you can now type make and you will create your own local radmc3d executable. NOTE: Do not type make install in this case, because it should remain a local executable, only inside the run_mymodel directory.

    7. If you want (though this is not required) you can clean up all the local .o and .mod files by typing make clean, so that your run_mymodel directory is not filled with junk.

    8. You can now use this special purpose version of radmc3d by simply calling on the command line: ./radmc3d, with any command-line options you like. Just beware that, depending on the order in which you have your paths set (in tcsh or bash) typing just radmc3d may instead use the global version (that you may have created in the src/ directory with make install). So to be sure to use the local version, just put the ./ in front of the radmc3d.

Note: In chapter Modifying RADMC-3D: Internal setup and user-specified radiative processes there is more information on how to set up models internally in the code using the method described here.

Note: You can use make clean to remove all the .o and .mod files from your model directory, because they can be annoying to have hanging around. By typing make cleanmodel you remove, in addition to the .o and .mod files, also all model input and output files, with the exception of dust opacity or molecular data files (because these latter files are usually not created locally by the problem_setup.py script). By typing make cleanall you remove everything except the basic files such as the Makefile, any .f90 files, any .py files, the dust opacity or molecular data files and README files.