EQcorrscan installation
=======================
EQcorrscan is a Python package with C extensions. The C extensions in EQcorrscan
have their own dependencies on compiled libraries. We heavily recommend installing
EQcorrscan using conda because this will:
* make your life easier;
* separate your EQcorrscan install from your system Python, meaning you can
experiment to your hearts-content without breaking your operating system (yay);
* ensure that compiled modules are compiled using the correct C-compiler against
the correct libraries
If you do not have either a miniconda or anaconda installation you can follow
the |conda-install| instructions.
If you do not already have a conda environment we recommend creating one
with the following:
.. code-block:: bash
conda create -n eqcorrscan -c conda-forge eqcorrscan
source activate eqcorrscan
This will create an environment called eqcorrscan and install eqcorrscan and its
dependancies in that environment.
If you already have a conda environment that you want to use then to install EQcorrscan
you can simply run:
.. code-block:: bash
conda install -c conda-forge eqcorrscan
Installation without conda
--------------------------
Installing EQcorrscan without conda involves two steps:
1. Installing fftw3 libraries;
2. Installing python dependancies and EQcorrscan.
How you undertake the first step depends on your operating system and system
package manager.
Non-Python dependencies--Ubuntu:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Prior to installing the python routines you will need to install the fftw
library. On linux use apt (or your default package manager - note you may need
sudo access):
.. code-block:: bash
apt-get install libfftw3-dev
Note that you will need to ensure you have the single-precision libraries of
fftw3 (files named fftw3f...). On CentOS you can install the `fftw-libs` package.
Non-Python dependencies--OSX:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For MacOS/OS-X systems we have tested using homebrew and macports (fink options
are available, but we haven't tested them).
Homebrew
........
You will need a recent version of gcc (the homebrew gcc-4.9 port has issues with openMP).
We have tested the following and found it to work (note that you may need to prepend
sudo depending on your configuration):
.. code-block:: bash
brew install gcc6
brew install fftw
Then run the following to install EQcorrscan (note the need to select CC=gcc, you can
install using clang, but you will need additional libraries for openmp support):
.. code-block:: bash
CC=gcc pip install eqcorrscan
MacPorts
........
The following has been tested and found to work (note that you may need to prepend
sudo depending on your configuration):
1. Install an up-to-date gcc (gcc is needed for openmp compatibility) - any gcc should work (>4), here we use gcc6 for example:
.. code-block:: bash
port install gcc6
2. Install python from macports (tested for python35, but its up to you)
.. code-block:: bash
port install python35`
# optional: select python35 as default python for terminal:
port select --set python python35
3. Install numpy and pip from macports:
.. code-block:: bash
port install py35-numpy py35-pip
# optional, select pip35 as default pip
port select --set pip pip35
4. Install fftw3 from source:
a. |fftw-3.3.7| - link to fftw 3.3.7, most recent as of 10/01/2018
b. unzip/untar
c. Run the following from within the expanded directory:
.. code-block:: bash
./configure --enable-threads --enable-float && make
make install
./configure --enable-threads && make # Need both double and float precision files
make install
5. Run: (if you didn't run the `port select --set pip pip35` command you will need to replace `pip` with `pip35`)
.. code-block:: bash
CC=gcc pip install eqcorrscan
Non-Python dependencies--Windows:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For Windows systems you should follow the instructions on the |fftw-windows|
page and use the pre-compiled dynamic libraries. These should be installed
somewhere on your system path, or the install location added to your path.
The correlation routines use openMP for parallel workflows, however, some aspects
of this run into issues with version of MSVC < 10.0 (due to old C standards being
used), as such, by default, the correlation routines are compiled as serial
workflows on windows. If you have a need for this threading in windows please
get in touch with the developers.
EQcorrscan install via pip:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once you have installed fftw the EQcorrscan install should be as simple as:
.. code-block:: bash
pip install eqcorrscan
.. |conda-install| raw:: html
conda-install
.. |fftw-install| raw:: html
fftw installation
.. |fftw-3.3.7| raw:: html
Download
.. |fftw-windows| raw:: html
fftw-windows install
Installation from source
~~~~~~~~~~~~~~~~~~~~~~~~
pip pulls the package from the |pypi| package repository and runs the `setup.py` file.
If instead you wish to install from source, download the package (either by cloning
the git repository, or by downloading the source code) from |eqcorrscan-github|,
change directory to the `EQcorrscan` directory and run:
.. code-block:: bash
python setup.py install
If this fails because the default compiler is `clang` you can run:
.. code-block:: bash
CC=gcc python setup.py install
Note though that this will compile EQcorrscan using a different compiler than
used to build your Python, which may have unwanted effects, if you do this you
MUST test you install using the instructions here: :ref:`RunningTests`.
.. |pypi| raw:: html
PyPi
.. |eqcorrscan-github| raw:: html
github
Using Intel's MKL
~~~~~~~~~~~~~~~~~
For versions >= 0.3.0 EQcorrscan supports compilation against the Intel Math Kernel
Libraries (MKL). This has shown |speed-ups| compared to the standard FFTW library.
To enable this you must install MKL before compiling EQcorrscan. MKL is available from
most package managers (including conda). Once you have MKL installed you can
follow the `Installation from source`_ section. Check that near the top of the
install that the MKL libraries are found.
Notes
-----
You may have issues with these installs if you don't have numpy installed: but if
you don't have numpy installed then you have bigger issues...
If you plan to generate a grid of synthetic templates you will need to have
grid csv files, which the authors have previously used NonLinLoc to generate.
This is not provided here and should be sourced from |NLLoc_link|. This will provide
the Grid2Time routine which is required to set-up a lag-time grid for your
velocity model. You should read the NonLinLoc documentation for more
information regarding how this process works and the input files you are
required to give.
.. |NLLoc_link| raw:: html
NonLinLoc
.. |speed-ups| raw:: html
speed ups