Chkpes Documentation

General

The Python script 'checkpes.py' is used to compute an estimate of an implemented cluster-expansion (read as MCTDH pes file) and the exact potential. A random tracectory over grid points of the full product grid is generated using a Monte-Carlo scheme. The input needed by checkpes in general follows the rules of the usual MCTDH input. The input is organized in two sections, a RUN-SECTION with specifications of the job parameters and an INIT-SECTION to set up the random walker (see below).

Important: The trajectory is generated according to a user-provided potential energy routine which recieves a coordinate vector Q and returns a potential value V(Q). The routine must be callable through Python. If the routine is written in Fortran we suggest using the f2py Fortran to Python interface generator available at the NumPy/SciPy homepage. Another possibility could be a wrapper routine which sends the coordinate vector via pipes to a background process which passes the potential value back to the wrapper. See also 'usersource.py'.

The trajectory generated by chkpes.py resambles a Boltzman distribution η(Q) = exp(-βV(Q)) with β^-1 being the temperature.

----------------------------------------------------------------------------

Purpose:     Use a Monte-Carlo sampling to check a sampled PES file against
             an analytic potential routine.

Usage:       chkpes.py [-D -n -mnd -deb -w -t -ver -h -? ] inputfile.inp

  -D <dir>   Denotes the directory where files are written to
             (name in .inp file ignored).
  -n <int>   Use <int> Monte-Carlo steps (value in .inp is ignored).
  -mnd       Make name directory.
  -deb       Run in debug mode (more detailed logging).
  -w         Allow to overwrite existing data.
  -t <file>  Run with a given trajectory stored in <file>.
  -ver       Print version info.
  -h -?      Print this help text.
----------------------------------------------------------------------------

Input Documentation

The input consitst of two sections, the RUN-SECTION and the INIT-SECTION. Within the RUN-SECTION the job parameters are defined while in the INIT-SECTION the initial position of the random walker is specified.

RUN-SECTION

Required keywords
Keyword	Description
name = S	The 'name' directory to which output files are written.
user-source = S	The path (relative or absolute) to the module containing the potential energy routine. See using the 'user-source' keyword.
temperature=R(,S)	The 'temperature' (including the Botlzmann constant) used to generate the Monte-Carlo trajectory. S may be a unit: "cm-1", "eV" or "au". Default: S = "au".
steps = I	The number of accepted Monte-Carlo steps, i.e, the length of the trajectory.
pesdir = S	The directory containing the PES file generated by MCTDH. 'pesdir' can be omitted if 'walk-only' is set. In this case 'dvrdir' has to be given,
dvrdir = S	The directory containing the DVR file generated by MCTDH. If 'pesdir' is given, 'dvrdir' defaults to 'pesdir'. Note: For generating the trajectory there is no check whether a given DVR is compatatible with a given PES file.
Optionmal keywords
Keyword	Description
potential-routine = S	The name of the potential routine in the module set by the 'user-source' keyword (see above). Deufault: S = "potential"
vminmax-exe = S	The name of the executable of the MCTDH analysis program 'vminmax'. Default: S = "vminmax84".
nham = I	Number of the Hamiltonian within the PES file. Default: I = 1 (system).
trajectory = S	Path to a previously calculated trajectory (same as option -t). If 'trajectory' is set, the Monte-Carlo run is omitted. Instead, ony the 'energies' file in the name directory is updated and, if required, vminmax is invoked.
overwrite	Allow overwrite of existng files in the 'name' directory. Similar is option -w in the command line.
walk-only	Just obtain a Monte-Carlo trajectory and stop thereafter. Do not invoke vminmax.
wrcoord	Write the (real) coordinate vector for each step to the 'coordinates' file (the tracectory is usually stored as the interger grid index in file 'dvrindex').

INIT-SECTION

The INIT-SECTION is used to set ob the initial location of the random walker. Each line starts with a coordinate label which must match a coordinate label of the dvr-file specified in the RUN-SECTION. The coordinate label is followed by an integer that specifies the initial grid point and an optional keyword 'fix' which indicates that this coordinate is to be kept constant.

Example: A system containing four DOF, (Q1, Q2, Q3, Q4), where the initial dvr-index of Q1 is 7, the dvr-index of Q2 is 6, etc. In Addition, the dvr-index of Q4 is set to 13 and kept constand during the calculation.

INIT-SECTION        
#coord.label   initial point   const?  
 Q1               7              
 Q2               6      
 Q3               6      
 Q4               13           fix
end-init-section

Output Documentation

Depending on the input a number of output files (all ASCII) are generated:

input: A copy of the input file.
log: Logging information.
energies: The potential values along the trajectory path. One energy per line.
dvrindex: The trajectory consisting of accepted Monte-Carlo steps in terms of the DVR grid index. Blank separated integers, one index vector per line.
coordinates: The trajectory as in file 'dvrindex' but in terms of the coordinate values. Blank separated real numbers, one vector per line.
ratio: The (cumulated) ratio between accepted and rejected Monte-Carlo steps. The value in line n is n/(n+m), where m is the total number of rejected steps until n steps have been accepted.
vmm_checkpes: The output file generated by the analysis program vminmax.
vmm.log: The log file generated by the analysis program vminmax.

Note: Once the files 'dvrindex' and 'energies' are created, vminmax is used in a standard way and could also be run from the command line (see options -t and -c of vminmax).