Manual:Installation
From OctopusWiki
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); some sample files in PREFIX/share/octopus/samples/; 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.
Contents |
Dowloading
The main download page for Octopus is http://www.tddft.org/programs/octopus/download/3.0.1
Binaries
If you want to install Octopus in a x86 Linux box which is deb or rpm based, you don't need to compile it; you can download and install the binary packages. Keep in mind that these packages are intended to run on different systems and are therefore only moderately optmized. If this is an issue you have to compile the package yourself with the appropriate compiler flags and libraries (see below).
- For Debian-based systems (Debian, Ubuntu), download the .deb file and install it with the command (you need root access for this):
$ dpkg -i octopus_package.deb
- For rpm-based distributions (RedHat, Fedora, SuSe, Mandriva, etc.) download the .rpm file and issue the following command line as root:
$ rpm -i octopus_package.rpm
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:
$ gzip -cd octopus-3.0.1.tar.gz $ cd octopus-3.0.1 $ ./configure $ make $ make install
This will probably not work, so before giving up, just read
the following paragraphs.
Long instructions
The code is written in standard Fortran 90, 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 90 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. GNU cpp is just fine, but any cpp that accepts the -C flag (preserve comments) should work just as well. If you have problems, try to switch to the GNU preprocesor.
- FFTW
- We have relied on this great library to perform the Fast Fourier Transforms (FFTs). You may grab it from the FFTW site. You may use FFTW version 2 as well as FFTW version 3. Octopus will try first to use the latter one, since it is significantly faster in some architectures.
- LAPACK/BLAS
- Our policy is to rely on these two libraries as much as possible on these libraries for the 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 heavyweight 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.
- Perl
- During the build process Octopus runs several scripts in this language. It's normally available in every modern Unix system.
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.
- 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. Don't ask.... (The simulation box in 2D can be specified via
BoxShapeImage.) Available from http://www.libgd.org/
- arpack
- If you install ARPACK you have the option to use it as the
EigenSolverfor diagonalizing the Kohn-Sham Hamiltonian. ARPACK contains BLAS and LAPACK libraries, so if you have already installed some different ones, be sure to edit the ARmakes.inc file and comment out the bits about BLAS and LAPACK when you are making this library. You can obtain it from Rice University.
Note: The ARPACK support has been removed after the release of Octopus 2.1.
- SPARSKIT
- Library for sparse matrix calculations.
Unpacking the sources
Uncompress and untar it (gzip -cd octopus-3.0.1.tar.gz ). In the following, OCTOPUS-SRC/ denotes the source directory of octopus, created by the tar command.
The OCTOPUS-SRC/ contains the following subdirectories:
- autom4te.cache/, build/, debian/
- contains files related to the building system. May actually not be there. Not of real interest for the plain user.
- doc/
- The documentation of Octopus in texinfo format.
- liboct/
- Small C library that handles the interface to GSL and some assorted routines that we didn't want to write in boring Fortran.
- liboct_parser/
- The C library that handles the input parsing.
- libxc/
- This is the directory of the NANOQUANTA XC library that contains many exchange and correlation functionals and that is shared with other codes.
- share/PP/
- Pseudopotentials. In practice now it contains the Troullier-Martins 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.
- share/samples/
- A couple of sample input files.
- src/
- Fortran 90 source files. Note that these 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 with the following command (you need the subversion package):
$ svn co http://www.tddft.org/svn/octopus/trunk
Before running the configure script, you will need to run the GNU autotools. This may be done by executing:
$ cd trunk $ autoreconf -i $ ./configure
Note that you need to have working versions of the automake (1.9) and autoconf (2.59) (the versions we currently use are between parentheses). Note that the autoreconf script will likely fail if you have (much) older versions of the autotools.
Configuring
Before configuring you can (should) setup 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.
For example, in bash you would typically do:
$ export FC=abf90 $ export FCFLAGS="-O -YEXT_NAMES=LCS -YEXT_SFX=_"
if you are using the Absoft Fortran 90 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=fftw2- Instruct the
configurescript to use the FFTW version 2. You may also set--with-fft=fftw3or even--disable-fft, although this last option is discouraged.
--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_LIBSenvironment 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.
Compiling and installing
Run make (this may take sometime) and then make install. 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. The sample input files will be copied to PREFIX/share/octopus/samples.
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).
To run the tests, in the sources directory of octopus use the command
$ make check
which will start running the tests, informing you whether the tests are passed or not.
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 this is not the case, try to look for help in the octopus mailing list.
