Potfit Input Documentation

General Structure

The input file is divided into sections containing information for the various parts of the program. The sections of the input file may appear in arbitrary order. All input is based on keywords with arguments. The input file ends with the keyword end-input.

Upper and Lower Case Characters

Certain parts of the input are processed in a case insensitive manner whereas others are interpreted in a case sensitive way. In general, all upper keywords are internally converted to lower case characters. Therefore any mixture of upper and lower case characters, e.g. EnD-iNPuT is permitted on input for keywords. However, certain strings like

are interpreted in a case sensitive manner!

Special Characters

All lines containing only blanks and/or hash marks '#' are ignored. All keywords that start with an exclamation mark '!' are ignored. Any text following a hash mark '#' is ignored till the end of the line. Any line which begins with five minus-signs or underscore-signs is ignored.

Keyword Placement

In general, keywords are specified in a free format. They are separated by blanks or semicolons. Hence, the lines

keyword1 keyword2
keyword1 ; keyword2

are all valid.

However, keywords specifying a block-structure like run-section must be the only one in a line. The same holds for the keywords in the Primitive-Basis-Section and the Separable-Weight-Section . Otherwise, the order and placement of the keywords within a section is arbitrary.

Arguments to Keywords

If a keyword requires arguments, these are normally indicated by an '=' symbol, and divided by ',' symbols. Brackets '(' ')' as well as spaces can also be used to help readability. e.g.

keyword = arg1 , arg2,...
keyword = (arg1 , arg2,...)

are all possible formats.

The arguments are optional in most cases. The equal-sign '=' and/or the comma ',' indicates that the keyword following it is an argument. Each of the three lines given below is a correct example input line

output psi timing
output psi = double timing
output psi = double, natur timing
output psi = (double, natur) timing

since the keyword psi "knows" the arguments double and natur . However,
output psi = double, timing
is an incorrect input line, because timing is not an argument of psi but a keyword of its own.

Note that if a keyword has several arguments the program is likely to accept only one unique sequence.

In some cases there is no '=' following the keyword and there are no commas separating the arguments. In addition, the sequence of the arguments is fixed in these cases. This input format is used in the Primitive-Basis-Section and in the Separable-Weight-Section .


Units are specified in the same manner as in the MCTDH input Units.


General Remarks

The section XXX starts with the keyword xxx-section and ends with end-xxx-section.

The various sections are listed below. Those with a STATUS of C are compulsory, O marks optional sections.

XXX Status Description
Whether iteration is started, whether to read DVR information, what files are to be opened, etc.
Which surface to be used, coordinate systems, energy cut-offs, subtraction of one-dimensional potentials, etc.
Definition of primitive basis.
Size of natural potential basis, contracted mode, etc.
Definition of separable weights.
Definition of correlated, i.e. non-separable, weights.

Below, tables of keywords are given for some input section.

A first table describes 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 = S,R' indicates that the keyword takes two arguments, the first is a string, the second a real number. The status column indicates whether the keyword is compulsory, C, or optional, O.

A second table defines the default values for optional keywords and arguments.


Keyword Status Description
name = S
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
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!
niteration = I (,I1)
(Can be abbreviated to niter.)
I denotes the number of iteration steps to be performed. I<0 enables the interactive mode where the user is prompted for the number of iterations. If this keyword is not provided, no iteration steps are performed. A Correlated-Weight Section is then ignored. Note that iterations are useless, if there is no Correlated-Weight-Section.
The (optional) second argument, I1, allows to reduce the number of evaluations of the fit error during iteration. These evaluations are quite costly for large grids. The fit error is evaluated for iterations which are integer multiples of I1. The error of the last iteration is always evaluated.
iteration-factor = R
R denotes a factor, with which the weights are multiplied when iteration steps are performed. Values of R<1 will be ignored, values of R>2 usually lead to divergence. Values like 1.6 ≤ R < 2 are recommended to speed-up the iteration process.
buffer = I
Maximum size (in Mb) of the buffer used when reading the vpot file. Default is 64 Mb. The program is slightly faster, when the buffer can load the full potential at once. Compare vpotdim and niobuf which are recorded in the log file.
readdvr (= S)
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.
The DVR file will be generated unconditionally. (This is the default)
The DVR file will be deleted at the end of the calculation.
readvpot (= S)
The vpot file S will be read. S will never be overwritten or deleted irrespective of all other keywords. "readvpot" differs from "readdvr": First, S is a FILE, not a directory. Second, the potential parameters written at the head of file S do NOT overwrite the parameters found in the .inp file. Instead, both sets are compared to each other. If they are not identical, the program stops with an error message. The same happens if the vpot cannot be read. If S is not given, name-directory/vpot is assumed..
The vpot file will be generated unconditionally. A vpot file specified via the "readvpot" keyword, however, will never be overwritten.
The vpot file will be deleted at the end of the calculation unless it has not been specified via the "readvpot" keyword.
(Can be abbreviated to wo.)
"write only" mode. In this mode only the potential on the product grid is calculated and writen to the vpot file. No fitting is done, hence the memory consumption is rather low in this mode.
(Can be abbreviated to sp.)
The potential is stored in a single precision vector v and written in single precision to dik. Thus, for large grids the memory and disk space consumption is cut down by a factor of two whereas the CPU time remains nearly unchanged.
Any files already in name directory may be overwritten. (It is safer not to use overwrite but the option -w).
After every iteration the potential fit will be written to disk. File names are `natpot.iii' where iii is the number of the associated iteration. `natpot.000' contains the initial fit. Useful for fits with long run times and unknown total number of iterations.
output = S
The output will be written to the file name/output. If this keyword is omitted, output will be to the screen. 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.
The output will be directed to the screen, no output-file is opened. Alternatively to screen one may give the keywords no-output or nooutput.
Some error measures will be written to the file name/iteration.
If a Separable-Weight-Section has been specified, separable weights will be written to the file name/prodwei.
Program timing information will be written to the file name/timing   (default).
The timing file is not opened.
pestiming = I
Special program timing information concerning the calculation of the exact potential and the potential fit will be written to the file name/ptiming (see timer labels vextiming and fittiming ). Ignored if the timing keyword has not been set. If I is > 0 the exact potential and the potential fit are calculated I times over the full grid.

For more details on the format of the various data files see the Potfit Output Documentation.

A normal run allocates a single double precision vector v of full grid size which holds either V'=(V-V1d)*SW or the modified reference potential (MRV) (the latter case occurring during the iterations if a correlated weight is applied). Here, V is the exact potential, V1d denotes an optional 1D potential, and SW is an optional separable weight. Two additional work vectors are allocated, the largest of which has a size reduced by a factor of MAX(GDIM(f)/POTDIM(f)) as compared to v. Here, f runs over all degrees of freedom. The most important steps can be vectorised with this set of vectors. The "raw" potential on the product grid is written to a file "vpot". In a following invocation of potfit in the same directory the program looks for the "vpot" file and, if the latter exists, reads the parameters which precede the potential data. If both sets coincide, the potential is read from the vpot file instead of being recalculated. If the two sets differ, a warning message is issued and the "vpot" file is recreated (just like a dvr file). During a given run, V is loaded several times from the "vpot" file into the vector v. Memory may be saved by using the "single-precision" keyword.


Keyword Status Description
pes = S {pesopts}
S is the name of a potential energy surface which must have been encoded in the mctdh package. 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/Liouvillian Documentation -- Available Surfaces. If you want to fit a vpot file that was created by a different program (e.g. adproj or projection) use the "pes = none" option. This means that potfit uses only the vpot file and does not look for a potential energy surface.

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:


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 centre 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.

oned_S1 = S2
Subtraction of the one-dimensional potential S2 for the degree of freedom with modelabel S1. S1 and S2 are interpreted in a case sensitive manner and must exactly match the name of a mode as specified in the Primitive-Basis-Section and a one-dimensional potential curve encoded in the mctdh package.
order = S/I
order defines the ordering of the variables passed to the potential routine. If S=dof, then the ordering is as in the PRIMITIVE-BASIS-SECTION. Note that this is the default, order=dof need not to be given. If S=mode (or S=particle), then the ordering is as in the NATPOT-BASIS-SECTION. Finally, one may give a blank separated list of integers, which define the ordering with respect to the dof-ordering.
E.g.:     order = 3 1 2
passes the third dof as the first argument to the potential routine. The first dof becomes the second and the second dof the third argument. The arguments of order must be a permutation of the numbers 1...ndof. See the log-file to inspect if the order is correct.
NOTE: order DOES NOT work for readsrf.
vcut < R
Energy cut-off for exact potential energy surface. All potential energy values greater than R are set to R.
vcut > R
Energy cut-off for exact potential energy surface. All potential energy values less than R are set to R.
cspot = R1,R2,R3
Whether an additional centrifugal potential of the following form is added to the potential energy surface (so far only installed for the 3D LSTH-surface in Jacobian coordinates):

where R1 denotes jtot, R2 denotes K and R3 denotes mass_rd. 'cspot' is compulsory if option '-jtot' has been specified on the command line.

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 ). 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 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 reorderd 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.


The input defines for each degree of freedom the modelabel, the number of natural potentials to be used in the product expansion and whether a one-dimensional potential should be subtracted. Exactly one mode must be chosen as contraction mode. No special sequence of the modes is required in this section.

The format for each degree of freedom is

mode_label = I, contr

where I is the number of natural potentials which is not allowed to be greater than the number of primitive grid points in this degree of freedom. The order of the arguments is arbitrary. Exactly one mode must be defined as contracted mode, i.e. must have as argument contr. For the contracted mode, the number of natural potentials, I, is usually omitted. In this case, I is set to the largest possible value (= number of grid points specified for this mode in the Primitive-Basis-Section). More than one mode definition can be written on a line.
Two or several degrees of freedom can be combined into a single mode in the same way as it is done in MCTDH. (See the MCTDH   SPF-Basis-Section). If the resulting natpot file is used in a mctdh run the degrees of freedom combined in potfit must also be combined in the spf-basis-section (in same order!). Assume that there is the following combination scheme, indicated by braces {}:

  MCTDH: {r1,r2,r3} {r4,r5,r6}
Then the following combinations are allowed in potfit:
  potfit: {r1,r2,r3} {r4,r5,r6}
  potfit: r1, r2, r3 {r4,r5,r6}
  potfit: {r1,r2,r3} r4, r5, r6
But the following potfit combinations are not consistent with the above MCTDH combination scheme:
  potfit: {r1,r2,r3} {r4,r5} r6
  potfit: {r1,r3,r2} r4, r5, r6


For a 3-mode system, with labels rd, rv, and theta, to define a basis with 10 natural potentials in the second, and 6 in the third mode, which is contracted over the first mode, the natpot-basis-section reads:

rd = contr
rv = 10
theta = 6


rd = contr    rv = 10    theta = 6

To contract the degrees of freedom rd and rv into a single mode:

rd, rv = contr
theta = 6


rd, rv = 10
theta = contr


The definition of the separable weights is written one line per degree of freedom. The input is free format with blanks dividing the various parameters. The format for each line is

mode_label   weight_type   para1, para2, ...

mode_label is an alphanumeric string attached to the degree of freedom. This must match one of the labels defined in the Primitive-Basis-Section . The specification of the modes is not subject to any specific order. weight_type is an integer denoting the functional form of the one-dimensional separable weight function. Depending on weight_type a number of parameters must be provided in order to define the separable weights. Where appropriate, energy or length units may be appended to the numerical parameters.

The parameters to be input depend on the weight_type as follows:

Weight Type Parameters and Functional Dependence
0   w=1
1   w=(q/(para1+q))**4
2 para1=name w=(1/(1+((wpot(q)-wpot_min)/para2)))**para3
3   w=exp(-para2*(q-para1)**2)
4   w=cos(0.5*(q-para1))
5   w=0.5+1/Pi*atan((q-para1)/para2)
6 obsolete  
7   w=0.5-1/Pi*atan((q-para1)* tan((0.5-para3)*Pi)/para2)
8   w=1-(1-para1)*sin(q)**2
9   w=cos(q-para1)**2+para2

For weight_type=2, name represents the name of the 1D potential used for the weight, i.e. for wpot. This potential must be chosen from the same collection as the one specified via string S2 with the keyword oned in the Operator-Section. wpot_min represents the minimum of wpot on the grid points. The minimun is calculated by the program.


In this section one can specify correlated, i.e. non-separable, weights. The correlated weight is either zero or one, and it is thus sufficient to specify the relevant region, i.e. the region where the weight is one. The relevant region is defined through inequalities, limiting either the coordinates directly or through the energy they represent.


v < -1.0,eV         # Energy bound defining relevant regions.
                    # Gridpoints associated with energies > -1.0eV
                    # have zero weights.
v > -5.0,eV         # Meaning similar as above.
rd < 6.54           # Coordinate cut-offs defining relevant
rv < 3.74,au        # regions. Instead of "<" the symbol ">"
                    # is also valid having the opposite meaning.
theta < 0.9,sin     # Only gridpoints with sin(theta) < 0.9 and
theta > -0.8,cos    # cos(theta) > -0.8 are relevant for the fit.

All entries are optional.

Example Input Files