Monte-Carlo Potfit Documentation

General Remarks

Monte-Carlo Potfit (or MC-Potfit) is a variant of the traditional Potfit where the integrals over the complete primitive grid are replaced by Monte-Carlo integrals. This on the one hand enables the use of larger potentials, but on the other hand also introduces a statistical error into the resulting natpot which is hard to control. However, the error can be estimated again by statistical methods.

It should be noted that the Monte-Carlo integration error manifests mainly in an integral over the residue potential (the part not represented by an optimal natpot once the SPP are determined). In Particular this means: if the potential can be completely expressed in the SPP basis obtained by MC-Potfit in the first step, then also the obtained natpot file will be numerically exact. If this is not the case, that is, if the SPP cannot represent the exact potential, one needs to keep in mind that the role of the SPP is actually to interpolate the potential between the Monte-Carlo ponts which were used to calculate the coefficients. This can lead to a paradox situation that the total error of the fit can increase if more SPP are used and the number of Monte-Carlo points is not increased appropriately.

A great advantage of using Monte-Carlo techniques is that correlated weights are implemented straight forwardly by means of the sampling density, i.e., the distribution of the sampling points. At present, generating a uniform distribution and a Boltzmann distribution using a Metropolis algorithm are implemented. Furthermore, external samplings can be read in and used for generating natpot files.

MC-Potfit does not yet support all features of the original Potfit. Implemented features are outlined below. Another difference is that the internal structure of the resulting natpot file is somewhat different from the original Potfit. A contracted mode is not mandatory. When creating the natpot file, however, there will be an retrospectively contracted mode for compatibility reasons.

Usage and command line options

Monte-Carlo potfit is called as other programs of the package from he command line. With the command
mcpotfit84 -h
a help text is printed: 

  Purpose: creates a natural potential fit.
    Usage:  mcpotfit<vers><d> [-h|-?]  [-ver -rd -w -D name] inpf
     vers:  program version (e.g. 84 for version 8.4)
        d:  indicates debug version
     inpf:  input file (with or without extension ".inp")
     optn: -h   : print this help-text.
           -?   : print this help-text.
           -ver : Version information.
           -rd  : Reading of the dvr-file is enforced.
           -w   : overwrite enabled.
           -D name: 'name' denotes the directory where files are
                    written to, (name in ~.inp file ignored).

     The order of the options does not matter, but "inpf"
     must be the last argument.

Sections

General Remarks

As in other programs of the Heidelberg MCTDH package, the input file is organized in sections, where the section XYZ starts with the keyword xyz-section and ends with end-xyz-section. At present, the MC-Potfit input may contain three or four sections, as listed below. Those with a STATUS of C are compulsory, O marks optional sections.

XYZ Status Description
RUN
C
Defines general parameters, most importantly the Monte-Carlo samplings.
OPERATOR
C
Which surface to be used, energy cut-offs.
PRIMITIVE-BASIS
O
Definition of primitive basis. Optional if an external DVR file is specified in the RUN-SECTION.
NATPOT-BASIS
C
Size of natural potential basis, optional contracted mode, etc.

Below, tables of keywords are given for the input sections.

The following tables describe the keywords. The number and type of arguments is specified. The type is S for a character string, R for a real number, and I for an integer. For instance, 'keyword = I,R[,S]' indicates that the keyword takes two or optionally three arguments where the optional argument is indicated by square brackets. Here, the first argument is an integer, the second a real number, and the optional third one a character string. The status column indicates whether the keyword is compulsory, C, or optional, O.


Run-Section

Keyword Status Description
name = S
C
The output files will be written to the directory S. Note: If the -D name option is used (see To Run the Program), the name-string given in the input file is ignored.
title = S
O
The string S is taken as the title of the run and printed to the log and output files. Note: everything that follows the equal sign '=' till the end of the line is taken as title!
readdvr (= S)
O
The DVR information will be taken from the DVR file in directory S. Note that the primitive-basis-section of the input file is completely ignored if this keyword is given. A DVR file residing in directory S will NEVER be overwritten or deleted, even if the keywords deldvr and/or gendvr have been specified. If S is not given, name-directory/dvr is assumed.
gendvr
O
The DVR file will be generated unconditionally. (This is the default)
deldvr
O
The DVR file will be deleted at the end of the calculation.
overwrite
O
Any files already in name directory may be overwritten. (It is safer not to use overwrite but the option -w).
output = S
O
The output will be written to the file name/output. The string S may take the values short or long. When long is specified, additional information on grids and weights are printed. short is default, i.e. output is equivalent to output=short .
Note: output is default.
dvronly
O
The program generates the dvr file and then stops.
timing
O
Program timing information will be written to the file name/timing   (default).
no-timing
O
The timing file is not opened.
no-OMPpotential
O
If openMP parallelization is used with this flag no calls to the PES routine are performed in parallel. This is useful if the PES routine is not thread safe.
no-omega
O
Do not allocate the SPP-configuration-sampling matrix Ω which is needed to calculate the coefficients, but calculate it on the fly as needed. This saves considerable amounts of memory but also takes considerably longer, especially for large sampling sets. Dimensions of Ω: (Nsample-coeff × Nconfig) where Nconfig is the product of the number of SPP given in the NATPOT-BASIS-SECTION. Default: not set.
no-omega-t
O
Do not allocate the transpose of the SPP-configuration-sampling matrix ΩT. ΩT is in this case calculated on the fly as needed. This saves considerable amounts of memory but also takes considerably longer, especially for large sampling sets. Note: ΩT is only allocated and used when invert-method = conjgrad is set, see below. Default: not set.
no-omega-spp
O
Do not allocate the grid-sampling matrix ΩSPP for calculating the reduced density matricies of the potential. This saves considerable amounts of memory if the (combined) modes hava large grids, but it also takes considerably longer, especially for large sampling sets. Default: not set.
density = S
O
 If the reduced densities of the modes are calculated (and not read-in, see below) the densities are stored in a file such that they can be re-used in a later run if for instance more coefficients are needed. The density keyword describes the format of the file. S can be either ASCII or binary, where binary is default. The ASCII format is usefull if a visualization of the densiy, for instance with gnuplot is desired. The density keyword is ignored if the reduced densities are read-in. In this case the format is determined from the files directly.
invert-method = S
O
 Method used to invert the overlap matrix. S can be one of direct or conjgrad. When direct is selected, the overlap matrix (ΩTΩ) es explicitely calculated and inverted using the LAPACK DPOSV routine. If conjgrad. is selected, a conjugate gradients method is used that avoids explicit calculation of the overlaps. Default is direct.
cg-tolerance = R
O
 When invert-method = conjgrad is used, cg-tolerane is the value of the error-estimate. Default 1.E-12
cg-maxiter = I
O
 When invert-method = conjgrad is used, then at most I iterations are used to achieve the requestes error-estimate. Default 1000.
sampling[-S1] = S2, I1 [,I2, I3, R [,S3]]
C
The sampling method and the number of sampling points to use. See remark below .
sampling-only
O
Do not create a natpot file but only calculate the sampling points and exit.
same-sets
O
Use the same set of sampling points for all tasks. remark below .
iseed = I
O
Calculates the initial random seed from I. If not set, the random seed is calculated from the system time. .
substract-pes = S
O
Substract a potential stored in a PES file (created with the -pes option of MCTDH) from the potential that is defined in the OPERATOR-SECTION. S is the full path to a PES file.

This option is useful if one already has an approximate description of the potential (for instance a cluster-expansion) and only wants to produce a natpot of the difference to the exact potential. If substract-pes is given, then the OPERATOR-SECTION itself may not use the "pes-file" option but only "usersurf" or built-in surfaces from the MCTDH operator library.

Sampling methods

Monte-Carlo samplings are used for tree different purposes in MC-Potfit:

  1. generation of the reduced densities, of which the eigenvectors are the SPP,
  2. subsequent calculation of the coefficient vector,
  3. and finally testing the natpot file.
The sampling[-S1] keyword can be used to assign different sampling methods and sampling sizes for these different tasks. The suffix S1 is an optional string that specifies the particular task a sampling method is used for. S1 can be omitted. In this case the same sampling method and ensemble size are used for all three tasks. Note, that the actual sets of sampling points will be different for all tasks unless one also provides the same-sets keyword. The following specifications are possible: sampling[-S1]
sampling-spp
sampling for generating the reduced densities of which the SPP are the eigenfunctions.
sampling-coeff
sampling for calculating the coefficient vector and the overlaps of the SPP with the potential routine.
sampling-test
sampling to calculate mean and RMS values of the natpot error.
sampling
sampling for all the above tasks with the same sampling method.
If the calculation is a new run, either sampling or sampling-spp and sampling-coeff must be given. The test sampling is optional and only used to estimate error measures of the potfit. A test is in any case performed with the sampling used for calculating the coefficients.

If the run is a re-run of a previous calculation one can also skip the SPP sampling. In this case the SPP are calculated from previously stored density matrices. If sampling-spp is anyhow specified, the density matrices are re-calculated. Note, that if the densities are read in, at present only the grid dimensions are checked. It is not checked weather the density represents a valid representation of the given mode. That is, interchanging modes in the NATPOT-BASIS-SECTION will not lead to an error if the combined grids of the modes have the same sizes.

The first argument of the sampling[-S1] keyword is the sampling method, followed by a set of parameters. Possible sampling methods - with parameters - are:

uniform, I
Uniform sampling: each grid point is chosen as a sampling point with the same probability. The integer I defines the total number of sampling points
metropolis, I1, I2, I3, R [,S3]
A Metropolis algorithm is used to generate I1 sampling points. The sampling points are selected from a random walk on the total grid. The initial starting position of the walker is a random point on the primitive grid. Therefore the first, I2 initial steps of the random walk can be skipped before any sampling points are recorded (burn-in). The integer I3 specifies that only every I3th accepted Metropolis-step from the random walk is actually used as a sampling point. This means that I3-1 of accepted Metropolis-steps are skipped and not used. This reduces the correlation between subsequent sampling points. If I3=1 then all accepted Metropolis-steps (after burn in) are used. R defines the temperature (times the Boltzmann konstant, so R is actually an energy) used to create a Boltzmann distribution. It may bear a unit defined by S3. Default unit is au.
readidx{/path/to/indexfile} [,I1 [,I2 [,I3]]]
The sampling points are read from an ASCII file, of which optionally only the first I1 data points are used. If I2 is given the first I2 sampling points are skipped before I1, sampling points are read. If also I3 is given, then I2 sampling points are skipped and of the remaining sampling points only every I3th point is used until I1 sampling points are read in. If I3 == 1 no sampling points are skipped, in which case I3 might as well be ommited. If no intergers are given all data points from the file are read in. The file must contain integers separated by spaces defining the DVR grid index with one sampling point per line.
Note: By default, even if the same sampling method with the same parameters is used for all sub-tasks, for each of the sub-tasks a different set of sampling-points will be created. There are two exceptions, however: 1) if readidx is set, the same sampling points will be extracted for all tasks. 2) If the keyword same-sets is set in the RUN-SECTION the usage of the same sampling points for all tasks is enforced.

The following examples demonstrate the use of the sampling[-S1] keyword.

Example 1

  1. Uniform sampling with 10000 points for generating the SPP
  2. Metropolis sampling with 10000 points created with a temperature of 400 wave numbers. Furthermore the first 1000 sampling points are skipped and then only every 10th sampling point is used for the trajectory. So altogether 101000 points are generated of which 10000 are used for calculating the coefficients.
  3. For testing the natpot, an external file containing the dvr-index is read in. From this file, only the first 15000 data sets are used.
    sampling-spp   = uniform, 10000
    sampling-coeff = metropolis, 10000, 1000, 10, 400.0, cm-1
    sampling-test  = readidx{/path/to/indexfile}, 15000
Example 2

Uniform sampling with 10000 points for generating the SPP, the coefficients and also for testing the natpot. The sampling points will be different for the three individual tasks, only the method of their generation is the same. 

    sampling = uniform, 10000
Example 3

Uniform sampling with 10000 points for generating the SPP, the coefficients and also for testing the natpot. The sampling points will be the same for all three individual tasks. 

    sampling = uniform, 10000
    same-sets


Natural-Potential-Basis-Section

For the Natural-Potential-Basis-Section the same roles as in the Natural-Potential-Basis-Section of Potfit apply. There is one important difference, though: a contracted mode is not mandatory. A number of SPP can be set for every mode. For compatibility, one of the modes will be retrospectively contracted in the natpot file. This will be the mode that causes the smalled increase in memory usage.

Operator-Section

Keyword Status Description
pes = S {pesopts}
C
S can be either the keyword "usersurf" in which the program assumes that the potential energy routine has been implemented in the file $MCTDH_DIR/source/potfit/userpot.f90 or it can be the name of a potential energy surface which has been encoded in the mctdh package.
A third option is pes = pes-file{path/to/pes} in which case an existing operator file is re-fitted.
The first option has been provided to allow easy implementation of user provided routines using a Fortran 90 interface. Note, that options from the input file are not supported in this case, i.e, there must not be any {pesopts}.

In case that a potential energy from the MCTDH library the name is interpreted in a case sensitive manner. If a surface depends on additional parameters, one can change the encoded default values by adding those parameters via the string '{pesopts}'. Parameter names specified within the braces '{}' are processed in a case sensitive manner. The selected surface determines which parameter names are possible. For a description of the available surfaces see Hamiltonian Documentation -- Available Surfaces. Note that fitting 'vpot' files is not supported at present.

Example:
For the lsth surface use 'pes = lsth {tfac = 0.5d0}'. tfac is a mass-dependent parameter which is needed to transform between binding and Jacobian coordinates. Let r1,r2, and r3 denote the binding and rd,rv, and theta the Jacobian coordinates. Then the transformation rules are as follows:

2D:
  r1=rd-tfac*rv
  r2=rv
3D:
  r1=sqrt(rd**2+(tfac*rv)**2
          -2d0*tfac*rd*rv*ctheta)
  r2=rv
  r3=sqrt(rd**2+((1d0-tfac)*rv)**2
          +2d0*(1d0-tfac)*rd*rv*cos(theta))

For a homonuclear diatomic molecule tfac=0.5d0, in general tfac=m1/(m1+m2). rv denotes the distance between the two atoms of the diatom, rd the distance between the third atom and the center of mass of the diatom, and theta the angle between rd and rv.

Note: tfac is not used if binding coordinates are selected for a calculation.
vcut < R
O
Energy cut-off for exact potential energy surface. All potential energy values greater than R are set to R.
vcut > R
O
Energy cut-off for exact potential energy surface. All potential energy values less than R are set to R.


Primitive-Basis-Section. Ordering of arguments

The primitive basis is defined in the same way as it is done in the input file of an mctdh run (see the MCTDH Primitive-Basis-Section ). As for the traditional Potfit, there is, however, one important difference. The order of the degrees of freedom defines the ordering of the arguments passed to the potential routine. To see, how a particular pes from the MCTDH library is implemented see the file funcsrf.F (just type   mcb funcsrf.F ). Inspect also the log-file log, which is created when running potfit. There one finds a message like: 

BKMP2 PES : 3D model in Jacobian Coordinates
Dissociative Coordinate : rd
Vibrational Coordinate  : rv
Angular Coordinate      : theta
A line like Dissociative Coordinate : theta would hint to a wrong ordering of the degrees of freedom in the Primitive-Basis-Section.
The arguments passed to the potential routine may be reordered with the aid of the order keyword of the Operator-Section.
NB: In MCTDH the ordering of the degrees of freedom in an HAMILTONIAN-SECTION (i.e. the ordering of the mode-line) must be consistent with the potential definition. There the ordering within the Primitive-Basis-Section is arbitrary.


Example input


Output files

natpot
File containing the potential fit in MCTDH compatible format. See also Potfit documentation. In case no contracted mode is specified in the input file, the mode which leads to the smallest increase of the file size, is retrospectively contracted. This does not lead to a loss of precision.

natpot_t
File containing the potential fit in the native format of mcpotfit. To see the file format type mcb save_natpot_t.

dvr
See MCTDH output documentation

output
The output will be saved to file or written to the screen, depending on the output keyword in the Run-Section. It contains some standard results like the "Natural weights" (see the MCTDH review for this) for all the modes. It also prints, after Monte-Carlo testing, the mean and RMS errors of the fit. Finally, total CPU-time, host, date and time, path of the name-directory and (if specified in the input) the title of the run are printed.

input
This is a copy of the input file used with the program version progver and the list of options (if any given) added.

log
This file contains information about the type of calculation performed, the potential energy surface used, memory sizes, arrays that have been allocated, opened data files and error messages - if any. The most important thing in this file is to check the labelling of the parameters of the coordinate system used which should be consistent with the arguments of the potential energy surface used.

timing
This file contains various timing statistics of the potential fitting run. For each subroutine, the number of times the routine is called, the total CPU time (user and system) spent in the routine and in all subroutines below it are listed, as well as the CPU time per function call.

dvrindex-spp
This file contains the integer indices of the dvr grid points that were used as sampling points to generate the SPP. Each line in this file represents one sampling point. The index is given in the same order as the DOF in the PRIMITIVE-BASIS-SECTION

dvrindex-coeff
Same as for dvrindex-spp, but contains the sampling used for obtaining the coefficients.

dvrindex-test
Same as for dvrindex-spp, but contains the sampling used for testing the natpot against the PES routine.

dvrindex
Same as for dvrindex-spp, but in case of the keyword same-sets in the RUN-SECTION the indices of the dvr grid points for all, SPP, coefficients and testing. Since the sampling sets are the same for all tasks in this case there is no need to store them separatly.

energies-spp
This file contains the single-point energies obtained from the sampling stored in dvrindex-spp. One energy per line obtained from the PES routine.

energies-coeff
Same as energies-spp, but for the coefficients.

energies-test
Same as energies-spp but for the set that was used for testing the natpot against the PES routine.

energies
Same as energies-spp but in case of the keyword same-sets in the RUN-SECTION the single-point energies obtained from the sampling stored in dvrindex. As for dvrindex there is no need to store the energy of the same sets several times.


Troubleshooting

  1. When using OpenMP parallelization there is a segmentation fault!
    Try setting and/or increasing the OMP_STACKSIZE environment variable.

  2. When using OpenMP parallelization I see much less CPU usage then theoretically possible!
    Try setting OMP_SCHEDULE="dynamic,1". Also, if the CPUs support hyper-threading, try setting the OMP_NUM_THREADS environment variable to 1.5 times the number of CPU cores. To our experience this value gives the best performance.

  3. My results are garbage when using parallelization!
    Is the PES routine thread-safe? Try the no-OMPpotential keyword in the RUN-SECTION.

  4. I get different results for different runs with the same input!
    This can have different reasons: