☰
Navigation :

Installation

Maybe somebody else installed Octopus for you. In that case, the files should be under some directory that we can call PREFIX/ , the executables in PREFIX/bin/ (e.g. if PREFIX/ =/usr/local/ , the main Octopus executable is then in /usr/local/bin/octopus ); the pseudopotential files that Octopus will need in PREFIX/share/octopus/PP/ , etc.

However, you may be unlucky and that is not the case. In the following we will try to help you with the still rather unfriendly task of compiling and installing the Octopus.

Instructions for Specific Architectures

See step-by-step_instructions for some specific supercomputers and generic configurations (including Ubuntu and Mac OSX). If the system you are using is in the list, this will be the easiest way to install. Add entries for other supercomputers or generic configurations on which you have successfully built the code.

Downloading

Download the latest Octopus version here: Octopus 14.1 .

Source code

If you have a different system from those mentioned above or you want to compile Octopus you need to get the source code file (.tar.gz file) and follow the compilation instructions below.

Building

Quick instructions

For the impatient, here is the quick-start:

$ tar xzf octopus-14.tar.gz
$ cd octopus-14
$ ./configure --prefix=<INSTALLATION_DIR>

$ make
$ make install

This will probably not work, so before giving up, just read the following paragraphs.

As we are transitioning from autotools to CMake , you can also try:

$ tar xzf octopus-14.tar.gz
$ cd octopus-14
$ cmake -B ./build -G Ninja --install-prefix=<INSTALLATION_DIR>

$ cmake --build ./build
$ ctest --test-dir ./build -L short-run
$ cmake --install ./build

With CMake it is now possible to use any version directly from the Gitlab repository.

$ git clone https://gitlab.com/octopus-code/octopus
$ cd octopus
$ cmake -B ./build -G Ninja
...

For more details on building Octopus using CMake see the CMake ReadMe

Slow instructions

There is an appendix with detailed instructions on how to compile Octopus and the required libraries from scratch – you only need to do this if you are unable to install from a package manager or use per-built libraries.

Long instructions

The code is written in standard Fortran 2003, with some routines written in C (and in bison, if we count the input parser). To build it you will need both a C compiler (gcc works just fine and it is available for almost every piece of silicon), and a Fortran 2003 compiler. You can check in the Compilers Appendix which compilers Octopus has been tested with. This appendix also contains hints on potential problems with certain platform/compiler combinations and how to fix them.

Requirements

Besides the compiler, you will also need:

Optional libraries

There are also some optional packages; without them some parts of Octopus won’t work:

--with-etsf-io-prefix="$DIR" 

  --with-psolver-prefix=DIR
                          Directory where PSolver was installed.
  --with-psolver-include=DIR
                          Directory where PSolver Fortran headers were
                          installed.

Unpacking the sources

Uncompress and untar it (gzip -cd octopus-{{< octopus_version > .tar.gz | tar -xvf -}}). In the following, OCTOPUS-SRC/ denotes the source directory of Octopus, created by the tar command.

The OCTOPUS-SRC/ contains the following subdirectories of interest to users:

Development version

You can get the development version of Octopus by downloading it from the Octopus project on Octopus git.

You can also get the current version with the following command (you need the git package):


git clone git@gitlab.com:octopus-code/octopus.git

Before running the configure script, you will need to run the GNU autotools. This may be done by executing:


autoreconf -i

Note that you need to have working recent versions of the automake and autoconf. In particular, the configure script may fail in the part checking for Fortran libraries of mpif90 for autoconf version 2.59 or earlier. The solution is to update autoconf to 2.60 or later, or manually set FCLIBS in the configure command line to remove a spurious apostrophe.

If autoreconf is failing with “aclocal: warning: couldn’t open directory ‘m4’: No such file or directory”, create an empty folder named m4 inside external_libs/spglib-1.9.9/.

Please be aware that the development version may contain untested changes that can affect the execution and the results of Octopus, especially if you are using new and previously unreleased features. So if you want to use the development version for production runs, you should at least contact Octopus developers.

Configuring

Before configuring you can (should) set up a couple of options. Although the configure script tries to guess your system settings for you, we recommend that you set explicitly the default Fortran compiler and the compiler options. Note that configure is a standard tool for Unix-style programs and you can find a lot of generic documentation on how it works elsewhere.

For example, in bash you would typically do:


export FC=ifort

export FCFLAGS="-O2 -xHost"

if you are using the Intel Fortran compiler on a linux machine.

Also, if you have some of the required libraries in some unusual directories, these directories may be placed in the variable LDFLAGS (e.g., export LDFLAGS=$LDFLAGS:/opt/lib/ ).

The configuration script will try to find out which compiler you are using. Unfortunately, and due to the nature of the primitive language that Octopus is programmed in, the automatic test fails very often. Often it is better to set the variable FCFLAGS by hand, check the Compilers Appendix page for which flags have been reported to work with different Fortran compilers.

One can also manually set environment variables like LIBS_PSOLVER and FCFLAGS_ELPA to influence the library detection. For eg:
export LIBS_PSOLVER='-L$BIGDFT_PSOLVER_ROOT/lib -lPSolver-1 -lgomp'

export LIBS_ELPA='-lelpa_openmp' # or -lelpa

export FCFLAGS_ELPA='-I$ELPA_ROOT/include/elpa_openmp-2021.11.001/modules'
Do note however, not all dependency tests might support such environmental variables.

You can now run the configure script
./configure

You can use a fair amount of options to spice Octopus to your own taste. To obtain a full list just type ./configure --help . Some commonly used options include:

If you have problems when the configure script runs, you can find more details of what happened in the file config.log in the same directory.

Compiling and installing

Run make and then make install . The compilation may take some time, so you might want to speed it up by running make in parallel (make -j ). If everything went fine, you should now be able to taste Octopus.

Depending on the value given to the --prefix=PREFIX/ given, the executables will reside in PREFIX/bin/ , and the auxiliary files will be copied to PREFIX/share/octopus .

Testing your build

After you have successfully built Octopus, to check that your build works as expected there is a battery of tests that you can run. They will check that Octopus executes correctly and gives the expected results (at least for these test cases). If the parallel version was built, the tests will use up to 6 MPI processes, though it should be fine to run on only 4 cores. (MPI implementations generally permit using more tasks than actual cores, and running tests this way makes it likely for developers to find race conditions.)

To run the tests, in the sources directory of Octopus use the command


make check

or if you are impatient,


make check-short

which will start running the tests, informing you whether the tests are passed or not. For examples of job scripts to run on a machine with a scheduler, please see Specific_architectures.

If all tests fail, maybe there is a problem with your executable (like a missing shared library).

If only some of the tests fail, it might be a problem when calling some external libraries (typically blas/lapack). Normally it is necessary to compile all Fortran libraries with the same compiler. If you have trouble, try to look for help in the Octopus mailing list.

Fast recompilation

NOTE: This feature is currently only available in the development version and the plan is to include it in the Octopus 9 release.

If you have already compiled the code and if you are changing only one file, you can run


make NODEP=1

to ignore the dependencies due to Fortran module files. This will only compile the files that have changed and link the executables; therefore, it is much faster. If you change, e.g., interfaces of modules or functions, you need to to run make without NODEP=1 to ensure a correct handling of the dependencies.