Installation

Shekhar Prasad Rajak edited this page Jan 30, 2017 · 31 revisions

NOTE: These instructions are for nmatrix 0.2.0 and later. For 0.1.0 and earlier releases, see the previous version of these instructions.

Standard installation procedure

This section covers the standard installation procedure. The rest of the document contains operating system specific information about prerequisites that must be installed before the standard installation.

To install the gem:

gem install nmatrix

The plugin gems nmatrix-lapacke and nmatrix-atlas can be installed similarly.

For developers:

Run:

git clone https://github.com/SciRuby/nmatrix.git
cd nmatrix/
gem install bundler
bundle install
bundle exec rake compile
bundle exec rake spec

(For a parallel build you can run MAKE='make -j4' bundle exec rake compile.) Then, if you want to try out the code without installing:

bundle exec rake pry

or if you want to install:

bundle exec rake install

The plugins nmatrix-lapacke and nmatrix-atlas can be built/installed/tested by running rake with the nmatrix_plugins=X option, e.g. rake compile nmatrix_plugins=all, rake install nmatrix_plugins=atlas, rake clean nmatrix_plugins=atlas,lapacke. Each of these commands apply to the nmatrix gem and any additional plugin gems specified. For example, rake spec nmatrix_plugins=atlas will test both the core nmatrix gem and the nmatrix-atlas gem.

Linux

Ubuntu/Debian

If you only want to install the main nmatrix gem you can skip directly to the standard installation procedure. If you want to install the nmatrix-atlas and/or nmatrix-lapacke gems, continue reading. These gems depend on external libraries which you must install before installing the gems.

For nmatrix-atlas, you must install the ATLAS library. The easiest way to do this is to use the version in the repository:

sudo apt-get install libatlas-base-dev

and then use the update-alternatives command to set ATLAS as your default provider of liblapack.so and libblas.so libraries:

sudo update-alternatives --set liblapack.so.3 /usr/lib/atlas-base/atlas/liblapack.so.3
sudo update-alternatives --set liblapack.so /usr/lib/atlas-base/atlas/liblapack.so
sudo update-alternatives --set libblas.so.3 /usr/lib/atlas-base/atlas/libblas.so.3
sudo update-alternatives --set libblas.so /usr/lib/atlas-base/atlas/libblas.so

This step prevents any other versions of LAPACK you might have installed from interfering with ATLAS. (On older Ubuntu versions (12.04), you should replace liblapack.so.3 with liblapack.so.3gf and libblas.so.3 with libblas.so.3gf.) After this you should be able to build nmatrix-atlas (and also nmatrix-lapacke).

nmatrix-lapacke is designed to work with any implementation of LAPACK and BLAS, rather than just working with ATLAS. If you limit yourself to packages in the repositories you have three choices: ATLAS (see above), the reference implementations of LAPACK and BLAS (sudo apt-get install liblapack-dev) and OpenBLAS (sudo apt-get install libopenblas-dev, doesn't work in Ubuntu <14.10). As above, you must use the update-alternatives command to select the correct variety of LAPACK and BLAS, before you attempt to install. The switch_lapack_ubuntu.rb script is designed to help with this (but has only been tested on Ubuntu 15.04).

Which flavor of LAPACK should you use? The reference implementation will be the slowest by far, but it is most likely to be already installed on your system as many other programs depend on it. ATLAS and OpenBLAS will be faster, and even faster if you build them from source. The OpenBLAS package in the repository (Ubuntu 15.04) is built with multi-threading enabled, while the ATLAS package is not, so this could make a big difference on multi-core machines.

It also should be possible to build nmatrix-lapacke with the Intel MKL (non-free, not available in repositories), but this is not officially supported. This might be helpful.

Archlinux

If you want to install the nmatrix-atlas gem, you should install the atlas-lapack package from AUR. If you use yaourt:

yaourt atlas-lapack

Or you can get the tarfile from [https://aur.archlinux.org/packages/atlas-lapack/ (https://aur.archlinux.org/packages/atlas-lapack/) and install it manually (untar it, makepkg, sudo pacman -U pkg.tar.xz).

A few notices

Installing atlas-lapack will require removing the packages blas, cblas and lapack, because they are integrated into atlas-lapack.

Mac OS X

You will need to install the Command Line Tools and Homebrew.

The one tricky step is that you will need a recent version of gcc. One easy way to install this is thru homebrew-versions (note that nmatrix doesn't yet support gcc >=5.0):

brew tap homebrew/versions
brew install gcc48

gcc will now be available at /usr/local/bin/gcc-4.8 and /usr/local/bin/g++-4.8. nmatrix will automatically detect these versions of gcc. If this newly installed version(gcc-4.8) is not detected, means you haven't added this line in your .bash_profile :

export PATH=/usr/local/bin:$PATH$

Add it in your .bash_profile and then run $ source .bash_profile. Another way is running this command in your terminal :


$ cd usr/local/bin 
$ rm gcc # remove if present
$ ln -s gcc-4.8 gcc
$ gcc -v # this will show your 4.8 version

so now you can proceed with the standard installation procedure.

OS X comes pre-installed with liblapack.dylib and libblas.dylib, so you should be able to install the nmatrix-lapacke with no extra work.

Installing ATLAS

The version of ATLAS provided by Apple doesn't include CLAPACK, which means that many useful features will be missing from the nmatrix-atlas gem. For this is reason it is recommended to use nmatrix-lapacke instead of nmatrix-atlas. However if you really want to use nmatrix-atlas, here is one way to set up ATLAS:

First you will need an older version of XCode (5.1.1 or lower), available for download here. This is because newer version of XCode don't include ATLAS.

Then you will need to set up a few symlinks for the relevant files

sudo ln -s /System/Library/Frameworks/Accelerate.framework/Versions/Current/Frameworks/vecLib.framework/Versions/Current/Headers/cblas.h /usr/include/cblas.h
sudo ln -s /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.8.sdk/usr/lib/libatlas.dylib /usr/lib/libatlas.dylib

After this it should be possible to build nmatrix-atlas

Notes

  • There is a bug with backports 3.6.0 and Ruby 2.1.x -- inclose': Bad file descriptor @ fptr_finalize. The fix is to update the gem to 3.6.3+ viabundle update backports`.