====== 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 source code, 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 ‘&’.


===== Installation of pre-built binaries =====

==== Prerequisites ====

Our Linux binaries are built on the oldest supported version of Rocky Linux, from Molpro 2024.2 onwards this is Rocky Linux 8 and the binaries will therefore require a glibc of 2.28 or greater. If your system is older than this you can either install an older version of Molpro binary, [[installation_guide#installation_from_source_files|install Molpro from source]] if you have access, or update your system to a newer OS. For running on multiple nodes using the MPI-PR binary it is recommended to install UCX.

==== Installation ====

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. You will need to run with ''%%sudo%%'' if you are installing somewhere outside of your own user space.

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.

==== Detailed installation of the trial version ====

If you hold a trial licence, then this corresponds to the installation of pre-built binaries as just described 
([[installation_guide#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:  **12m00224dacb030**\\ 
In some cases, it may look like this:    **12m00224dacb030:12m00224dacb031**\\ 
The first number is the number of cores, i.e. in this example 12m means 12 cores.\\
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)\\ 

==== Installation of a full version ====

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.


===== Installation from source files =====

==== Overview ====

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
    - The ''molpro'' shell script which launches the main executable.
    - 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''.
    - 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.

==== Prerequisites ====

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

  - A modern version of GNU 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.
  - A C++17 standard C++ compiler. We aim to test Molpro regularly with the latest released version of GCC.
  - A C99 standard C compiler. This is used to compile external libraries such as [[https://gitlab.com/libxc/libxc | libxc]] and [[https://github.com/KarypisLab/METIS | METIS]].
  - A Python interpreter.
  - GNU Make.
  - CMake, version 3.14 or newer. This is used to build external libraries such as [[https://gitlab.com/libxc/libxc | libxc]].
  - Eigen template library, version 3.3 or newer.
  - Git, version 1.9 or newer.
  - 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.
  - A large scratch file system containing a directory that users may write on.
  - 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 [[https://hpc.pnl.gov/globalarrays/|Global Arrays toolkit]]. See [[GA installation]] for more details.
  - The source code of Molpro.

There are example Dockerfiles for {{:Dockerfile.fc36.txt|fedora}}, {{:Dockerfile.lp154.txt|suse}} and {{:Dockerfile.ubuntu22.04.txt|ubuntu}}. For Mac with Apple Silicon one could use:
<code>
# build Molpro on MacOS, ARM architecture
# MacOS 12.6 Monterey
# prerequisite 1: command line developer tools, start with xcode-select --install
#                 Note: Xcode 14.0 is incompatible with gcc, and cannot be used. See https://stackoverflow.com/questions/73714336/xcode-update-to-version-2395-ld-compile-problem-occurs-computedatomcount-m/73765819#73765819
# prerequisite 2: install homebrew, starting from https://brew.sh
brew unlink open-mpi
brew install doxygen eigen gcc lapack python3 mpich cmake coreutils wget
brew link mpich
export CC=gcc-12 CXX=g++-12
export MPICXX=mpicxx MPICC=mpicc MPICH_CC=${CC} MPICH_CXX=${CXX}
wget -O - https://github.com/GlobalArrays/ga/releases/download/v5.8.1/ga-5.8.1.tar.gz | tar xzf - && cd ga-5.8.1 && ./configure --with-blas=no --with-lapack=no --with-scalapack=no --disable-f77 --with-mpi-pr && make -j10 && sudo make install && cd .. && rm -rf ga-5.8.1
git clone git@github.com:molpro/molpro
cd molpro
./configure && make -j20 && version=$(grep PACKAGE_VERSION build/molpro_config.h|sed -e 's/^.*PACKAGE_VERSION *"//' -e 's/" *$//') && sudo make install && sudo ln -sf /usr/local/molpro/molpro_${version}/bin/molpro /usr/local/bin/molpro
</code>
and for Mac with Intel:
<code>
# build Molpro on MacOS, Intel architecture
# MacOS 12.6 Monterey
# prerequisite 1: command line developer tools, start with xcode-select --install
#                 Note: Xcode 14.0 is incompatible with gcc, and cannot be used. See https://stackoverflow.com/questions/73714336/xcode-update-to-version-2395-ld-compile-problem-occurs-computedatomcount-m/73765819#73765819
# prerequisite 2: install homebrew, starting from https://brew.sh
# prerequisite 3: Intel MKL from https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl-download.html?operatingsystem=mac&distributions=webdownload&options=online

brew install eigen gcc python3 openmpi cmake coreutils
git clone https://github.com/GlobalArrays/ga ga_mpipr && cd ga_mpipr && git checkout v5.8.1 && ./autogen.sh && ./configure --with-blas=no --with-lapack=no --with-scalapack=no --disable-f77 --with-mpi-pr && make -j10 && sudo make install && cd .. && rm -rf ga_mpipr
git clone git@github.com:molpro/molpro
export OMPI_CXX=g++-12 OMPI_CC=gcc-12
cd molpro
./configure && make -j10 && sudo make install && sudo ln -s /usr/local/molpro/molpro_*/bin/molpro /usr/local/bin/molpro
</code>

Molpro can also be built using compilers and libraries from 
[[https://conda-forge.org|conda-forge]]. Here is how to construct a conda
environment with Molpro:
<code>
# build Molpro using conda toolchain
build_environment=molpro-build
deploy_environment=molpro-build # change this to an existing environment in which you want molpro, if you like

conda create -y -n ${build_environment} cxx-compiler c-compiler fortran-compiler mpich mkl-devel eigen cmake git curl wget make
conda activate ${deploy_environment} && deploy_prefix=${CONDA_PREFIX} || exit 1
conda activate ${build_environment}
wget -O - https://github.com/GlobalArrays/ga/releases/download/v5.8.1/ga-5.8.1.tar.gz | tar xzf - 
cd ga-5.8.1 && ./configure --prefix=${CONDA_PREFIX} --with-blas=no --with-lapack=no --with-scalapack=no --disable-f77 --with-mpi-pr && make -j10 && make install && cd .. && rm -rf ga-5.8.1
git clone git@github.com:molpro/molpro
cd molpro
./configure --prefix=${deploy_prefix} CXX=mpicxx && make -j20 && version=$(grep PACKAGE_VERSION build/molpro_config.h|sed -e 's/^.*PACKAGE_VERSION *"//' -e 's/" *$//') && make install && ln -sf ${CONDA_PREFIX}/molpro_${version}/bin/molpro ${CONDA_PREFIX}/bin/molpro
</code>
==== Configuration ====

After untarring the source code, change to the directory that has been created.

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

<code>
./configure
</code>
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:

<code>
./configure --help
</code>
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:

<code>
./configure CPPFLAGS=-I/usr/local/include \
            LDFLAGS=-L/usr/local/lib
</code>
Another case could be specifying the location of Eigen:

<code>
./configure CPPFLAGS=-I/usr/local/eigen3
</code>
==== Building ====

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 [[installation guide#prerequisites|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''.

==== Tuning ====

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.

==== Testing ====

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, see our [[https://www.molpro.net/info/support|support page]] for details.

==== Final Install ====

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.