Merge lp:~fluidity-core/fluidity/supportingsoftwaremanualupdates201403 into lp:fluidity

[Tim Greaves]

General updates to the external libraries appendix and the primer.

The external libraries appendix is updated to the latest software versions used for Fluidity, and install methods for external libraries on Red Hat, Fedora, and OpenSuSE are added.

Primers are made specific to Ubuntu, Red Hat (and derivatives), Fedora, and OpenSuSE.

Feedback welcomed on these changes - to some extent this has been discussed in dev meetings and the proposed merge here is following decisions made there, but more specific formatting and description comments would be appreciated if anyone has suggestions for improvement.

Unmerged revisions

4336. By Tim Greaves on 2014-04-17

Updating the Ubuntu section in 'External Libraries' to reflect a more time-
independent description of supported releases.

4335. By Tim Greaves on 2014-04-17

Formatting and content bugfixes.

4334. By Tim Greaves on 2014-04-17

Updating to a neater method for adding repositories.

4333. By Tim Greaves on 2014-04-17

Adding a primer for OpenSuSE.

4332. By Tim Greaves on 2014-04-17

Adding a primer for Fedora.

4331. By Tim Greaves on 2014-04-17

Formatting fixes for the Red Hat primer

4330. By Tim Greaves on 2014-04-17

Syntax correction to the Red Hat primer

4329. By Tim Greaves on 2014-04-17

Adding in a primer for Red Hat Enterprise Linux and derivatives; first draft.

4328. By Tim Greaves on 2014-04-17

Setting up a main page for the primer section, and moving the previous primer
page (with some updates to reflect which versions of Ubuntu we support, and
referring users to Ubuntu's 'releases' page) in preparation for adding more
primer pages for other Linux distributions.

4327. By Stephan Kramer on 2014-04-10

Update recommended petsc configuration options.

=== modified file 'manual/external_libraries.tex'
--- manual/external_libraries.tex	2013-09-23 20:07:28 +0000
+++ manual/external_libraries.tex	2014-04-17 13:06:05 +0000
@@ -18,78 +18,230 @@
 run:
 
 \begin{itemize}
-\item Fortran 90 and C++ compiler (gcc build tested version 4.8.1, expected working for gcc 4.5.x and higher; Intel 11.1 for versions above 11.1.073)
+\item Fortran 90 and C++ compiler (gcc tested version 4.8.2, expected working for gcc 4.5.x and higher; other compilers not currently supported but work is ongoing with Intel to support their 2014 releases)
 \item BLAS (tested netlib, ATLAS, MKL)
 \item LAPACK (tested netlib, ATLAS, MKL)
-\item MPI2 implementation (build tested OpenMPI version 1.6.5)
-\item PETSc (build tested version 3.4.1, fully tested version 3.1p8)
-\item ParMetis (build tested version 3.2)
+\item MPI2 implementation (tested OpenMPI version 1.6.5)
+\item PETSc (tested version 3.4.3)
+\item ParMetis (tested version 3.2, 4.x not supported)
 \item Python (build tested version 2.7.5) 
-\item NumPy (build tested version 1.7.1)
-\item VTK (tested version 5.10.1)
-\item Zoltan (build tested version 3.6)
+\item NumPy (build tested version 1.8.1)
+\item VTK (tested version 5.10.1, 6.x not supported)
+\item Zoltan (build tested version 3.8)
+\item GMSH (tested version 2.8.4)
 \end{itemize}
 
 \fluidity recommends also making available the following:
 
 \begin{itemize}
 \item Trang (tested version 20030619, any recent version should work)
-\item NetCDF (tested version 4.0)
-\item UDUnits (tested version 2.1.23)
-\item Bazaar (tested version 2.4.0)
-\item SciPy (tested version 0.11.0)
-\item ARPACK (tested version 96)
-\item XML2 (tested version 2.6)
+\item NetCDF (tested version 4.1.3)
+\item UDUnits (tested version 2.2.0)
+\item Bazaar (tested version 2.6.0)
+\item SciPy (tested version 0.13.3)
+\item ARPACK (tested version 3.1.5)
+\item XML2 (tested version 2.9.1)
 \end{itemize}
 
-\section{Installing required libraries on Debian or Ubuntu}
-\label{sec:required_ḻibraries_debian}\index{libraries!installing on debian and ubuntu}
-
-By far the easiest way to obtain all the supporting libraries and other
-software required to build and run \fluidity is to make use of the \fluidity
-packages available from the Launchpad fluidity-core PPA. These are available
-for as many Ubuntu versions as \fluidity currently supports; at the time of
-writing, 10.10 (Maverick) and newer, though support for 10.10 will end as of
-April 2012 when central Ubuntu support ends.
-
-\textbf{BE AWARE:} AMCG packages are provided for use at your own risk and
-without warranty. You should ensure that any packages installed from external
-repositories are not going to adversely affect your system before installing
-them!
-
-To access the repository containing the \fluidity support packages, you will
+\section{Installing required libraries on major Linux distributions}
+\label{sec:required_ḻibraries_linux}\index{libraries!installing on linux}
+
+\fluidity comes pre-packages for many major Linux distributions, both as a set
+of libraries for building the code and as a pre-built \fluidity binary package
+for immediate use.
+
+\textbf{BE AWARE:} All packages from \fluidity repositories are provided for
+use at your own risk and without warranty. You should ensure that any packages
+installed from external repositories are not going to adversely affect your
+system before installing them!
+
+\subsection{Installing on Ubuntu}
+\label{sec:required_ḻibraries_Ubuntu}\index{libraries!installing on Ubuntu}
+
+\fluidity aims to fully support the latest Ubuntu LTS distribution at any given
+time, to offer support for previous LTS distributions for as long as practical
+within the official five-year Ubuntu support period, and to offer packages for
+building and installing \fluidity on all other main Ubuntu releases still
+listed as current on
+\href{https://wiki.ubuntu.com/Releases}{https://wiki.ubuntu.com/Releases}
+. A full testing program will be carried out on the latest LTS
+distribution as a matter of \fluidity general policy, whilst testing on other
+Ubuntu versions will be carried out as available resources permit.
+
+At the time of writing (April 2014), all current releases are supported bar
+Ubuntu 10.10 LTS (lucid).
+
+Going forward, timely support for six-monthly Ubuntu releases is intended,
+although the faster-moving nature of this target may mean that from time to
+time there is a delay in releasing a full \fluidity package set. Users move
+from the LTS to six-month releases at the price of being on a lower-priorty
+platform as far as central \fluidity support and testing is concerned.
+
+To access the repository containing the \fluidity packages, you will
 need to run:
 
 \begin{lstlisting}[language=bash]
 sudo apt-add-repository -y ppa:fluidity-core/ppa
 \end{lstlisting}
 
-You will then need to update your system and install the fluidity-dev package,
-which depends on all the other software required for building \fluidity:
+To develop or locally build \fluidity, you will then need to update your system
+and install the fluidity-dev package, which depends on all the other software
+required for building \fluidity:
+
 
 \begin{lstlisting}[language=bash]
 sudo apt-get update
 sudo apt-get install fluidity-dev
 \end{lstlisting}
 
-To benefit from the environment modules supplied from AMCG you may want to add
-the following lines to your \lstinline[language=bash]+/etc/bash.bashrc+ file:
-
-\begin{lstlisting}[language=bash]
-if [ -f /usr/share/Modules/init/bash ]; then
-    . /usr/share/Modules/init/bash
-fi
-\end{lstlisting}
-
-New bash shells should automatically inherit the modules environment now, and
-you should be able to type:
-
-\begin{lstlisting}[language=bash]
-module load petsc-gcc4
-\end{lstlisting}
-
-to enable use of PETSc, required for building \fluidity.
- 
+If you wish to install the \fluidity binary packages you can also run:
+
+\begin{lstlisting}[language=bash]
+sudo apt-get install fluidity
+\end{lstlisting}
+
+Note that the above is tested on a clean Ubuntu LTS install with no other PPAs
+or other external repositories enabled; if you have other software sources
+which may conflict with the core repositories and the \fluidity PPA then you
+will need to contact your local technical support team in the case of package
+conflicts or version mismatches.
+
+\subsection{Installing on Red Hat Enterprise and derivatives}
+\label{sec:required_ḻibraries_redhat}\index{libraries!installing on redhat}
+
+\fluidity aims to fully support the latest Red Hat Enterprise Linux release at any given
+time, and to offer support for previous distributions for as long as practical
+within the official Red Hat support period. Development and testing is carried
+out using the CentOS community rebuild of Red Hat Enterprise. Packages are also
+sourced from the Extra Packages for Enterprise Linux (EPEL) repository,
+maintained by Fedora.
+
+It is expected that the community rebuilds of Red Hat Enterprise Linux,
+including CentOS and Scientific Linux, should be able to use the \fluidity Red
+Hat package repositories.
+
+At the time of writing, Red Hat Enterprise Linux (Desktop) version 6.5 is the
+supported and tested release, though it is expected that packages provided from
+the \fluidity repository will work on most 6.x systems. Red Hat Enterprise 5.x
+systems are not supported, as the provided compiler and python versions are too
+old for building and testing \fluidity. When version 7 is released, support from
+the \fluidity repositories is expected to be promptly provided as Fedora 19, on
+which Red Hat Enterprise 7 is based, is already fully supported.
+
+The following methods assume that the EPEL repository is enabled on your
+system. If this is not the case, follow instructions at
+\url{https://fedoraproject.org/wiki/EPEL} to enable use of EPEL by installing
+an 'epel-release' package. Note that this assumes no other third-party
+repositories are enabled; if, for example, the rpmforge repository is enabled,
+you may well encounter package versioning issues against EPEL and the Fluidity
+repository.
+
+To access the repository containing the \fluidity packages, you will
+need to run the following, typed all on one line:
+
+\begin{lstlisting}[language=bash]
+sudo yum-config-manager --add-repo
+                   http://amcg.ese.ic.ac.uk/yum/rhel/6/fluidity.repo
+\end{lstlisting}
+
+To develop or locally build \fluidity you will then need to install the
+fluidity-dev package, which depends on all the other software required for
+building \fluidity:
+
+\begin{lstlisting}[language=bash]
+sudo yum install fluidity-dev
+\end{lstlisting}
+
+If you wish to install the \fluidity binary packages you can also run:
+
+\begin{lstlisting}[language=bash]
+sudo yum install fluidity
+\end{lstlisting}
+
+Note that the above is tested on a clean CentOS 6.5 install with no other
+external repositories enabled; if you have other software sources which may
+conflict with the \fluidity, EPEL, or core repositories then you will need to
+contact your local technical support team in the case of package conflicts or
+version mismatches. Problems have been reported using the rpmforge repositories
+alongside the \fluidity and EPEL repositories, for example.
+
+\subsection{Installing on Fedora}
+\label{sec:required_ḻibraries_fedora}\index{libraries!installing on fedora}
+
+\fluidity aims to fully support all Fedora releases that are supported
+centrally by the Fedora team, although the faster-moving target presented by
+Fedora means that from time to time latest release may not be immediately or
+fully supported.
+
+At the time of writing, Fedora 19 is fully supported and tested for \fluidity,
+but Fedora 20 is not yet supported as \fluidity does not yet support building
+with VTK6.
+
+To access the repository containing the \fluidity packages for Fedora 19, you
+will need to run the following, typed all on one line:
+
+\begin{lstlisting}[language=bash]
+sudo yum-config-manager --add-repo http://amcg.ese.ic.ac.uk/yum/fedora/19/fluidity.repo
+\end{lstlisting}
+
+To develop or locally build \fluidity you will then need to install the
+fluidity-dev package, which depends on all the other software required for
+building \fluidity:
+
+\begin{lstlisting}[language=bash]
+sudo yum install fluidity-dev
+\end{lstlisting}
+
+If you wish to install the \fluidity binary packages you can also run:
+
+\begin{lstlisting}[language=bash]
+sudo yum install fluidity
+\end{lstlisting}
+
+Note that the above is tested on a clean Fedora 19 install with no other
+external repositories enabled; if you have other software sources which may
+conflict with the \fluidity or Fedora repositories then you will need to
+contact your local technical support team in the case of package conflicts or
+version mismatches.
+
+\subsection{Installing on OpenSuSE}
+\label{sec:required_ḻibraries_opensuse}\index{libraries!installing on opensuse}
+
+\fluidity aims to fully support all OpenSuSE releases that are supported
+centrally by the OpenSuSE team, for as long as they remain in support and are
+realistic platforms on which \fluidity can be built.
+
+At the time of writing, OpenSuSE 12.3 is fully supported and tested for \fluidity,
+but OpenSuSE 13.1 is not yet supported as \fluidity does not yet support building
+with VTK6.
+
+To access the repository containing the \fluidity packages for OpenSuSE 12.3, you
+will need to run:
+
+\begin{lstlisting}[language=bash]
+sudo zypper ar -f http://amcg.ese.ic.ac.uk/yast/opensuse/12.3/
+\end{lstlisting}
+
+To develop or locally build \fluidity you will then need to install the
+fluidity-dev package, which depends on all the other software required for
+building \fluidity:
+
+\begin{lstlisting}[language=bash]
+sudo zypper install fluidity-dev
+\end{lstlisting}
+
+If you wish to install the \fluidity binary packages you can also run:
+
+\begin{lstlisting}[language=bash]
+sudo zypper install fluidity
+\end{lstlisting}
+
+Note that the above is tested on a clean OpenSuSE 12.3 install with no other
+external repositories enabled; if you have other software sources which may
+conflict with the \fluidity or core OpenSuSE repositories then you will need to
+contact your local technical support team in the case of package conflicts or
+version mismatches.
+
 \section{Manual install of external libraries and software}
 \label{sec:required_ḻibraries_manual_install}\index{libraries!installing externals from source}
 
@@ -110,7 +262,7 @@
 should be relatively tolerant of older versions, as long as they work and are
 POSIX-compliant.
 
-As a side-note, the gcc-multilib requirement for building gcc 4.7 appears to be
+As a side-note, the gcc-multilib requirement for building gcc appears to be
 the result of gcc failing to check for the existence of 32-bit headers at
 configure time, and thus requiring the 32-bit compatibility libraries to be
 installed on 64-bit systems. There may be a workaround for this of which the
@@ -124,11 +276,12 @@
 recommended that you ensure that your builds will use a compiler that is also
 able to build \fluidity. If you do not, you may encounter problems when you try
 to interface \fluidity with the libraries. At present, \fluidity is tested with
-gcc/g++/gfortran versions 4.5-4.7 and the Intel compiler with version 11.1.073
-and later versions of 11.1. Versions of 11.1 earlier than 11.1.073 contain bugs
-that prevent building \fluidity, as do all other major and minor versions of
-the Intel compiler. Bug reports have been filed with Intel to remedy this but 
-remain outstanding as of this document date (August 2013).
+gcc/g++/gfortran versions 4.8 (and expected to behave reasonably with versions
+4.6 and later) and the Intel compiler with version 11.1.073 and later versions
+of 11.1. Versions of 11.1 earlier than 11.1.073 contain bugs that prevent
+building \fluidity, as do all other major and minor versions of the Intel
+compiler. Bug reports have been filed with Intel to remedy this but remain
+outstanding as of this document date (March 2014).
 
 \subsection{Build environment}
 \label{sec:required_libraries_build_environment}
@@ -171,7 +324,7 @@
 \fluidity has been tested with gfortran $\geq$ 4.4 and Intel 11.1 for versions
 $\geq$ 11.1.073. It is not supported for gfortran $\leq$ 4.3 or Intel $\leq$
 11.1.073, and if using gfortran some features are not available except for
-gfortran $\geq$ 4.5. Current testing is with gfortran 4.6, so whilst it is
+gfortran $\geq$ 4.5. Current testing is with gfortran 4.8, so whilst it is
 expected that 4.4 and 4.5 will function correctly, this is not guaranteed.
 
 Unsupported compilers generally have incorrect Fortran 90 implementations for
@@ -206,14 +359,13 @@
 \subsubsection{GMP, MPFR, and MPC}
 \label{sec:required_libraries_compilers_gmp_mpfr_mpc}
 
-GMP (tested for \fluidity build compatibility with gmp-5.1.2, fully tested
-gmp-4.3.2) MPFR (tested for \fluidity build compatibility with mpfr-3.1.2,
-fully tested mpfr-3.1.0), and MPC (tested for \fluidity build compatibility
-with mpc-1.0.1, fully tested mpc-0.9) are needed for the GCC 4.8 build if you
-do not already have them.  Download GMP from \url{http://gmplib.org/} and build
-it in the source directory, appending
-\lstinline[language=bash]+--build=x86_64-linux-gnu --enable-cxx+ to the
-standard configure, then running the standard make and install.
+GMP (tested version 5.1.3), MPFR (tested version 3.1.2), and MPC (tested
+version 1.0.1) are needed for the GCC 4.8 build if you do not already have
+them. Download GMP from \url{http://gmplib.org/} and build it in the source
+directory, appending
+\lstinline[language=bash]+--build=x86_64-linux-gnu --enable-cxx+
+to the standard configure, then running the standard make and
+install.
 
 Once GMP has been installed, download MPFR from
 \url{http://www.mpfr.org/mpfr-current/} and build it in the source directory,
@@ -239,8 +391,7 @@
 \subsubsection{GCC}
 \label{sec:required_libraries_compilers_gcc}
 
-GCC (tested for \fluidity build compatibility up to gcc-4.8.1, fully tested
-gcc-4.6.3) can be downloaded from the UK mirror at
+GCC (tested for \fluidity with version 4.8.2) can be downloaded from the UK mirror at
 \url{http://gcc-uk.internet.bs/} Before the build, make sure that the GMP,
 MPFR, and MPC libraries are on LD{\textunderscore}LIBRARY{\textunderscore}PATH
 or the stage 1 configure will fail even if
@@ -265,7 +416,7 @@
 --prefix=$WORKING/fluidity --with-gmp=$WORKING/fluidity
 --with-mpfr=$WORKING/fluidity --with-mpc=$WORKING/fluidity
 --enable-checking=release --enable-languages=c,c++,fortran 
---disable-multilib --program-suffix=-4.8.1
+--disable-multilib --program-suffix=-4.8.2
 \end{lstlisting}
 
 followed by the standard make and install. Note you may well want to change the
@@ -276,11 +427,11 @@
 environment variables, ie:
 
 \begin{lstlisting}[language=bash]
-export CC=gcc-4.8.1
-export CXX=g++-4.8.1
-export FC=gfortran-4.8.1
-export F90=gfortran-4.8.1
-export CPP=cpp-4.8.1
+export CC=gcc-4.8.2
+export CXX=g++-4.8.2
+export FC=gfortran-4.8.2
+export F90=gfortran-4.8.2
+export CPP=cpp-4.8.2
 \end{lstlisting}
 
 (with suitable version changes if necessary), or if you prefer you could reset
@@ -298,8 +449,7 @@
 non-MPI code as it is assumed that serial runs will be precursors to large
 parallel runs and will be built with MPI enabled for later use.
 
-OpenMPI (tested for \fluidity build compatibility up to version 1.6.5, and
-fully tested to 1.4.3) can be downloaded from
+OpenMPI (tested version 1.6.5) can be downloaded from
 \url{http://www.open-mpi.org/software/}. It is built in the source directory
 with the standard configure, make, and install.
 
@@ -376,8 +526,8 @@
 \label{sec:required_libraries_numerical_parmetis}\index{ParMetis}
 
 ParMetis (tested for \fluidity build compatibility with version 3.2.0, fully
-tested with version 3.1.1, NOT tested with version 4.x) is required for mesh
-partitioning and sparse matrix operations, and can be downloaded from
+tested with version 3.1.1; \fluidity does NOT work correctly with version 4.x) is required for mesh
+partitioning, and can be downloaded from
 \url{http://glaros.dtc.umn.edu/gkhome/fsroot/sw/parmetis/OLD}
 
 ParMetis is built in the source directory with:
@@ -388,27 +538,22 @@
 cp parmetis.h $WORKING/fluidity/include
 \end{lstlisting}
 
-Note that \fluidity is NOT currently tested with ParMETIS 4.0.0, and further
-note that ParMETIS is subject to licensing conditions for commercial users.
-Commercial users should contact the University of Minnesota's Office for
-Technology Commercialization directly. 
-
-\fluidity is in the process of transitioning away from using ParMETIS to avoid
-this restrictive commercial licensing, and by release 4.2 should have an
-alternative partitioner which is free to use for commercial partners.
+Note that \fluidity is NOT currently tested with ParMETIS 4.0.0 and it is
+expected that \fluidity will not work correctly with versions higher than 3.2.
 
 \subsubsection{PETSc}
 \label{sec:required_libraries_numerical_petsc}\index{PETSc}
 
 If you do not already have it installed, you will need Cmake (tested for
-version 2.8.11.2, download from
+version 2.8.12, download from
 \url{http://www.cmake.org/cmake/resources/software.html}) for the PETSc Metis
 build.  Cmake is built in its source directory with the standard configure,
 make, and install.
 
-PETSc (currently tested for \fluidity build compatibility with version 3.3-p7,
-fully tested with version 3.1p8, not tested with version 3.4.x) is required for
-efficient solver methods within \fluidity. PETSc can be downloaded from
+PETSc is required for
+efficient solver methods within \fluidity. Currently,
+\fluidity supports PETSc versions 3.1 to 3.4, using version 3.4
+is recommended. It can be downloaded from
 \url{http://www.mcs.anl.gov/petsc/download/} and built in the source directory.
 First, set PETSC{\textunderscore}DIR in the source directory:
 
@@ -419,13 +564,21 @@
 Then configure with the following all on one line:
 
 \begin{lstlisting}[language=bash]
-./configure --prefix=$WORKING/fluidity --with-mpi-shared=1
-   --with-shared-libraries=1 --with-debugging=0 --with-parmetis=1
-   --download-parmetis=1 --with-hypre=1 --download-hypre=1
-   --with-prometheus=1 --download-prometheus=1 --with-metis=1
-   --download-metis=1 --with-fortran-interfaces=1
+./configure --prefix=$WORKING/fluidity 
+   --download-fblaslapack=1 --download-blacs=1 --download-scalapack=1 
+   --download-ptscotch=1 --download-mumps=1 --download-hypre=1
+   --download-suitesparse=1 --download-ml=1 --with-fortran-interfaces=1
 \end{lstlisting}
 
+This set of configuration options provides you with the additional
+multigrid preconditioners hypre and ml, and direct solvers umfpack 
+from SuiteSparse and mumps. These are not strictly necessary to run
+Fluidity, but have been found useful in different applications. NOTE:
+you should NOT build PETSc with parmetis
+(so no --download/with-parmetis=1) as the version used by PETSc 
+(parmetis 4.x) leads to incorrect behaviour in Fluidity. Therefore, the above
+configuration options uses ptscotch as an alternative.
+
 When configure completes, it should supply you with a 'make all' command line,
 including various configuration variables. Copy and paste this into your
 terminal and run it. Once it completes, it will supply you with a further 'make
@@ -444,50 +597,10 @@
 \subsubsection{Zoltan}
 \label{sec:required_libraries_numerical_zoltan}\index{Zoltan}
 
-Zoltan (fully tested with version 3.6) is available as a tarball from  
-\url{http://www.cs.sandia.gov/~kddevin/Zoltan_Distributions/zoltan_distrib_v3.6.tar.gz}
-
-After uncompressing that file, you will fix a known issue with Zoltan Fortran
-modules by editing the file Zoltan{\textunderscore}v3.6/src/Makefile.in: at the
-end of that file and finding lines looking like:
-
-\begin{lstlisting}[language=bash]
-   #if F90_MODULE_LOWERCASE
-   #FORTRAN_MODULES = \
-   # lb_user_const.mod \
-   # zoltan_types.mod \
-   # zoltan.mod \
-   # zoltan_user_data.mod
-   #else
-   #FORTRAN_MODULES = \
-   # LB_USER_CONST.mod \
-   # ZOLTAN_TYPES.mod \
-   # ZOLTAN.mod \
-   # ZOLTAN_USER_DATA.mod
-   #endif
-\end{lstlisting}
-
-Delete lines and leading \# characters appropriately so you end up with the above replaced by:
-
-\begin{lstlisting}[language=bash]
-   FORTRAN_MODULES = \
-          lb_user_const.mod \
-          zoltan_types.mod \
-          zoltan.mod \
-          zoltan_user_data.mod
-\end{lstlisting}
-
-If you are using gcc 4.7.2 or later you will need to make some small
-modifications to the source of Zoltan 3.6, as per the bug reported at
-\url{https://bugs.launchpad.net/fluidity/+bug/1101906}, replacing the file
-\lstinline[language=bash]+<source-root>/src/fort/set_hiermethod.fn+ with the
-new version downloaded from the bug report (
-\url{https://bugs.launchpad.net/fluidity/+bug/1101906/+attachment/3489641/+files/set_hiermethod.fn}
-).
-
-Without this fix in place, a build-time error will be encountered.
-
-Make a build directory and change into it:
+Zoltan (fully tested with version 3.8) is available as a tarball from  
+\url{http://www.cs.sandia.gov/~kddevin/Zoltan_Distributions/zoltan_distrib_v3.8.tar.gz}
+
+Uncompress the tarball, then make a build directory and change into it:
 
 \begin{lstlisting}[language=bash]
    mkdir Zoltan-build/
@@ -510,7 +623,7 @@
 line:
 
 \begin{lstlisting}[language=bash]
-   ../Zoltan_v3.6/configure x86_64-linux-gnu --prefix=$WORKING/fluidity
+   ../Zoltan_v3.8/configure x86_64-linux-gnu --prefix=$WORKING/fluidity
       --enable-mpi --with-mpi-compilers --with-parmetis
       --enable-f90interface --disable-examples
       --enable-zoltan-cppdriver --with-parmetis-libdir=$WORKING/fluidity/lib
@@ -527,16 +640,16 @@
 Python is widely used within \fluidity for user-defined functions and for
 diagnostic tools and problem setup, and currently tested up to Python version
 2.7. Earlier Python version may be suitable for use but may lack later
-functionality. Python extensions required are: setuptools for \fluidity builds,
-Python-4suite and Python-XML for options file parsing, and NumPy for custom
-function use within \fluidity.
+functionality. \fluidity is not yet tested with Python3. Python extensions
+required are: setuptools for \fluidity builds, Python-4suite and Python-XML for
+options file parsing, and NumPy for custom function use within \fluidity.
 
 If you do not have a working version of Python it can be built from source. 
 
 \subsubsection{Readline}
 \label{sec:required_libraries_python_readline}\index{Python!readline}
 
-Readline (tested version 6.2) is not strictly needed for Python to build but is
+Readline (tested version 6.3) is not strictly needed for Python to build but is
 very handy if you want to make use of things like Python command history.
 Download readline from \url{http://ftp.gnu.org/pub/gnu/readline/} and then add
 -fPIC to CFLAGS and FFLAGS for the duration of this build with:
@@ -573,7 +686,7 @@
 \subsubsection{NumPy}
 \label{sec:required_libraries_python_numpy}\index{Python!numpy}
 
-NumPy (tested version 1.7.1) can be downloaded as a compressed tarball from
+NumPy (tested version 1.8.1) can be downloaded as a compressed tarball from
 \url{https://pypi.python.org/pypi/numpy} and after unsetting CFLAGS and
 LDFLAGS:
 
@@ -697,6 +810,35 @@
 
 Finally, run the standard make and install.
 
+\subsection{GMSH}
+\label{sec:required_libraries_gmsh}\index{gmsh!installing}
+
+GMSH is strongly recommended for mesh conversion and creation and is tested
+with version 2.8.4. It can be downloaded from the 'source' link at 
+\url{http://geuz.org/gmsh/#Download}.
+
+Uncompress the downloaded tarball, then make a build directory and change into
+it:
+
+\begin{lstlisting}[language=bash]
+   mkdir gmsh-build/
+   cd gmsh-build/
+\end{lstlisting}
+
+From this build directory (assuming it's in the same location as the
+uncompressed source), run:
+
+\begin{lstlisting}[language=bash]
+   ccmake -i ../gmsh-2.8.4-source
+\end{lstlisting}
+
+Press 'c' to configure, then when that completes leave all options at defaults
+and press 'c' a second time to configure again, then when that completes press
+'g' to generate a configuration and exit. If at any point you end up in a help
+screen, press 'e' to exit it.
+
+Finally, run the standard make and install.
+
 \subsection{Supporting Libraries}
 \label{sec:required_libraries_supporting}
 
 
=== modified file 'manual/getting_started.tex'
--- manual/getting_started.tex	2013-09-23 20:07:28 +0000
+++ manual/getting_started.tex	2014-04-17 13:06:05 +0000
@@ -13,25 +13,25 @@
 \subsection{Overview}
 \label{sec:obtaining_fluidity_overview}
 
-\fluidity\ is available both as precompiled binaries for Ubuntu Linux version
-12.04 (Precise) and newer, and as source code available via bzr (bazaar) or as
-gzipped tarballs. Which method you use to obtain \fluidity\ depends primarily on
-whether you use Ubuntu Linux and whether you wish to modify the \fluidity\
-source code. 
-
-\fluidity\ generally attempts to support any given release of Ubuntu for 18
-months from the point of release.
-
-Users who run Ubuntu Linux and who have no need to change the source code will
-probably wish to use binary packaged \fluidity. Developers and users on
-non-Ubuntu platforms will probably wish to build \fluidity\ from source.
+\fluidity\ is available both as precompiled binaries for a number of major,
+recent Linux distributions and as source code available via bzr (bazaar) or as
+gzipped tarballs. Which method you use to obtain \fluidity\ depends primarily
+on whether you use a recent Linux distribution and whether you wish to modify
+the \fluidity\ source code.
+
+\fluidity\ attempts to support as many major Linux platforms based on recent
+compilers as possible. This currently includes Ubuntu versions 12.04, 12.10,
+13.10, and 14.04, Red Hat Enterprise Linux version 6 and its derivatives
+(including CentOS and Scientific Linux), Fedora 19, and OpenSuSE 12.3. Fedora
+20 and OpenSuSE 13.1 are not yet supported, but are intended to be supported
+soon.
 
 \subsection{\fluidity\ binary packages for Ubuntu Linux}
 
-\fluidity\ is distributed via the \lstinline[language=Bash]+fluidity-core+
-launchpad package archive. If you run Ubuntu Linux version 12.04 (Precise) or
-newer and have administrative privileges on
-your computer, you can add the package archive to your system by typing:
+\fluidity\ is distributed for all centrally-supported Ubuntu desktop systems
+via the \lstinline[language=Bash]+fluidity-core+ launchpad package archive. If
+you have administrative privileges on your computer, you can add the package
+archive to your system by typing:
 
 \begin{lstlisting}[language=Bash]
 sudo apt-add-repository -y ppa:fluidity-core/ppa
@@ -54,6 +54,78 @@
 tar -zxvf /usr/share/doc/fluidity/examples.tar.gz
 \end{lstlisting}
 
+\subsection{\fluidity\ binary packages for Red Hat Enterprise Linux}
+
+\fluidity\ is distributed for all systems based on Red Hat Enterprise 6 via a
+package repository which can be installed by users who have administrative
+privileges on their computer by typing:
+
+\begin{lstlisting}[language=Bash]
+sudo yum-config-manager --add-repo http://amcg.ese.ic.ac.uk/yum/rhel/6/fluidity.repo
+\end{lstlisting}
+
+Type your password if prompted. \fluidity\ can then be installed with:
+
+\begin{lstlisting}[language=Bash]
+sudo yum install fluidity
+\end{lstlisting}
+
+You now have \fluidity\ installed on your computer. Examples, as referred to in
+chapter \ref{chap:examples}, are available as a compressed tarball and can be
+expanded into a writeable directory with:
+
+\begin{lstlisting}[language=Bash]
+tar -zxvf /usr/share/doc/fluidity/examples.tar.gz
+\end{lstlisting}
+
+\subsection{\fluidity\ binary packages for Fedora}
+
+\fluidity\ is distributed for Fedora 19 (but not yet for Fedora 20 due to VTK6
+incompatibility) via a package repository which can be installed by all users
+who have administrative privileges on their computer by typing:
+
+\begin{lstlisting}[language=Bash]
+sudo yum-config-manager --add-repo http://amcg.ese.ic.ac.uk/yum/fedora/19/fluidity.repo
+\end{lstlisting}
+
+Type your password if prompted. \fluidity\ can then be installed with:
+
+\begin{lstlisting}[language=Bash]
+sudo yum install fluidity
+\end{lstlisting}
+
+You now have \fluidity\ installed on your computer. Examples, as referred to in
+chapter \ref{chap:examples}, are available as a compressed tarball and can be
+expanded into a writeable directory with:
+
+\begin{lstlisting}[language=Bash]
+tar -zxvf /usr/share/doc/fluidity/examples.tar.gz
+\end{lstlisting}
+
+\subsection{\fluidity\ binary packages for OpenSuSE}
+
+\fluidity\ is distributed for OpenSuSE 12.3 (but not yet for OpenSuSE 13.1 due to VTK6
+incompatibility) via a package repository which can be installed by all users
+who have administrative privileges on their computer by typing:
+
+\begin{lstlisting}[language=Bash]
+sudo zypper ar -f http://amcg.ese.ic.ac.uk/yast/opensuse/12.3/
+\end{lstlisting}
+
+Type your password if prompted. \fluidity\ can then be installed with:
+
+\begin{lstlisting}[language=Bash]
+sudo zypper install fluidity
+\end{lstlisting}
+
+You now have \fluidity\ installed on your computer. Examples, as referred to in
+chapter \ref{chap:examples}, are available as a compressed tarball and can be
+expanded into a writeable directory with:
+
+\begin{lstlisting}[language=Bash]
+tar -zxvf /usr/share/doc/fluidity/examples.tar.gz
+\end{lstlisting}
+
 \subsection{\fluidity\ source packages}
 
 \fluidity\ is released as compressed source archives which can be downloaded
 
=== added file 'manual/primer.tex'
--- manual/primer.tex	1970-01-01 00:00:00 +0000
+++ manual/primer.tex	2014-04-17 13:06:05 +0000
@@ -0,0 +1,4 @@
+\input{primer_ubuntu.tex}
+\input{primer_redhat.tex}
+\input{primer_fedora.tex}
+\input{primer_opensuse.tex}
 
=== added file 'manual/primer_fedora.tex'
--- manual/primer_fedora.tex	1970-01-01 00:00:00 +0000
+++ manual/primer_fedora.tex	2014-04-17 13:06:05 +0000
@@ -0,0 +1,54 @@
+\chapter*{Fluidity Primer for Fedora}
+% \pagenumbering{roman} \setcounter{page}{}
+
+Please check the \fluidity\ webpage at
+\href{http://amcg.ese.ic.ac.uk/Fluidity}{http://amcg.ese.ic.ac.uk/Fluidity}
+to ensure you are reading the most recent version of this manual. Methods for
+installing Fluidity may sometimes change, and instructions may be updated!
+
+This is a one-page primer for obtaining \fluidity\ and running a simple example. It assumes that:
+
+\begin{itemize}
+ \item You are running Fedora 19 (Fedora 20 is not yet supported)
+ \item You have administrative rights on your computer
+ \item You know how to run a terminal with a command prompt
+ \item You have a directory in which you can create files
+\end{itemize}
+
+Set up your computer to access the Fluidity repository by typing the following,
+all on one line:
+
+\begin{lstlisting}[language=Bash]
+sudo yum-config-manager --add-repo
+                   http://amcg.ese.ic.ac.uk/yum/fedora/19/fluidity.repo
+\end{lstlisting}
+
+Type your password when prompted.
+
+Once this completes, update your system and install \fluidity along with its
+supporting software by typing:
+
+\begin{lstlisting}[language=Bash]
+sudo yum install fluidity
+\end{lstlisting}
+
+Now uncompress the packaged examples to a directory in which you can create
+files (in this example, \lstinline[language=Bash]+/tmp+) by typing:
+
+\begin{lstlisting}[language=Bash]
+cd /tmp
+tar -zxvf /usr/share/doc/fluidity/examples.tar.gz
+\end{lstlisting}
+
+Change into an examples directory (top\_hat is suggested as a straightforward
+starter) and run the example:
+
+\begin{lstlisting}[language=Bash]
+cd examples/top_hat/
+make preprocess
+make run
+make postprocess
+\end{lstlisting}
+
+You have now run your first \fluidity model. Chapter \ref{chap:examples}
+describes this and the other examples provided with \fluidity.  
 
=== added file 'manual/primer_opensuse.tex'
--- manual/primer_opensuse.tex	1970-01-01 00:00:00 +0000
+++ manual/primer_opensuse.tex	2014-04-17 13:06:05 +0000
@@ -0,0 +1,52 @@
+\chapter*{Fluidity Primer for OpenSuSE}
+% \pagenumbering{roman} \setcounter{page}{}
+
+Please check the \fluidity\ webpage at
+\href{http://amcg.ese.ic.ac.uk/Fluidity}{http://amcg.ese.ic.ac.uk/Fluidity}
+to ensure you are reading the most recent version of this manual. Methods for
+installing Fluidity may sometimes change, and instructions may be updated!
+
+This is a one-page primer for obtaining \fluidity\ and running a simple example. It assumes that:
+
+\begin{itemize}
+ \item You are running OpenSuSE 12.3 (OpenSuSE 13.1 is not yet supported) 
+ \item You have administrative rights on your computer
+ \item You know how to run a terminal with a command prompt
+ \item You have a directory in which you can create files
+\end{itemize}
+
+Set up your computer to access the Fluidity repository by typing:
+
+\begin{lstlisting}[language=Bash]
+sudo zypper ar -f http://amcg.ese.ic.ac.uk/yast/opensuse/12.3/
+\end{lstlisting}
+
+Type your password when prompted.
+
+Once this completes, update your system and install \fluidity along with its
+supporting software by typing:
+
+\begin{lstlisting}[language=Bash]
+sudo zypper install fluidity
+\end{lstlisting}
+
+Now uncompress the packaged examples to a directory in which you can create
+files (in this example, \lstinline[language=Bash]+/tmp+) by typing:
+
+\begin{lstlisting}[language=Bash]
+cd /tmp
+tar -zxvf /usr/share/doc/fluidity/examples.tar.gz
+\end{lstlisting}
+
+Change into an examples directory (top\_hat is suggested as a straightforward
+starter) and run the example:
+
+\begin{lstlisting}[language=Bash]
+cd examples/top_hat/
+make preprocess
+make run
+make postprocess
+\end{lstlisting}
+
+You have now run your first \fluidity model. Chapter \ref{chap:examples}
+describes this and the other examples provided with \fluidity.  
 
=== added file 'manual/primer_redhat.tex'
--- manual/primer_redhat.tex	1970-01-01 00:00:00 +0000
+++ manual/primer_redhat.tex	2014-04-17 13:06:05 +0000
@@ -0,0 +1,62 @@
+\chapter*{Fluidity Primer for Red Hat Enterprise and derivatives}
+% \pagenumbering{roman} \setcounter{page}{}
+
+Please check the \fluidity\ webpage at
+\href{http://amcg.ese.ic.ac.uk/Fluidity}{http://amcg.ese.ic.ac.uk/Fluidity}
+to ensure you are reading the most recent version of this manual. Methods for
+installing Fluidity may sometimes change, and instructions may be updated!
+
+This is a one-page primer for obtaining \fluidity\ and running a simple example. It assumes that:
+
+\begin{itemize}
+ \item You are running Red Hat Enterprise Linux 6.x or a derivative such as CentOS 6.x
+ \item You have the EPEL repository enabled
+         \footnote{
+           If you do not already have the EPEL repository enabled on your workstation, 
+           download the relevant 'epel-release' package from
+           \href{https://fedoraproject.org/wiki/EPEL}{https://fedoraproject.org/wiki/EPEL}
+           and install it on your workstation. 
+         }
+         (and no other third-party repositories)
+ \item You have administrative rights on your computer
+ \item You know how to run a terminal with a command prompt
+ \item You have a directory in which you can create files
+\end{itemize}
+
+Set up your computer to access the Fluidity repository by typing the following,
+all on one line:
+
+\begin{lstlisting}[language=Bash]
+sudo yum-config-manager --add-repo
+                  http://amcg.ese.ic.ac.uk/yum/rhel/6/fluidity.repo
+\end{lstlisting}
+
+Type your password when prompted.
+
+Once this completes, update your system and install \fluidity along with its
+supporting software by typing:
+
+\begin{lstlisting}[language=Bash]
+sudo yum install fluidity
+\end{lstlisting}
+
+Now uncompress the packaged examples to a directory in which you can create
+files (in this example, \lstinline[language=Bash]+/tmp+) by typing:
+
+\begin{lstlisting}[language=Bash]
+cd /tmp
+tar -zxvf /usr/share/doc/fluidity/examples.tar.gz
+\end{lstlisting}
+
+Change into an examples directory (top\_hat is suggested as a straightforward
+starter) and run the example:
+
+\begin{lstlisting}[language=Bash]
+cd examples/top_hat/
+make preprocess
+make run
+make postprocess
+\end{lstlisting}
+
+You have now run your first \fluidity model. Chapter \ref{chap:examples}
+describes this and the other examples provided with \fluidity.  
 
=== renamed file 'manual/primer.tex' => 'manual/primer_ubuntu.tex'
--- manual/primer.tex	2011-11-07 17:57:08 +0000
+++ manual/primer_ubuntu.tex	2014-04-17 13:06:05 +0000
@@ -1,4 +1,4 @@
-\chapter*{Fluidity Primer}
+\chapter*{Fluidity Primer for Ubuntu}
 % \pagenumbering{roman} \setcounter{page}{}
 
 Please check the \fluidity\ webpage at
@@ -9,10 +9,13 @@
 This is a one-page primer for obtaining \fluidity\ and running a simple example. It assumes that:
 
 \begin{itemize}
-\item You are running Ubuntu Linux, release 10.10 (Maverick) or newer
-\item You have administrative rights on your computer
-\item You know how to run a terminal with a command prompt
-\item You have a directory in which you can create files
+ \item You are running a current version of Ubuntu Linux
+         \footnote{
+See \href{https://wiki.ubuntu.com/Releases}{https://wiki.ubuntu.com/Releases}
+                  }, 12.04 or later
+ \item You have administrative rights on your computer
+ \item You know how to run a terminal with a command prompt
+ \item You have a directory in which you can create files
 \end{itemize}
 
 Set up your computer to access the Fluidity repository by typing: