Vés al contingut (premeu Retorn)



text/plain README_dpm.txt — 28 KB

Continguts del fitxer

<---- README for DPM programs  -------------------------------------->
      This file was created on May 2, 2001.


 1) Copyright
 2) Acknowledgement
 3) General
 4) How to install DPM
 5) How to run DPM
 6) Programs
 7) Data files
 8) Parameters and user-defined routines
 9) Sample problem
10) Benchmarks and timings
11) Changes in v1.1

<---- 1. COPYRIGHT  ------------------------------------------------->

Copyright (c) 2000,2001
Polytechnical University of Catalonia

Permission to use, copy, modify, distribute and sell this software and
its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation.  The Polytechnical University of Catalonia
makes no representations about the suitability of this software for
any purpose. It is provided "as is" without express or implied

Copyright (c) 2000,2001
The University of Michigan

Permission to use, copy, modify, distribute and sell this software and
its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation.  The University of Michigan makes no
representations about the suitability of this software for any
purpose. It is provided "as is" without express or implied warranty.

Copyright (c) 2000,2001
The University of Barcelona

Permission to use, copy, modify, distribute and sell this software and
its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation.  The University of Barcelona makes no
representations about the suitability of this software for any
purpose. It is provided "as is" without express or implied warranty.

<---- 2. ACKNOWLEDGEMENT  ------------------------------------------->

We (Scott Wilderman, Josep Sempau and Alex Bielajew) would like to
thank Drs. Dick Fraass, Kwok Lam, Dan McShan and Randy Ten Haken, from
the Radiation Oncology department of the University of Michigan, Dr Ed
Larsen from the Department of Nuclear Engineering and Radiological
Sciences, and Dr. F. Salvat, from the ECM Department of the
Universitat de Barcelona, for fruitful discussions. One of the authors
(JS) gratefully acknowledges the financial support of the Direccio
General de Recerca de la Generalitat de Catalunya (Spain) grant no.
1997BEAI400256 as well as the financial support from the Spanish Fondo
de Investigacion Sanitaria under contract no. 98/0047-01. Financial
support for this work has been provided by ADAC Laboratories
(Milpitas, California). In addition, financial support for this work
has been provided under the auspices of the U.S. Department of Energy
by the Lawrence Livermore National Laboratory under contract number

<---- 3. GENERAL ---------------------------------------------------->

DPM is a computer code that simulates the transport of high energy
electrons and photons using Monte Carlo (MC) methods.

DPM has been designed to deal with radiotherapy-class problems. More
specifically, it is optimized for the calculation of the dose
distribution delivered by high energy (~1 MeV up to ~20 MeV) electron
and photon beams to patients, whose geometries are defined in terms of
a (usually) large number of small volume elements, or voxels. Some
approximations in the description of the physical processes involved
assume that voxels are made of low atomic number materials, such as
water, lung, bone, titanium, etc.

There are 4 programs in the DPM suite. The first one is a slightly
modified version of the program MATERIAL that comes with the general
purpose MC code PENELOPE. MATERIAL extracts raw physics data from
PENELOPE's library of constants, and produces tables and cross
sections for given materials. The second program is a pre-processing
program, PREDPM, that uses PENELOPE data (generated with MATERIAL) and
produces a series of input files for a DPM run. The third program,
GENVOXEL, takes a PENELOPE-style surface/solid geometry file and
creates a voxel-by-voxel list of volume densities for DPM. The fourth
program is the Monte Carlo program itself, DPM.

It is assumed that the user is fairly familiar with Monte Carlo
electron-gamma transport programs. Concepts such as cutoff energies
for secondary particle producing processes and absorption energies are
referenced but not explained.

At some points it is also assumed that the user is running on a Unix
environment. This assumption affects things such as the names of the
executables (e.g. 'dpm.x' as opposite to 'dpm.exe') and the commands
in the make-all file (e.g. 'mv' instead of 'move').

Except when otherwise noted, DPM handles energies in eV and distances
in cm.

<---- 4. HOW TO INSTALL DPM ----------------------------------------->

After downloading and unzipping you should have the following files
under your DPM directory,

readme.txt   ->  This file
*.f          ->  FORTRAN 77 sources
make-all     ->  Combined make file (compile+link) for the 4 programs
*.in         ->  Input files for the sample problem
sample.geo   ->  PENELOPE-style geometry file for the sample problem
sample.out   ->  Results of the sample problem
_pendat/*    ->  Material data
benchmarks/* ->  ICCR2000 benchmark figures and photon spectrum

Now follow these steps:

1) Have a look at 'make-all'. It is provided as a way to show what
   FORTRAN files need to be linked together. 'make-all' is prepared
   for a Linux environment using the GNU g77 compiler with no
   optimization options. Adapt it to your system, invoking your
   FORTRAN 77 compiler and using the best optimization options

2) DPM has been prepared to make use of some time functions in order
   to provide information regarding simulation efficiency after each
   run. However, depending on your operative system and compiler,
   these system functions may not work on your computer or be invoked
   in a way different from the one used by DPM. Therefore, to avoid
   complications in the compilation and link process, all calls to
   time functions are NOT activated by default.

   If you have a GNU compiler and linker you may be interested in
   turning time functions ON at this point. To do so, edit the file
   'time.f' and follow the instructions provided next to each
   occurrence of the string 'opt-Time ON'. If you don't have the GNU
   compiler but you know how to invoke the corresponding functions in
   your system, then you can modify time.f so that each routine
   provides the information described in the corresponding header.

3) Execute

   % make-all

   from the DPM directory. Notice that on an Unix system you may need
   first to change the permissions with

   % chmod u+x make-all

   This step will create four executable files, namely dpm.x,
   predpm.x, genvoxel.x and _pendat/material.x.

You are now ready to go. Proceed to the next section.

<---- 5. HOW TO RUN DPM --------------------------------------------->

Once DPM has been 'installed', follow these steps:

1) Create your DPM geometry file (here named *.vox). In section "Data
   files" the format of a .vox file is presented.

   When the geometry to be described is made of one or several
   homogeneous bodies limited by quadric surfaces (planes, spheres,
   cylinders, etc), the auxiliary program GENVOXEL can be employed. In
   this case, a PENELOPE-style geometry file (*.geo) must be prepared
   beforehand. GENVOXEL will read the .geo file and create the
   corresponding .vox file compatible with DPM for you. GENVOXEL also
   needs an input file (e.g. genvoxel.in). To run,

   % genvoxel.x < genvoxel.in

2) Create your input file for PREDPM (here named predpm.in)

   Two examples of input files, predpm4elec.in and predpm4phot.in, are
   provided. In these two files the values assigned to the simulation
   parameters shigh, slow and ecross are appropriate for the
   simulation of electron and photon therapeutic beams respectively.

   Make sure you have one DPM material file for each material referred
   to in predpm.in. DPM material files are stored in _pendat/. Some of
   the most frequently used materials have already been included in
   the distribution (e.g. Water). Note that the input files provided
   as an example are prepared to generate five materials, namely,
   water, lung (ICRP definition), cortical bone (ICRP), aluminum and
   titanium. If, however, a material is needed and not present, it can
   be easily prepared by running the interactive program MATERIAL,
   from the PENELOPE suite. Notice that this latter program must be
   located in the _pendat/ directory ('make-all' automatically places
   it there).

3) Run predpm.x < predpm.in

   This will create a set of files (with the common prefix specified
   in predpm.in) to be read by dpm. This step needs to be done only
   once for a given set of materials.

4) Create your input file for DPM.

   Material and geometry files are specified by name in the input
   file. An example is provided for the sample problem described below
   (dpm.in). Recall that all the information regarding timings (such
   as "allotted time" in dpm.in) will have no effect if you did not
   activate the routines in time.f (see section "How to install").

5) Run dpm.x < dpm.in > dpm.out

   The result of the simulation will be written to dpm.out after

See section "Sample problem" for more details.

<---- 6. PROGRAMS --------------------------------------------------->

The following FORTRAN 77 files are included,

dpm.f                - DPM source
genvoxel.f           - GENVOXEL source
getnam.f             - program for getting file name prefixes
inscat.f             - routines for sampling Compton angles exactly,
                       taken from PENELOPE
libelastic.f         - library of elastic and multiple elastic scattering
libeloss.f           - library of energy loss and inelastic scattering routines
libgeom.f            - library of simple voxelized geometry programs
libmat.f             - library of routines for working with compounds, etc.
libmath.f            - library of useful math routines
libpenmath.f         - library of useful math routines adapted from PENELOPE
libphoton.f          - library of photon routines, some used by DPM, some by
                       PREDPM, and some for reference
material.f           - PENELOPE2000 material processing program
pbrem.f              - routines to set up accurate bremsstrahlung sampling in
penelope.f           - PENELOPE2000 Monte Carlo and pre-processing library
pengeom2.f           - PENELOPE2000 geometry routines
predpm.f             - PREDPM source
time.f               - Time routines

Note that compiling some of the subprograms which borrow heavily from
PENELOPE with explicit type checking invoked may generate WARNING

1) DPM

DPM is optimized for radiotherapy-class problems as described in
"DPM, a fast, accurate Monte Carlo code optimized for photon and
electron radiotherapy treatment planning dose calculations", Physics
in Medicine and Biology 45 (2000) p 2263-91. DPM 1.1 introduces some
slight modifications in the physics described in this paper.

It reads its input data from stdin and writes to stdout, both of which
are normally redirected to a file, like in

% dpm.x < dpm.in > dpm.out

The file dpm.in provided for the sample problem should be self-

In addition to the input file, DPM also reads a file called
'command.in'. This file contains instructions to be performed by DPM
at execution time, typically to query about the results obtained up to
that moment (which are written to 'progress.out') or to change the
settings regarding the number of histories or the simulation time
requested. In particular, it can be used to stop the simulation at
once. The command file is a self-explanatory plain text file that can
be edited by the user while DPM is running.


GENVOXEL reads a PENELOPE formatted geometry file and converts it into
a plain text 'voxel' file in the format required by DPM.

It reads its input data from stdin, which is normally redirected to an
input file, like in

genvoxel.x < genvoxel.in

The file genvoxel.in provided for the sample problem should be self-

It is necessary to have a PENELOPE geometry file prepared in advance.
Refer to PENELOPE documentation for details. An example for the sample
problem is given in sample.geo. PENELOPE is freely available from NEA.
See http://www.nea.fr


MATERIAL is an interactive program that constructs PENELOPE data files
for given materials. To run,

% material.x

Input material is queried from the command line, and can either be
specified in terms of Z and weight fractions, or can be specified from
a default list of PENELOPE materials. The list is found in

The output file is loaded into _pendat, with a name specified by the
user. Note that this file name must match the material names in the
PREDPM input file (and recall that file names are case sensitive in
Unix!). During the course of execution of MATERIAL, the user will be
recommended that the default values given in the program output be
used for all non-insulating materials. For insulators, these
quantities should be set equal to 0.


PREDPM prepares material data to be read by DPM.

Some local modifications to PREDPM may be required.  In particular
there may be some machine dependencies in the subroutines GETNAM and
GETNAM2, which are found in files inscat.f and getnam.f.  These
routines are used to read in variable length names of materials and
DPM input file prefixes.

PREDPM reads data files that are generated by the PENELOPE pre-
processor MATERIAL (see above).

To run,

% predpm.x < predpm.in

Problem parameters (cutoffs, materials, etc) are specified in the
input file, as described below. A series of output files (DPM data
inputs) are generated, all having the same prefix, as specified in the
input file.

<---- 7. DATA FILES ------------------------------------------------->

Generated by PREDPM

PREDPM generates a set of data files to be read by DPM. See section
"Programs" for more details.

The DPM Geometry file

Its structure is as follows:

FILE BEGINS HERE *********************************************
 HEADER section: DPM geometry file     --> This is a comment line
                                       --> This blank line MUST be here
     61     61    150                  --> No of voxels in {x,y,z} directions
 dxvox,dyvox,dzvox (cm):
  5.000E-01  5.000E-01  2.000E-01      --> Voxel size {dx,dy,dz} (cm)
 Mat#[nx,ny+,nz++] -- dens(g/cm^3):
 1 1.000                               --> 1st column is material no. (following
 1 1.000                                   the order in which they are introduced
 1 1.000                                   in the PREDPM input file). 2nd column is
 1 1.000                                   density.
 1 1.000
 1 1.000                                   Note that the 1st
 1 1.000                                   row refers to the voxel with one corner
 1 1.000                                   in the (0,0,0) position and the center
 1 1.000                                   at (dx/2,dy/2,dz/2); the 2nd row refers
 1 1.000                                   to the voxel centered at (dx/2,dy/2,3dz/2)
 4 2.699                                   and so on. In the example shown, row #151
 4 2.699                                   (there are 150 voxels in the z-direction)
 4 2.699                                   would refer to the voxel centered at
 4 2.699                                   (dx/2,3dy/2,dz/2).
 4 2.699
 2 2.600E-01
 2 2.600E-01
 2 2.600E-01
 2 2.600E-01
 2 2.600E-01

END OF FILE *************************************************

In _pendat/.

penepN.tab     -> electron and positron elemental raw data files for
penphN.tab     -> photon elemental raw data files for MATERIAL
compdata.tab   -> composition and physical parameters for several hundred
idlist.tab     -> list of the PENELOPE ID numbers of the materials in
A150           -> MATERIAL output files for common media, provided for
AdiposeTissue     convenience

<---- 8. PARAMETERS AND USER-DEFINED ROUTINES ----------------------->


The operation of DPM is controlled by the parameters shown in the
table below.

Name    File       Value recommended         Comment
Emin    predpm.in  199.0e3 eV     Minimum e- energy in look-up tables

Emax    predpm.in  21.0e6  eV     Maximum e- energy in look-up tables

Eminph  predpm.in  49.0e3  eV     Minimum photon energy in look-up tables

Wcc     predpm.in  200.0e3 eV     Cutoff energy for delta ray production

Wcb     predpm.in  50.0e3  eV     Cutoff energy for bremsstrahlung production

Eabs    dpm.in     = wcc          Absorption energy for e-

Eabsph  dpm.in     = wcb          Absorption energy for photons

shigh   predpm.in  5.0 cm for e-  Step length for energies above 'ecross'
                   1.0 cm for photons

slow    predpm.in  1.0 cm for e-  Step length for energies below 'ecross'
                   0.5 cm for photons

ecross  predpm.in  12.0e6 eV e-   See 'shigh' and 'slow'
                   5.0e6 eV photons

Notice that shigh, slow and ecross should be given different values
depending on whether one wants to simulate electron or photon beams.
Thus, PREDPM must be run twice for each set of materials, changing the
prefix of the generated data files to avoid confusion. Two different
PREDPM input files, named predpm4elec.in (used for the sample problem)
and predpm4phot.in have been provided with the recommended values.

Note also that all the names of the materials in the PREDPM input file
have to match exactly file names created by MATERIAL in _pendat (i.e.
Water, LungICRU, CorticalBone, etc).


DPM sets the initial state of primary particles in subroutine SOURCE.
As it stands, SOURCE generates monodirectional, monoenergetic
electrons (or photons, depending on the corresponding input in dpm.in)
that impinge on the phantom surface through a square field centered on
the x=y=0 face of the geometry. The side of the field is also defined
in dpm.in.

However, the user may want to define different types of initial
states, e.g. to simulate primary photons with an energy distribution
that reproduces the spectrum produced by an accelerator head. It is
virtually impossible to write a SOURCE subroutine that is able to cope
with all the possibilities that one may think of. Instead, DPM
provides full flexibility by allowing users to write their own SOURCE.
To help in this task, some (commented out) examples of how to code
other initial states are also provided in dpm.f.

In any case, SOURCE must always set the following variables, all
contained in common /dpmpart/,

energy         -> kinetic energy of the particle (eV)
{vx,vy,vz}     -> direction of flight, normalized to 1
{x,y,z}        -> position coordinates (cm)
ptype          -> 0 for photons, -1 for e- and +1 for e+

After setting {x,y,z}, subroutine WHERE must be called. Notice that
the simulated geometry is assumed to lie in the region {x,y,z} >= 0.


Some users may find useful to modify subroutine SCORE in order to keep
track of quantities of interest other than the dose (e.g. particle
fluence) or to define different regions of interest (RoIs). Notice
that, in the default version, SCORE scores only energy depositions
occurring inside a user-defined RoI.


Similarly to SOURCE, subroutine REPORT can be modified to suit the
users needs. In the present version, REPORT prints out the dose
delivered to the voxels inside some region of interest defined by the
user in the DPM input file.

<---- 9. SAMPLE PROBLEM --------------------------------------------->

Follow these steps to run the sample problem,

1) Follow the steps described in section "How to install DPM".

2) From the DPM directory:

% cd _pendat
% material.x  (prepare water --ID # 277 in PENELOPE's list)
% material.x  (prepare aluminum --ID # 13 in PENELOPE's list)
% cd ..
% genvoxel.x < genvoxel.in
% predpm.x < predpm4elec.in
% dpm.x < dpm.in > dpm.out

MATERIAL will create files for water and aluminum which should be
identical, within machine precision, to 'Water' and 'Al'. When
prompted, provide names for output files diffent from 'Water' and
'Al', so that you do not overwrite the files included in the
distribution. This step is done only to exercise the use of MATERIAL.
Once they have been proven identical, you can delete your water and
aluminum files and use the originals instead. Please, notice that file
names 'Water' and 'Al' are case sensitive. These file names must match
the ones in 'predpm4elec.in'. During the course of execution of
MATERIAL, the user will be asked to input "ENERGY AND OSCILLATOR
STRENGTH OF THE PLASMON".  It is recommended that the default values
given in the program output be used for all non-insulating materials.
For insulators, these quantities should be set to 0.

GENVOXEL will create a file 'sample.vox'.

PREDPM will create a series of input files prefixed 'pre4elec'.

DPM should give results (in dpm.out) similar to those found in
sample.out, within statistical uncertainties. Note that if a round-off
difference between the user's machine and the DPM benchmark platform
leads to a different branching in a single IF test in the sample
problem, the subsequent random walks simulated on the two machines
could be completely different.  Thus, as with all Monte Carlo programs
being run on different platforms, exactly matching results should not
be expected.

The report printed corresponds to the central axis depth dose produced
by a 20 MeV parallel e- beam (1.5 x 1.5 cm^2) on a water/Al/water
(2/3/30 cm) phantom. The simulation of the sample problem should take
less than 7 minutes on an Intel Pentium III/733 MHz computer.

<---- 10. BENCHMARKS AND TIMINGS ------------------------------------>

The results of some benchmarks performed with DPM 1.1 can be found
in benchmarks/.

The following files are included:

iccr-e.ps      -> ICCR benchmark for a 20 MeV e- beam
iccr-ph.ps     -> ICCR benchmark for 18 MeV photon beam
water10m.ps    -> homogeneous water, 10 MeV e- beam
water05m.ps    -> homogeneous water,  5 MeV e- beam
ti20m.ps       -> homogeneous titanium, 20 MeV e- beam
ti-ph.ps       -> homogeneous titanium, 18 MeV photon beam

A detailed description of the ICCR2000 benchmark can be found in
http://www.irs.inms.nrc.ca/inms/irs/papers/iccr00/iccr00.html (as of
the time of writing this file). The spectrum used for the simulation
of the photon beam cases can be obtained from the same web page. It is
also available in the file benchmarks/ICCR2000-18Mphot.spc

All benchmarks refer to the central axis depth dose in a 30.5 x 30.5 x
30 cm phantom filled with 5 x 5 x 2 mm^3 voxels. The source position
and field size (and energy spectrum in the photon case --- e- are
monoenergetic) are the same as in the ICCR benchmark.

In all figures,
- Dashed lines represent depth doses calculated with PENELOPE
- Solid green lines are dose differences (DPM-PENELOPE) relative
  to the PENELOPE dose maximum (in percentage).
- Solid black lines (when shown) are dose differences (EGS4-PENELOPE)
  relative to the PENELOPE dose maximum (in percentage).

The table below shows the timings (in seconds) for each case.

CASE        HISTORIES(*10^6)   SIGMA(%)   TIME(s)
--------    ----------------   --------   -------
iccr-e        1.5               0.249      264

iccr-ph       20                0.387      902

water10m      1.5               0.264      100

water05m      1.5               0.260       51

ti20m         1.5               0.260      422

ti-ph         20                0.394     3260

SIGMA refers to the relative standard deviation averaged over all
voxels (on the central axis) having a dose larger than half the dose

These timings were obtained with a PC (AMD K7 processor at 1200 MHz
and 128 MB of RAM) and using the optimization options
g77 *.f -O3 -ffast-math -malign-double -mcpu=i686 -march=i686

It is important to emphasize that DPM does not take advantage of
neighbor voxels being made of the same material. Therefore, very
similar timings can be expected for highly heterogeneous situations,
such as those encountered in some cases in the clinical practice.

<---- 11. CHANGES IN DPM 1.1  --------------------------------------->

Some of the changes introduced in the current version affect the
interface with the user, whereas some other do not. Among the ones
that do affect the interface, the most relevant are

1) The format of the geometry file has been slightly changed. To
   convert an old .vox file to the new format, simply delete the
   following two lines from the header:

        Using predpm set no:

  so that the first 3 lines of the file look like:

        HEADER section: comments go here
                <blank line>

2) In the new DPM, two different step lengths (shigh & slow) and one
   crossover energy (Ecross) are defined (in the input file). 'shigh'
   operates at energies above Ecross, whereas slow is active below.

   Due to the different approach adopted for determining distances
   between elastic events, the same step length parameter will not
   produce the same actual steps in the new and old DPM versions,
   being somewhat shorter in DPM 1.1.

3) All data files generated by PREDPM have to be regenerated with the
   new version. The old format is not compatible with DPM 1.1.

4) DPM calls routines contained in time.f which are compatible with
   the GNU FORTRAN 77 compiler, but may not be supported by your
   system. To deactivate these calls, just edit time.f search for the
   string "opt-Time OFF" and follow the instructions provided.

5) Subroutine REPORT prints out the dose delivered to a region of
   interest defined by the user in the DPM input file.

Other changes:

6) The PENELOPE bremsstrahlung DCS has been activated by default.
   Thus, the routines lambre() and stpbre() have been substituted by
   plambr() and pstpbr() respectively.

7) A more accurate method to calculate the rate at which the
   bremsstrahlung fuel is burnt (instead of assuming that it is
   constant with E) has been introduced by default. This implies
   frequent calls to routine ilabip(), which interpolates the inverse
   bremsstrahlung MFP as a function of material and energy, thus
   incrementing the time spent to simulate each history. However, the
   improvement observed in some extreme cases (i.e. 20 MeV e- on Ti)
   provides the motivation.

8) The accuracy with which elastic fuel is burnt has been improved (in
   routine flight()). With the new procedure, the distance to the next
   scattering event is much less dependent on factors such as voxel
   size. The cost of this improvement is more calls to routine
   scpwip(), which interpolates the inverse 1st transport MFP
   (scattering power).

9) To somewhat compensate for the former changes, the following
   routines have been optimized:

   rstpip (stopping power)
   ilabip (bremsstrahlung mean free path)
   scpwip (scattering power)

   Now linear interpolation is used instead of 3splines.

10) The routines electr() and flight() have been optimized.

11) Small changes (mainly aesthetic or to improve speed) to other
   routines in dpm.f and its libraries (such as rotate) have been
   introduced. libelastic.f and libmat.f have been reviewed.

12) The way in which the spreading parameter and the q surface are
   obtained by PREDPM has been changed. Goudsmit&Saunderson theory is
   now used instead of Lewis'.

   The former produces a much faster predpm and gives practically the
   same dose distributions because in both cases the relevant quantity
   is the accumulated scattering strength (defined as the integral of
   the inverse 1st transport MFP (lambda_1^{-1}) over the step
   length), which determines the first term in the respective series.

13) An option that allows using a different q surface for each
   material has been introduced (NOT active by default). This implies
   that predpm.f calculates now the spreading parameter and the q
   surface for every material in the input file. To activate this
   option, search for the string "opt-qSingleMat" and follow the
   instructions provided.

BUGS fixed.

14) A bug in rvoxg() has been corrected. The density was set to the
   value assigned to the reference material, irrespective of the
   values read from the .vox geometry file.

15) A factor Z(Z+1) was incorrectly plugged into the bremsstrahlung
   routines. It should be Z^2.

**** END OF FILE *****************************************************