- Getting the code
- Running calculations
- Documentation and help
For building and running OpenMolcas you will need at least:
A C compiler.
A Fortran compiler with Fortran 2008 support.
CMake, version 2.8.11 or later.
makeimplementation like GNU Make.
For the parallelized version:
Also recommended, but not compulsory:
Most of these can probably be easily installed using your system's package manager, if they are not already available.
Getting the code
To obtain a copy of the code, you should clone the repository with
git clone https://gitlab.com/Molcas/OpenMolcas.git [directory]
[directory] is optional and defaults to
OpenMolcas, the repository
name. It should be a new or empty directory, it will be created if it doesn't
exist. If you write a directory name, do not include the brackets.
If the above command fails, it may be that you need updating your git version. You can also try using the SSH protocol instead of HTTPS. In order to use SSH you'll need a GitLab.com account and associate an SSH key with it, then you run this command instead:
git clone [email protected]:Molcas/OpenMolcas.git [directory]
It is possible to download the full source code as an archive file (zip, tar, etc.), but it is not recommended to use this to compile OpenMolcas, since the version identification will not work properly and there will be no indication in the output files of the OpenMolcas version they were generated with.
The OpenMolcas repository includes some external codes as git submodules, and
there are corresponding options that can be activated to compile the codes
together with OpenMolcas. These are quite heterogeneous, some of them are
independent programs, some are add-ons designed to work with OpenMolcas. They
have also different status regarding support, maintenance and accessibility.
The submodules are located in the
External directory, you can download them
by running from within the
OpenMolcas directory (or whichever name you
git submodule update --init External/<name>
<name> is the submodule name (without the angle brackets). In
particular if you are not using a linear algebra library, or if you want to use
Runtime option (see below), you will need the
lapack submodule before
git submodule update --init External/lapack
To compile OpenMolcas you need to run CMake first. CMake configures the
compilation environment and prepares the sources for building. It is important
to remark that with CMake the program will be built in a directory separate
from where the source files are located (i.e.,
OpenMolcas by default). It
could be a new subdirectory inside
OpenMolcas, or a completely unrelated
directory. Let us call it
build, but you can choose any other name. Create
the directory, switch to it, and run
cmake, pointing to the location where
you have the OpenMolcas sources:
mkdir build cd build cmake </path/to/OpenMolcas>
</path/to/OpenMolcas> is the absolute or relative path to OpenMolcas,
typically it could be
../OpenMolcas. Then run
If you have multiple cores in your machine, you can benefit from parallel
compilation by adding the flag
-j N, where
N is the number of
threads to run simultaneously. Note that this is not compiling a parallelized
version of OpenMolcas, it is only compiling it faster.
Configuring the build
The above CMake command will configure OpenMolcas with default options, which
is probably not the best choice and not what you want. With CMake you can
enable or modify the options affecting the build before running
after, but then you'll have to run
make again). To do this, you pass options
cmake command of the form
-D OPTION=VALUE (for enabling or disabling
an on/off option, use
-D OPTION=ON or
-D OPTION=OFF). Once you have run
cmake the first time, you can specify
. instead of
You can also use an interactive interface to modify the options by running:
For some options to work you need to define an environment variable before
ccmake. If you are using bash, this is done by running:
Choosing the compilers
If you want to use specific compilers and not rely on the default ones found by
CMake, you can use the environment variables
FC for the fortran compiler,
CC for the C compiler and
CXX for the C++ compiler, for example:
export FC=ifort export CC=icc export CXX=icpc
If you need to pass an option to the compiler in addition to the flags generated by CMake, it may be possible to indicate this as well, as in:
export FC="pgfortran '-tp=x64'"
Unlike other options, to change the compiler once you have run
cmake you will
have to remove the
CMakeCache.txt file and the
Selecting a linear algebra library
It is highly recommended to use an optimized linear algebra library
implementing BLAS and LAPACK routines, as it will have a significant impact on
the performance. It is possible to use an "internal" library, which is compiled
from the Netlib sources, but this is mainly
useful for debugging. The desired linear algebra library is selected with the
LINALG=Internal: This is the default, and not recommended. It requires the
LINALG=OpenBLAS: Use OpenBLAS, an open source optimized library, which you can compile in advance.
LINALG=MKL: Use Intel Math Kernel Library
LINALG=ACML: Use AMD Core Math Library (deprecated).
LINALG=Runtime: Allow selection of a library at run time. It uses the "internal" library as a fallback, so it requires the
Note that when compiled for a 64-bit processor OpenMolcas will use a 64-bit-integer interface for the BLAS and LAPACK calls, so you will need the appropriate version of the library (usually identified as "ilp64" or "i8").
Runtime option you can select the used library at run time, this is
mainly useful for testing or comparing different libraries or versions without
building OpenMolcas specifically for each of them. To select the library when
running OpenMolcas use the
MOLCAS_LINALG environment variable, assigning it a
colon-separated list of the required libraries, for example:
Options for parallelization
GA: Enable usage of the Global Arrays toolkit. This is currently required by OpenMolcas whenever
MPIis enabled. If you are using the
EXTRApackage (see below) you can use the alternative DGA implementation and leave this disabled.
OPENMP: If enabled, a multithreaded version of the linear algebra library will be used. If there is any OpenMP code, it will be enabled too.
Known problems: Sometimes CMake may use wrong MPI wrappers to detect the
configuration, which may result in a faulty compilation. To override the MPI
wrappers used you can specify them with the options
With Open MPI and some compiler versions, the order of the detected MPI
libraries may be wrong and compilation fails. If that happens, make sure that
CMakeCache.txt file, the
MPI_Fortran_LIBRARIES line includes the
libraries in the order
Options for additional features
HDF5: Enable HDF5 support if installed. This allows the creation and use of portable binary files (with
.h5extension). It is enabled by default.
TOOLS: Compile the auxiliary programs in the
FDE: Enable frozen density embedding interface.
EXTRA: Specify the location of the
molcas-extracode. For this you need access to www.molcas.org as a developer. This contains Molcas codes not included in OpenMolcas and not released under an open-source license.
GROMACS: Enable Gromacs interface. This currently needs a compiled version of a development branch of Gromacs (http://repo.or.cz/w/gromacs.git/shortlog/refs/heads/qmmm).
DMRG: Enable density matrix renormalization group support through the QCMaquis program.
BLOCK: Enable density matrix renormalization group support through the BLOCK program.
CHEMPS2: Enable density matrix renormalization group support through the CheMPS2 program.
EFPLIB: Enable effective fragment potential support. It requires the
GRID_IT: Enable the gridit program. It requires the
NECI: Enable interface with the NECI program.
WFA: Enable wave function analysis through the libwfa library. It requires the
NEVPT2: Enable DMRG-NEVPT2 support. It requires QCMaquis DMRG support (
Other compilation options
Other options that affect how the code is compiled, but not the available features, are listed below:
CMAKE_BUILD_TYPE: General type of build. Allowed values:
BUILD_SHARED_LIBS: Enable it to create a shared instead of static
libmolcaslibrary, it will reduce the size of the binaries.
BUILD_STATIC_LIB: If enabled and building a shared
libmolcas, build a static version too.
BIGOT: Turn on all compiler warnings and treat them as errors.
BOUNDS: Enable bounds checking for memory allocation (only with gcc 4.8 or later).
GCOV: Enable code coverage reports (only with gcc).
GPERFTOOLS: Enable usage of gperftools.
After successful compilation, you should check the installation to make sure
OpenMolcas runs as expected and produces reliable results. The
includes a large number of tests intended for this. Although the tests are not
exhaustive, they are a good way to catch many common errors. They are also a
source of examples for different kinds of calculations. To run the verification
Note that the
pymolcas script should have been created and copied to a
location in your
PATH during compilation. If it cannot be found, try running
make pymolcas explicitly.
The full verification suite can take around 2 hours to complete. You can run a
basic subset with
pymolcas verify .basic. Run
pymolcas verify --help to see
Tests marked as "skipped" could not be completed because some necessary feature
for that particular test is missing in your installation. Tests marked as
"failed" did not finish for some other reason or produced results too different
from the reference values, and they should be checked. Failed tests with a
grayzone:* name are known to be problematic and can be ignored.
By default, OpenMolcas will be installed in
/opt/molcas, but this can be
modified with the CMake option
CMAKE_INSTALL_PREFIX. The current installation
expects a dedicated tree for OpenMolcas, i.e.
be a specific directory for OpenMolcas and not a system-wide directory (do
/home... but e.g.
/home/OpenMolcas). To install OpenMolcas in the chosen location, run:
This will copy the required files to the directory and write this location to
.Molcas/molcas in your home directory (see below). Note that the
installation creates some hidden files (with a filename starting with a dot),
so make sure to include them if you copy or transfer the directory.
The OpenMolcas installation can be further customized by each user. This is
done with files in the user's
.Molcas directory (
~/.Molcas). The most
important settings are detailed below.
The environment variable
MOLCAS defines the location of the OpenMolcas
installation that will be used in a calculation. If this variable is undefined,
it's value will be read from the file
~/.Molcas/molcas. Since this file is
overwritten every time you run
make install, you may want to specify a fixed
default location in
~/.Molcas/molcas_default, this will not be overwritten.
You can always override the OpenMolcas location for any specific calculation by
In the file
~/.Molcas/xbin.cfg you can define the location of external
programs that should be called within the OpenMolcas environment. For example,
if you download GV, you can place
$MOLCAS/bin directory, or you can write in
pymolcas gv will run
gv.exe with the proper environment.
~/.Molcas/molcasrc lets you specify default values for environment
variables that will be read before every calculation. Running
will help you write an initial
~/.Molcas/molcasrc file by letting you choose
the value of some common variables. An example file could look like this:
MOLCAS_WORKDIR=/tmp MOLCAS_REDUCE_PRT=NO MOLCAS_MOLDEN=ON MOLCAS_MEM=1000 MOLCAS_LINALG=/usr/local/OpenBLAS/lib/libopenblas_i8.so
MOLCAS, if you define a variable before, it will not be overridden by
the value in
~/.Molcas/molcasrc file is not interpreted by a shell, so the values
written there must be static. If you want to specify values computed at run
time, you can do that in the file
~/.Molcas/molcas.shell, which will be
interpreted by a shell.
As implied above, calculations with OpenMolcas are run using the
script. The simplest way to run a calculation is just passing the name of an
input file as an argument:
<input_file> is the name of the input file (without the angle
brackets). This however, sends the output to the terminal, which is not very
convenient. If you want to save the output to a file, you can use:
pymolcas <input_file> -f
which will automatically create a
<name>.log and a
<name>.err file with the
output and error streams of the calculation, respectively, where
the input filename, without the extension. You can instead choose a different
name for these files with
-e, or combine them with
pymolcas <input_file> -oe <output_file>
To ensure a faster update of the output file and allow a live view of its
content, specify a 1-line buffer with the
-b 1 option:
pymolcas <input_file> -oe <output_file> -b 1
Documentation and help
You can build the HTML documentation with:
make doc_html), or
make doc_pdf if you prefer the pdf format, or
make doc_all for both. The current documentation can be viewed at
https://molcas.gitlab.io/OpenMolcas/sphinx/ (HTML) and
There is also the possibility of getting command-line help, with: