Beginners Guide¶
This guide should help new users to get an idean on how to use ProDiMo. It will not go into any details or discuss the science behind the model. It should just show you how to run a model, how to change some parameters and how to visualize some of the results.
We also recommend to take a look at the papers from the Summer School “Protoplanetary Disks: Theory and Modeling Meet Observations”, which provide a great general introduction for disk modelling.
ProDiMo is run from the command line and you need to launch a
Terminalor shell to work with ProDiMo. Also a text editor is required to edit the input files.
Setting up a model¶
I almost any case you will never start from scratch when setting up a ProDiMo model. So also here we will start with an existing model. In your ProDiMo installation directory you will find an examples folder. So let's copy an example
cp -r ~/git/prodimo/examples/Technical/FirstModel .Now change into that directory (cd FirstModel) and do an ls -l. You should see something like this:
-rw-r--r-- 1 work staff 163B Jun 25 15:34 LineTransferList.in
-rw-r--r-- 1 work staff 6.1K Jun 25 15:34 Parameter.in
-rw-r--r-- 1 work staff 408B Jun 25 15:34 README.md
-rw-r--r-- 1 work staff 1.3K Jun 25 15:34 Species.in
-rw-r--r-- 1 work staff 839B Jun 25 15:34 Elements.inThe README.md is just a short description of the purpose of the model. It is not necessary for ProDiMo. The *.in files are the input files that tell ProDiMo what to do. And those are all you need for now.
Running the model¶
If you have installed ProDiMo correctly, all you need to do is to run ProDiMo in this directory. If you have used conda to install ProDiMo, don't forget to activate your environment first (e.g. conda activate prodimo).
prodimoThis will start the model and you should see some output in your terminal. However, we stop this model (Ctrl-C) and call prodimo properly:
prodimo > prodimo.log 2>&1 &This will start ProDiMo in the background and writes all the screen output to the file prodimo.log. You can check the progress of the model by looking at this file, using e.g. (cat prodimo.log or tail prodimo.log, or open it with some editor). This model should not run very long, (on a 4 year old MacBook pro about 10 minutes).
When you again make an ls -l in your FirstModel directory, you will already see a couple of new files. The code is finished when you see a file called finished.out, but you will also see it in the prodimo.log file. When the model is finished your FirstModel directory should look like this:
-rw-r--r-- 1 work staff 106K Jun 25 15:58 prodimo.log
-rw-r--r-- 1 work staff 140B Jun 25 15:58 finished.out
-rw-r--r-- 1 work staff 25K Jun 25 15:58 line_flux.out
-rw-r--r-- 1 work staff 2.7M Jun 25 15:58 line_image.out
-rw-r--r-- 1 work staff 67M Jun 25 15:58 FlineEstimates.out
-rw-r--r-- 1 work staff 1.0M Jun 25 15:58 restart.fits.gz
-rw-r--r-- 1 work staff 4.5M Jun 25 15:58 ProDiMo.out
-rw-r--r-- 1 work staff 17K Jun 25 15:49 SED.out
-rw-r--r-- 1 work staff 18M Jun 25 15:49 image.out
-rw-r--r-- 1 work staff 84K Jun 25 15:49 SEDana.out
-rw-r--r-- 1 work staff 1.3K Jun 25 15:49 RTconv.out
-rw-r--r-- 1 work staff 77K Jun 25 15:45 dust_opac.out
-rw-r--r-- 1 work staff 20K Jun 25 15:45 Parameter.out
-rw-r--r-- 1 work staff 2.2M Jun 25 15:45 Mie.fits.gz
-rw-r--r-- 1 work staff 501K Jun 25 15:45 StarSpectrum.out
-rw-r--r-- 1 work staff 3.5M Jun 25 15:45 LineList.out
-rw-r--r-- 1 work staff 8.7K Jun 25 15:45 Species.out
-rw-r--r-- 1 work staff 657B Jun 25 15:45 Elements.out
-rw-r--r-- 1 work staff 163B Jun 25 15:34 LineTransferList.in
-rw-r--r-- 1 work staff 6.1K Jun 25 15:34 Parameter.in
-rw-r--r-- 1 work staff 408B Jun 25 15:34 README.md
-rw-r--r-- 1 work staff 1.3K Jun 25 15:34 Species.in
-rw-r--r-- 1 work staff 839B Jun 25 15:34 Elements.inThe main results are in the *.out files, in particular the ProDiMo.out file. You can open that one with a text editor and take a look. But usually you will want to visualize the results in some way.
Visualizing the results¶
We have two options to visualize the results, one are IDL scripts and the other one is the Python package prodimopy. If you never haver heard of IDL or if you do not have an IDL installation (and license!), we recommend to just use prodimopy.
IDL scripts¶
In the PRODIMODIR/idl directory you will find a couple of scripts, but for now we need only one. If you have setup the IDL environment variables (see OS environment) or if you followed the conda way installation you can just run idl within the FirstModel directory:
idland then run the script prodimo.pro (within IDL):
IDL> .run prodimo.proYou will see a lot of screen output, which is not relevant for now. When it is finished press CTRL D to exit IDL. In your model directory you should see now a file out.ps, which you can open with your favourite PostScript viewer. You will see many plots, and it will take some time until you understand all of them. However, for most of them it should be quite clear what they show (e.g. the density/temperature structure of the disk, the Spectral Energy Distribution (SED) etc.).
prodimopy¶
To use prodimopy for plotting you will need Python3 and the prodimopy package. The details on how to install it can be found in the prodimopy Documentation. If you just want to use it right now simply type: pip install prodimopy. Once the package is installed, you can use the command:
pplotwithin your model directory to create a couple of plots. Once the script is finished, you will find a new file called out.pdf, which you can view with any pdf viewer. For most figures it should be quite clear what they show, however, all the details are explained in the User Guide.
This is just an example on how to use prodimopy, further examples (e.g. how to use it in a Jupyter notebook) can be found in the prodimopy Documentation.
You have now run your first ProDiMo model and visualized the results. Congratulations!
Change model Parameters¶
Here we will give you a quick crash course on how to set some of the parameters of your model. We recommend to duplicate your FirstModel directory and work in that copy, so that you can compare the results with your original model.
The main input file for ProDiMo is the Parameter.in file. Open it in any text editor and you should see something like this
----------------------------------------------------------------------
*** Model setup used for the Beginners Guide in the prodimo wiki ***
*** This one is not suited to do any real science! ***
----------------------------------------------------------------------
----- star and irradiation -----
0.7 ! Mstar [Msun] : stellar mass
1.0 ! Lstar [Lsun] : stellar luminosity
4000.0 ! Teff [K] : stellar effective temperature
0.01 ! fUV [-] : LUV/Lstar
1.3 ! pUV [-] : UV powerlaw exponent
.true. ! Xrays [-] : use Xray chemistry and heating?
1.E+30 ! Xray_Lum [erg/s] : X-ray luminosity
2.E+7 ! Xray_Temp [K] : X-ray emission temperature
1.7E-17 ! CRI [1/s] : cosmic ray ionisation of H2
1.0 ! CHI_ISM [-] : strength of incident vertical UV
------ disk mass & shape ------
0.001 ! Mdisk [Msun] : disk mass
.false. ! solve_diskstruc : solve the vertical hydrostatic eq.?
.true. ! MCFOST_LIKE : parametric disk structure like in MCFOST?
0.15 ! Rin [AU] : inner disk radius
30.0 ! Rtaper [AU] : tapering-off radius
200.0 ! Rout [AU] : outer disk radius
1.0 ! epsilon [-] : column density exponent
10.0 ! MCFOST_H0 [AU] : scale height ...
100.0 ! MCFOST_RREF [AU] : ... belonging to reference radius
1.15 ! MCFOST_BETA : flaring power
.false. ! stop_after_init : use this to check the model setup
...Here we will not explain each an every parameter, but focus on some general aspects of this input file.
If a line start with --- or ***, it is a comment line and will be ignored by ProDiMo. E.g. the first three lines are just comments.
The order of the Parameters is not important, but we recommend to keep a structure similar to the one in this example. Setting a Parameter looks like this:
0.001 ! Mdisk [Msun] : disk massThe first column of the model is the actual value for the Parameter and the ! Mdisk is the Parameter name, indicated by the !. What comes after the Parameter name (separated by at least one space) is also a comment, and is ignored by ProDiMo. With only a few exceptions, all Parameters are set in that way.
If you like, you can now change some of the Parameters (e.g. the stellar and disk properties) and run the model again, make the plots and compare it with your first model.
There are only a couple of mandatory Parameters, and most have default values. However, as one usually starts with an existing model setup, many more Parameters are usually already included in the Parameter.in.
TODO: list of mandatory Parameters
If you want to get an idea on how many parameters there are, you can open the Parameter.out file, which lists all the Parameters and their values (even if they were not in your Parameter.in). This is a very useful file, as you can check if you have set everything you wanted to set. Please note, the values of the parameters in the Parameter.out are in code units (cgs), so for example ! Mdisk is given in solar masses in the Parameter.in but listed in grams in the Parameter.out.
In the documentation you will also find a Parameter index which lists all the Parameters and links to the according documentation page. As you can see, there are many Parameters, and unfortunately not all of them are documented yet. However, depending on what you want to do with ProDiMo, one usually only deals with a couple of Parameters, and many you will never change.
Additional input files¶
In addition to the Parameter.in file, there are a couple of other input files, which are also used by ProDiMo. Only two of them are mandatory, namely the Species.in and the Elements.in file. The Species.in file lists all the chemical species, and the Elements.in file lists all the elements that are used in the model.
All the other input files, besides the Parameter.in, Species.in and Elements.in are optional, and are only required if you activate certain parameters in the Parameter.in file.
One example is the LineTransferList.in file, which is only required (or used by ProDiMo) if you activate the line transfer in the Parameter.in like that:
.true. ! line_transfer : calculate line transfer? In our example model this is already the case, and you might have seen some spectral line profile plots in the out.ps or out.pdf file, those are only possible if you have ! line_transfer set to .true.. Further details and other such cases are part of the User Guide documentation.
Output files¶
Similar to the input files, there are also several output files. Some of them are only written if certain parameters are activated in the Parameter.in file. One example is the SED.out file, which is only produced by ProDiMo if you have set:
.true. ! calcSED : calculate SED and images?WARNING: One can run a ProDiMo model (which is one directory) again and again in the same directory. However, if you e.g. switch of the
! calcSED(just an example) Parameter, theSED.outfile will not be deleted, but ProDiMo will not write a new one. This can lead to inconsistent results in your model (i.e. if you change any other parameter). The safest way is to always delete the output file before you run your model again, or copy the input files (*.in) to a new directory before you change them.
Although most of the output files are text files, and one can look at them in a text editor, usually one uses the IDL or python scripts to analyze the results (e.g. read data from there). For example the prodimopy package reads (almost) all the output for a model with one command and puts it into a Python object. This is more convenient (and safer) to extract numbers from the model, compared to searching for them in the output files. In particular if you run a "bigger" (e.g. more grid points) model.
It should also not be required to write your own code to read the files. Please check first the prodimopy read routines or the IDL scripts. If you are unsure, ask one of the ProDiMo developers. You are of course very welcome to make your own figures, but again you might check first what is already there and maybe adapt it if they are not to your liking.
Conclusion¶
As you have seen it is not that difficult to run a ProDiMo model and visualize the results, as already many tools are available. However, until you have setup your model for the science you want to do, it will take some time, and you will have to read the documentation, in particular the User Guide. In general it is useful to maybe discuss your science idea(s) with a more experienced ProDiMo user or with one of the developers, before you start. That might save you a lot of time.