Installation and Compilation

Overview of Package

The MCTDH package is a set of programs able to set up and propagate a wavepacket using the MCTDH method. Numerically exact propagation is also possible for small systems, as is the solution of the time-independent Schrödinger equation using Lanczos diagonalisation. The program can also be used to generate a ground state wavefunction using energy relaxation (i.e. propagation in imaginary time). With "improved relaxation" it is even possible to generate (low lying) excited states. The numerically exact diagonalisation of a one-dimensional Hamiltonian to obtain the eigenvalues and eigenvectors is also possible. The latter eigenfunctions are then used as initial single-particle functions.

Within the MCTDH package there are also programs to propagate density operators. The Liouville-von Neumann equation is solved for open and closed system dynamics. Open systems are treated in Markov approximation. However, the present versions 8.4 and 8.5 are not able to propagate density operators. Use version 8.3 for this purpose.

The program input is keyword driven. Of especial practical importance, the Hamiltonian operator is input using a simple ASCII file, selecting functions from a library. Adding new functions to the library is also reasonably straightforward.

The rest of the package consists of utility routines to help setting up the input, and to analyse the output from the propagation.

The POTFIT program is able to produce a fit to a complicated multi-dimensional potential energy function. This fit is of the form required by the MCTDH algorithm, i.e. it is a sum of products of one-dimensional operators, which in this case are the "natural potentials".

The ANALYSE programs are a set of programs, which are able to, e.g. calculate the error between wavefunctions from different calculations, enable the plotting of a potential energy surface or a wavefunction, or check the quality of the basis used for the propagation. There are also ANALYSE programs for density operators available.

The FILTER programs are a set of programs, which determine bound or resonance energies by filter-diagonalisation. The input is the autocorrelation function generated by MCTDH. The program set filter is to compute (real) bound state eigenenergies (and Intensities) and fdc is to determine (complex) resonance energies.

The VCHAM programs are a set of programs, which determine the parameters of a vibronic coupling Hamiltonian by fitting this model to (adiabatic) potential energy points. It interfaces directly with GAUSSIAN and GAMESS-UK.

The documentation should be self explanatory. There is a User's Guide which provides examples and details of how to set about a calculation. The on-line documentation is then designed to give up-to-date information about all the options.

Use of the program is unrestricted. However, please do not further distribute the MCTDH package by yourself but rather tell the interested person to contact the Heidelberg group. For copyright and citation details see the User's Guide. Please report any bugs in the code, and mistakes or dead links in the documentation to the authors. Other comments are also welcome.

If the installation of the MCTDH package fails, see Installation Problems.

Documentation Nomenclature

The environment-variable $MCTDH_DIR is used to denote the directory which hosts the MCTDH package.

All program names have a version number, e.g. mctdh84. In the documentation this is represented as mctdh<ver>. The relevant version number is made up of the version and release number, given on the index page of the on-line documentation. Thus mctdh84 is the MCTDH program from version 8 release 4 of the package. The complete information on the version is obtained by the command  mctdh84 -ver (and similar for the other programs).

Installing the Program

If you have already installed MCTDH, but want to update it, see the page Applying patches.

Please read the README file of the $MCTDH_DIR/install directory. The installation is also discussed in Appendix E of the MCTDH guide.

For the installation of the complete package, one needs a computer with a UNIX (or UNIX-like, e.g. Linux) operating system. On MS Windows, it is possible to install and run MCTDH inside the Cygwin environment (see also our Cygwin hints).

The following software is required:

For a list of known installation problems click this link. If one works on a computer network one often is faced with very long path-names. Click here to see what you can do to shorten the path-name.

To install the MCTDH package, first move to a suitable directory. We recommend that you create a directory named MCTDH. The path of this directory will be termed $MCTDH_DIR. If the package has been obtained as a tared and zipped file, e.g. mctdh<ver>.tgz, where <ver> is the version number such as 84.1, unpack the archive using

gunzip mctdh<ver>.tgz
tar xvf mctdh<ver>.tar
All the files required by the package will now be present. If you have a GNU tar, you may use the command tar xzvf mctdh<ver>.tgz

An alternative, and in fact the recommended way to download the code is to use subversion (svn). See the description svn-repository to learn, how to use svn.

Before installing the package, please run the script check_system.

$MCTDH_DIR/install/check_system

To do so, move to $MCTDH_DIR/install and type ./check_system . Note the the environment variable $MCTDH_DIR is not yet set (it will be set by the install script). Hence you have to replace $MCTDH_DIR with the path of the directory of the downloaded code, e.g. /home/myname/MCTDH/mctdh84.9

The package can be simply installed by invoking the bash shell script

$MCTDH_DIR/install/install_mctdh

To execute install_mctdh, move to $MCTDH_DIR/install and type "./install_mctdh", or call the script with its full absolute path. (You may wish to try the option -h and -r before actually running the install script). The install script asks a few simple questions, and automatically generates the executables and documentation. At the end of the installation process, you have to source your .bashrc (or .kshrc or .cshrc) in order to set some environment variables The MCTDH environment variables are listed if you type menv.
If you are using bash, it will be very convenient to copy the script $MCTDH_DIR/install/mctdhrc to ~/.mctdhrc . (The install_mctdh script may do this for you). The (hidden) file ~/.mctdhrc will then be sourced when the .bashrc is sourced. The .mctdhrc script sets some aliases (e.g. the command brc will then source the ~/.bashrc), sets the link ~/mctdh -> $MCTDH_DIR , and defines the bash-function cdm. The command cdm cd-es to $MCTDH_DIR and e.g. the command cdm genoper or even only cdm geno cd-es to $MCTDH_DIR/source/genoper. Note also that there is also the bash-function minstall. This function allows very conveniently for a switching between (installed) MCTDH-directories, i.e. it re-sets the MCTDH environment variables. (Type minstall -h for help).

Running the script install_mctdh is in general all what you will have to do!
If you are not happy with the default choice of the compiler, you should install a private platform.cnf script. To do so, please move to $MCTDH_DIR/install/ and copy platform.cnf.priv.template to platform.cnf.priv and edit this script according to the guidelines given there. For each of your computers (identified by there hostnames) you may specify the most appropriate compiler. However, you can only choose among compilers which are listed in script compile.cnf. (Hint: compile.cnf is generated when running install_mctdh. It is simply a copy of either compile.cnf_le, compile.cnf_be, compile.cnf_lenp, or compile.cnf_benp. Here le and be mean little endians and big endians, repectively, and np stands for no parallelization. Similarly, platform.cnf is a copy, made by install_mctdh, of either platform.cnf.* ). Then run install_mctdh again.

If you are using a platform or a compiler we have not used before, you need to add some lines to $MCTDH_DIR/install/platform.cnf and $MCTDH_DIR/install/compile.cnf . This is described below: Configuring the MCTDH Package
Important Note:   Do not change the path-names within the MCTDH directory. If you re-name, move or copy the whole MCTDH directory,   you must run install_mctdh again!  Type menv (MCTDH environment) to see the current setting of the paths. The command compile config tells you what compile will do. Hint for advanced users: If you have more than one MCTDH-directory and want to compile the currently not installed one, you can do so by using the option -l (local). Just type /absolute_path_of_second_MCTDH_DIR/bin/compile -l  task , or move to somewhere in the second_MCTDH_DIR and execute compile -l   task.

If one wants to use one of the multi-dimensional potential energy surfaces implemented (see Available Surfaces), one has to download the tar-file addsurf.tgz. Unpack this file and copy the desired surfaces to $MCTDH_DIR/source/surfaces. Alternatively (recommended) one may set links from $MCTDH_DIR/source/surfaces to addsurf. This is most conveniently done by running the script mklinks. To link the additional surfaces use the -i option (include). E.g.:

compile -i 'nocl1sch hoosrf' mctdh
will link the surfaces nocl1sch and hoosrf to the mctdh executable. (The names may be abbreviated, as long as the abbreviation is unique. In the present case -i 'n ho' is sufficient). Alternatively one may edit the compile-script (line 18) to
surflist='lsth nocl1sch hoosrf'

If you however prefer to do the installation by hand, i.e. without invoking the install_mctdh script, the following steps are required. (This is listed mainly to make you understand, what install_mctdh is doing).

Step 1

Before using the package, a few environment variables need to be set. This is best done by adding the following lines to your .profile or .bashrc file.
export MCTDH_DIR=/usr/people/mctdh/mctdh84.1
source $MCTDH_DIR/install/mctdh.profile
substituting "/usr/people/mctdh/mctdh84.1" by the relevant installation path for the $MCTDH_DIR variable. The environment required by the package is then set correctly on login.

If you are using a C-shell, add the lines

setenv MCTDH_DIR /usr/people/mctdh/mctdh84.1
source $MCTDH_DIR/install/mctdh.profile.csh
to your .profile or .cshrc file.

The script $MCTDH_DIR/install/mctdh.profile includes the paths for the script files and executables into your $PATH environment variable. It also sets the environment variable $MCTDH_VERSION with the version number of the package. This is required by various scripts used to run the programs.

After the remaining steps of the installation have been performed, the .profile (or .bashrc/.cshrc) must be sourced before the package is used.

Step 2

For the compilation of the executables, the environment variables $MCTDH_PLATFORM and $MCTDH_COMPILER must be set. These are required to set the path where the executable will be stored, and to select the compiler environment (i.e. compiler, linker, make-command, etc.) that will be used. These variables are taken from the file $MCTDH_DIR/install/platform.cnf.

Before installation this file does not exist. The file $MCTDH_DIR/install/platform.cnf.def (or $MCTDH_DIR/install/platform.cnf.csh.def) contains default settings, which chooses these variables depending only on the system (e.g. Linux, or IRIX). Thus if you are using an Intel Pentium II PC running under Linux, $MCTDH_PLATFORM=i686 and $MCTDH_COMPILER=g77 would be selected from this file. To use the default settings, platform.cnf.def (or platform.cnf.csh.def) should be copied to platform.cnf.

The file $MCTDH_DIR/install/platform.cnf.hd contains machine dependent settings for the Heidelberg cluster.

Step 3

The next stage is the compilation of the documentation. Some of the document files are in Latex format, and must be compiled before they can be read. If this compilation is not done, the on-line HTML documentation can still be read. The index to the on-line documenation is $MCTDH_DIR/doc/index.html. At the end of the installation, the User's Guide in postscript format is in $MCTDH_DIR/doc/guide/guide.ps

Step 4

The final part of the installation is the compilation of the programs.

Before compilation, the file $MCTDH_DIR/source/include/paths.inc has to be installed. The install_mctdh script does this automatically. See this script, if you really want to do it "by hand".

Using the installation script, first the compiler and compiler options that will be used are listed. These are selected according to the $MCTDH_PLATFORM and $MCTDH_COMPILER variables selected from the $MCTDH_DIR/install/platform.cnf file.

This is then followed by the question whether the code should be compiled. If the chosen options are not correct, e.g. a different compiler is wanted, answer no. The programs can then be compiled using the compile script. See Compiling the Programs for more details.

Note 1:

Before you compile, you should inspect lines 12-31 of the compile-script (see: $MCTDH_DIR/bin/compile). There you should set the permissions permb and permo according to your demands. When you receive the MCTDH package, the permissions may be set rather generously in order to avoid conflicts. If you are the only one who is using the MCTDH package, you may wish to set the permissions to 700 and 600.

Note 2:

The MCTDH directory may be given any name you like. However, when you change the name or the path of your MCTDH directory, (i.e. $MCTDH_DIR), you have to (re-)run the script install_mctdh.

Note 3:

The script install_mctdh creates backups of the files which it modifies. These backups are called ~/.save-* or $MCTDH_DIR/install/save-pltfrm.* (where * stands for anything). You may remove these backups, if they are no longer needed.

Note 4:

If you are using bash, it will be very convenient to copy the script $MCTDH_DIR/install/mctdhrc to ~/.mctdhrc . This (hidden) file will then be sourced when the .bashrc is sourced. The .mctdhrc script sets some aliases, the link ~/mctdh -> $MCTDH_DIR , and defines the bash-function cdm. The command cdm cd-es to $MCTDH_DIR and e.g. the command cdm genoper cd-es to $MCTDH_DIR/source/genoper. Note also that there is the bash-function minstall. This function allows very conveniently for a switching between (installed) MCTDH-directories.

Multi user installation of the MCTDH Package

If several MCTDH-users shall use the same package, the master-user shall install the package as described above. All additional users (client-users) then have to run the install script with the -u option, i. e.  <path-of-the-MCTDH-directory>/install/install_mctdh -u . Make sure that the permissions are set appropriately. If everybody uses bash, there is even a simpler solution. The install script generates the file MCTDH_client. A client user merely has to source this file. To this end he should add the line
.   <path-of-the-MCTDH-directory>/install/MCTDH_client
to his .bashrc file.
To check whether the paths are set correctly, one should run the script menv.

Configuring the MCTDH Package

The MCTDH package has been successfully installed on a variety of platforms, ranging from PCs through workstations to vector computers. Therefore, there is a good chance that you do not need to configure the MCTDH package at all. In case of problems with the installation, or if you are not satisfied with the default settings, you need to modify some of the installation scripts. We will thus briefly discuss the strategy the MCTDH package employs in the installation.

The first step of the installation process is to detect the operating system being used, by employing the uname -s  command. You may enter this command on your console to find out the result. In dependence of the operating system, the values of the $MCTDH_PLATFORM and $MCTDH_COMPILER variables are set. This is done by the $MCTDH_DIR/install/platform.cnf script, which is generated during the installation. The default values are given in the following table.

Operating system Producer $MCTDH_PLATFORM $MCTDH_COMPILER
Linux various result of  uname -m gfortran or g77
Darwin Apple result of  uname -m gfortran or g77
AIX IBM risc risc
HP-UX HP hp hp
IRIX SGI result of  uname -p mips
OSF1 DEC result of  uname -p alpha
SunOS Sun result of  uname -p sparc
sn* CRAY t90 t90
other   default default

The $MCTDH_PLATFORM determines the directory the executables and object files are moved to and the $MCTDH_COMPILER variable serves to define the compiler environment. Executables are stored in $MCTDH_DIR/bin/binary/$MCTDH_PLATFORM and object files are stored in $MCTDH_DIR/object/$MCTDH_PLATFORM/$MCTDH_COMPILER . For instance, on a DEC alpha workstation the executables will be stored in $MCTDH_DIR/bin/binary/alpha and the object files in $MCTDH_DIR/object/alpha/alpha. The former path will also be added to your $PATH variable. On a Pentium II PC running under Linux the corresponding directories are $MCTDH_DIR/bin/binary/i686 and $MCTDH_DIR/object/i686/g77. If you compile a MCTDH program using a non-default compiler (by using the -c option of compile, see below), the executable will have the extension .$MCTDH_COMPILER, e.g. mctdh84.absoft . It is hence possible to install the MCTDH package on a workstation cluster with different architectures but a shared file system, without any conflicts between the different executables.

The $MCTDH_COMPILER variable serves to define the compiler environment, i.e. the Fortran77 and C compilers, the compiler options, the linker, the make-command, etc. A number of compiler environments are available, compiled in the following table. For optimal performance of the MCTDH package you should check whether an environment exists which better fits your platform than the default one.

Compiler environment Description
gfortran Linux linker, make-command, etc., with GNU Fortran and C compilers. GCC-version 4.2 and up. Produces 32bit or 64bit executables, depending on your platform's standard.
gfortran-32 Similar to gfortran, but explicitly generates 32bit executables.
gfortran-64 Similar to gfortran, but explicitly generates 64bit executables.
g95 Linux linker, make-command, etc., with GNU C compiler and G95 Fortran compiler.
absoft Same as above, but with Absoft Fortran compiler.
intel Intel compilers for Linux (version 8.0), probably works only on Pentium4.
intel64 Intel compilers for ia64 and x86_64 Linux (ifort version ≥ 8.0), works on Itanium an Xeon. Options set for 32 bit data storage and pointers uniprocessor.
pgf77 Linux make, etc., with compilers and linker of the Portland Group.
alpha DEC compilers, linker, etc., but with GNU make-command. The code is optimised for the architecture being used.
mips SGI compilers, linker, make-command, etc. The code is optimised for the mips2 architecture.
risc IBM compilers, linker, make-command, etc. The code is not optimised for a particular architecture.
pwr Same as above, but the code is optimised for Power1 platforms.
pwr2 Same as above, but the code is optimised for Power2 platforms.
pwr3 Same as above, but the code is optimised for Power3 platforms.
ppc Same as above, but the code is optimised for PowerPC platforms.
hp HP compilers, linker, make-command, etc. The code is not optimised for a particular architecture.
sparc SUN compilers, linker, make-command, etc. The code is not optimised for a particular architecture.
t90 CRAY compilers, linker, make-command, etc. The code is optimised for the T90 vector architecture, but runs also on J90 vector machines.
default Assumes that the Fortran and C compilers are named "f77" and "cc", and that a POSIX-make exists. A minimum of compiler options are used that should be available on most platforms.

Depending on the compiler environment, a variety of variables are set that specify which compiler, compiler options, linker, make-command, etc. to use. This is done in $MCTDH_DIR/install/compile.cnf. The following table describes these variables:

In order to define a new compiler environment, the above variables have to beset appropriately. If you have done so, please send us the modified files to include them in future versions of this distribution. See compile.cnf for the current setting.

Minimising the Memory Requirements

The MCTDH program allocates most of its required memory dynamically. Some smaller arrays, however, are allocated statically, since they appear in common blocks. Although none of these needs an appreciable amount of memory, their overall memory requirements might accumulate to a few Megabyte. The sizes of these arrays are defined by limits stored in the include files in $MCTDH_DIR/source/include. The current settings, together with a brief description, of these limits can be found by the command
mctdh84 -max
The max-parameters are probably set to rather large numbers when you receive the MCTDH distribution. This makes it fairly unlikely that the program will not run because of a too small parameter setting. However, to ensure that no memory is wasted, you may wish to decrease some of these values according to the system under investigation.

For instance, in the file maxsta.inc the maximum number maxsta of electronic states is defined. If your system includes only one electronic state, you may set maxsta=1 and then re-compile the package (compile all).

Compiling the Programs

If the programs need to be compiled, then this can be done automatically using the $MCTDH_DIR/bin/compile shell script and the associated Makefile. The shell script is called automatically during installation. It can be called from any directory if $MCTDH_DIR/binis in your $PATH environment variable. The $PATH will be correctly set, if you have run install_mctdh and then sourced your ~/.bashrc (or ~/.profile, or ~/.cshrc) configuration file.

The compilation is started by typing

compile [-opt] progname
The argument progname compiles the named program, or group of programs. Examples are mctdh, potfit, analyse, or all.

To find the full list of options and arguments, type

compile -h
The compilation procedure produces a set of executables in the directory $MCTDH_DIR/bin/binary/$MCTDH_PLATFORM, using the compiler specified by the $MCTDH_COMPILER variable. These variable are taken by default from the file $MCTDH_DIR/install/platform.cnf according to the system being used. To display the compiler options being used, type
compile config

Since there are now a number of potential energy surfaces available, we no longer include all of them. To link a desired potential energy surface to mctdh or potfit, one has to specify the surface(s) via the -i option of compile. E.g.:

compile -i bkmp2 -i hoosrf mctdh
or
compile -i 'bkmp2 hoosrf' mctdh
Both forms will link both, the bkmp2 and the HO2surfaces to mctdh. Alternatively, one may edit line 18 of the compile script.
surflist='lsth bkmp2 hoosrf'
This is convenient, if one always wants to include a particular potential energy surface.

Compiling the Documentation

The script $MCTDH_DIR/install/dcompile is used to compile the Latex files in the documentation. If this has not already been done during the installation, this script can be run independently.

Starting A Program

To start a program on a platform for which you have compiled it just type:
progname< ver >  [-opt]  arguments

where progname is the name of the program,  ver is the version number (and optionally a "d" or a name) and  arguments specifies any arguments required by the program.

To find the possible options and arguments required for a program, the argument -h can be used. For example, to find the possible options for the MCTDH program version 8 release 3 type:

mctdh84 -h

Almost all programs (and scripts) of the MCTDH package know the option -h. Use it!

Variable Description
FC Denotes the Fortran compiler, e.g. f77 or f90. One may also specify a path, e.g. /usr/bin/f77.
CC Denotes the ANSI-C compiler, e.g. cc. One may also specify a path, e.g. /usr/bin/cc.
MCTDH_FFLAGS_OPT A list of options for the Fortran compiler. These options are employed when the code is optimised.
MCTDH_FFLAGS_DEB A list of options for the Fortran compiler. These options are employed when the code is to be processed by a debugger.
MCTDH_FFLAGS_INC Options needed by the C preprocessor to specify the path of the include files.
Include files are read in the Fortran routines by the #include statement, which is actually a C preprocessor directive. Since the include files are stored in a special directory, the Fortran compiler must pass the corresponding path to the preprocessor. The variable MCTDH_FFLAGS_INC defines the option(s) for this, e.g. "-I".
MCTDH_FFLAGS_MOD Sets path for compiled module files. (The path is actually set in the compile script)
MCTDH_OMP_FLAGS Sets flag to enable OpenMP.
EXTERNAL_BLAS Compiler options that specify where an external BLAS library can be found.
Normally, MCTDH uses code from NETLIB's reference implementation for the few BLAS and LAPACK routines that it uses. However, this can be changed with the -x switch of the compile script; e.g. "compile -x blas mctdh" would generate an MCTDH executable that is linked not with the reference BLAS, but with an external BLAS. This variable tells the linker where to find such an external BLAS.
EXTERNAL_LAPACK Compiler options that specify where an external LAPACK library can be found.
Normally, MCTDH uses code from NETLIB's reference implementation for the few BLAS and LAPACK routines that it uses. However, this can be changed with the -x switch of the compile script; e.g. "compile -x lapack mctdh" would generate an MCTDH executable that is linked not with the reference BLAS and LAPACK, but with external libraries. This variable tells the linker where to find the external LAPACK; the external BLAS is specified by the variable EXTERNAL_BLAS.
MCTDH_ADD_LIBS A list of additional libraries to be linked to the MCTDH code.
Although normally only the libraries of the MCTDH package are required, there might be cases where additional libraries must be linked. For example, the Absoft compiler needs the library "-L/usr/lib/ -lU77", which contains e.g. the "getarg" routine.
MCTDH_CFLAGS A list of options for the C compiler.
MCTDH_ARFLAGS A list of options for the archive command "ar".
MCTDH_OP_SYSTEM Denotes the operating system.
MCTDH_MAKE_CMD The name of the make-command, e.g. gmake. One may also specify a path, e.g. /usr/bin/posix/make.
MCTDH_FLUSH_EXT Defines the flush command to be used.
The flush command enforces the contents of a file buffer to be written to disk immediately. This is regularly done to reduce the risk of loosing data in case a calculation crashes. If this variable is set to _lib, then the MCTDH program assumes that your Fortran compiler provides a flush-routine, named flush. If no value is set, a corresponding routine of the MCTDH package is used. If $MCTDH_FLUSH_EXT=_no, then the buffers are not flushed. The latter value should be chosen if the I/O-time (i.e. system time) is strongly increased by flushing the buffers, i.e. if the system time amounts to more than a few percent of the CPU time. (See the log file for this information.)
MCTDH_F2C_STYLE This variable selects how Fortran symbols are seen from C code.
Different architectures use different methods to convert Fortran symbols into C symbols. This is important when Fortran and C code are linked together, as is the case in MCTDH. The following values are possible:
MCTDH_F2C_STYLE Fortran symbol C symbol Example architecture
0 FOO foo_ SGI, Tru64, Linux
1 FOO foo AIX, HP-UX
2 FOO FOO Cray
MCTDH_PTHREAD_STYLE Pthread style. (In gereral 0)