**Programs for generating a cluster expansion**

##
Cluster-expansion of a potential energy surface

For many systems with more then a few degrees of freedom the potential
is not given in a form suitable for MCTDH calculations. In this case
one can expand the exact potential in terms of n-particle interaction
terms called the clusters. The
expansion can be developed around several so-called reference points
`Q`_{ref,i}.
The approximated potential is then given as a (weighted) sum over all
reference points.

There are several *flavors* of cluster-expansions, for
instance, expansion around a single reference point or a reference
coordinate (with the other coordinates fixed to possibly different values).
The implementation of
the programs documented here does not strictly distinguish between
those two, instead the user is free to *mix* them. A cluster or
n-particle interaction term is identified only by the coordinates or
combined modes it spans. The clusters form a hierarchical tree of
n-particle interaction terms with several layers. The position, i.e,
layer, in the tree is determined by the number of (combined) modes the
cluster spans. This is independent from whether or not a
combined mode is included completely or just partly. The hierarchy
of clusters must have one single root term, i.e., a single cluster which
is of the lowest order - usually this is a cluster containing a single
point or mode. Here, *mode* can refer to a single degree of freedom
('coordinate') or a combined mode (' logical coordinate')

## Generation of clusters

The clusters are generated in hierarchical order, starting from the
lowest order cluster, the root of the hierarchy. This cluster is given as
the *cut* through the potential energy surface (PES), i.e.,
the potential energy at the reference point or reference mode with all
other coordinates fixes to the reference values. In case of a reference
mode the cut is coordinate dependent. In a next step, for
all clusters being one layer up the hierarchy, also PES cuts are
obtained, where the coordinate dependence is now extended to at least
one further mode. From those PES cuts now the lowest order cluster is
subtracted. This procedure is repeated for all layers in the
hierarchy. In general, the algorithm works as follows: 1. Calculate PES
cuts for all clusters in a layer. 2. Obtain clusters for this layer by
subtracting all lower layer clusters from the PES cut. 3. Repeat
in the next higher level.

## Programs

This package defines a number of tools to find a particular
cluster-expansion and relevant terms of the expansion and - when found
- to sample those clusters on a DVR grid. To find a suitable cluster
expansion the tools for statistical analysis can be used. Here a trial
expansion can be tested for convergence. If a suitable expansion is
found, the clusters of interest can be sampled on a DVR grid and be
potfitted. Finally the complete approximated potential sampled and
potfitted within MCTDH can be checked against the exact potential.

All programs are written in Python and rely on the
NumPy and
SciPy packages which are
open-source and freely available for download. Both packages are included in many Linux
distributions but usually not installed by default. Note: for Apple computers the
Numpy/SciPy developers strongly recommend using the official Python distribution
and not the version shipped with Mac OS X.
### Statistical analysis - data generation.

With the Python script `clusterstat.py`
a Monte Carlo algorithm is used to explore the potential energy surface
in the most relevant regions. Alternatively an already given trajectory
of coordinate values can be used. The main purpose of this script is
the calculation of the contribution of the clusters along the trajectory.
This data can then be further analyzed by the script `clusterana.py.`
### Statistical analysis - data analysis

The data produced by `clusterstat.py` can be further analyzed with the
Python script `clusterana.py`.
This allows detailed statistics for single clusters, a particular expansion etc.

### Sampling of clusters on a DVR grid

Generating the relevant clusters on a DVR grid is performed with the python script
`clusterbuild.py`.
The script can also create (initial) potfits of the clusters.
### Checking a PES file

To check an already processed PES by MCTDH, the script
`chkpes.py`
may be used. Here again a Monte Carlo sampling is used to test the
potential energy surface against the exact potential. Alternatively an
already given trajectory of DVR indices can be used.

## Technical Remarks

The current implementation has been tested with
Python versions 2.4.4 and 2.5.2 on Linux machines and assumes that the
path to the Python intepreter is found in `/usr/bin/env python`.
On some architectures this could be different. In this case the path
can be changed in the first line of the Python scripts in
`$MCTDH_DIR/bin/python/clusters/`.
All scripts rely on many features of the
NumPy/SciPy
package which is not installed by
default on many platforms. Please make sure that NumPy 1.1 or later and a
recent version of SciPy are installed.

Note: for Apple computers the Numpy/SciPy developers
strongly recommend using the official Python distribution and not the version
shipped with Mac OS X.