If the installation of the MCTDH package fails, see Installation Problems.
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 86.1, unpack the archive using
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
gunzip mctdh<ver>.tgz
tar xvf mctdh<ver>.tar
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/mctdh86.1
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).
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.
Running the script install_mctdh is in general all what you will have to do!
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.:
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
compile -i 'nocl1sch hoosrf' mctdh
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).
substituting "/usr/people/mctdh/mctdh86.1" by the relevant installation path for the $MCTDH_DIR variable. The environment required by the package is then set correctly on login.
export MCTDH_DIR=/usr/people/mctdh/mctdh86.1
source $MCTDH_DIR/install/mctdh.profile
If you are using a C-shell, add the lines
to your .profile or .cshrc file.
setenv MCTDH_DIR /usr/people/mctdh/mctdh86.1
source $MCTDH_DIR/install/mctdh.profile.csh
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.
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.
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.
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 |
| Darwin | Apple | result of uname -m | gfortran |
| 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. mctdh86.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 5.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. | |
| mpi-gfortran | Similar to gfortran, but generates mpi-executables. | |
| g95 | Linux linker, make-command, etc., with GNU C compiler and G95 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. | |
| mpi-intel | Similar to itel64, but generates mpi-executables. | and pointers uniprocessor. |
| pgf77 | Linux make, etc., with compilers and linker of the Portland Group. | |
| mpi-pgf77 | Similar to pgf77, but generates mpi-executables. | |
| pgf90 | Linux make, etc., with compilers and linker of the Portland Group. | |
| mpi-pgf90 | Similar to pgf90, but generates mpi-executables. | |
| default | Assumes that the Fortran and C compilers are named "f90" 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.
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.
mctdh86 -max
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).
The compilation is started by typing
The argument progname compiles the named program, or group of programs. Examples are mctdh, potfit, analyse, or all.
compile [-opt] progname
will create both, mctdh86 and potfit86.
compile [-opt] mctdh potfit
To find the full list of options and arguments, type
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 -h
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.:
or
compile -i bkmp2 -i hoosrf mctdh
Both forms will link both, the bkmp2 and the HO2surfaces to mctdh. Alternatively, one may edit line 18 of the compile script.
compile -i 'bkmp2 hoosrf' mctdh
This is convenient, if one always wants to include a particular potential energy surface.
surflist='lsth bkmp2 hoosrf'
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 5 type:
mctdh86 -h
Almost all programs (and scripts) of the MCTDH package know the option -h. Use it!
| Variable | Description | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| FC | Denotes the Fortran 90/95 compiler, e.g. f90. One may also specify a path, e.g. /usr/bin/f90. | ||||||||||||||||
| 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_PTHREAD_STYLE | Pthread style. (In gereral 0) |