Potfit / Candecomp Tools
General Remarks
The Potfit/CANDCOMP tools are a collection of programs to modify, convert, and analyse natpot, cpd, and hcpd files.Documentation of the Individual Programs
The following programs are available for analysis and manipulation of natural potentials and cpd potentials calculated by the natpot, mccpd or mcpotfit programs:
- chksampling
- Check the sampling points of a mccpd/mcpotfit run.
- chnpot
- Interpolation of natpot terms to another grid.
- compactoper
- Reduces the rank of a given operator (oper or pes from mctdh) in sum-of-products form using and alternative least squares algorithm.
- cpdcorrelation
- Calculates pair-wise correlations (entropies) of a potential in CANDECOMP form..
- cutcpd
- Remove one or more DOF from a CPD file by freezing coordinates to a reference value.
- natpot2cpd
- Read a natpot file and convert to a canonical polyadic decomposition (CPD) which is subsequently optimized using ALS.
- npotminmax
- Like vminmax. Reads a set of natpot files and runs over the total product grid or a selection of grid points to determine the maxima and minima of a potential energy surface.
- rdnatpot
- Reads a natpot file and prints information on it to rdnatpot.log.
- showpot
- Enables plotting of a PES fit from a natpot or cpd file. Comparison with true potential can be made if vpot file is present.
chksampling
OptionsChecks the sampling made during a mccpd/mcpotfit calculation. It can also be used to remove to remove sampling points close to boundaries, if they are of unsuitable high or low energy. It also can write a covariance matrix, which provides hints to useful mode combinations. .
chnpot
OptionsThe program interpolates natural potential terms calculated by program Potfit (written in "natpot" file) from one grid to another. Normally one runs Potfit on an initial coarse grid, then interpolates the natpot terms to a finer grid. At present, the program can interpolate only one or two dimensional natpot terms. The program reads the old grid from "dvr" file. The input file consist of three sections, a Run-Section, a Primitive-Basis-Section and a Fit-Section (see below) and the final keyword "end-input".
In Run-Section following keywords are possible:
| Keywords of chnpot RUN-SECTION | |||
|---|---|---|---|
| Keyword | compulsory / optional | Description | equivalent option |
| name=S | C | The name of the calculation. A directory with path S is required in which files will be written. | -D |
| dvrdir=S | C | The old DVR file is located in directory S. | -d |
| natpotdir=S | O | The old natpot file is located in directory S. If this keyword is not given, natpotdir=dvrdir is assumed. | -nd |
| natpotfile=S | O | The path of the old natpot file is S. If this keyword is not given, natpotfile=natpotdir/natpot, or natpotfile=dvrdir/natpot is assumed. | -nf |
| readdvr=S | O | The new DVR should be read from directory S. Without argument, S = name is assumed. Without this keyword the dvr file is created in the name directory. | -rd |
| overwrite | O | Files in name directory will be overwritten. | -w |
The Primitive-Basis-Section is as in QUANTICS.
In the Fit-Section the parameters for interpolation are given. For translational degrees of freedom one can use cubic (bicubic) spline interpolation or ENO (Essentially Non Oscillatory) interpolation. For angular degrees of freedom (in the case of periodicity) one can select between cosine, sine or fourier interpolation. Note, that the interpolation method should be defined for each degree of freedom, and not for each mode. If grid points for some degree of freedom have not changed, it can be omitted. The keyword "spline" ("spl") is used for spline interpolation. ENO interpolation is currently implemented for non-combined modes. It consists basically on a polynomial interpolation where the points from the original data set used to obtain the interpolant function are automatically selected to fulfill some smooth criterium. The algorithm will provide a continuous non-oscillatory interpolation near regions with sudden changes in slope, as encountered for example when an energy cut is found in the original data. The formulation of the algorithm can be found in J. Comput. Phys. 71, (1987), 231-303. ENO interpolation is requested using the keyword eno, which can optionally be followed by the keywords rmax=integer, maximum degree of interpolation (default 3), rmin=integer, minimum degree of interpolation (default 1) and dfac=real, weight factor controling how preferential is the symmetric interpolation with respect to the asymmetric one (default 50.0). The ENO implementation is a new feature and by now is rather experimental. Use it with care. The defaults should provide a reasonable behaviour of the interpolator, specifically, setting a higher maximum order or lowering dfac too much may result in a noisy potential energy function at the end. Increasing too much dfac (say, above 200) will tight the interpolator always to a symmetric interpolation, thus not being able to avoid discontinuities. A good idea would be to compare it for a given case to the corresponding spline interpolation and pick up the most satisfactory result. The keywords "cosine" ("cos"), "sine" ("sin") and "fourier" ("ft") are used for the Fourier-interpolation of angular degrees of freedom. (NB: "ft" or (equivalently) "fourier" means that sine and cosine functions are used). The keyword "sym" after "sin", "cos" and "ft" can be used, indicating that only even functions (i.e. Cos2x, Cos4x, ...) should be used. The angular fit procedure is described in JCP 104,(1996) 7974. The parameter M (default is max(50,2*gdim)) can be given as a keyword following the sin, cos, or ft keyword (see Eq.(37) in JCP 104,(1996) 7974). Finally, the keyword "period=xx" defines the period of the potential curve, for which xx="2pi/N" or "P" format can be used, where N is an integer and P is a real number. If the keyword period is missing, period=2pi is taken as default. If the variable under discussion is not an angle, period should be set to the interval of periodicity. If the potential is not periodic, period should be set to twice the grid length.
The order of the arguments which follow the method keyword is arbitrary.
Here is an example of Fit-Section:
Fit-Section R spline r fourier 120 period=7.85 q eno rmax=3 dfac=60 Q eno dfac=70 rmin=1 theta cosine 60 period=2pi/2 phi fourier sym period=2pi end-fit-section
Here it was assumed that V(theta=0) = V(theta=pi), e.g. H2O in Jacobian coordinates. If this periodicity is not given, e.g. H2O in valence coordinates, period=2pi should be used.
Note, that the interpolation method for the degrees of freedom in combined mode should be the same (for angular modes cosine, sine and fourier can be mixed). Some parameters of the calculation are written to the "chnpot.log" file. The program writes the new natural potentials file "natpot" and the "dvr" file (if the option -rd or keyword readdvr in Run-Section are not used) to the name directory. For over-writing of the natpot file use "-w" option. For an example input file see $QUANTICS_DIR/inputs/pinputs/chnpot.inp
Example:
chnpot -w -rd inputNote that chnpot may be used to change the modelabels. Chnpot maps the n-th old DOF onto the n-th new DOF, the modelabels are not used. If you just want to change the modelabels without re-fitting the potential, simply set up the PRIMITIVE-BASIS-SECTION of the chnpot input file using the new modelabels but otherwise the old basis definitions. A FIT-SECTION is not needed in this case.
compactoper
OptionsRead an MCTDH oper or pes file and convert to a Hamiltonian canonical polyadic decomposition (HCPD) of a canonical polyadic decomposition (CPD), respectively, which is subsequently optimized using ALS.
Important remark 1This program should in general not be used to reduce the rank of kinetic energy operators. Kinetic energy operators contain mostly unit operators and other diagonal operators which is exploited in MCTDH. The output of compactoper for general operators is a hcpd file that contains matrix operators for all modes and all terms in the operator. Using this program therefore only makes sense for operators where all single-particle operators are matrices in the first place (for instance second quantized operators) or if all single-particle operators are diagonal in the first place (for instance a potential, see -pes option). Mixed operators with diagonal and non-diagonal single-particle operators usually lead to poor performance in MCTDH.
Important remark 2
As mentioned in the help text this program relies on being linked to optimized
and parallel BLAS/LAPACK libraries. A number of such libraries are available
for free, for instance OpenBLAS,
ATLAS or
Intel oneMKL.
To add optimized BLAS/LAPACK libraries edit the file $MCTDH_DIR/install/compile.cnf.
Locate the section of the compiler you are using and within this section
locate the lines "EXTERNAL_BLAS=..." and "EXTERNAL_LAPACK=...". Replace the entries
with the link line for your optimized BLAS/LAPACK library. For instance:
EXTERNAL_BLAS=-L/path/to/library -lmyblas
EXTERNAL_LAPACK=-L/path/to/library -lmylapack
Then compile with
compile -x lapack compactoper
Some libraries may need more complicated link lines.
See for instance
Intel link line advisor. Also special environemnt variables may be required.
cutcpd
OptionsThe program needs an input file containing a RUN-SECTION and a REFERENCE-SECTION, specifying the source cpd and dvr file as well as the reference geometry, respectively. A new CPD file will be produced where all coordinates specified in the reference section are fixed to the reference geometry such that the resulting CPD file only contains the remaining DOF. Combined modes that are fixed to their reference geometry are removed from the CPD file. If only one combined mode remains, then the resulting CPD will contain only one term.
In Run-Section following keywords are possible:
| Keywords of cutcpd RUN-SECTION | |||
|---|---|---|---|
| Keyword | compulsory / optional | Description | equivalent option |
| name = S | C | The name of the calculation. A directory with path S is required in which files will be written. | -D |
| readcpd = S | C | The input cpd-file to be cutted is read from directory S | |
| readdvr = S | O | The DVR file associated with the input CPD file should be read from directory S. Default: same directory as the input CPD file. | |
| overwrite | O | Files in name directory will be overwritten. | -w |
The REFERENCE-SECTION must contain the keywords begin-reference and end-reference enclosing the definitions of reference points. The reference points themselves are specified one coordinate per line, starting with the coordinate label of the primitive DOF that is to be fixed to a reference value. The reference value itself can be defined in two ways: index-based or value-based.
Index-based reference point
Here one specifies the number of the DVR point that defines the reference geometry using square brackets enclosing an integer number after the coordinate label. For instance,
begin-reference
theta[7]
end-reference
will fix the DOF theta to the value of the 7th grid point.
Value-based reference point
Here one sprecifies the value of the DVR point that defines the reference geometry using the equal sign (=) and a floating point number. The program will then find the closest DVR point to the given value (see log for the final value) and use this as reference value. For instance,
begin-reference
theta = 3.14159
end-reference
will fix the DOF theta to the value of the DVR point closest to 3.14159.
An example file can be found in $QUANTICS_DIR/inputs/pinputs/
cutcpd_zundel.inp
cpdcorrelation
OptionsThe program cpdcorrelation calculates pair-wise correlations (entropies) of a potential in CANDECOMP form. It can be used to investigate the coupling between modes and thus provides hints for a useful choice of mode combinations. One may run a (low accurate) cpd calculation without mode combinations. Then run cpdcorrelation on these cpd data and identify a useful mode combination scheme. Using this scheme one may then run a final, accurate cpd fit.
natpot2cpd
Options The program reads a natpot file and converts it to canonical
polyadic decomposition (CPD) format. The CPD file will use the same
mode-combinations and mode-labels as the natpot.
In a first step, an initial guess in CPD format is created,
depending on the given command line options from the given natpot
file or simply from random numbers. Subsequently, an optimization procedure
is started to iteratively improve the quality of the CPD fit compared
to the natpot file using alternating least squares (ALS).
Several output files will be written to the name-directory:
- cpd The output file containing the potential in CPD format. Can be used similar to natpot files. See Hamiltonian input documentation.
- np2cpd.log The log file with various information.
- np2cpd_iterations Fit error as a function of the iterations of iterations. Also contains the condition number of the problem and, if -spd is set, total functional that is being optimized, including the regularization part.
- np2cpd_timing Information in time spend in various subroutines.
- np2cpd_stop Stop file. Can be used to stop the ALS optimizer prematurely. The iterations are stoped if np2cpd_stop is removed or does not contain the word "continue" as its first entry.
- als_eigenval_mode_m If -ev is set, these files contain the eigenvalues of the problem solved during the ALS iteration for mode number m. This file is only produced in last iteration step.
- cpdovlp If option -o is given this file contains the overlap matrix of the cpd basis functions.
- cpdcoeff If option -l is given this file contains the coefficients of the cpd basis functions (the core tensor).
Examples
natpot2cpd84 -r 30
natpot2cpd84 -mnd -DD CPD.r100 -r 100 -n 25000 -g 10 1000 -v -l
natpot2cpd84 -mnd -DD CPD.r200 -CC CPD.r100 -r 200 -n 12000 -v -l -ev 1.d-10
The use of the -g option is recommended. Using the -ev option often provides a better fit, but at higher computational costs. The smaller the regularization parameter, the larger become the coefficients (CPD core-tensor) and hence the condition number. The latter should not exceed the value of 1000.
The program supports parallelization with OpenMP. We recommend
compilation with the -P option. Furthermore, as several liner algebra
operations are performed, linking to an optimized Lapack
package is of advantage (needs editing of compile.cnf).
For instance: compile -P -x lapack natpot2cpd
npotminmax
OptionsThe program is similar to the analysis program vminmax, except that a set of natpot and/or CPD files is used to generate the potential operator. The program requires an input file which contains at least a RUN-SECTION specifying job parameters and a NATPOT-SECTION and/or CPD-SECTION listing paths to natpot and CPD files. In addition, either the keyword readdvr in the RUN-SECTION needs to be set or a PRIMITIVE-BASIS-SECTION needs to be present in the input file. Note, that the system DVR may contain more degrees of freedom than the natpot/CPD files are defined on. Furthermore, the natpot files can have different sets of degrees of freedom compared to each other as long as all degrees of freedom are contained in the system DVR, i.e., it is similar to constructing the operator-file from different natpot/CPD files.
In Run-Section following keywords are possible:
| Keywords of npotminmax RUN-SECTION | |||
|---|---|---|---|
| Keyword | compulsory / optional | Description | equivalent option |
| name = S | C | The name of the calculation. A directory with path S is required in which files will be written. | -D |
| readdvr = S | C/O | The DVR file containing all system DOF is located in directory S. Compulsory if there is no PRIMITIVE-BASIS-SECTION. | -d |
| trajectory = S | O | The scan is not done over all grid points but only over a
subset. S is the path to an ASCII file containing the DVR
indices of the grid points, where one grid point is given
per line. There may be more than one trajectory file! Note,
that the indexing is assumed to be in the same order as the
DOF appear in the PRIMITIVE-BASIS-SECTION, i.e., the first
index belongs the first coordinate in the
PRIMITIVE-BASIS-SECTION, etc. The indices are assigned to
the natpotfiles by their modelabels as in the Hamiltonian
generation. A trajectory of DVR indices can be either created using the chkpes program or (more conveniently) with mcpotfit or with mccpd |
|
| compare = S | O | Compare the sum of all natpot files to a surface file
S. That is, after summing the contributions of all natpot
files for the n-th grid point, substract the value from the
n-th line in S. If the trajectory keyword is
given, there must be exactly as many compare files as
trajectory tiles. Moreover, trajectory and compare files
must be consistent (i.e. it is assumed that the n-th line of
S corresponds to the n-th line of the trajectory) and they
must appear in the same order. If the trajactory option is not given, S must contain as many lines as there are grid points in the system DVR, where the index of the first coordinate runs fastest, the index of the second coordinate second fastest etc. Note, that the chkpes as well as mcpotfit and mccpd programs produce surface files along a dvrindex trajectory as used for the trajectory = S keyword. |
|
| wrsrf | O | Write the sum of all natpot files to a surface file srf.dat in the name directory. | -srf |
| overwrite | O | Files in name directory will be overwritten. | -w |
The NATPOT-SECTION only contains a list of paths to directories holding a natpot or CPD file.
Example:
RUN-SECTION
name = npmm-h3o2m
readdvr = mccpd_h3o2m
trajectory = mccpd_h3o2m/dvrindex-test-1
trajectory = mccpd_h3o2m/dvrindex-test-2
trajectory = mccpd_h3o2m/dvrindex-test-3
trajectory = mccpd_h3o2m/dvrindex-test-4
compare = mccpd_h3o2m/energies-test-1
compare = mccpd_h3o2m/energies-test-2
compare = mccpd_h3o2m/energies-test-3
compare = mccpd_h3o2m/energies-test-4
END-RUN-SECTION
NATPOT-SECTION
mcpf_h3o2m_r_R # directory with natpot of r and R
mcpf_h3o2m_u1_u2 # directory with natpot of u1 and u2
end-natpot-section
CPD-SECTION
mccpd_h3o2m # directory with cpd file
end-cpd-section
end-input
Output files (in name directory)
- log
- The log file.
- dvr
- The primitive grid definitions. (Only if a
PRIMITIVE-BASIS-SECTION is given in the input
file.)
- largest
- The set of num largest values is found and
displayed. Then the coordinates as well as contributions of the
single natpot/cpd files are printed. If compare
is set, then energy differences V-Vcompare are
showwn, rather than the potential energies.
- smallest
- Similar to largest, except that smallest
potential values or differences are shown.
- smallest_abs
- Similar to largest, except that smallest
absolute values of potential or differences are show.
- statistics
- For each natpot file its mean and RMS values as well as largest, smallest and smallest absolute values found plus their coordinates.
rdnatpot
OptionsThis program is useful to obtain a quick overview on what is on a given natpot file. Information on the grids, mode combinations, and numbers of SPPs are written to rdnatpot.log. On demand the program writes the natural potentials (SPPs) and the D-tensor to ASCII files.
showpot
OptionsCuts of a potential energy surface (PES) can be generated from a vpot and a natpot file. Both files are generated by the potfit program. The first one contains the exact potential on the complete product grid, the latter a corresponding fit.
After starting the program a menu is presented by the help of which one can select a cut via an interactive process. The menu offers the following choices:
- Select WHAT is plotted: if both files, a vpot file and a natpot file, are read one can plot the PES or a fit of it or the (absolute) difference of both.
- Select between 1D and 2D cuts.
- Select new energy bounds for the plot.
- Change the bounds for the one or two modes which define the cut.
- For a 2D cut contour plots can be generated for which one can specify the number of contours and the corresponding PES levels. Choose between a linear and a logarithmic spacing (see below).
To define a cut, one must attribute x to one coordinate, and one may attribute y to another coordinate (the latter choice generates a 2D plot). The remaining coordinates must be assigned numbers (coordinate values), but at most one of these coordinates may be assigned with the label min or max. If min or max is given, the program sets this coordinate such that the potential is minimal (maximal)with respect to variations of this particular coordinate. max is useful for the plottask abs(Vfit-Vpot).
Description of the logarithmic spacing if Gnuplot commands are included into the output file:
- Firstly, the program calculates the difference d=zmax-zmin, where zmax (zmin) is the upper (lower) bound chosen for the contour levels. In a second step, the program calculates a basis b<1 such that bn-1=r, where n is the number of contour levels and r<1 is a so-called "reduction factor" provided by the user. Contour level i is now fixed at zmin+d*bi , where i runs from 0 to n-1. Note that according to this procedure zmax and/or zmin may be negative!
Compiling the Programs
The programs should all be compiled during the installation of the package. If this is not the case, or a code needs re-compiling after making changes, they can be compiled using the shell script $QUANTICS_DIR/bin/compile. Type:
compile prognameto produce the executable $QUANTICS_DIR/bin/$QUANTICS_PLATFORM/progname, where progname is the name of one of the natpot / cpd tools (e.g. chnpot or npot2cpd). Typing
compile npottoolswill compile all the programs.
The compile script has various options (type compile -h for a list). For example, to produce the executable $QUANTICS_DIR/bin/$QUANTICS_PLATFORM/cpdcorrelationd with debug information, type
compile -d overlapFor more information on the compile script, see Compiling the programs.