modules
=======

Andy Nowacki
a.nowacki@leeds.ac.uk

About
-----
http://github.com/anowacki/seismo-fortran

This repo contains Fortran modules which I have adapted or written for use in
my geophysics work, primarily dealing with seismic anisotropy.

Many command line utility programs wrap the functionality in these modules for
use in scripting and quick processing of data.


Installation
------------
A Fortran and C compiler are needed.

The modules can be statically compiled directly into your own code like this:

    $ $FC -o program module.f90 program.f90

Typing `make' in the root directory builds the modules as shared and static
libraries.  Edit the Makefile to reflect the compiler and options you need.

On OS X, nothing more is needed to use the dynamic libraries; just link to them
as normal with -L and -l options.  The absolute path to the shared libraries is
written into the programs on linking.

On Linux, you will need to export LD_LIBRARY_PATH to include the `lib` directory
like so:

    $ export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${path_to_seismo-fortran}/lib"

I use these modules on various flavours of Linux and OS X without trouble,
but portability issues are always possible.  Any reports of how to make them
work on unusual distributions are welcome.


Requirements
------------
The codes rely on a some freely-available libraries:
    - FFTW (http://www.fftw.org/), including the single-precision version.
      This can be installed, e.g., using MacPorts.  (If using this, make
      sure to install the variant relevant for the compilers you are using.)
      Edit the Makefile to reflect where the libraries are installed.
    - LAPACK.  This often comes supplied as a vendor-optimised library; by
      default these codes use the Accelerate framework provided by OS X, but
      update the Makefile if this is not available.


Site specific notices
---------------------
The code has been developed using gfortran/gcc on Mac OS X, so some idiosyncracies
of this platform may have crept in, though I've tried to make everything as
portable as possible.  Current portability issues are as follows:

. plate_motion.f90:  This won't compile with the Cray compilers, complaining about
        the declaration of type parameters.  I don't know if this is a bug in
        the compiler, or a violation of the standard.  A workaround is to simply
        to not build this module if you don't need it.
. On ARCHER, when running any programs on the head node, you will see when using
        the Cray compilers:
            LIBDMAPP WARNING: Unable to open kgni version file 
            /sys/class/gemini/kgni0/version errno 2
        This is because the Cray communication libraries have been linked in but
        are not accessible to serial programs on the head nodes.  You can silence
        this (harmless) warning by compiling with
            -target=local_host
        (From: https://bluewaters.ncsa.illinois.edu/faq)


Acknowledgements
----------------
The module anisotropy_ajn has benefited hugely from David Mainprice's
expectionally clear articles, and from James Wookey and Andrew Walker's prowess
with coding.

Some of the code is taken wholly or partly from other sources; see the licences
of the respective packages for more info.  These are:
    - f90sac         (c) James Wookey (f90sac/f90sac.F90)
    - SHTOOLS        (c) Mark Wieczorek (spherical_splines/SHTOOLS/LICENSE)

Individual routines and modules contain references where appropriate to
publications relevant.


Notice about EmatrixUtils
-------------------------
The repo contains references to EmatrixUtils, a module which contained routines
written by David Mainprice for his Ematrix CareWare programs
(http://www.gm.univ-montp2.fr/PERSO/mainprice/W_data/CareWare_Unicef_Programs/)
which I have replaced with my own routines.  This means that checking out older
commits may lead to not being able to build some of the modules.  The offending
routine will be CIJ_phasevels(), which has been replaced by CIJ_phase_vels().
'use EmatrixUtils' statements can be replaced by 'use anisotropy_ajn' and
changing the calling convention of the CIJ_phasevels() routine for the new one.


Licence
-------
See the LICENCE file for details.