Installation and Compilation

Back to Main Menu

Installation and Compilation

Overview of Package

The QUANTICS package is a set of programs able to set up and propagate a wavepacket using various methods such as MCTDH. 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 QUANTICS 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.

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 QUANTICS. 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.

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 QUANTICS package by yourself but rather tell the interested person to contact the developers. 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 QUANTICS package fails, see Installation Problems.

Documentation Nomenclature

The "variable" $QUANTICS_DIR is used to denote the directory from which the QUANTICS package was installed.


Installing the Program

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

For the installation of the complete package, one needs a computer with a UNIX (or UNIX-like, e.g. Linux) operating system.

The following software is required:

A FORTRAN 90 compiler
This compiler must support some extensions like lower case fortran code, the getarg function, etc (all the compilers we tried did so). You also need a C compiler which cooperates with your FORTRAN compiler, and you need a POSIX make. If your make-command does not obey the POSIX standard, you should install a GNU-make. (See make problems).
Quantics is tested on a few compilers, but the GFORTRAN compiler is recommended. Versions up to 8 are known to compile without problem.
The fortran compiler requires SQLite capabilities. For gfortran this requires the installation of the sqlite3 and sqlite3-devel packages.
A bash shell
Version 2.0 is recommended, but version 1.14 should do as well. See bash problems if bash is not available on your computer or is not located in /bin .
A Latex2e package
including xdvi, dvips and some Latex packages, such as "AMSmath" or "fancyhdr". You need Latex to compile some part of the documentation, in particular the QUANTICS User's Guide.
A WWW browser
such as Firefox or Konqueror is required to read this on-line documentation.
GNUPLOT Version 5.0 or above
is required to take full advantage of the analyse routines. Version 3.7 also works, but offers less functionality. See gnuplot problems if gnuplot is not available on your computer.
EVINCE (pdf viewer)
is required to use the plotting program in VCHAM (vcplot).
JMOL (molecule viewer)
is required to plot molecular structures using the analysis programs on direct dynamics simulations.

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 QUANTICS package, first move to a suitable directory. We recommend that you create a directory named QUANTICS. The path of this directory will be termed $QUANTICS_DIR. If the package has been obtained as a tared and zipped file, e.g. quantics<ver>.tgz, where <ver> is the version number such as 1.1, unpack the archive using

gunzip quantics<ver>.tgz
tar xvf quantics<ver>.tar

All the files required by the package will now be present. If you have a GNU tar, you may use the comand tar xzvf quantics.tgz

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

$QUANTICS_DIR/install/install_quantics

To execute install_quantics, move to $QUANTICS_DIR/install and type "./install_quantics", 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 QUANTICS environment variables are listed if you type menv.

Running the script install_quantics is in general all you will have to do!

If you are not happy with the default choice of the compiler, you should edit the platform.cnf script. For each of your computers (identified by their hostnames) you may specify the most appropriate compiler. However, you can only choose among compilers which are listed in script compile.cnf. Then run install_quantics again.

If you are using a platform or a compiler we have not used before, you need to add some lines to $QUANTICS_DIR/install/platform.cnf and $QUANTICS_DIR/install/compile.cnf . This is described below: Configuring the QUANTICS Package

Important Note: Do not change the path-names within the QUANTICS directory. If you re-name, move or copy the whole QUANTICS directory, you must run install_quantics again! Type menv (QUANTICS 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 QUANTICS-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_QUANTICS_DIR/bin/compile -l task , or move to somewhere in the second_QUANTICS_DIR and execute compile -l task.

If you are using bash, the script $QUANTICS_DIR/install/quanticsrc sets some aliases and functions that may be useful. For example, the command cdm cd-es to $QUANTICS_DIR and e.g. the command cdm genoper or even only cdm geno cd-es to $QUANTICS_DIR/source/genoper. Note also that there is also the bash-function minstall. This function allows very conveniently for a switching between (installed) QUANTICS-directories, i.e. it re-sets the QUANTICS environment variables. (Type minstall -h for help).

Manual installation

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

Step 1

Before using the package, a few environment variables need to be set. First set QUANTICS_DIR=/usr/people/quantics
source $QUANTICS_DIR/install/quantics.profile

substituting "/usr/people/quantics" by the relevant installation path for the $QUANTICS_DIR variable. If these are added to your .profile or .bashrc file, the environment required by the package is then set correctly on login.

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

setenv QUANTICS_DIR /usr/people/quantics
source $QUANTICS_DIR/install/quantics.profile.csh

to your .profile or .cshrc file.

The script $QUANTICS_DIR/install/quantics.profile includes the paths for the script files and executables into your $PATH environment variable. .

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 $QUANTICS and $QUANTICS_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 $QUANTICS_DIR/install/platform.cnf.

Before installation this file does not exist. The file $QUANTICS_DIR/install/platform.cnf.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, $QUANTICS=i686 and $QUANTICS_COMPILER=gfortran would be selected from this file. To use the default settings, platform.cnf.def should be copied to platform.cnf.

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 documentation is $QUANTICS_DIR/doc/index.html. At the end of the installation, the User's Guide in postscript format is in $QUANTICS_DIR/doc/guide/guide.ps

Step 4

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

Before compilation, the file $QUANTICS_DIR/source/include/paths.inc has to be installed. The install_quantics 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 $QUANTICS and $QUANTICS_COMPILER variables selected from the $QUANTICS_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: $QUANTICS_DIR/bin/compile). There you should set the permissions permb and permo according to your demands. When you receive the QUANTICS package, the permissions may be set rather generously in order to avoid conflicts. If you are the only one who is using the QUANTICS package, you may wish to set the permissions to 700 and 600.

Note 2:

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

Note 3:

The script install_quantics creates backups of the files which it modifies. These backups are called ~/.save-* or $QUANTICS_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 can be convenient to source the script $QUANTICS_DIR/install/quanticsrc on login. The quanticsrc script sets some aliases and defines the bash-function cdm. The command cdm cd-es to $QUANTICS_DIR and e.g. the command cdm genoper cd-es to $QUANTICS_DIR/source/genoper. Note also that there is the bash-function minstall. This function allows very conveniently for a switching between (installed) QUANTICS-directories.

Known Problems

MacbookPro (May 2021): On both Darwin and Mojave OS the installed gfortran9 does not work - various libraries cannot be found. Gfortran8 installed from either Brew or Port works.

Parallel Code

Quantics can use either OpenMP or MPI to take advantage of multi-core architectures and run parts of the code in parallel. The installation script installs the serial version. To compile the parallel versions, you first have to run the install script to set up the platform.cnf and compile.cnf files. You then have to set the required environment variables

export QUANTICS_DIR=path-of-the-QUANTICS-directory export source $QUANTICS_DIR/QUANTICS_client

This does not need to be done if your user has been installed and relevant profile (e.g. .bashrc) sourced.

To compile with OMP, type

compile -O quantics

To compile with MPI, type

compile -m quantics

The OMP code is called quantics.omp, the MPI code quantics.mpi. See Starting A Program for details of how to define the no. of processors.

Static Code

By default Quantics uses dynamic libraries of potential surfaces to make adding new functions easier and to save loading code that is not used. It is possible to make a static build, e.g. to make moving the code eaiser.

To compile with static libraries, type

compile -S quantics

Multi user installation of the QUANTICS Package

If several QUANTICS-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-QUANTICS-directory>/install/install_quantics -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 QUANTICS_client. A client user merely has to source this file. To this end they should add the line

. <path-of-the-QUANTICS-directory>/install/QUANTICS_client

to their .bashrc or .profile file.

To check whether the paths are set correctly, one should run the script menv.

Configuring the QUANTICS Package

The QUANTICS 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 QUANTICS 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 QUANTICS 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 $QUANTICS and $QUANTICS_COMPILER variables are set. This is done by the $QUANTICS_DIR/install/platform.cnf script, which is generated during the installation. The default values are given in the following table.

Operating system Producer $QUANTICS $QUANTICS_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 $QUANTICS determines the directory the executables and object files are moved to and the $QUANTICS_COMPILER variable serves to define the compiler environment. Executables are stored in $QUANTICS_DIR/bin/binary/$QUANTICS and object files are stored in $QUANTICS_DIR/object/$QUANTICS/$QUANTICS_COMPILER . For instance, on a DEC alpha workstation the executables will be stored in $QUANTICS_DIR/bin/binary/alpha and the object files in $QUANTICS_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 $QUANTICS_DIR/bin/binary/i686 and $QUANTICS_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 .$QUANTICS_COMPILER, e.g. quantics.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 $QUANTICS_COMPILER variable serves to define the compiler environment, i.e. the Fortran90 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.1 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), works only on Pentium4.
intel64 Intel compilers for ia64 Linux (version ≥ 8.0), works only on Itanium. 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 "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 $QUANTICS_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.

Compiling the Programs

If the programs need to be compiled, then this can be done automatically using the $QUANTICS_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 $QUANTICS_DIR/binis in your $PATH environment variable. The $PATH will be correctly set, if you have run install_quantics 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 quantics, 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 $QUANTICS_DIR/bin/binary/$QUANTICS, using the compiler specified by the $QUANTICS_COMPILER variable. These variable are taken by default from the file $QUANTICS_DIR/install/platform.cnf according to the system being used. To display the compiler options being used, type

compile config

Compiling the Documentation

The script $QUANTICS_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[-opt] arguments

where progname is the name of the program 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 QUANTICS program type:

quantics -h

Almost all programs (and scripts) of the QUANTICS package know the option -h.

If the OMP code has been compiled, the number of processors to be used can be specified with the option -omp

quantics.omp -omp n input

to ask for n cores. For the MPI version, use -m

mpirun -np n quantics.mpi -mpi input

Variable Description
FC Denotes the Fortran 90 compiler, e.g. gfortran. One may also specify a path, e.g. /usr/bin/gfortran.
CC Denotes the ANSI-C compiler, e.g. cc. One may also specify a path, e.g. /usr/bin/cc.
QUANTICS_FFLAGS_OPT A list of options for the Fortran compiler. These options are employed when the code is optimised.
QUANTICS_FFLAGS_DEB A list of options for the Fortran compiler. These options are employed when the code is to be processed by a debugger.
QUANTICS_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 QUANTICS_FFLAGS_INC defines the option(s) for this, e.g. "-I".
EXTERNAL_BLAS Compiler options that specify where an external BLAS library can be found.
Normally, QUANTICS 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 QUANTICS 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, QUANTICS 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 QUANTICS 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.
QUANTICS_ADD_LIBS A list of additional libraries to be linked to the QUANTICS code.
Although normally only the libraries of the QUANTICS 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.
QUANTICS_CFLAGS A list of options for the C compiler.
QUANTICS_ARFLAGS A list of options for the archive command "ar".
QUANTICS_OP_SYSTEM Denotes the operating system.
QUANTICS_MAKE_CMD The name of the make-command, e.g. gmake. One may also specify a path, e.g. /usr/bin/posix/make.
QUANTICS_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 QUANTICS program assumes that your Fortran compiler provides a flush-routine, named flush. If no value is set, a corresponding routine of the QUANTICS package is used. If $QUANTICS_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.)
QUANTICS_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 QUANTICS. The following values are possible:
QUANTICS_F2C_STYLE Fortran symbol C symbol Example architecture
0 FOO foo_ SGI, Tru64, Linux
1 FOO foo AIX, HP-UX
2 FOO FOO Cray