******************
Anuga Installation
******************
.. contents::
Introduction
============
AnuGA_ is a python package with some C extensions (and an optional fortran
extension). At present AnuGA has only been run and tested using python 2.x.
We recommend python 2.7.
Dependencies
============
AnuGA requires the following packages:
* `numpy `_
* `scipy `_
* `matplotlib `_
* `gdal `_
* `netcdf `_
* `nose `_
* A C compiler (preferably GCC or TDM-GCC_ MinGW_ on Windows)
Installing the latest DEVELOPMENT version on Ubuntu
===================================================
AnuGA is developed on Ubuntu. The preferred way to install the dependencies is
to use the standard ubuntu ``apt-get`` method.
We suggest installing the latest version of ANUGA_ from Github_.
We try to maintain the *master* branch stable and
`passing all tests `_,
so it should be safe to use.
First, you'll need to `install git`_.
Then, open a terminal and run::
git clone git://github.com/GeoscienceAustralia/anuga_core.git
This will fetch the source code from Github_
and place it in a folder called ``anuga_core`` in the directory where you ran the
command.
We have a script in the ``anuga_core/tools`` directory,
`install_ubuntu.sh `_
which when run from the ``anuga_core`` directory will install AnuGA and all the dependencies using ``apt-get``
and ``pip`` to install the dependencies.
Parallel Support
----------------
At this stage you can decide whether you want Parallel support or not.
We support two versions of MPI, ``mpich`` and ``openmpi``
Just during the setup stage, you should create an environment variable ``ANUGA_PARALLEL`` via::
export ANUGA_PARALLEL=openmpi
or::
export ANUGA_PARALLEL=mpich
then the install script will load the ``openmpi`` or ``mpich`` libraries and binaries respectively.
If you don't want parallel support set the variable to something else, e.g::
export ANUGA_PARALLEL=false
Running the installation script
-------------------------------
Change into the newly downloaded ``anuga_core`` directory and run the installation script
(this will take 5 to 10 minutes depending on your network connection)::
cd anuga_core
bash tools/install_ubuntu.sh
Some of the commands in this script use sudo, so you will have to provide
a password to install into the system wide directories.
If all has been successful then anuga should be installed.
Testing the install
-------------------
To test the installation, from the ``anuga_core`` directory run ``python runtests.py``::
python runtests.py
If there are no errors then you have successfully installed aunga.
Errors with runtests
--------------------
If you get an error message or a weird result when running ``runtests.py``,
please write to the `mailing list`_ or `create an issue on the github site
`__.
To make it easier for us to debug you problem, please include the following
information:
* Operating system
* Python distribution (Anaconda_, PythonXY_, `ETS/Canopy`_, own install)
* Python version (2.6, 2.7 etc)
* The script you ran (and gave you an error/weird result)
* The error message (the part that says ``Traceback: ...``) or result (figure,
numbers, etc)
For extended instructions on installing on Ubuntu checkout the wiki page
`install ANUGA on Ubuntu `_
Alternative Ubuntu Install
==========================
An alternative is to install the dependencies using the Anaconda_ or the Miniconda_ Python
distributions by `Continuum Analytics`_.
Miniconda_ has the advantage of allowing you to create multiple
python environments and is particularly
useful if you want to keep multiple versions of AnuGA.
Both Anaconda_ and Miniconda_ do not require administrative rights
to your computer and do not interfere with the Python installed
in your system.
Anaconda and Miniconda
----------------------
Once you have downloaded and installed Anaconda_ or Miniconda_
open a terminal (or ``cmd.exe`` on Windows).
With Miniconda_, you can create
a specific environment for AnuGA, by running::
conda create -n anuga_env python=2.7
source activate anuga_env
With either Anaconda_ or Miniconda_ you can now install the dependencies by running::
conda install pip nose numpy scipy matplotlib netcdf4
conda install -c pingucarsti gdal
and setup GDAL_DATA environment variable::
export GDAL_DATA=`gdal-config --datadir`
(You should add this command to your .bashrc file.)
Windows Dependency Installation
===============================
We have successfully install AnuGA on windows using Gohlke Binaries and using Miniconda.
At present we recommend using the Gohlke Binaries.
Follow the instructions
`install ANUGA on Windows using the Gohlke Binaries
`_
Alternatively if you want ot use Miniconda, follow the instructions
`install ANUGA on Windows using Miniconda
`_
GCC dependency for Windows users
--------------------------------
Unfortunately, the ``gcc`` compiler MinGW_ included in Anaconda or
installable via Miniconda_ doesn't have OpenMP_ support. This is required to compile
some extension modules in AnuGA (those that have multi-threaded parallel code).
We suggest that you download and install the version of MinGW_ provided by TDM-GCC_
**after** you've installed Anaconda and **before** you install AnuGA.
Don't forget to mark the ``openmp`` and ``gfortran`` options in the "Choose Components" part of
the installation. See this `excellent documentation for Windows users`_
(they even have screenshots!). The same applies if you are using Miniconda_.
Installing the latest development version of AnuGA om Windows
=============================================================
We suggest instaling the latest code and features,
by installing AnuGA directly from Github_.
We try to maintain the *master* branch stable and
`passing all tests `__,
so it should be safe to use.
First, you'll need to `install git`_.
Then, open a terminal and run::
git clone git://github.com/GeoscienceAustralia/anuga_core.git
This will fetch the source code from Github_
and place it in a folder called ``anuga_core`` in the directory where you ran the
command.
Then, just ``cd`` into the directory and run ``pip``::
cd anuga_core
pip install --upgrade .
Testing the install
-------------------
From the source directory run ``python runtests.py``::
python runtests.py
If you get an error message or weird result,
please write to the `mailing list`_ or `create an issue on the github site
`__.
To make it easier for us to debug you problem, please include the following
information:
* Operating system
* Python distribution (Anaconda_, PythonXY_, `ETS/Canopy`_, own install)
* Python version (2.6, 2.7 etc)
* The script you ran (and gave you an error/weird result)
* The error message (the part that says ``Traceback: ...``) or result (figure,
numbers, etc)
Using pip_ to install anuga
===========================
You can alternatively use pip_ to install the lateest released version of `anuga`
Open a terminal (or ``cmd.exe`` on Windows) and run::
pip install anuga
If you already have AnuGA installed and want to **upgrade** to a newer
released version, use::
pip install anuga --upgrade
To uninstall simply run::
pip uninstall anuga
.. note::
The Windows installer from older versions is no longer supported.
.. _AnuGA: http://anuga.anu.edu.au/
.. _install git: http://git-scm.com/
.. _Github: https://github.com/stoiver/anuga_core/
.. _Python: http://www.python.org/
.. _pip: http://www.pip-installer.org
.. _MinGW: http://www.mingw.org/
.. _mailing list: anuga-user@lists.sourceforge.net
.. _Continuum Analytics: http://continuum.io/
.. _Anaconda: http://continuum.io/downloads
.. _Miniconda: http://conda.pydata.org/miniconda.html
.. _PythonXY: http://code.google.com/p/pythonxy/
.. _ETS/Canopy: http://code.enthought.com/projects/index.php
.. _OpenMP: http://openmp.org/
.. _TDM-GCC: http://tdm-gcc.tdragon.net/
.. _excellent documentation for Windows users: http://docs-windows.readthedocs.org/en/latest/devel.html#mingw-with-openmp-support