# 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 12 .

### 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-12.tar.gz
cd octopus-12
./configure
make
make install


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

### 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:

• make: most computers have it installed, otherwise just grab and install the GNU make.

• cpp: The C preprocessor is heavily used in Octopus to preprocess Fortran code. It is used for both C (from the CPP variable) and Fortran (FCCPP). GNU cpp is the most convenient but others may work too. For more info, see Preprocessors.

• Libxc: The library of exchange and correlation functionals. It used to be a part of Octopus, but since version 4.0.0 it is a standalone library and needs to be installed independently. For more information, see the libxc page. Octopus 4.0.0 and 4.0.1 require version 1.1.0 (not 1.2.0 or 1.0.0). Octopus 4.1.2 requires version 2.0.x or 2.1.x, and won’t compile with 2.2.x. (Due to bugfixes from libxc version 2.0 to 2.1, there will be small discrepancies in the testsuite for functionals/03-xc.gga_x_pbea.inp and periodic_systems/07-tb09.test). Octopus 5.0.0 supports libxc versions 2.0.x, 2.1.x and 2.2.x. Please note: The Libxc testsuite prior to 2.1 will report some errors in most cases. This is not something to worry about.

• FFTW: We have relied on this great library to perform Fast Fourier Transforms (FFTs). You may grab it from the FFTW site. You require FFTW version 3.

• LAPACK/BLAS: Our policy is to rely on these two libraries as much as possible on these libraries for linear-algebra operations. If you are running Linux, there is a fair chance they are already installed in your system. The same goes to the more heavy-weight machines (alphas, IBMs, SGIs, etc.). Otherwise, just grab the source from netlib site.

• GSL: Finally someone had the nice idea of making a public scientific library! GSL still needs to grow, but it is already quite useful and impressive. Octopus uses splines, complex numbers, special functions, etc. from GSL, so it is a must! If you don’t have it already installed in your system, you can obtain GSL from the GSL site. You will need version 1.9 or higher. Version 4.0 of Octopus (and earlier) can only use GSL 1.14 (and earlier). A few tests will fail if you use GSL 1.15 or later. Version 5.0.0 of Octopus (and earlier) can only use GSL 1.16 or earlier, due to a bug in our configure script.

• Perl: During the build process Octopus runs several scripts in this language. It’s normally available in every modern Unix system.

#### Optional libraries

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

• MPI: If you want to run Octopus in multi-tentacle (parallel) mode, you will need an implementation of MPI. MPICH or Open MPI work just fine in our Linux boxes.

• PFFT: We rely on this great library for highly scalable parallel Poisson solver, based on Fast Fourier Transforms (FFTs). You may grab it from the M. Pippig's site. You also require FFTW version 3.3 compiled with MPI and with a small patch by M. Pippig (also available there).

• NetCDF: The Network Common Dataform library is needed for writing the binary files in a machine-independent, well-defined format, which can also be read by visualization programs such as OpenDX

• GDLib: A library to read graphic files. See Particle in an octopus. (The simulation box in 2D can be specified via BoxShapeImage.) Available from GDLib.

• SPARSKIT: Library for sparse matrix calculations. Used for one propagator technique.

• ETSF I/O: An input/output library implementing the ETSF standardized formats, requiring NetCDF, available at libraries_and_tools. Versions 1.0.2, 1.0.3, and 1.0.4 are compatible with Octopus (though 1.0.2 will produce a small discrepancy in a filesize in the testsuite). It must have been compiled with the same compiler you are using with Octopus. To use ETSF_IO, include this in the configure line, where $DIR is the path where the library was installed: --with-etsf-io-prefix="$DIR"
• LibISF: (version 5.0.0 and later) To perform highly scalable parallel Poisson solver, based on BigDFT 1.7.6, with a cheap memory footprint. You may grab it from the BigDFT site. You require BigDFT version 1.7.6 compiled with MPI, following these instructions: installation instructions. Probably, you have to manually copy the files “libwrappers.a” and “libflib.a” to the installation “/lib” directory. To configure Octopus, you have to add this configure line:
--with-isf-prefix="$DIR" From version 10.0 on, the ISF library is replaced by its successor [PSOLVER](https://gitlab.com/l_sim/psolver). The corresponding configure line is:  --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: • doc/ : The documentation of Octopus, mainly in HTML format. • liboct_parser/ : The C library that handles the input parsing. • share/PP/ : Pseudopotentials. In practice now it contains the Troullier-Martins (PSF and UPF formats) and Hartwigsen-Goedecker-Hutter pseudopotential files. • share/util/ : Currently, the utilities include a couple of IBM OpenDX networks (mf.net ), to visualize wavefunctions, densities, etc. • testsuite/ : Used to check your build. You may also use the files in here as samples of how to do various types of calculations. • src/ : Fortran90 and C source files. Note that the Fortran90 files have to be preprocessed before being fed to the Fortran compiler, so do not be scared by all the - directives. #### 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.

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:

• --prefix=PREFIX/ : Change the base installation dir of Octopus to PREFIX/ . PREFIX/ defaults to the home directory of the user who runs the configure script.

• --with-fft-lib=<lib> : Instruct the configure script to look for the FFTW library exactly in the way that it is specified in the <lib> argument. You can also use the FFT_LIBS environment variable.

• --with-pfft-prefix=DIR/ : Installation directory of the PFFT library.

• --with-pfft-lib=<lib> : Instruct the configure script to look for the PFFT library exactly in the way that it is specified in the <lib> argument. You can also use the PFFT_LIBS environment variable.

• --with-blas=<lib> : Instruct the configure script to look for the BLAS library in the way that it is specified in the <lib> argument.

• --with-lapack=<lib> : Instruct the configure script to look for the LAPACK library in the way that it is specified in the <lib> argument.

• --with-gsl-prefix=DIR/ : Installation directory of the GSL library. The libraries are expected to be in DIR/lib/ and the include files in DIR/include/ . The value of DIR/ is usually found by issuing the command gsl-config --prefix .

• --with-libxc-prefix=DIR/ : Installation directory of the Libxc library.

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.