Manual:Installation

From OctopusWiki
Revision as of 23:52, 17 March 2006 by Xavier (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

<a name="Installation"></a> <a name="SEC1"></a>

[ < ] [<a href="#SEC2" title="Next section in reading order"> > </a>]   [ << ] [ Up ] [ >> ]         [<a href="#SEC1" title="Cover (top) of document">Top</a>] [Contents] [Index] [<a href="#SEC_About" title="About (help)"> ? </a>]

1. Installation

Maybe somebody else installed the @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 /usr/local/bin/octopus); the documentation in info format in PREFIX/info (so that you may see it by typing info -f PREFIX/info/octopus.info if the info program is installed in your system); 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 .


<a name="Quick-instructions"></a> <a name="SEC2"></a>

[<a href="#SEC1" title="Previous section in reading order"> < </a>] [<a href="#SEC3" title="Next section in reading order"> > </a>]   [<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>] [<a href="#SEC1" title="Up section"> Up </a>] [ >> ]         [<a href="#SEC1" title="Cover (top) of document">Top</a>] [Contents] [Index] [<a href="#SEC_About" title="About (help)"> ? </a>]

1.1 Quick instructions

For the inpatients, here goes the quick-start:

 
prompt> gzip -cd octopus<-version>.tar.gz | tar xvf -
prompt> cd octopus-<version>
prompt> ./configure
prompt> make
prompt> make install

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

Also, rpm and deb binaries for linux are supplied on the web-page.


<a name="Long-instructions"></a> <a name="SEC3"></a>

[<a href="#SEC2" title="Previous section in reading order"> < </a>] [<a href="#SEC4" title="Next section in reading order"> > </a>]   [<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>] [<a href="#SEC1" title="Up section"> Up </a>] [ >> ]         [<a href="#SEC1" title="Cover (top) of document">Top</a>] [Contents] [Index] [<a href="#SEC_About" title="About (help)"> ? </a>]

1.2 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 a Fortran 90 compiler. No free-software Fortran 90 compiler is available yet, so, if you want to chew the octopus, you will have either to help the <a href="http://g95.sourceforge.net">g95</a> or <a href="http://gcc.gnu.org/fortran">gfortran</a> projects, or use any of the available comercial compilers.

Besides the compiler, you will also need:

  1. make: most computers have it installed, otherwise just grab and install the GNU make.
  2. cpp: The C preprocessor is heavily used in octopus. GNU cpp is just fine, but any cpp that accepts the -C flag (preserve comments) should work just as well.
  3. FFTW: We have relied on this great library to perform the Fast Fourier Transforms (FFTs). You may grab it from <a href="http://www.fftw.org/">here</a>. 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.
  4. LAPACK/BLAS: Required. Our politics 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 <a href="http://www.netlib.org">here</a>.
  5. GSL: Finally that 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 <a href="http://sources.redhat.com/gsl/">here</a>. You will need version 1.0 or higher.
  6. MPI: If you want to run octopus in multi-tentacle (parallel) mode, you will need an implementation of MPI. <a href="http://www-unix.mcs.anl.gov/mpi/mpich/">MPICH</a> works just fine in our Linux boxes.

First you should obtain the code file, octopus<-version>.tar.gz, (this you probably have already done). The code is freely available, and can be downloaded from <a href="http://www.tddft.org/programs/octopus">http://www.tddft.org/programs/octopus</a>. There exists a cvs server, which you can browse at <a href="http://nautilus.fis.uc.pt/cgi-bin/cvsweb.cgi/marques/octopus/">http://nautilus.fis.uc.pt/cgi-bin/cvsweb.cgi/marques/octopus/</a>. The sources of the cvs version (in general more unstable the the official distribution) may be downloaded by anonymous cvs access:

 
prompt> cvs -d :pserver:anonymous@nautilus.fis.uc.pt:/server/cvsroot 
        login

prompt> cvs -d :pserver:anonymous@nautilus.fis.uc.pt:/server/cvsroot 
        co marques/octopus

Uncompress and untar it (gzip -cd octopus<-version>.tar.gz | tar -xvf -). In the following, OCTOPUS-HOME denotes the home directory of octopus, created by the tar command.

The OCTOPUS-HOME contains the following subdirectories:

  • autom4te.cache, build, CVS, debian: contains files related to the building system or the CVS repository. 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 the parsing of the input file. It also contains some assorted routines that we didn't want to write in boring Fortran.
  • 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 (wf.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.

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. These are some of the options reported to work:

`intel ifc (PIV)'

-u -zero -fpp1 -nbs -i_dynamic -pc80 -pad -align -unroll -O3 -r8 -ip -tpp7 -xW

`absoft (i386)'

-O3 -YEXT_NAMES=LCS -YEXT_SFX=_

`absoft (opteron)'

-O3 -mcmodel=medium -m64 -cpu:host -YEXT_NAMES=LCS -YEXT_SFX=_

`NAG (opteron)'

-colour -kind=byte -mismatch_all -abi=64 -ieee=full -O4 -Ounroll=4

`pgi (opteron)'

-fast -mcmodel=medium -O4

`alpha'

-align dcommons -fast -tune host -arch host -noautomatic

`xlf (IBM)'

-bmaxdata:0x80000000 -qmaxmem=-1 -qsuffix=f=f90 -Q -O5 -qstrict -qtune=auto -qarch=auto -qhot -qipa

`sgi'

-O3 -INLINE -n32 -LANG:recursive=on

You can now run the configure script (./configure). <a name="DOCF1" href="#FOOT1">(1)</a> 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. The executable will be installed in PREFIX/bin, the libraries in PREFIX/lib and the documentation in PREFIX/info. PREFIX defaults to the home directory of the user who runs configure. <a name="DOCF2" href="#FOOT2">(2)</a>
  • --with-fft=fftw2: Instruct the configure script to use the FFTW library, and specifically to use the FFTW version 2. You may also set --with-fft=fftw3 or even --disable-fft, although this last option is dis-encouraged.
  • --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, i.e --with-fft-lib='-L/opt/lib -lfftw3'.
  • --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 BLAS 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. (If the GSL library is installed, the program gsl-config should be somewhere.)
  • --with-netcdf=<lib>: NETCDF library. This is a recommended library, although not necessary.

In addition to these options, several other options have to be passed to build different executables of octopus (parallel, debugging version, etc) - See section <a href="#SEC4">Different octopus executables</a>.

Run make, and then make install. If everything went fine, you should now be able to taste octopus. Depending on the options passed to the configure script, some suffixes could be added to the generic name octopus -- i.e. octopus_cmplx for the code compiled for complex wave-functions, octopus_cmplx_mpi for a parallel version of the code compiled for complex wave-function, and so on.

Depending on the value given to the --prefix=PREFIX given, the executables will reside in PREFIX/bin, the info file with the documentation in PREFIX/info (so that it may be viewed running info -f PREFIX/info/octopus.info), and the auxiliary files will be copied to PREFIX/share/octopus. The sample input files will be copied to PREFIX/share/octopus/samples.

The program has been tested in the following platforms:

  • i686*-linux-gnu: with the <a href="http://www.absoft.com">Absoft</a>, and the <a href="http://www.intel.com/software/products/compilers/">Intel</a> compiler.
  • alphae*: both in Linux and in OSF/1 with Compaq's fort compiler.
  • powerpc-ibm-aix4.3.3.0: with native xlf90 compiler.
  • cray: with native f90 compiler.
  • opteron: with NAG, PGI, and ABSOFT compilers.
  • SGI: with native compiler.

If you manage to compile/run octopus on a different platform or with a different compiler, please let us know so we can update the list. Patches to solve compiler issues are also welcomed.

Build the documentation in the format you prefer. Since you are reading this, you already have it in some format (but maybe not the correct version). Due to the power of texinfo, a series of formats are available, namely dvi, html, pdf and info. The octopus.texi source code of this document is in the OCTOPUS-HOME/doc directory.


<a name="Different-octopus-executables"></a> <a name="SEC4"></a>

[<a href="#SEC3" title="Previous section in reading order"> < </a>] [ > ]   [<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>] [<a href="#SEC1" title="Up section"> Up </a>] [ >> ]         [<a href="#SEC1" title="Cover (top) of document">Top</a>] [Contents] [Index] [<a href="#SEC_About" title="About (help)"> ? </a>]

1.3 Different octopus executables

By performing the standard install, you will get an executable called octopus, and a set of utility programs called oct-something. However, the code may be compiled differently in order to profit from special feautures (e.g parallel executables, etc). The following is a list of the options that have to be passed to the configure script in order to obtain these different executables.

  • --enable-complex: Builds a version with complex wave-functions for the ground-state calculations (wave-functions are always complex for the evolution). This is needed when spinors are needed -- e.g. noncollinear magnetism is going to be considered, or the spin-orbit coupling term will be used. The suffix _cmplx is appended to the octopus executable name.
  • --enable-single: Builds a version that works in single precision mode, rather than in the standard double precision. It will work faster. Unfortunately we are not yet fully sure of the proper functioning of the code in this manner. The suffix _single is appended to the octopus executable name. (This is currently broken).
  • --enable-mpi: Builds the parallel version (MPI) of octopus. The suffix _mpi is appended to the octopus executable name.

<a name="SEC_Foot"></a>

[<a href="#SEC1" title="Cover (top) of document">Top</a>] [Contents] [Index] [<a href="#SEC_About" title="About (help)"> ? </a>]

Footnotes

<a name="FOOT1" href="#DOCF1">(1)</a>

If you downloaded the cvs version, you will not find the configure script. In order to compile the development version you will first have to run the GNU autotools. This may be done by executing the autoreconf perl script (a part of the autoconf distribution). Note that you need to have working versions of the automake (1.8.5), autoconf (2.59) and libtool (1.5.6) programs (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.

<a name="FOOT2" href="#DOCF2">(2)</a>

You may fine-tune further the instalation by making use of a set of standard options (--exec-prefix, --bindir, --datadir, --program-prefix, etc) that are described in the output of ./configure --help


<a name="SEC_About"></a>

[<a href="#SEC1" title="Cover (top) of document">Top</a>] [Contents] [Index] [<a href="#SEC_About" title="About (help)"> ? </a>]

About This Document

This document was generated by xavier on March, 17 2006 using <a href="http://texi2html.cvshome.org/">texi2html 1.76</a>.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back previous section in reading order 1.2.2
[ > ] Forward next section in reading order 1.2.4
[ << ] FastBack beginning of this chapter or previous chapter 1
[ Up ] Up up section 1.2
[ >> ] FastForward next chapter 2
[Top] Top cover (top) of document  
[Contents] Contents table of contents  
[Index] Index index  
[ ? ] About about (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

  • 1. Section One
    • 1.1 Subsection One-One
      • ...
    • 1.2 Subsection One-Two
      • 1.2.1 Subsubsection One-Two-One
      • 1.2.2 Subsubsection One-Two-Two
      • 1.2.3 Subsubsection One-Two-Three     <== Current Position
      • 1.2.4 Subsubsection One-Two-Four
    • 1.3 Subsection One-Three
      • ...
    • 1.4 Subsection One-Four

This document was generated by xavier on March, 17 2006 using <a href="http://texi2html.cvshome.org/">texi2html 1.76</a>.