python-ase-doc 3.9.1.4567-3 / usr / share / python-ase / doc / download.rst

.. _download_and_install:

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

In order to choose the right method for installing ASE
identify your computer system and your goals related to ASE.
Is it a personal laptop or maybe an HPC cluster?
Are you just trying out ASE or need a full development environment
in order to participate in developing ASE?

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`).

Please skip to :ref:`installationguide_manual` if you prefer
to install from sources.

If you are on Mac OSX, please follow :ref:`installationguide_macosx`.


.. _installationguide_package:

Installation with package manager on Linux
==========================================

Install the binaries with the software package manager of your Linux
distribution.

This is **the preferred** way to install on a Linux system.

If you prefer to install from sources follow :ref:`installationguide_manual`.

The currently supported systems include (issue the commands below **as root**):

- Fedora::

    yum install -y python-ase

- RHEL/CentOS - available after enabling https://fedoraproject.org/wiki/EPEL::

    yum install -y python-ase

- openSUSE 13.1::

    zypper ar -f http://download.opensuse.org/repositories/home:/dtufys/openSUSE_13.1/home:dtufys.repo
    yast -i python-ase
    yast -i python-matplotlib # optionally

- Debian 7.0::

    sudo bash -c 'echo "deb http://download.opensuse.org/repositories/home:/dtufys/Debian_7.0 /" > /etc/apt/sources.list.d/home_dtufys.sources.list'
    wget http://download.opensuse.org/repositories/home:/dtufys/Debian_7.0/Release.key && sudo apt-key add Release.key && rm Release.key
    sudo apt-get update
    sudo apt-get -y install python-ase
    sudo apt-get -y install python-matplotlib # optionally

- Ubuntu 14.04::

    sudo bash -c 'echo "deb http://download.opensuse.org/repositories/home:/dtufys/xUbuntu_14.04 /" > /etc/apt/sources.list.d/home_dtufys.sources.list'
    wget http://download.opensuse.org/repositories/home:/dtufys/xUbuntu_14.04/Release.key && sudo apt-key add Release.key && rm Release.key
    sudo apt-get update
    sudo apt-get -y install python-ase
    sudo apt-get -y install python-matplotlib # optionally

For the full list of supported distributions check
https://build.opensuse.org/package/show?package=python-ase&project=home%3Adtufys

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 `Homebrew
<https://wiki.fysik.dtu.dk/gpaw/install/MacOSX/homebrew.html>`_.

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


.. _installationguide_windows:

Installation on Windows
=======================

.. note::

   ASE is not yet fully functional on Windows!
   https://trac.fysik.dtu.dk/projects/ase/ticket/62

Python(x,y), on both 32- and 64-bit Windows,
requires Microsoft Visual C++ 2008 Redistributable Package (x86),
download and install it from:
https://www.microsoft.com/en-us/download/details.aspx?id=5582
Use http://www.dependencywalker.com/ to find missing DLLs in case of
"ImportError: DLL load failed: The specified module could not be found".

Continue with:

.. note:: installation assumes the python TARGETDIR C:\\Python27,
          leave also the default C:\\Program Files\\pythonxy.

-  pythonxy_. Download the *2.7.5.2* exe installer (other versions
   may be incompatible)and install with::

     Python(x,y)-2.7.5.2.exe /Log="%TMP%\pythonxy_install.log" /S

.. note::

   Open Task Manager and control when the process in finished.

- pygtk_win32_. Download the msi **pygtk-all-in-one** installer.
  Specify the correct TARGETDIR and install::

     pygtk-all-in-one-2.24.2.win32-py2.7.msi TARGETDIR="%HOMEDRIVE%\Python27" ALLUSERS=1 /l*vx "%TMP%\pygtk_install.log" /passive

.. note::

   If performing clicking-installation make sure that the default
   python Windows TARGETDIR is selected.

- Download the python-ase-win32.msi_ installer and install with::

     python-ase-X.X.X.win32.msi /l*vx "%TMP%\python-ase_install.log" /passive

.. note::

   You can build the msi ASE package on Windows with::

      python setup.py bdist_msi

   The msi package will be created under the *dist* directory.

.. _pythonxy: http://code.google.com/p/pythonxy
.. _pygtk_win32: http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/2.24/

.. _python-ase-win32.msi:
    https://wiki.fysik.dtu.dk/ase-files/python-ase.win32.msi

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


.. _installationguide_manual:

Manual installation
===================

ASE binaries are available only for the :ref:`latest_stable_release`,
and all available ASE releases are listed at the :ref:`download` page.

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

This is the **preferred** way of manually installing ASE.
It offers the following advantages:

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

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

Requirements
------------

The following packages are required for basic ASE functionality:

1) Python2_ version 2.6 or newer. Python3 is not supported yet.
2) NumPy_.

.. _Python2: http://www.python.org
.. _NumPy: http://www.numpy.org/

It is highly recommended (but not required) to install also these:

3) matplotlib_.
4) libpng_.
5) pygtk_.
6) SciPy_.

Matplotlib and libpng are needed for :mod:`writing png files <ase.io>`, and
together with pygtk are needed for ASE's simple GUI
(called **ase-gui**, see :mod:`ase.gui`).
Some of these packages may already be installed on your system.

.. _matplotlib: http://matplotlib.org/
.. _libpng: http://www.libpng.org/pub/png/libpng.html
.. _pygtk: http://www.pygtk.org
.. _SciPy: http://www.scipy.org/


Installation process
--------------------

After the :ref:`download` of ASE source create the link
to the requested version, e.g.:

- if retrieved from ``svn``::

   $ cd $HOME
   $ ln -s ase-3.9.0 ase
    
- if retrieved as tar-file::

   $ cd $HOME
   $ tar -xf python-ase-3.9.0.4465.tar.gz
   $ ln -s python-ase-3.9.0.4465 ase

It is sufficient to
put the directory :file:`$HOME/ase` in your :envvar:`PYTHONPATH`
environment variable, and the directory :file:`$HOME/ase/tools` in
your :envvar:`PATH` environment variable.  Do this permanently in
your :file:`~/.bashrc` file::

  export PYTHONPATH=$HOME/ase:$PYTHONPATH
  export PATH=$HOME/ase/tools:$PATH

or your :file:`~/.cshrc` file::

  setenv PYTHONPATH ${HOME}/ase:${PYTHONPATH}
  setenv PATH ${HOME}/ase/tools:${PATH}

Instead of :envvar:`HOME`, you may use any other directory.

Alternatively, you can install ASE to the user-specific site-packages
directory with::

  $ cd ase
  $ python setup.py install --user

This way, the ASE modules are found on the python path without any
explicit configuration, though you still need to ensure that
:file:`$HOME/.local/bin` (or on Windows,
:file:`%APPDATA%/Python/Scripts`) is on your :envvar:`PATH`.

.. index:: test

Optional, **NOT** recommended way of installing ASE system-wide is::

  $ cd ase
  $ sudo python setup.py install

This is one of the best ways to ruin a Linux system.


.. _download:

Download
--------

.. highlight:: bash

.. _latest_stable_release:

Latest stable release
+++++++++++++++++++++

The latest stable release can be obtained from SVN or as a
`tar-file <http://xkcd.com/1168/>`__.

.. note::

   The recommended installation path is :envvar:`$HOME`.

When using svn please set the following variable:

- bash::

   export ASE_TAGS=https://svn.fysik.dtu.dk/projects/ase/tags/

- csh/tcsh::

   setenv ASE_TAGS https://svn.fysik.dtu.dk/projects/ase/tags/

======= =========== ============================================ =============================
Release Date        Retrieve as svn checkout                     Retrieve as tar-file
======= =========== ============================================ =============================
 3.9.0_ May 28 2015 ``svn co -r 4465 $ASE_TAGS/3.9.0 ase-3.9.0`` python-ase-3.9.0.4465.tar.gz_
 3.8.1_ Nov 22 2013 ``svn co -r 3440 $ASE_TAGS/3.8.1 ase-3.8.1`` python-ase-3.8.1.3440.tar.gz_
 3.8.0_ Oct 22 2013 ``svn co -r 3420 $ASE_TAGS/3.8.0 ase-3.8.0`` python-ase-3.8.0.3420.tar.gz_
 3.7.1_ May 16 2013 ``svn co -r 3184 $ASE_TAGS/3.7.1 ase-3.7.1`` python-ase-3.7.1.3184.tar.gz_
 3.7.0_ May 13 2013 ``svn co -r 3168 $ASE_TAGS/3.7.0 ase-3.7.0`` python-ase-3.7.0.3168.tar.gz_
 3.6.0_ Feb 24 2012 ``svn co -r 2515 $ASE_TAGS/3.6.0 ase-3.6.0`` python-ase-3.6.0.2515.tar.gz_
 3.5.1_ May 24 2011 ``svn co -r 2175 $ASE_TAGS/3.5.1 ase-3.5.1`` python-ase-3.5.1.2175.tar.gz_
 3.4.1_ Aug 11 2010 ``svn co -r 1765 $ASE_TAGS/3.4.1 ase-3.4.1`` python-ase-3.4.1.1765.tar.gz_
 3.4.0_ Apr 23 2010 ``svn co -r 1574 $ASE_TAGS/3.4.0 ase-3.4.0`` python-ase-3.4.0.1574.tar.gz_
 3.3.1_ Jan 20 2010 ``svn co -r 1390 $ASE_TAGS/3.3.1 ase-3.3.1`` python-ase-3.3.1.1390.tar.gz_
 3.2.0_ Sep 4 2009  ``svn co -r 1121 $ASE_TAGS/3.2.0 ase-3.2.0`` python-ase-3.2.0.1121.tar.gz_
 3.1.0_ Mar 27 2009 ``svn co -r 846 $ASE_TAGS/3.1.0 ase-3.1.0``  python-ase-3.1.0.846.tar.gz_
 3.0.0_ Nov 13 2008 ``svn co -r 657 $ASE_TAGS/3.0.0 ase-3.0.0``  python-ase-3.0.0.657.tar.gz_
======= =========== ============================================ =============================

.. _3.9.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.9.0

.. _python-ase-3.9.0.4465.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.9.0.4465.tar.gz

.. _3.8.1:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.8.1

.. _python-ase-3.8.1.3440.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.8.1.3440.tar.gz

.. _3.8.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.8.0

.. _python-ase-3.8.0.3420.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.8.0.3420.tar.gz

.. _3.7.1:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.7.1

.. _python-ase-3.7.1.3184.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.7.1.3184.tar.gz

.. _3.7.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.7.0

.. _python-ase-3.7.0.3168.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.7.0.3168.tar.gz

.. _3.6.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.6.0

.. _python-ase-3.6.0.2515.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.6.0.2515.tar.gz

.. _3.5.1:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.5.1

.. _python-ase-3.5.1.2175.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.5.1.2175.tar.gz

.. _3.4.1:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.4.1

.. _python-ase-3.4.1.1765.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.4.1.1765.tar.gz

.. _3.4.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.4.0

.. _python-ase-3.4.0.1574.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.4.0.1574.tar.gz

.. _3.3.1:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.3.1

.. _python-ase-3.3.1.1390.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.3.1.1390.tar.gz

.. _3.2.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.2.0

.. _python-ase-3.2.0.1121.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.2.0.1121.tar.gz

.. _3.1.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.1.0

.. _python-ase-3.1.0.846.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.1.0.846.tar.gz

.. _3.0.0:
    https://trac.fysik.dtu.dk/projects/ase/browser/tags/3.0.0

.. _python-ase-3.0.0.657.tar.gz:
    https://wiki.fysik.dtu.dk/ase-files/python-ase-3.0.0.657.tar.gz


.. _latest_development_release:

Latest development release
++++++++++++++++++++++++++

The latest revision can be obtained like this::

  $ svn checkout https://svn.fysik.dtu.dk/projects/ase/trunk ase

or from the daily snapshot: `<snapshot.tar.gz>`_.

.. note::

   The recommended checkout path is :envvar:`$HOME`.


.. _running_tests:

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

Make sure that everything works by running the test
suite.  This will create many files, so run the tests in a new
directory (preferably using bash)::

  $ bash
  $ mkdir /tmp/testase.$$; cd /tmp/testase.*
  $ python -c "from ase.test import test; test(verbosity=2, display=True)" 2>&1 | tee testase.log

.. note::

   The last test :trac:`ase/test/COCu111.py` requires closing
   the graphics windows to terminate the whole test-suite.

.. note::

   If matplotlib_ or pygtk_ is not installed, this test will
   fail - avoid this with ``display=False``.

If any of the tests fail,
then please send us :file:`testase.log` (see :ref:`bugs`).


Video tutorial
==============

In the video: :ref:`overview` of the features of ASE,
followed by a :ref:`installationguide_manual` of ASE on a Linux system.

.. note::

   Use "Right Click -> Play" to play.

.. raw:: html

        <p></p>
        <object width="800" height="600">
        <embed src="https://wiki.fysik.dtu.dk/ase-files/oi_en_800x600.swf"
        type="application/x-shockwave-flash"
        allowFullScreen="false"
        allowscriptaccess="never"
        loop="false"
        play="false"
        width="800" height="600">
        <p></p>
        Video not playing? Download avi <a href="https://wiki.fysik.dtu.dk/ase-files/oi_en.avi">file</a> instead.
        </embed></object>
        <p></p>