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