Install Guide

Install Guide
1. Basic Installation
2. Configuring Chaste

This is the place to start if you want to be able to build the Chaste source code, to run your own tests or simulations on your machine. These instructions are not needed for an executable 'XML User' (see GettingStarted).

The easiest ways to install Chaste are:

On Ubuntu - use the Ubuntu .deb package.
Other Linux systems - try following the minimal instructions provided lower down this page.
Mac OS X 'Mountain Lion' (and possibly newer releases) - see InstallGuides/ChasteInstallationOnMountainLion, but note you'll need to use the latest development version of Chaste, not release 3.1 or earlier.
Any system - install a virtual machine (e.g. using VirtualBox) running the latest long-term support Ubuntu Linux, and install the Ubuntu package as above.

Then either download the latest code release (if you have not done so already), or see the section on checking out the code.

If you encounter any problems, or have/want an unusual setup, then the full DeveloperInstallGuide, or alternative guides listed at InstallGuides, may be useful.

Basic Installation

The following instructions detail an installation using the preferred versions of our dependencies, for a non-root user. For a full list of the compatibility of various versions of our dependencies see DependencyVersions. Some alternative versions of the libraries are incompatible, and others may have minor bugs.

NB: The newest versions of the libraries may not have been tested yet, so don't simply install the top one on each external download page! Ideally follow these instructions, if this isn't possible (or you have pre-installed versions) then check DependencyVersions first.

Some pre-requisites

The following tools are required or useful, most systems will already have these installed, or provide an easy way to set them up:

gcc and g++
gfortran --- if you want to build PETSc with HYPRE support (--download-hypre option below).
wget
python-devel
svn --- subversion, for Code Developers or Code Users of development version.
valgrind --- for memory testing - optional.
cmake --- for VTK installation from source - optional.

You need to know whether you are running a 32 or 64 bit system. In the terminal, type

uname -m

this should return either

x86_64 --- this means you have a 64-bit system, or
i686 --- this means you have a 32-bit system

and you should follow the below instructions accordingly. Note that Chaste 3.1 was the last release to support 32-bit; Chaste is now only tested on 64-bit machines.

Many systems will also include some of the below Chaste dependencies already. You can usually have a look for them with locate, e.g.

locate petsc

If you find pre-existing versions, then check DependencyVersions to see if they are compatible with Chaste, if so you may be able to skip their installation below, but make sure that you have the 'includes' and 'libraries' where required (if you don't know what this means then just follow all the below instructions!).

Define a folder to install all the dependencies in

First define the folder where you want to install the libraries which Chaste depends on. It is generally best if this is on a local hard disk for speed.

export CHASTE_LIBS=/home/scratch/chaste-libs

If it doesn't already exist, create this directory:

mkdir -p $CHASTE_LIBS

The following instructions assume that:

wget is installed.
You are connected to the internet.

If either of these is not true, then download the http links in your browser and copy them onto the machine you wish to install on.

SCONS

wget http://prdownloads.sourceforge.net/scons/scons-2.3.1.tar.gz
tar zxf scons-2.3.1.tar.gz
cd scons-2.3.1
python setup.py install --prefix=$CHASTE_LIBS
cd ..
rm -rf scons-2.3.1.tar.gz scons-2.3.1

BOOST

wget http://downloads.sourceforge.net/project/boost/boost/1.54.0/boost_1_54_0.tar.gz
tar zxf boost_1_54_0.tar.gz
cd boost_1_54_0
./bootstrap.sh --prefix=$CHASTE_LIBS --with-libraries=system,filesystem,serialization
./b2 install
cd ..
rm -rf boost_1_54_0.tar.gz boost_1_54_0

PETSc

Newer versions of PETSc (>3) can install a lot of Chaste's dependencies for us.

(There is a --download-boost option, but this doesn't include the particular libraries we need, so we can't use that.)

These steps can take some time (up to an hour or more)...

cd $CHASTE_LIBS
wget http://ftp.mcs.anl.gov/pub/petsc/release-snapshots/petsc-lite-3.4.4.tar.gz
tar zxf petsc-lite-3.4.4.tar.gz
rm -f petsc-lite-3.4.4.tar.gz
cd petsc-3.4.4
export PETSC_DIR=`pwd`

export PETSC_ARCH=linux-gnu
./config/configure.py --download-f2cblaslapack --download-openmpi --download-hypre --download-sundials --download-hdf5 --download-parmetis --download-metis --with-x=false --with-clanguage=cxx --with-shared-libraries --with-gnu-compilers
./config/builder.py

# Optional - optimised petsc build too.
export PETSC_ARCH=linux-gnu-opt
./config/configure.py --download-f2cblaslapack --download-openmpi --download-hypre --download-sundials --download-hdf5 --download-parmetis --download-metis --with-x=false --with-clanguage=cxx --with-shared-libraries --with-gnu-compilers --with-debugging=0
./config/builder.py

XSD

For XSD we use the distributed binaries. For 32-bit (deprecated):

cd $CHASTE_LIBS
wget http://www.codesynthesis.com/download/xsd/3.3/linux-gnu/i686/xsd-3.3.0-i686-linux-gnu.tar.bz2
tar -xjf xsd-3.3.0-i686-linux-gnu.tar.bz2
ln -s $CHASTE_LIBS/xsd-3.3.0-i686-linux-gnu/bin/xsd $CHASTE_LIBS/bin/xsd
rm -f xsd-3.3.0-i686-linux-gnu.tar.bz2

Or for 64 bit:

cd $CHASTE_LIBS
wget http://www.codesynthesis.com/download/xsd/3.3/linux-gnu/x86_64/xsd-3.3.0-x86_64-linux-gnu.tar.bz2
tar -xjf xsd-3.3.0-x86_64-linux-gnu.tar.bz2
ln -s $CHASTE_LIBS/xsd-3.3.0-x86_64-linux-gnu/bin/xsd $CHASTE_LIBS/bin/xsd
rm -f xsd-3.3.0-x86_64-linux-gnu.tar.bz2

NB: Upon compiling Chaste with gcc4.7 I got a compiler error, and a suggested fix, in the following file: $CHASTE_LIBS/xsd-3.3.0-i686-linux-gnu/libxsd/xsd/cxx/zc-istream.txx So simply change line 35 of zc-istream.txx to read

this->setg(

instead of

setg(

XERCES

For fedora machines try the following line

sudo yum install xerces-c xerces-c-devel

For machines without a system Xerces package:

wget http://www.eu.apache.org/dist/xerces/c/3/sources/xerces-c-3.1.1.tar.gz
tar -zxf xerces-c-3.1.1.tar.gz
cd xerces-c-3.1.1/
export XERCESCROOT=`pwd`
./configure --prefix=$CHASTE_LIBS
make
make all
cd $CHASTE_LIBS
rm -rf xerces-c-3.1.1 xerces-c-3.1.1.tar.gz

For PyCml

Python package installs are generally smoothest using pip. Either install as a system package, e.g. sudo yum install python-pip, or follow the instructions here. Unfortunately some of Amara's dependencies are so old, we need to use easy_install for that. It will probably already be installed, but you can sudo yum install python-setuptools or similar if not.

pip install --user "python-dateutil==1.5"
easy_install --user "Amara==1.2.0.2"
pip install --user "rdflib==2.4.2"
pip install --user lxml

VTK

One of the following commands may well work on your system:

sudo apt-get install libvtk5-dev       #(Ubuntu/Debian)
sudo yum install vtk-devel             #(Fedora/RedHat)

Note that Fedora 20 ships only with VTK 6, which is not supported by Chaste 3.1; you'll need the latest version of Chaste.

(If you get an error saying Error: community-mysql conflicts with 1:mariadb, you might have to remove community-mysql. If you do not have sudo yum remove permission, you might be able to ask the IT support desk to take care of this for you.)

Otherwise, from source:

wget http://www.vtk.org/files/release/5.10/vtk-5.10.1.tar.gz
tar zxf vtk-5.10.1.tar.gz
rm -f vtk-5.10.1.tar.gz
cd VTK5.10.1
ccmake -Wno-dev .

This takes you to an option editor, set BUILD_SHARED_LIBS to 'On', and configure the CMAKE_INSTALL_PREFIX to the path you defined as $CHASTE_LIBS. Press 'c' to configure when done, then 'g' to generate and exit. You may need to "sudo yum install mesa-libGL-devel" (or similar) to get OpenGL headers installed before this point, if you get a configure error stating that these headers have not been found.

make
make install

Setting paths automatically

You probably then want to add $CHASTE_LIBS/bin to your path so you can run scons every time you build Chaste without having to type the full path to this directory. How to do this depends on your shell, but if you are running bash the easiest way is to add it to your .bashrc file, e.g. using

gedit ~/.bashrc

At the end of the file add the line (edited to reflect your setting for $CHASTE_LIBS above):

export PATH=/home/scratch/chaste-libs/bin:$PATH

Save, quit and then re-load .bashrc (or log out and back in again):

source ~/.bashrc

Configuring Chaste

Once you've installed the dependencies as above, you need to get hold of the Chaste code. See GettingStarted for the options to pick here.

Again, machines that use the Ubuntu package are handled automatically - you are ready to go.

Otherwise, you need to get scons configured to build Chaste on your machine, basically to tell it where all the libraries and includes that you installed above are situated.

The configuration ("hostconfig") files you need to look at are in python/hostconfig in the source code. An example file is attached to this wiki page, but you may need to edit it slightly to change installation paths to match those you used. Additional tweaks may be required if you installed different versions of the dependencies to those discussed above. See ChasteGuides/HostconfigSystem for full details of what can go into the hostconfig file to configure the scons build system.

Once you've done this, you are ready to build and run the test suite, see ChasteGuides/RunningFirstTests.