LELUYA Manual v.0.0
For internal use only!
These instructions are for LELUYA v.1.1, prepared for Zeljko Ivezic by Dejan Vinkovic (Princeton, Sep.21, 2001)
Installation
Input files and parameters
Introducing a new dust density distribution
Running the code and preparing the initial grid
Running radiative transfer iterations
Calculating images and fluxes
A demo run
install the source code
before the code is compiled, the user should set the default input and output paths:
- open the file named _install_parameters.c in the LELUYA's root directory
- set _2D_DUSTY_SOURCE_PATH to the LELUYA's root directory
- set _2D_DUSTY_RUN_PATH to the directory used for running the models (input directory)
- set _2D_DUSTY_TEMP_PATH to the temporary directory used by the operating system
- set _2D_DUSTY_OUTPUT_PATH to the directory used for data output
if the code will be compiled in the parallel mode then:
- open the file named _install_parameters.h and add the line:
#define _2DD_MPI_before the last line with #endif
- open the file named _install_parameters.c and add the line:
#define _2DD_MPI_before the last line with #endif
- set _2D_DUSTY_SOURCE_PATH to the LELUYA's root directory
- set _2D_DUSTY_MPIRUN_PATH to the directory used for running the models (input directory)
- set _2D_DUSTY_TEMP_PATH to the temporary directory used by the operating system
- set _2D_DUSTY_MPIOUT_PATH to the directory used for data output
compile the code:
- make compile - compiles all subroutines and creates the executable file
- make exe - creates the executable file (all subroutines should be compiled already)
- make debug - compiles all subroutines with the debug flag -g and creates the executable file with the same debug flag
- make debug_exe - creates the executable file with the debug flag -g
- make mpi_compile - compiles all subroutines by using the MPI compiler and creates the MPI executable file
- make mpi_exe - creates the MPI executable file
- make mpi_debug - compiles all subroutines by using the MPI compiler with the debug flag -g and creates the MPI executable file with the same debug flag
- make mpi_debug_exe - creates the MPI executable file with the debug flag -g
- make clean - removes *.o, *~, and *.exe files from the LELUYA's directory structure
The main input file for LELUYA is Leluya.inp. It is an ASCII file and the input data comes after the equal sign =. Here is one example of this file, followed by the explanation of each line:
--- input file for LELUYA --
lambda grid = 0
tau total = 90.0 at azimuthal angle = 90 and wavelength = 0.55
Rout = 1000
source type = 0 (black body temperature = 4500 K)
total number of the dust components = 2
*********** dust 1 ****************
Sublimation temperature = 900 K
dust input type = 0
cross section file = cold_Silicates_Ossenkopff.dat
*********** dust 2 ****************
Sublimation temperature = 1500 K
dust input type = 0
cross section file = amC_standard_MRN.dat
*********** dust 1 ****************
Dust density type = 2
p = 2
*********** dust 2 ****************
Dust density type = 2
p = 1.5
End of the input file
- lambda grid = 0
Specify the wavelengths for radiative transfer. Currently, there is only option 0 - reading from the default file:
_2D_DUSTY_SOURCE_PATH/MALIK/lambda_grid.dat
(_2D_DUSTY_SOURCE_PATH is the LELUYA's root directory). The file has to have one equal sign, followed by the total number of wavelengths and the list of wavelengths in microns after that.
- tau total = 90.0 at azimuthal angle = 90 and wavelength = 0.55
The optical depth and spatial scale are scaled by the dust along one arbitrary radial line. The user has to specify the total optical depth along this line, the line's azimuth (the symmetry axis has azimuth of zero) , and the wavelength in microns at which the total optical depth is specified (this wavelength has to be part of the lambda grid).
- Rout = 1000
The radius of computational domain. It is a dimensionless quantity, since it is scaled by the dust sublimation point on a given scaling radial line (see the previous input line).
- source type = 0 (black body temperature = 4500 K)
The central energy source. Currently, it has only one option 0 - the black body emission for a given temperature in kelvins.
- total number of the dust components = 2
LELUYA can handle an arbitrary multi-grain dust density distribution. The user has to specify the total number of dust types (components).
- Sublimation temperature = 900 K
dust input type = 0
cross section file = cold_Silicates_Ossenkopff.dat
The user has to specify the dust sublimation temperature and the chemical and physical properties of dust for each dust type separately. The temperature is in kelvins. Currently, the dust properties can be specified only as a file with the absorption and scattering cross sections (input type 0, followed by the file name). The first three rows in the file are ignored and the rest of it are three columns, with the wavelengths in microns as the first one, the absorption cross section as the second, and the scattering cross section as the third one. The cross sections can have an arbitrary unit.
- Dust density type = 2
p = 2
The user has to specify the dust density distribution for each dust type separately. There are several dust density types already incorporated into the code, but the user can add additional ones (see Introducing a new dust density distribution). The existing density types are:
-
type = 1
This model is used by Dejan Vinkovic for testing the code and it does not have a fixed structure. DO NOT USE THIS MODEL!!!
-
type = 2
This as a 1D model (a spherical model) with the dust density distribution r -p, where p has to be specified in the input file.
-
type = 3
This is an ellipsoidal dust density. See Introducing a new dust density distribution for more detail.
-
type = 101
This model is used for modeling CIT3, an oxygen-rich AGB star. The model is created by Dejan Vinkovic during his visit to the Max Planck Institute fuer Radioastronomie, Bonn (http://www.mpifr-bonn.mpg.de/) (NOTE: still under development)
If some dust density distribution is not already included into the LELUYA code then the user has to include it by hand. Here is an example how to include the ellipsoidal dust density (x2+ez2) -n/2 (Ellipsoid Model). Some important comments are in bold, the C program language lines are in blue:
- open the file DAZhBOG/_DAZhBOG__Read_Density_Type.c and add the following code before the line "return 1;" :
/***********************************************************************/
/* be sure that type=3 is not already in use */
if (INPUT.DUST_DENSITY_TYPE[dust_counter]==3) {
/* give an unique name to your model */
sprintf(INPUT.DUST_DENSITY_TYPE_NAME[dust_counter],"Ellipsoid Model");
/* dust density = 1 / (X*X + e*Z*Z)^(n/2)
parameters: n = Dust_Density_Param[dust_counter].param
e = Dust_Density_Param[dust_counter].next->param */
err = _DAZhBOG__Search_for_char (GLOBAL_FILE,"=");
if (err) return 1; /* check for possible input errors */
err=fscanf(GLOBAL_FILE,"%lf",&Dust_Density_Param[dust_counter].param); /* read n */
if (err!=1) return 1; /* check for possible input errors */
/* allocate memory for the second parameter */
Dust_Density_Param[dust_counter].next = (struct density_parameters *)
malloc (sizeof(struct density_parameters));
if (Dust_Density_Param[dust_counter].next==NULL) return 1;
Dust_Density_Param[dust_counter].next->next = NULL;
/* read the second parameter */
err = _DAZhBOG__Search_for_char (GLOBAL_FILE,"=");
if (err) return 1;/* check for possible input errors */
err=fscanf(GLOBAL_FILE,"%lf",&Dust_Density_Param[dust_counter].next->param);
/* read e */
/* check for possible input errors */
if (err!=1 || Dust_Density_Param[dust_counter].next->param <= 0.0) return 1;
return 0; /* return OK flag */
}
/***********************************************************************/
Notice that the introduced density profile has to have an unique type number and an unique name. The model can have an arbitrary number of parameters, but they require memory allocaton. For example, a third parameter would be:
Dust_Density_Param[dust_counter].next->next->param
and it would require:
Dust_Density_Param[dust_counter].next->next = (struct density_parameters *)
malloc (sizeof(struct density_parameters));
Dust_Density_Param[dust_counter].next->next->next = NULL;
- open the file _data_calc_output_flags.h in the LELUYA's root directory and add a description of this new density model
- open the file RADGOST/_RADGOST_Dust_Density.c and add the actual calculation of the dust density for given coordinates (x,z). Temporary variables param1, param2, param3, and param4 are already declared and can be used in the code. The dust density should be copied to density and returned as a result.
Here is the example of Ellipsoid Model:
/***********************************************************************/
if (INPUT.DUST_DENSITY_TYPE[dust_counter]==3) {
param1 = 0.5*Dust_Density_Param[dust_counter].param;
param2 = Dust_Density_Param[dust_counter].next->param;
density = x*x + param2*z*z;
density = 1.0 / pow(density,param1);
*err = 0; /* there is no error */
return density;
}
/***********************************************************************/
- Recompile LELUYA and, to use this dust density model, write this in the input file Leluya.inp (in case of n=1.5 and e=0.8):
Dust density type = 3
n = 1.5
e = 0.8
The input data have to be in the directory _2D_DUSTY_RUN_PATH and the output results in _2D_DUSTY_OUTPUT_PATH (see Installation). LELUYA can be started with various flags:
- -s n
Stop flag: a run of the code can be stopped at various positions in the code, marked by a number n. The amount and type of the output data created after these stops depend on the position of stop in the code. This creates output files that can be used later for continuing the run (see -c flag). n is one of the following numbers:
--------------------
1 = stops immediately after the input flags analysis, creates no output
2 or 200 = stops after the analysis of the input data, creates a file 2D-Dusty.dump.STOP2.2dd. This file has all the input data and allows a further running of LELUYA with just this file only.
201 = stops after the initial approximative temperature and energy density are calculated but without the computational grid, creates 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP201.2dd
202 = stops after the initial approximative temperature and energy density are calculated and interpolated over the initial computational grid, creates 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP202.2dd
302 = stops after one radiation transfer iteration finishes, creates 2D-Dusty.dump.STOP3.2dd and
2D-Dusty.dump.STOP302.2dd
- -c n
Continue flag: if a computational run was stopped with the "-s" flag, it can be continued with this flag. The output files created by the stop flag should be copied to the LELUYA's input directory. n is one of the following numbers:
--------------------
2 or 200 = starts a computational run of LELUYA if the file 2D-Dusty.dump.STOP2.2dd exists in the LELUYA's input directory. If the file 2D-Dusty.dump.STOP3.2dd exists, rename it into 2D-Dusty.dump.STOP2.2dd (these two file do not differ, except by the location in the code where they are created).
201 = starts LELUYA if files 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP201.2dd exist (see "-s 201" flag). The computational grid is calculated from the initial temperature and energy density approximations contained in 2D-Dusty.dump.STOP201.2dd
202 = starts LELUYA if files 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP202.2dd exist. The computational grid is NOT created and the grid from 2D-Dusty.dump.STOP202.2dd is used instead. The file 2D-Dusty.dump.STOP302.2dd can be renamed into 2D-Dusty.dump.STOP202.2dd, if we do not want to update the computational grid from a previous iteration.
203 = starts LELUYA if files 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP202.2dd exist. A new computational grid is calculated. The file 2D-Dusty.dump.STOP302.2dd can be renamed into 2D-Dusty.dump.STOP202.2dd, if we want to update the grid from a previous iteration.
4 or 400 = calculate the luminosity at various radii. The luminosity is calculated on a sphere and it should be a constant. It creates files with the flux dependence on azimuth q (for example, Luminosity_flux_r=1.1000E+00.dat), where q=0 corresponds to the symmetry axis. The flux is considered constant between the azimuth of q-Dq- and q+Dq+. Such a file has several columns, with the following order: q, Dq_, Dq+, stellar flux, dust emission flux streaming out of the sphere, emission flux streaming in, dust scattering flux streaming out, scattering flux streaming in, and the total flux (sum of all the flux contributions). Also, it creates the file Luminosity_shells.dat with integrated fluxes over the surface of spheres (luminosity) and these numbers should remain constant with radius.
401 = calculates 2D images (with ray tracing method) and the total flux from the modeled object. A 2D image can have a very complicated structure and it is written in a file named Image-cells-##.#deg.dat, where ##.# is the inclination angle. Also, it creates a 3D VRML model of the cells 2D_Image-##.#.wrl used in this image and the SED for this inclination angle Flux-total-##.#deg.dat. The files with 2D images have a special data format and the images can be plotted by the LELUYA's supplementary programs (Plot_PS_GIF_images.c or Plot_PS_GIF_image.c, but they require PGPLOT in C). If this flag is used without the flags "-A" and "-L" (see below) then the images will be calculated for the inclination angles from 0o to 90o (10o increment) and at all lambda grid wavelengths. (NOTE: this part of LELUYA is still not parallelized, so DO NOT use it with MPI)
402 = calculates a radial temperature profile. It should be used in combination with the "-A" flag which can be used to specify the inclination angle for this profile. It creates a file Radial_Profile_at_theta=####.dat, where #### is the inclination angle.
- -d n
Debug flag: During a computational run of LELUYA, it is good to haver some information about the current status of the computation. This flag switches on the screen messages, and it has three levels n: 1, 2, and 3, each one with more messages than the previous one. (NOTE: Currently, there is a lot of confusion about these debug levels in the code. Use "-d 1" most of the time, and "-d 2" only for the first run before the start of radiative transfer iterations).
- -L n
Wavelength flag: creates a theoretical image at the wavelength n (in microns; it has to be part of the lambda grid). This flag works in a combination with the flag "-c 401". It creates a file named Image-cells-####mic-$$.$deg.dat, where #### is the wavelength and $$.$ is the inclination angle. Use the supplementary program Plot_PS_GIF_image.c for plotting the image (requires PGPLOT in C). If the inclination angle is not specified by the flag "-A", the image will be created for a range of angles from 0o to 90o (10o increment).
- -A n
Inclination flag: creates output data for a given inclination angle of n degrees. If it is used in a combination with the flag "-c 401" then it creates a 2D image Image-cells-##.#deg.dat, where ##.# is the inclination angle n, and a VRML model of the image cells 2D_Image-##.#.wrl. Use the supplementary program Plot_PS_GIF_images.c for plotting the image (requires PGPLOT in C). If it is used in a combination with the flag "-c 402" then it creates a file Radial_Profile_at_theta=####.dat, where #### is the inclination anglen.
The first run should include only the creation of initial computational grid. This is done by using:
LELUYA.exe -s 202 -d 2
The file Leluya.inp has to be prepared in the LELUYA's input directory. The flag "-s 202" creates the files
2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP202.2dd in the output directory. There will be some other files related to the visualization of the grid and input data, like 2DD_interactive_grid_START.vrml.wrl. The debug flag "-d 2" creates some additional files like 2D_dusty.initial_temperature.dust000.polar.html or 2D_dusty.dust_density.dust000.rect.html.
The user should check the computational grid and be sure that it is good enough for the type of a problem and precision that the user wants.
Once the files 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP202.2dd exist, the user can start with the radiation transfer iterations. Currently, the code does not have the radiative transfer loop, thus each iteration has to be started by hand. Anyhow, since the code is still under development, it is a good idea to check the results after each iteration, just to be sure that the result and the grid make sense.
A next iteration can be easily started in two ways: with an update of the computational grid and without a new grid. In both cases, move the files 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP202.2dd to the LELUYA's input directory (note that you do not need Leluya.inp and other input files! All the data is incorporated into 2D-Dusty.dump.STOP2.2dd). If this is a continuation of previous iteration, rename 2D-Dusty.dump.STOP3.2dd into 2D-Dusty.dump.STOP2.2dd and rename 2D-Dusty.dump.STOP302.2dd into 2D-Dusty.dump.STOP202.2dd. After that, you can start the next iteration either with:
LELUYA.exe -c 202 -s 302 -d 1
or with:
LELUYA.exe -c 203 -s 302 -d 1
In the case of "-c 202", LELUYA will not update the computational grid, but rather use the existing grid from 2D-Dusty.dump.STOP202.2dd created in the previous iteration. Actually, if this is going to be the first iteration then use "-c 202" because there is no need for updating the grid.
In the case of "-c 203", LELUYA will create a new computational grid based on the temperature from the previous iteration in
2D-Dusty.dump.STOP202.2dd (this file is renamed from 2D-Dusty.dump.STOP302.2dd). It is a good idea to carefully check the grid from previous iteration, before starting this new iteration. Especially the sublimation surface were you should take a close look. There are some problems with the algorithm for reshaping the sublimation surfaces and LELUYA can crash on this problem.
Thus, run a couple of iterations with "-c 202", until the temperatures converge, and then start with iterations that can change the grid and reshape the sublimation surface. This problem of reshaping the sublimation surfaces, and a convergence of such process, is poorly understood and it is still under investigation.
The radiative transfer modeling is numerically correct if the luminosity is conserved on spheres with different radii within the dust cloud. This can be checked by:
LELUYA.exe -c 4 -d 1
For more details see the manual for "-c 4" flag.
Once we have a radiation transfer iteration finished, and the files 2D-Dusty.dump.STOP3.2dd and 2D-Dusty.dump.STOP302.2dd
created, we can run LELUYA to create 2D images and calculate the fluxes. Keep in mind that this part of the code is still not parallelized and it takes a lot of CPU time to calculate a complete SED for a given inclination angle.
- Rename 2D-Dusty.dump.STOP3.2dd into 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP302.2dd into 2D-Dusty.dump.STOP202.2dd, and move the files into the LELUYA's input directory
- If you want to calculate a complete set of images (and SEDs) for various inclination angles, you can simply run LELUYA with this:
LELUYA.exe -c 401 -d 1
and LELUYA will create a set of files: Flux-total-##.#deg.dat, Image-cells-##.#deg.dat, and 2D_Image-##.#.wrl, where ##.# is the inclination angle from 0o to 90o (10o increment). Use the supplementary program Plot_PS_GIF_images.c for plotting the images (requires PGPLOT in C).
- if the user wants images and SED for only one inclination angle, the run LELUYA with the "-A" flag:
LELUYA.exe -c 401 -A n -d 1
where n is the angle in degrees.
- if the user wants to explore the image at only one wavelength, use the "-L" flag:
LELUYA.exe -c 401 -L n -d 1
where n is the wavelength in microns (it has to be part of the lambda grid!). This will create a set of output files Image-cells-#.####mic-$$.$deg.dat, where #.#### is the wavelength in microns and $$.$ is the inclination angle from 0o to 90o (10o increment). Use the supplementary program Plot_PS_GIF_image.c for plotting the images (requires PGPLOT in C).
- A combination of a fixed wavelength and fixed inclination angle can be very useful for a fast data analysis, since it can be calculated relatively fast. For example, if the model has to explain a given observational image, this can be a fast way of checking the LELUYA's results.
LELUYA.exe -c 401 -L n -A m -d 1
this will create a file Image-cells-#.####mic-$$.$deg.dat, where #.#### is the wavelength n in microns and $$.$ is the inclination angle m in degrees. Use the supplementary program Plot_PS_GIF_image.c for plotting the image (requires PGPLOT in C).
There is one additional flag that can be useful:
LELUYA.exe -c 402 -A n -d 1
This creates a file Radial_Profile_at_theta=#.###.dat with the radial temperature profile along the line of the azimuthal angle q=n.
- Copy the files in _2D_DUSTY_SOURCE_PATH/demo_model to the LELUYA's input direcotry.
- Run LELUYA with:
LELUYA.exe -s 202 -d 2
and get the following list of files in the LELUYA's output directory:
2D-Dusty.dump.STOP2.2dd
2D-Dusty.dump.STOP202.2dd
2DD_interactive_grid_START.data.html
2DD_interactive_grid_START.html
2DD_interactive_grid_START.vrml.html
2DD_interactive_grid_START.vrml.wrl
2D_dusty.Eta.0.550000mic.rect.gif
2D_dusty.dust_density.dust000.polar.gif
2D_dusty.dust_density.dust000.polar.html
2D_dusty.dust_density.dust000.rect.gif
2D_dusty.dust_density.dust000.rect.html
2D_dusty.dust_density.dust001.polar.gif
2D_dusty.dust_density.dust001.polar.html
2D_dusty.dust_density.dust001.rect.gif
2D_dusty.dust_density.dust001.rect.html
2D_dusty.initial_temperature.dust000.polar.gif
2D_dusty.initial_temperature.dust000.polar.html
2D_dusty.initial_temperature.dust000.rect.gif
2D_dusty.initial_temperature.dust000.rect.html
2D_dusty.initial_temperature.dust001.polar.gif
2D_dusty.initial_temperature.dust001.polar.html
2D_dusty.initial_temperature.dust001.rect.gif
2D_dusty.initial_temperature.dust001.rect.html
- copy 2D-Dusty.dump.STOP2.2dd and 2D-Dusty.dump.STOP202.2dd into the LELUYA's MPI input directory, and run LELUYA in the parallel mode:
LELUYA.exe -c 202 -s 302 -d 1