2. 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:

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:

conda install -c conda-forge eqcorrscan

2.1. 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.

2.1.1. 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):

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.

2.1.2. 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).

2.1.2.1. 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):

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):

CC=gcc pip install eqcorrscan

2.1.2.2. 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:

port install gcc6
  1. Install python from macports (tested for python35, but its up to you)

port install python35`
# optional: select python35 as default python for terminal:
port select --set python python35
  1. Install numpy and pip from macports:

port install py35-numpy py35-pip
# optional, select pip35 as default pip
port select --set pip pip35
  1. Install fftw3 from source:

    1. Download - link to fftw 3.3.7, most recent as of 10/01/2018

    2. unzip/untar

    3. Run the following from within the expanded directory:

    ./configure --enable-threads --enable-float && make
    make install
    ./configure --enable-threads && make # Need both double and float precision files
    make install
    
  2. Run: (if you didn’t run the port select –set pip pip35 command you will need to replace pip with pip35)

CC=gcc pip install eqcorrscan

2.1.3. Non-Python dependencies–Windows:

For Windows systems you should follow the instructions on the fftw-windows install 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.

2.1.4. EQcorrscan install via pip:

Once you have installed fftw the EQcorrscan install should be as simple as:

pip install eqcorrscan

2.1.5. 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 github, change directory to the EQcorrscan directory and run:

python setup.py install

If this fails because the default compiler is clang you can run:

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: Running tests.

2.1.6. 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.

2.2. 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 NonLinLoc. 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.