1. What you need.

  a) MaKL and Libu from KoanLogic. These are freely available. See
     http://koanlogic.com/makl and
     http://koanlogic.com/libu for further details.

  b) MPI is required to run in parallel, although we provide a
     simple replacement MPI if you want to make progress without it
     (serial only!).

  c) A simulation! FFS is a 'meta' method - it does nothing by itself.
     We provide some simple examples.

2. Install MaKL

   You can fetch this via

     $ git clone http://github.com/koanlogic/makl.git

   or download and build via

     $ wget http://koanlogic.com/download/makl/makl-1.9.0.tar.gz
     $ tar zvf makl-1.9.0.tar.gz
     $ cd makl-1.9.0
     $ sh configure.sh --prefix=/install/path/makl
     $ make install

   Please see the MaKL INSTALL file for further details. Note that
   /install/path/makl may need to be distinct from `pwd` on some
   platforms.

   Remember to add the appropriate bin directory to your PATH, e.g.,
   if you specified --prefix=/install/path/makl then
     $ export PATH=$PATH:/install/path/makl/bin

3. Install Libu

   Likewise, Libu can be obtained via

     $ git clone https://github.com/koanlogic/libu.git
   or
     $ wget http://koanlogic.com/download/libu/libu-2.2.0.tar.gz

   Please follow the instructions in the Libu README to install. It is
   acceptable to take the default options for the Libu build process
   at this point. The following may suffice in the top-level directory
   for libu:

     $ makl-conf --prefix=/install/path/libu
     $ makl
     $ makl -C test
     $ makl install

   See also troubleshooting section below if there are problems.

4. FFS

   In the top level FFS directory, configure via

     $ makl-conf --u-path=/install/path/libu
     $ makl

   This will automatically build the library. To run the tests

     $ makl -C test

   See also troubleshooting section below if there are problems.

5. FFS with LAMMPS

   If there is a LAMMPS library available in directory /install/path/lammps
   you can specify at the configure stage

     $ makl-conf  --u-path=/install/path/libu \
                  --lammps-path=/install/path/lammps

   in which case /install/path/lammps/include holds the LAMMPS library.h
   header file, and /install/path/lammps/lib holds the static library
   liblmp.a

   (Note that LAMMPS usually builds the library in its src directory; you
    will have to move it.)

   If LAMMPS requires FFTW, then FFS also needs to know where to find
   the FFTW library, in which case specify


     $ makl-conf  --u-path=/install/path/libu \
                  --fftw-path=/install/path/fftw \
                  --lammps-path=/install/path/lammps

   The configure script will check that these libraries are available.
   Failures at the configure stage can be investigated via makl-conf --verbose

   If you have doxygen installed, you can compile the documentation by
   adding a --docs flag.

Troubelshooting

1. Problems during configuration and compilation can occur. Use

     $ makl-conf --verbose

   to help to identify what is actually happening. Extremely verbose
   output to be compilation stage can be obtained with, e.g.,

     $ makl -d

   Makl uses a "toolchain" to find relevant compilers and so forth.
   If the defaults do not work, it is necessary to define a separate
   toolchain. This may be done via a .tc (some examples are given in
   the ./tc sub-directory).

   To update the toolchain settings using the file e.g., ./tc/darwin-mpi.tc
   (which is appropriate for mpicc on a Mac) use

     $ makl-tc --makl-etc=`pwd`/makl-etc/darwin-mpi \
               --makl-tc-file=./tc/darwin-mpi.tc \
               --makl-shlib=null

   where `pwd`/makl-etc/darwin-mpi is the destination directory for
   the resulting .mk and .cf files.

     $ export MAKL_ETC=`pwd`/makl-etc/darwin-mpi

   to allow makl to locate these files.

2. It may be necessary to create separate toolchains for compiling in serial
   and parallel, e.g. through issuing another command like 

     $ makl-tc --makl-etc=`pwd`/makl-etc/darwin-gcc \
               --makl-tc-file=./tc/darwin-gcc.tc \
               --makl-shlib=null

   This allows to compile e.g. Libu in serial and LAMMPS in parallel.

   Note that for each compilation step you will have to export the environmental
   variable MAKL_ETC anew.