Installation problems


compilation problems

MCTDH is running on several architectures including Linux PC, Silicon-Graphics IRIX, Compac/DEC OSF1, IBM AIX, Cray and Sun. However, your particular setup, i.e. operating system and compiler, may not be covered by our installation routine. In this case you have to modify the file install/compile.cnf and possibly also install/platform.cnf to set the appropriate compiler options etc. Note that these files are generated by the install_mctdh script and hence are overwritten when running install_mctdh again. These files are copies of one member of the compile.cnf_* and platform.cnf.* families, respectively. See Configuring the MCTDH Package for further details.

If the code is compiled correctly, but the link step fails because some routines like fcputime, fsystime, fpstartup, fgetcwd, fzeit, fhome, callprop, calldvr, etc are not found, then probably the FORTRAN and the C compiler are not cooperating correctly. All the above mentioned routines are C-routines. Most likely, an underscore is wrongly appended or not appended to the FORTRAN names of the C-routines. To change this, use the variable MCTDH_F2C_STYLE in the file install/compile.cnf. The possible values of this variable and their meanings are described at the top of this file.

There may also be a problem with make, see make problems below.

If you want to use a free GNU-compiler we recommend gfortran from the GCC compiler collection. However, one has to use GCC-5.2 or higher. Older GCC-4 versions do not work properly! (See Linux-PC problems below). Note that gfortran will be the default choice, if this compiler is installed.


make problems

The compilation of MCTDH package requires a POSIX make. The popular Compac/DEC-alpha computers are shipped with a non-POSIX make and the compilation fails. In this case one has to install a GNU-make. Download the GNU-make from the internet: www.gnu.org/software/make/make.html . Make sure that the paths to this program are set correctly. (You may need to edit the install/compile.cnf file(s)). It is often useful to set a link in /bin or in /usr/bin .



bash problems

The MCTDH package uses bash shell-scripts quite extensively. (There is also a small number of C-shell scripts). It will be very difficult to install the MCTDH package without bash. If bash is not available on your computer, download it from www.gnu.org/software/bash/bash.html . The GNU installation script by default installs bash to   /usr/local/bin  . As the MCTDH bash-scripts assume bash to reside on   /bin   you should set a link:   ln -s   /usr/local/bin/bash   /bin/bash


This, however, requires super-user rights. When your system administrator is not cooperative, you have to change the #!/bin/bash line in all scripts. This may be done with the help of the bashpath script, which can be found under $MCTDH_DIR/install . Just type "./bashpath path_of_bash" while being in the $MCTDH_DIR/install directory. Here path_of_bash denotes the full absolute path-name of your bash, e.g /usr/local/bin/bash .



gnuplot problems

The analyse programs of the MCTDH package use gnuplot quite extensively. One needs at least GNUPLOT Version 3.7, but we strongly recommend to use GNUPLOT Version 4.0 or higher. If you do not have this software installed on your computer, download it from the internet:   http://www.gnuplot.info/ .



Linux-PC problems

If you are working on a PC running under Linux, there should be no problems provided your Linux distribution is up-to-date (i.e. not older than May 2013). If you have an older Linux distribution, you may wish to download the latest gcc-compilers: GCC home page .
If you have a brand new Linux, it may come with the new GCC-4 compiler collection. This contains the Fortran95/90 compiler gfortran. It is recommended to use at least gcc-5.2.
A main reason for using a commercial compiler instead of the GNU compilers would be to have a better debugger. Unfortunately the GNU Debugger gdb still has many problems in connection with Fortran source. As for performance, our tests showed that recent versions of GCC are on par or even faster than most commercial compilers (this only holds for the i686 and x86_64 platforms). One notable exception are the Pathscale compilers for the x86_64 platform; in our tests they consistently showed a better performance than GCC.


Mac OS X (Apple) problems

Since version 8.4.4 MCTDH installs painlessly on a Mac. However, one first has to install a Fortran compiler, gnuplot, and Apples Xcode software including the Xcode command line tools. Run:

    xcode-select --install
    sudo xcodebuild -license
    sudo xcode-select -s /Library/Developer/CommandLineTools
  
For the compiler we recommend GNU gcc and gfortran version GCC-5.2.x or higher. (For Catalina, macOS 10.15, one must use gcc9 !) See Linux-PC problems above for remarks on compilers. We recommend to use the GNU compilers and gnuplot from the MacPorts project https://www.macports.org.

As an alternative to MacPorts one may use the Fink project http://www.finkproject.org or the Homebrew project https://brew.sh/index_de.html (both untested). In the following the installation using MacPorts is outlined.

Besides the compiler also other very useful toolsets from the MacPorts project can be installed with the coreutils package and gsed that add basic GNU tools like tar, sed, awk, etc. The tools shipped by Apple behave differently than the GNU versions which sometimes causes problems when executing shell scripts from the MCTDH package. Upon installation of coreutils the MacPorts installer will suggest to prepend the location of the GNU-Commands to the $PATH variable. We recommend to do this in the .bashrc.
Note: the 'Terminal' application will source .bash_profile by default and not the .bashrc. As the MCTDH installer will also write to the .bashrc we recommand sourcing the .bashrc in the .bash_profile.

In detail, after a fresh MacPorts installation issue the following:

    sudo port install coreutils
    sudo port install gsed
    sudo port install gcc9  (Or other gcc-version)
  
Then edit the $PATH variable in your .bashrc (e.g.: export PATH=/opt/local/libexec/gnubin:$PATH) and reload it (source ~/.bashrc).
Also add the following line to your .bash_profile (if not already there):

[[ -s ~/.bashrc ]]; source ~/.bashrc

The binaries of the GNU compilers (and some other packages from MacPorts) are named differently than on Linux platforms so they will not appear by their default names. For instance gfortran will be named gfortran-mp-9 or similar. To make them available by their standard names issue a command like

    sudo port select --set <group-name>  <group-version-name>
  
One can list installed MacPorts groups and versions like this:
    port select --list <group-name> # one specific group
    port select --summary           # all groups
  
For instance to make the GNU compilers version 9 the default compilers issue
    sudo port select --set gcc mp-gcc9
  
Thereafter the MacPorts version gfortran-mp-9 will be available by the usual short name gfortran. Also gnuplot (used by various analysis tools) can be installed from MacPorts. We suggest installing the wxwidgets variant (the base installation did not support interactive plot windows in our test installation):
    sudo port install gnuplot +wxwidgets
  
After the additional software is installed, the install script $MCTDH_DIR/install/install_mctdh should install the package with no problems. Previously one had to choose the no parallelization option, e.g. compile.cnf_lenp, but for versions launched after January 2018 this is no longer needed. Compilation with pthread support works for MacOS 10.6 (Snow Leopard) or newer. One may also download the OpenMPI software and use MPI-parallelization.


Stack size problems / mysterious segmentation faults

A few of the older analyse programs allocate big arrays of memory statically. Since such memory gets allocated on the stack, you can run into problems if the maximum stack size is limited (this can be checked with "ulimit -a"). This problem manifests itself in segmentation violations that occur immediately after program startup. To work around this problem, you can disable the limit on the stack size by "ulimit -s unlimited". However, you might not be allowed to do this on your system. In this case, try talking to your system administrator. If that doesn't help, you can decrease the needed stack size by changing the appropriate parameters in the affected programs.



Updating the source by applying patches



patch levels

To handle bug fixes more conveniently, we decided to introduce a patch level in addition to Version/Release/Revision. For these (rather small) changes we will supply only the patch files and not the full updated MCTDH directory. E.g. the files

GNUpatch84.2-84.2.1.gz
Mpatch84.2-84.2.1.tgz

contain the patches in GNU or Mpatch format, respectively, for updating mctdh84.2 to mctdh84.2.1, i.e. to patch-level 1. If there is a patch-level 2, the patch will be from the last version to patch-level 2, not from patch-level 1 to patch-level 2.



GNU patch

The GNU patch is a very useful piece of software. If you do not have it on your computer (it is included in most Linux distributions), we strongly encourage you, to download it from a GNU server:
www.gnu.org/software/patch/patch.html.
The GNU patch file contains only the differences between the old and the new version and is hence rather small. As the changes we have made and the changes you have made (e.g. adding a new potential surface) are likely to be on different files or at least on different portions of a file, it is very likely that the patch works on your modified version. It may, however, be a good practice to keep the *.tgz file of the previous complete version at some safe place. In case the patch should fail at your modified version, you then can at least apply it to the original one.

The patch-file is generated by us via the command:

LC_ALL=C TZ=UTC0 diff -Naur --exclude='.*mctdhall.*' --exclude='mctdhall*' \ --exclude='paths.inc' --exclude='platform.cnf*' --exclude='compile.cnf' \ --exclude='*~' --exclude='*_bk*' --exclude='*_md*' old-file   new-file > GNUpatch-old-new

(See $MCTDH_DIR/bin/mkGpatch). What you have to do is to download and un-gzip the patch-file, move it to the directory which hosts the MCTDH directory, and type:

patch -u -p0 < GNUpatch-old-new

Note:

After the patch is applied, you should rename the patched MCTDH directory to the name of the patched version and run install/install_mctdh.



Mpatch

For your convenience, we offer a second kind of patch, called Mpatch. Mpatch is a directory, structured like a MCTDH directory, but containing only the changed files. It may be thus rather large, but still considerably smaller than a full MCTDH distribution.

Download the Mpatch.tgz file and un-gzip and un-tar it. You then may replace the changed files by hand or you may use mdistribute to do that automatically. (mdistribute is on $MCTDH_DIR/bin). Type:

mdistribute path_of_Mpatch_directory

and mdistribute will tell you, what it is going to do. Inspect the output carefully, in particular whether the paths are set correctly, and when you are satisfied type:

mdistribute -c path_of_Mpatch_directory

to actually perform the replacement of the files. Here we have assumed that the environment variable MCTDH_DIR is set correctly, i.e. is set to the path of the MCTDH directory to which the patch shall be applied. (Use the command menv to check this). If this is not the case, you must give the path of the MCTDH directory to be patched as a second argument of mdistribute. (See mdistribute -h).

After the patch is applied, you should rename the patched MCTDH directory to the name of the patched version and run $MCTDH_DIR/install/install_mctdh.