To compile SPLASH v2.x you will need simply:

- A Fortran 90/95/2003 compiler (e.g. gfortran)
- X-Windows
- cairo

(As SPLASH is command-line driven, it is also
 assumed you have a basic knowledge of unix).

The basic steps for installation are:
1) make sure you have a Fortran 90/95 compiler (such as gfortran).
2) make sure you have cairo on your system
3) compile SPLASH/giza and link with cairo.
4) if desired/necessary write a read_data subroutine so that SPLASH can read
   your data format.
5) make pretty pictures.

As a first attempt, with gfortran as your Fortran compiler, just try

"make SYSTEM=gfortran"

and this may "just work". If not, read on...

For troubleshooting of some common installation problems,
 have a look at the online FAQ.
 
1) ---------------- Fortran 9x/2003 compilers ---------------------------

 By now, many Fortran 90/95 compilers exist. In terms of free ones, both Intel
and Sun have non-commercial versions available for Linux.

Gfortran is the free GNU compiler, as of version 4.3.0, can be used to compile SPLASH.
The latest version can be downloaded from:

http://gcc.gnu.org/wiki/GFortran

I strongly recommend downloading a more recent version of gfortran rather than
relying on any pre-installed version (use gfortran -v to check the version number).
In particular versions 4.2.0 and lower *do not* compile SPLASH2. Later versions also
have openMP, so you can compile and run SPLASH in parallel ("make PARALLEL=yes")

2) ----------------- The Cairo Graphics Library --------------------

 Cairo is a low-level system library used in many applications. Thus it is highly
likely that you already have a copy on your system and already in your library path.
Look for the header file cairo.h, e.g. using

"locate cairo.h"

or have a look in the usual places (e.g. /usr/include/cairo, /usr/X11/include). If not,
you can usually use your inbuilt package manager to install cairo as follows:

   Debian/Ubuntu:
      sudo apt-get install libcairo2-dev
   Fedora/Red Hat/CentOS:
      sudo yum install cairo-devel
   OpenSUSE:
      zypper install cairo-devel
   MacPorts:
      sudo port install cairo

Alternatively, use the script provided in the root-level splash directory:

  ./install-cairo.sh

which downloads and installs both pixman and cairo into the giza/ subdirectory.
Unlike the methods above, this does not require any admin/superuser permissions.

3) ----------------- Compiling SPLASH with the GIZA backend  ----------------

Type:

"make SYSTEM=xxx"

Where xxx corresponds to a SYSTEM setting in build/Makefile. These are presets
for most of the common Fortran compilers, the most useful of which are: 

gfortran -- settings for the gfortran/gcc compilers
g95 -- settings for the g95/gcc compilers
nagf95 -- settings for the NAG f95 compiler
sunf95 -- settings for the Sun f95 compiler
ifort -- settings for the Intel Fortran/C Compilers
pgf90 -- settings for the Portland Group Fortran 90 compiler

4) -------------- reading your data format -------------------

The default binaries installed are as follows:

splash  : alias for asplash
asplash : reads ascii formatted data files
gsplash : reads data files from GADGET code (http://www.mpa-garching.mpg.de/galform/gadget/)
dsplash : reads data files from DRAGON code
nsplash : reads data files from NDSPMHD code (http://users.monash.edu.au/~dprice/ndspmhd/)
tsplash : reads TIPSY files (ascii and binary) as used in GASOLINE
rsplash : reads data files from MAGMA code
ssplash : reads data files from sphNG code
srsplash : reads data files from SEREN code
vsplash : reads data files from VINE code

Other formats implemented but not compiled by default include:
h5splash : reads h5part formatted files
bsplash  : old Matthew Bate/Benz code format
(see the userguide for a full list)

The basic "splash" binary is quite general and will read any ascii or csv data file where
columns correspond to different quantities and rows correspond to each particle (actually
I use splash to plot graphs for nearly all data in this form, whether SPH or not)
-- it will also sensibly skip header lines which do not have the same number of columns.

However, it is ultimately desirable to use SPLASH to directly visualise the
(binary) output of your code. If your format is not amongst those distributed,
then BEFORE you start writing your own routine, please consider whether or not a routine
to read your format would be of more general use (e.g. to other users of your code).
If so, PLEASE email me to request a new read_data routine for your format, by sending an email attaching:

a) an example dump 

and

b) the source code from the routine which wrote the dump file.

Then I can write a read for your format that can be added to the SPLASH repository
and distributed in all future versions. Whilst I aim never to change the interface
to the read_data routines, it is not impossible that some changes may occur
somewhere down the line (or enhanced functionality -- for example the more advanced
data reads are able to read only the required columns for a given plot from the
file, rather than the whole file).

If you *really* want to hack one yourself it is best to look at some of the
other examples and change the  necessary parts to suit your data files. Note
that reading directly from unformatted data files is *much* faster than reading
from formatted (ascii) data.

If you do end up writing your own, again, please email me the end result so I
can add it to the officially supported data reads. This also makes it much
easier for you to upgrade to newer versions as you do not require a locally
customised version.

5) ----- running splash/ making pretty pictures

For detailed help on how to use SPLASH, refer to the (quite extensive) userguide
on the splash web page.

Have fun! And remember, if you get stuck you can always email me... 
(it doesn't hurt).

Daniel Price
daniel.price@monash.edu
