Mac OS Installation

Mac OS installation is broken up into two categories. The first is for end user installation and the second is for development.

End User Installation

The majority of users will want to simply install the binary distribution of the library. This can be accomplished using pip. If we do not have a binary wheel for your operating system, you must follow the development installation guide.

pip install matrixprofile

Development Installation

Due to our usage of Cython and OpenMP for some modules, you are required to use homebrew’s C compiler gcc. Mac OS decided to drop support for OpenMP requiring manual installation of it. This development installation will walk you through the preferred way to get set up for development.

Install Homebrew

Homebrew is required to install gcc, llvm and openmp. Go to the homebrew website and install homebrew. In most cases it will automatically prompt you to install XCode Command Line Tools. If it does not, please install it.

Install Anaconda

Anaconda has become the defacto Python distribution for scientific computing and is highly recommended. You may use a base installation of Python without it, but this document does not cover that use case.

Download the command line installer of Anaconda from the Anaconda website.

Open a terminal and execute the installer. If you are using the latest Mac OS (as of December 2019) Catalina, Anaconda does not automatically create a ZSH entry (the default shell). However, it does create an entry in your .bash_profile. To always load Anaconda environment when you launch a shell, run the following in a terminal:

Note that all commands assume you installed Anaconda in your home directory.

source ~/.bash_profile
conda init zsh

Conda will now load the (base) environment when you launch a terminal.

Install C Libraries

In this section you will install llvm, libomp and gcc via homebrew.

brew install llvm libomp gcc

Once this is finished we need to create a symlink to the gcc version installed. This way it will be found when Cython tries to compile the Cython modules. Note that you should change {version} to the version of gcc that you installed.

ln -s /usr/local/bin/gcc-{version} /usr/local/bin/gcc

We also need to add some entries to our .zshrc file so that openmp can be found. Copy and paste the following lines into your ~/.zshrc file.

export PATH="/usr/local/opt/llvm/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/llvm/lib"
export CPPFLAGS="-I/usr/local/opt/llvm/include"

Once this is complete, we can keep using the same terminal by simply sourcing the .zshrc file.

source ~/.zshrc

To verify that openmp is working properly with gcc, we can create a simple C application. Create a file named “omptest.c” with the following code:

#include <stdlib.h>
#include <stdio.h>
#include <omp.h>

int main() {
  #pragma omp parallel num_threads(4)
  {
    printf("Hello from thread %d, nthreads %d\n", omp_get_thread_num(), omp_get_num_threads());
  }
  return EXIT_SUCCESS;
}

Now we can compile and run the application.

gcc -fopenmp omptest.c -o omptest
./omptest

Install matrixprofile for Development

Finally, we can clone the matrixprofile source code and install it in development mode. If you wish, you may create a new Anaconda environment for this. Please refer to the Anaconda documentation to create a conda environment.

When I clone source code, I tend to favor putting all source files in a “src” directory within my home directory. Please substitute to suite your development preferences.

mkdir ~/src
cd ~/src
git clone https://github.com/matrix-profile-foundation/matrixprofile.git
cd matrixprofile

# for python 3.x
pip install -r requirements.txt

# for python 2.x
pip install -r python2-requirements.txt

pip install -e .

Once the installation completes, you can try running the tests to verify everything is OK.

pytest tests/

Please refer to our contribution guidelines for details on what we expect. Happy coding!