installationguide.rst 12.1 KB
Newer Older
1 2 3 4 5 6
.. _installationguide:

==================
Installation guide
==================

7 8
.. note::

9 10
   **CAMd users** installing on ``Niflheim``: please follow the
   instructions for :ref:`Niflheim`.
cpo's avatar
cpo committed
11

12 13 14 15 16
In order to choose the right method for installing GPAW
identify your computer system and your goals related to GPAW.
Is it a personal laptop or maybe an HPC cluster?
Are you just trying out GPAW or need a full development environment
in order to participate in developing GPAW?
cpo's avatar
cpo committed
17

18 19 20 21
For the installation on personal laptops we recommend
the binary packages provided for popular Linux distributions
(:ref:`installationguide_package`)
and MS Windows (:ref:`installationguide_windows`).
22

23 24
Please skip to :ref:`installationguide_developer` if you prefer
to install from sources.
25

26
If you are on Mac OSX, please follow :ref:`installationguide_macosx`.
dulak's avatar
doc  
dulak committed
27

28 29 30

.. _installationguide_package:

dulak's avatar
dulak committed
31
Installation with package manager on Linux
32
==========================================
33

dulak's avatar
dulak committed
34 35
This is **the preferred** way to install on a Linux system.
If you prefer to install from sources follow :ref:`installationguide_developer`.
36

Jens Jørgen Mortensen's avatar
Jens Jørgen Mortensen committed
37
Install GPAW with:
38

Jens Jørgen Mortensen's avatar
Jens Jørgen Mortensen committed
39
* on RHEL/CentOS/Fedora::
dulak's avatar
dulak committed
40

Jens Jørgen Mortensen's avatar
Jens Jørgen Mortensen committed
41 42 43
    $ yum -y install gpaw
    
  (enable https://fedoraproject.org/wiki/EPEL on RHEL/CentOS)
44

Jens Jørgen Mortensen's avatar
Jens Jørgen Mortensen committed
45 46 47 48
* on openSUSE::
    
    $ zypper ar -f http://download.opensuse.org/repositories/home:/dtufys/openSUSE_13.1/home:dtufys.repo
    $ yast -i gpaw
dulak's avatar
dulak committed
49

Jens Jørgen Mortensen's avatar
Jens Jørgen Mortensen committed
50
* on Debian/Ubuntu::
dulak's avatar
dulak committed
51

Jens Jørgen Mortensen's avatar
Jens Jørgen Mortensen committed
52 53
    $ sudo apt-get update
    $ sudo apt-get -y install gpaw
dulak's avatar
dulak committed
54

dulak's avatar
dulak committed
55 56 57
For the full list of supported distributions check
https://build.opensuse.org/package/show?package=gpaw&project=home%3Adtufys

58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
After performing the installation do not forget to :ref:`running_tests`!


.. _installationguide_macosx:

Installation on OS X
====================

For installation with http://brew.sh/ please follow
instructions at :ref:`homebrew`.

After performing the installation do not forget to :ref:`running_tests`!


.. _installationguide_windows:

Installation on Windows
=======================
dulak's avatar
dulak committed
76 77 78 79 80 81

.. note::

   GPAW is not yet fully functional on Windows! See
   http://listserv.fysik.dtu.dk/pipermail/gpaw-users/2013-August/002264.html

dulak's avatar
dulak committed
82
On Windows install Python(x,y) as described at
dulak's avatar
dulak committed
83 84
https://wiki.fysik.dtu.dk/ase/download.html#windows.

dulak's avatar
dulak committed
85 86
Download the gpaw.win32-py2.7.msi_ installer
(fix the incorrect *man* extension while downloading) and install with::
dulak's avatar
dulak committed
87 88 89 90 91 92 93 94

   gpaw.win32-py2.7.msi /l*vx "%TMP%\gpaw_install.log" /passive

.. _gpaw.win32-py2.7.msi:
       https://wiki.fysik.dtu.dk/gpaw-files/gpaw.win32-py2.7.msi

.. note::

dulak's avatar
dulak committed
95
    Unpack gpaw-setups under C:\gpaw-setups (see :ref:`setups`).
dulak's avatar
dulak committed
96

dulak's avatar
dulak committed
97
As the last step (this is important) install the ASE msi
dulak's avatar
dulak committed
98 99
(see https://wiki.fysik.dtu.dk/ase/download.html#windows).

100
After performing the installation do not forget to :ref:`running_tests`!
101 102


103
.. _installationguide_developer:
104

105 106
Manual installation
===================
107

108 109
GPAW binaries are available only for the :ref:`latest_stable_release`,
and all available GPAW releases are listed at the :ref:`download` page.
110

111 112 113
If you need a development version (or a historic version) of GPAW
perform a manual installation according to instructions below.
Follow the same instructions if you are configuring GPAW on an HPC cluster.
114

dulak's avatar
dulak committed
115

116 117
This is the **preferred** way of manually installing GPAW.
It offers the following advantages:
118

119 120
- installation is limited to standard user's account:
  it does not pollute the root filesystem,
121

122
- user gains access to version control updates, if necessary.
123

124 125
Requirements
------------
126

127 128
1) Python2 version 2.6 or newer. Python3 is not supported yet.
   Python is available from http://www.python.org.
129

dulak's avatar
dulak committed
130
2) NumPy_ 1.6.1 or newer.  Earlier versions may work for basic operations.
dulak's avatar
dulak committed
131

132
3) Atomic Simulation Environment (:ase:`ASE <>`).
133

134
4) C compiler - preferably gcc.
135

dulak's avatar
dulak committed
136
5) Libxc version 2.0.1 or newer (libxc-download_).
137

138 139
6) BLAS and LAPACK libraries. Start with your system provided defaults or
   e.g. acml_ or openblas_. Multithreading is not supported.
140

dulak's avatar
dulak committed
141
7) SciPy_ 0.7.0 or newer
dulak's avatar
dulak committed
142

143
Optionally:
144

145
8) an MPI library (required for parallel calculations).
146

147
9) HDF5 (> 1.8.0) library for parallel I/O and for saving files in HDF5 format
dulak's avatar
dulak committed
148

149

150 151 152 153 154 155 156
.. _NumPy: http://numpy.org/
.. _SciPy: http://scipy.org/
.. _libxc-download: http://www.tddft.org/programs/octopus/wiki/index.php/
                    Libxc:download
.. _acml: http://developer.amd.com/tools-and-sdks/cpu-development/
          amd-core-math-library-acml/
.. _openblas: http://www.openblas.net/
jensj's avatar
jensj committed
157

dulak's avatar
dulak committed
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174
Installation process
--------------------

After having installed the dependencies do:

1) Perform :ref:`developer_installation`.

   .. note::

       If you install on a cluster,
       take a look at :ref:`install_custom_installation` - it provides
       installation instructions for different platforms.

2) Perform :ref:`installationguide_setup_files`.

3) :ref:`running_tests`.

175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
The following environment variables are involved when installing GPAW:

.. envvar:: HOME

  The path to your home directory.

.. envvar:: GPAW_HOME

  Optional: points to the root directory of your GPAW installation, e.g.:
  ``~/gpaw``.

.. envvar:: PATH

  The ``$PATH`` environment variable should contain the paths to directory
  containing the ``gpaw-python`` executable and additional scripts.

.. envvar:: PYTHONPATH

  The ``PYTHONPATH`` should point to the directory containing the GPAW Python
  module and the ``_gpaw.so`` shared library.

.. envvar:: OMP_NUM_THREADS
  
  Currently should be set to 1.

.. envvar:: GPAW_SETUP_PATH

  Points to the directory containing the PAW datasets.

dulak's avatar
dulak committed
204 205
See below for hints how to customize your installation.

206 207 208 209 210
Installation tricks
-------------------

.. _install_custom_installation:

211 212
Customizing installation
++++++++++++++++++++++++
dulak's avatar
dulak committed
213

214 215 216 217 218 219
The install script does its best when trying to guess proper libraries
and commands to build GPAW. However, if the standard procedure fails
or user wants to override default values it is possible to customize
the setup with :svn:`customize.py` file which is located in the GPAW base
directory. As an example, :svn:`customize.py` might contain the following
lines::
dulak's avatar
dulak committed
220

221 222
  libraries = ['myblas', 'mylapack']
  library_dirs = ['path_to_myblas']
dulak's avatar
dulak committed
223

224 225 226 227 228
Now, GPAW would be built with "``-Lpath_to_myblas -lmyblas
-lmylapack``" linker flags. Look at the file :svn:`customize.py`
itself for more possible options.  :ref:`platforms_and_architectures`
provides examples of :file:`customize.py` for different platforms.
After editing :svn:`customize.py`, follow the instructions for the
229
:ref:`developer_installation`.
230 231 232 233 234 235 236 237

Installation with HDF5 support
++++++++++++++++++++++++++++++

HDF5 support can be enabled by setting in :file:`customize.py`::

 hdf5 = True

jensj's avatar
jensj committed
238 239
and, in this case, provide HDF5 ``include_dirs``, ``libraries``, and
``library_dirs`` as described in :ref:`install_custom_installation`.
240

241
.. _parallel_installation:
242

243 244 245 246 247 248 249 250 251 252 253
Parallel installation
+++++++++++++++++++++

By default, setup looks if :program:`mpicc` is available, and if setup
finds one, a parallel version is build. If the setup does not find
mpicc, a user can specify one in the :svn:`customize.py` file.

Additionally a user may want to enable ScaLAPACK, setting in
:file:`customize.py`::

 scalapack = True
dulak's avatar
dulak committed
254

jensj's avatar
jensj committed
255
and, in this case, provide BLACS/ScaLAPACK ``libraries`` and ``library_dirs``
256 257 258 259 260
as described in :ref:`install_custom_installation`.

Instructions for running parallel calculations can be found in the
:ref:`user manual <manual_parallel_calculations>`.

jensj's avatar
jensj committed
261

262 263 264 265 266 267 268 269 270
.. _PGO:

Profile guided optimization
+++++++++++++++++++++++++++

Some compilers allow one to use
`profile guided optimization <http://en.wikipedia.org/wiki/Profile-guided_optimization>`_ (PGO).
See :ref:`PGO_gcc_EL5` for an example how use PGO to compile GPAW on CentOS.

271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311
Libxc Installation
++++++++++++++++++

Libxc download/install instructions can be found `here <http://www.tddft.org/programs/octopus/wiki/index.php/Libxc:download>`_.  A few extra tips:

- Libxc installation requires both a C compiler and a fortran compiler.

- We've tried intel and gnu compilers and haven't noticed much of a
  performance difference.  Use whatever is easiest.

- Libxc shared libraries can be built with the "--enable-shared" option
  to configure.  This might be slightly preferred because it reduces
  memory footprints for executables.

- Typically when building GPAW one has to modify customize.py in a manner
  similar to the following::

    library_dirs += ['/my/path/to/libxc/2.0.2/install/lib']
    include_dirs += ['/my/path/to/libxc/2.0.2/install/include']

  or if you don't want to modify your customize.py, you can add these lines to
  your .bashrc::
  
    export C_INCLUDE_PATH=/my/path/to/libxc/2.0.2/install/include
    export LIBRARY_PATH=/my/path/to/libxc/2.0.2/install/lib
    export LD_LIBRARY_PATH=/my/path/to/libxc/2.0.2/install/lib

Example::
    
    wget http://www.tddft.org/programs/octopus/down.php?file=libxc/libxc-2.0.2.tar.gz -O libxc-2.0.2.tar.gz
    tar -xf libxc-2.0.2.tar.gz
    cd libxc-2.0.2
    ./configure --enable-shared --prefix=$HOME/xc
    make
    make install
    
    # add these to your .bashrc:
    export C_INCLUDE_PATH=~/xc/include
    export LIBRARY_PATH=~/xc/lib
    export LD_LIBRARY_PATH=~/xc/lib

jensj's avatar
jensj committed
312

313 314
.. _installationguide_setup_files:

dulak's avatar
dulak committed
315 316
Installation of PAW datasets
============================
317

318 319
The PAW datasets can be installed automatically or manually.

Jens Jørgen Mortensen's avatar
Jens Jørgen Mortensen committed
320
To install them automatically, run :command:`gpaw install-data
321 322 323 324 325 326
{<dir>}`.  This downloads and unpacks the newest package into
:file:`{<dir>}/gpaw-setups-{<version>}`.  When prompted, answer
yes (y) to register the path in the GPAW configuration file.

To manually install the setups, do as follows:

dulak's avatar
precise  
dulak committed
327
1) Get the tar file :file:`gpaw-setups-{<version>}.tar.gz`
328
   of the <version> of PAW datasets from the :ref:`setups` page
329
   and unpack it somewhere, preferably in :envvar:`HOME`
jensj's avatar
jensj committed
330
   (``cd; tar -xf gpaw-setups-<version>.tar.gz``) - it could
331
   also be somewhere global where
332 333 334 335 336 337
   many users can access it like in :file:`/usr/share/gpaw-setups/`.
   There will now be a subdirectory :file:`gpaw-setups-{<version>}/`
   containing all the atomic data for the most commonly used functionals.

2) Set the environment variable :envvar:`GPAW_SETUP_PATH`
   to point to the directory
338 339 340 341 342 343 344 345
   :file:`gpaw-setups-{<version>}/`, e.g. put into :file:`~/.tcshrc`::

    setenv GPAW_SETUP_PATH ${HOME}/gpaw-setups-<version>

   or if you use bash, put these lines into :file:`~/.bashrc`::

    export GPAW_SETUP_PATH=${HOME}/gpaw-setups-<version>

346
   Refer to :ref:`using_your_own_setups` for alternative way of
347
   setting the location of PAW datasets.
348 349 350

   .. note::

351 352
     In case of several locations of PAW datasets the first found setup
     file is used.
353

jensj's avatar
jensj committed
354

dulak's avatar
dulak committed
355 356 357 358 359
.. _running_tests:

Run the tests
=============

dulak's avatar
dulak committed
360 361
Make sure that everything works by running the test suite
in serial (using bash)::
dulak's avatar
dulak committed
362

dulak's avatar
dulak committed
363 364 365 366 367 368
  [gpaw]$ python `which gpaw-test` 2>&1 | tee test.log

If you compiled the custom interpreter (needed to running calculations
in parallel), test it too, in serial::

  [gpaw]$ gpaw-python `which gpaw-test` 2>&1 | tee test1.log
dulak's avatar
dulak committed
369

370
This will take a couple of hours.
dulak's avatar
dulak committed
371
Please report errors to the ``gpaw-developers`` mailing list (see
jensj's avatar
jensj committed
372 373 374
:ref:`mailing_lists`) Send us :file:`test.log`, as well as the
information about your environment (processor architecture, versions
of python and numpy, C-compiler, BLAS and LAPACK libraries, MPI
375 376
library), and (only when requested) :file:`build_ext.log`
(or :file:`install.log`).
dulak's avatar
dulak committed
377 378 379

If tests pass, and the parallel version is built, test the parallel code::

jensj's avatar
jensj committed
380
  [gpaw]$ mpirun -np 2 gpaw-python -c "import gpaw.mpi as mpi; print(mpi.rank)"
dulak's avatar
dulak committed
381 382 383
  1
  0

384 385
.. note::

jensj's avatar
jensj committed
386
   Many MPI versions have their own ``-c`` option which may
387 388 389
   invalidate python command line options. In this case
   test the parallel code as in the example below.

dulak's avatar
dulak committed
390 391
Try also::

jussie's avatar
jussie committed
392
  [gpaw]$ mpirun -np 2 gpaw-python gpaw/test/spinpol.py
dulak's avatar
dulak committed
393

jussie's avatar
jussie committed
394 395 396 397
This will perform a calculation for a single hydrogen atom.
First spin-paired then spin-polarized case, the latter parallelized
over spin up on one processor and spin down on the other.  If you run
the example on 4 processors, you get parallelization over both
dulak's avatar
dulak committed
398
spins and the domain.
399

dulak's avatar
dulak committed
400
If you enabled ScaLAPACK, do::
401

naromero's avatar
naromero committed
402
  [examples]$ mpirun -np 2 gpaw-python ~/gpaw/test/CH4.py --sl_default=1,2,2
403

dulak's avatar
dulak committed
404
This will enable ScaLAPACK's diagonalization on a 1x2 BLACS grid
405
with the block size of 2.
406 407 408 409 410

Finally run the tests in parallel on 2, 4 and 8 cores::

  [gpaw]$ mpirun -np 4 gpaw-python `which gpaw-test` 2>&1 | tee test4.log