Potfit Input Documentation

General Structure

Upper and Lower Case Characters

• the names of energy potential surfaces and their parameters,
• the names of degrees of freedom ("modelabels"),
• the names of directories and files,
• etc.

are interpreted in a case sensitive manner!

Special Characters

Keyword Placement

keyword1
keyword2
keyword1 keyword2
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

keyword=arg1,arg2,...
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

Single Precision

Sections

General Remarks

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

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.

Run-Section

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

A normal run allocates a double precision vector v of full grid size which holds either V'=(V-V_1d)*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, V_1d 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.

Notes on rdnpot.
When the keyword rdnpot is given, the natpot, vpot and dvr files of the name-directory are read, the fit error-measures are computed, and data is written to the files rdnpot_input, rdnpot_output, and rdnpot_log. (No timing file is created). Hence, no files of the potfit calculation will be overwritten. As rdnpot sets readdvr, a PRIMITIVE-BASIS-SECTION is not needed in the input file. The numbers of SPPs given in the NATPOT-BASIS-SECTION may be equal or smaller than the ones on the natpot file. Hence with rdnpot one can study the error which will be introduced by cutting the natpot with cutnpot. If Separable- and/or Correlated-Weight sections are included, the corresponding error measures will be computed, respectively whether the weights did appear in the potfit calculation.

Notes on cutnpot.
A cutnpot run should have its own (empty) name-directory (which may be generated by the -mnd option). The program reads a natpot file from the path given as argument to the keyword cutnpot. The number of natural potentials (also called single-particle potentials (SPPs)) is reduced to the values given in the NATPOT-SECTION of the input file. The thus downsized fit is written to the file natpot. If the directory which hosts the original natpot file contains a vpot file, a link to this vpot file will be set in the cutnpot name-directory. This is useful if one then wants to inspect the downsized natpot with the task rdnpot, or if one wants to add new iterations with the task continuation. A cutnpot run produces the files dvr, input, and log. There is no output file, all output is directed to log. And there are no timing and stop files. The OPERATOR, SEPARABLE-WEIGHT, and CORRELATED-WEIGHT sections are ignored in a cutnpot run, the input file may miss them.

Notes on continuation.
A continuation run is used to add additional iterations to a potfit calculation. The name-directory of the original potfit calculation should contain the files: dvr, natpot, and vpot. Except for the RUN-SECTION, the input file of a continuation run should be identical to the original *.inp file. It is recommended, that one simply uses this original input file and enables continuation through the option -c. The data produced by a continuation run will be appended to the files on the name-directory. Note that a continuation run will perform as many additional iterations as given by the keyword niter, irrespective of how many iterations have been previously done.

Note on MGPF calculations.
Multigrid Potfit (MGPF) is a variational method by means of which a product form of the potential can be obtained for systems in which the primitive grid size exceeds the integer overflow limit. This is achieved by minimizing the L² difference between the actual potential and the approximated one. In practice, a MGPF is obtained by successive potfit calculations on two different grids defined by the user: a coarse grid and a fine one The latter is the one eventually used by mctdh). MGPF is actually a Python script which calls potfit several times with different parameters. Here, potfit reads the DVR points from external ASCII files.

Operator-Section

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

Primitive-Basis-Section. Ordering of arguments

BKMP2 PES : 3D model in Jacobian Coordinates
Dissociative Coordinate : rd
Vibrational Coordinate  : rv
Angular Coordinate      : theta

Natural-Potential-Basis-Section

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}
  

  potfit: {r1,r2,r3} {r4,r5,r6}
  potfit: r1, r2, r3 {r4,r5,r6}
  potfit: {r1,r2,r3} r4, r5, r6
  

  potfit: {r2,r3} {r4,r5}
  

  potfit: {r1,r2,r3} {r4,r5} r6
  potfit: {r1,r3,r2} r4, r5, r6
  

Example:

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:

natpot-basis-section
rd = contr
rv = 10
theta = 6
end-natpot-basis-section

or

natpot-basis-section
rd = contr    rv = 10    theta = 6
end-natpot-basis-section

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

natpot-basis-section
rd, rv = contr
theta = 6
end-natpot-basis-section

or

natpot-basis-section
rd, rv = 10
theta = contr
end-natpot-basis-section

Separable-Weight-Section

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:

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.

Correlated-Weight-Section

Example:

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 regions.
rv < 3.74,au            # Instead of "<" the symbol ">" is also valid with 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.
readcw = [path/to/file] # if readcw is given, all other lines of this section will be ignored.
                        #
  or
readcw = [path/to/file],no-map # If the weights on file are unpacked and in mode order.
                               # One must set "no-map" to inhibit transformation from DOF to mode order.
                               # Note that the weights which are are generated by POTFIT
                               # are packed and in mode order. Unpacked weights
                               # are usually generated by an external program.

All entries are optional.

transformation-section

Only the vector definition part is not optional.

Example:

transformation-section
1  1  0.5               X   X  # The first vector, the first dummy atom is on the middle of this vector
                               # and the start and final points of the vector are two new dummy atoms.
2  2  0.0592649997001   O   H  # The second vector, the second dummy atom is on the center of mass
                               # of this vector and the start and final points of the vector are Oxygen and Hydrogen atoms, respectively.
3  3  0.0592649997001   O   H
4  1  0.0               X   H  # The fourth vector, the first dummy atom (middle point of the first vector)
                               # is the starting point of the fourth vector and the final point is the Hydrogen atom.
order = 1 7 8 9 3 5 6
cart = 4
cord = 5 1 2 3 4
fro = 2 1.85
fro = 4 1.85
end-transformation-section

  

Example Input Files

• 3D LSTH-surface (H₃) in Jacobian coordinates
• 3D HOO-surface in Jacobian coordinates
• 3D NOCl-surface in Jacobian coordinates
• 3D PJT2-surface (H₂O) in Binding coordinates
• Example for trasrf.F for the H₃O₂^-