Installation guide

Molpro is distributed to licensees on a self-service basis using the world-wide web. Those entitled to the code should obtain it from https://www.molpro.net/download supplying the username and password given to them. The web pages contain links to the binaries and details of how to access the source code via git, although not everyone is entitled to source code, and binaries are not available for every platform.

Execution of Molpro, whether a supplied binary or built from source, requires a valid licence key. Note that the key consists of two components, namely a list of comma-separated key=value pairs, and a password string, and these are separated by ‘&’.

Our Linux binaries are built on the oldest supported version of CentOS, from Molpro 2020.2 onwards this is CentOS 7 and the binaries will therefore require a glibc of 2.17 or greater. If your system is older than this you can either install an older version of Molpro binary, install Molpro from source if you have access, or update your system to a newer OS.

Binaries are given as self-extracting tar archives which are installed by running them on the command line. After downloading simply uncompress the gzip file, ensure it is executable, then directly run the file.

The binaries are fully relocatable, the location can be changed when running the script interactively, the default is /usr/local.

If the script finds a licence key which has been cached in $HOME/.molpro/token from a previous install then that key will be installed with the software. If the script cannot find a key or automatically download it from the molpro website then the script will prompt that this part of the install has failed. All files of Molpro are installed, but the user must then manually install the key with the library files in a file named .token, e.g.:
/usr/local/molpro-mpptype-arch/lib/.token

When your licence is valid for one specific computer only (e.g. licences of type node8, node32, and especially if you hold a trial licence), then it is necessary to determine and enter the sysid on your account page. Only after that, a valid token may be downloaded.

Other configuration options may also be specified in the molpro script file found in the bin directory of the install.

If you hold a trial licence, then this corresponds to the installation of pre-built binaries as just described (installation) , for one specific computer. Presently, trial licences are only available for Linux and Mac.

This is necessary:

1) On your account page which you made at www.molpro.net , in section “Licences”, there is a link “Sign now”. Click this link and sign the licence agreement.
2) The trial licence is only valid for one specific computer. You have to determine the sysid of this computer. Download the script getinfo.sh from https://www.molpro.net/resources/getinfo.sh
3) Run the script on the computer where you want to install Molpro on, like this:
sh getinfo.sh
This will give an output such as: 4m00224dacb030
In some cases, it may look like this: 4m00224dacb030:4m00224dacb031
4) Enter the full string on your account page in the section “Licences”, in the box “Sysid”, and hit the return key.
There should now be a link “Download token” and a line “Default token: Id= ….”
5) Now go to “Download” on your account page. It may take a few seconds, until the page is displayed. Download the version for your operating system (Linux or Mac, but not Windows).
6) Uncompress the file molpro-mpptype-arch.sh.gz (it might be called e.g. molpro-mpp-2021.2.1.linux_x86_64_sockets.sh.gz )
gunzip molpro-mpptype-arch.sh.gz
7) Run the file as root:
sudo sh molpro-mpptype-arch.sh
Questions as shown below pop up. You may hit the return key which will use the defaults.
Enter bin directory to link Molpro (optional) (hit return key)
Enter installation directory for Molpro files [/usr/local/molpro/molpro_20XX.X] (e.g. something like /usr/local/molpro/molpro_2021.2 will be suggested) ; hit return key
Please give your username for accessing molpro (enter the account name of your account)
Please give your password for accessing molpro (enter the password of your account)
When things have worked well, you should get a message: Token sucessfully downloaded and installed
You may now try to run molpro: /usr/local/molpro/molpro_20XX.X/bin/molpro (use proper path, e.g. something like /usr/local/molpro/molpro_2021.2/bin/molpro)

licences for single machines: the steps are the same as when installing the trial version

group, site, service licences: it is not necessary to determine a sysid. The other steps are similar as when installing the trial version. File permissions should be set in such a way that the code is only made available to users which are covered by the licence.

Installing Molpro from source files involves the following distinct stages:

• Configuration A shell script that allows specification of configuration options is run, and creates a configuration file that drives subsequent installation steps.
• Building The program is compiled and linked, and other miscellaneous utilities and files, including the default options file, are built. The essential resulting components are
  1. The molpro shell script which launches the main executable.
  2. The molpro.exe executable, which is the main program. For parallel computation, multiple copies of molpro.exe are started by a single instance of molpro shell script using the appropriate system utility, e.g. mpiexec.
  3. Machine-ready basis-set, and other utilities and libraries.
• Tuning The program can be tuned for production by running tuning inputs and by making manual changes to the environment.
• Testing A suite of self-checking test jobs is run to provide assurance that the code as built will run correctly.
• Final Install The program can be run directly from the source tree in which it is built, but it is usually recommended to run the procedure that installs the essential components in standard system directories.

The following are required or strongly recommended for installation from source code.

1. A modern Fortran compiler. Molpro has Fortran code spanning Fortran 77 standard up to and including F2018 standard features. We aim to test Molpro regularly using the latest released version of GNU Fortran compiler. The Intel compiler should not be used if Molpro will be used to run PNO-LCCSD calculations.
2. A C++17 standard C++ compiler. We aim to test Molpro regularly with the latest released version of GCC.
3. A C99 standard C compiler. This is used to compile external libraries such as libxc and METIS.
4. A Python interpreter.
5. GNU Make.
6. Libxml2 library and header files.
7. Eigen template library, version 3.3 or newer.
8. Git, version 1.9 or newer.
9. For good performance it is important to use an appropriate LAPACK library which must also contain a full implementation of BLAS; in particular, a fast implementation of the matrix multiplication dgemm is very important for Molpro. Therefore you should use a system tuned LAPACK library whenever available.
10. A large scratch file system containing a directory that users may write on.
11. An MPI wrapped C++ compiler, eg. mpicxx. On HPC systems there is normally a vendor supplied library, otherwise one can install easily Open MPI which is known to work well with Molpro. We also recommend building Molpro with the Global Arrays toolkit. See GA installation for more details.
12. The source code of Molpro, which should be cloned via git as per the instructions in the download section of the website.

After cloning the source code, change to the Molpro_release directory that has been created. Having changed to the Molpro_release directory, you should ensure that you have checked out a tagged version of Molpro. You can do this by running git log to see if the top commit has tag:<TAGNAME> in parenthesis, if not find the first tagged commit and check it out.

Next check that the tools you require, such as the Fortran compiler, are in your PATH. Then run the command

./configure

which creates the file CONFIG. This file contains machine-dependent parameters, such as compiler options. Normally CONFIG will not need changing, but you should at the least examine it, and change any configuration parameters which you deem necessary. Additionally a shell script bin/molpro is created, this is normally fine for a single machine install, but on other setups may need modification, eg. the LAUNCHER variable may need changing from mpiexec to srun on a slurm system. Any changes made to CONFIG or bin/molpro will be lost next time ./configure is invoked, so it is best to supply as many of these as possible via the command line.

Options specification

The configure script may be given command line options and is also influenced by some environment variables. The complete list can be obtained by running:

./configure --help

while some commonly used ones include:

• --prefix=dirname Specify the Molpro toplevel installation directory, the default is /usr/local/molpro.
• --bindir=dirname Specify a bin directory where symbolic links will be created to the Molpro executables.
• --with-lapack-path=dirname The configure script will try to detect the most appropriate LAPACK library, however in certain cases, in particular when the LAPACK library is installed in a non-default location, configure should be directed to the appropriate directory containing the LAPACK library files.
• COPT=flags Specify compiler optimization flags for compiling C++ code.
• FOPT=flags Specify compiler optimization flags for compiling Fortran code.

Additionally variables such as CPPFLAGS, LDFLAGS, …can be used in the normal autoconf way. For instance, when Global Arrays is installed in a location such that the compilers can not directly find the include and library files one can specify these with, for example:

./configure CPPFLAGS=-I/usr/local/include \
            LDFLAGS=-L/usr/local/lib

Another case could be specifying the location of Eigen:

./configure CPPFLAGS=-I/usr/local/eigen3

After configuration, the remainder of the installation is accomplished using the GNU make command. Remember to check the default make on the system is GNU make (cf. section prerequisites), Molpro cannot be built with other make programs. Everything needed to make a functioning program together with all ancillary files is carried out by default simply by issuing the command

make

in the Molpro base directory. Most of the standard options for GNU make can be used safely; in particular, -j can be used to speed up compilation on a parallel machine. The program can then be accessed by making sure the bin/ directory is included in the PATH and issuing the command molpro.

Molpro can be tuned for a particular system by running in the root directory the command

make tuning

This job automatically determines a number of tuning parameters and appends these to the file bin/molpro. Using these parameters, Molpro will select the best BLAS routines depending on the problem size. This job should run on an empty system. It may typically take 10 minutes, depending on the processor speed, and you should wait for completion of this run before doing the next steps.

Adjusting the default environment for Molpro

The default running options for Molpro are stored in the script bin/molpro. After program installation, either using binary or from source files, this file should be reviewed and adjusted, if necessary, to make system wide changes.

At this stage, it is essential to check that the program has compiled correctly. The makefile target test (i.e., command make test) will do this using the full suite of test jobs, and although this takes a significantly long time, it should always be done when porting for the first time. A much faster test, which checks the main routes through the program, can be done using make quicktest. For parallel installation, it is highly desirable to perform this validation with more than one running process. This can be done conveniently through the make command line as, for example,

make MOLPRO_OPTIONS=-n2 test

If any test jobs fail, the cause must be investigated. If, after due efforts to fix problems of a local origin, the problem cannot be resolved, the developers of Molpro would appreciate receiving a report. There is a web-based mechanism at https://www.molpro.net/bugzilla at which as many details as possible should be filled in. It may also be helpful to attach a copy of the CONFIG file along with the failing output. Please note that the purpose of such bug reports is to help the developers improve the code, and not for providing advice on installation or running.

Although the program can be used in situ, it is usually convenient to make a system wide install for production. The install process copies only those files needed at run time into appropriate installation directories as specified at configuration time (see configuration) and stored in the file CONFIG. To install the program in this way, do

make install

The complete source tree can then be archived and deleted.

During the install process the key from $HOME/.molpro/token is copied to PREFIX/lib/.token so that the key will work for all users of the installed version.