NMatrix¶ ↑

Fast Numerical Linear Algebra Library for Ruby

Description¶ ↑

NMatrix is a fast numerical linear algebra library for Ruby, with dense and sparse matrices, written mostly in C and C++. It is part of the SciRuby project.

Three gems are provided in this repository. The nmatrix gem provides all core matrix functionality, and requires minimal external dependencies, making it easy to install. The nmatrix-atlas and nmatrix-lapacke gems are optional extensions of the main nmatrix gem that rely on external linear algebra libraries to provide advanced features for dense matrices (singular value decomposition, eigenvalue/eigenvector finding, Cholesky factorization), as well as providing faster implementations of common operations like multiplication, inverses, and determinants. nmatrix-atlas requires the ATLAS library, while nmatrix-lapacke is designed to work with various LAPACK implementations (including ATLAS). The nmatrix-atlas and nmatrix-lapacke gems both provide similar interfaces for using these advanced features.

NMatrix was inspired by NArray, by Masahiro Tanaka.

Installation¶ ↑

To install the latest stable version:

gem install nmatrix

The requirements for NMatrix are:

GCC 4.3 or later (clang support is experimental)
Ruby 1.9.3 or later

To install nmatrix-atlas or nmatrix-lapacke, an additional requirement is a compatible LAPACK library. Detailed directions for this step can be found here.

If you want to obtain the latest (development) code, you should generally do:

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

If you want to try out the code without installing:

bundle exec rake pry

To install:

bundle exec rake install

JRuby¶ ↑

First, you need to download Apache Commons Math 3.6.1 (the JAR, which you can find in the binary package). For example, in the NMatrix directory, do:

wget https://www.apache.org/dist/commons/math/binaries/commons-math3-3.6.1-bin.tar.gz
tar zxvf commons-math3-3.6.1-bin.tar.gz
mkdir ext/nmatrix_java/vendor/
cp commons-math3-3.6.1/commons-math3-3.6.1.jar ext/nmatrix_java/vendor/

Next, create build directories:

mkdir -p ext/nmatrix_java/build/class
mkdir ext/nmatrix_java/target

Finally, compile and package as jar.

rake jruby

Plugins¶ ↑

The commands above build and install only the core nmatrix gem. If you want to build one or more of the plugin gems (nmatrix-atlas, nmatrix-lapacke) in addition to the core nmatrix gem, use the nmatrix_plugins= 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.

Upgrading from NMatrix 0.1.0¶ ↑

If your code requires features provided by ATLAS (Cholesky decomposition, singular value decomposition, eigenvalues/eigenvectors, inverses of matrices bigger than 3-by-3), your code now depends on the nmatrix-atlas gem. You will need to add this a dependency of your project and require 'nmatrix/atlas' in addition to require 'nmatrix'. In most cases, no further changes should be necessary, however there have been a few API changes, please check to see if these affect you.

Documentation¶ ↑

If you have a suggestion or want to add documentation for any class or method in NMatrix, please open an issue or send a pull request with the changes.

You can find the complete API documentation on our website.

Examples¶ ↑

Create a new NMatrix from a ruby Array:

>> require 'nmatrix'
>> NMatrix.new([2, 3], [0, 1, 2, 3, 4, 5], dtype: :int64)
=> [
    [0, 1, 2],
    [3, 4, 5]
   ]

Create a new NMatrix using the N shortcut:

>> m = N[ [2, 3, 4], [7, 8, 9] ]
=> [
    [2, 3, 4],
    [7, 8, 9]
   ]
>> m.inspect
=> #<NMatrix:0x007f8e121b6cf8shape:[2,3] dtype:int32 stype:dense>

The above output requires that you have a pretty-print-enabled console such as Pry; otherwise, you’ll see the output given by inspect.

If you want to learn more about how to create a matrix, read the guide in our wiki.

Again, you can find the complete API documentation on our website.

Using advanced features provided by plugins¶ ↑

Certain features (see the documentation) require either the nmatrix-atlas or the nmatrix-lapacke gem to be installed. These can be accessed by using require 'nmatrix/atlas' or require 'nmatrix/lapacke'. If you don’t care which of the two gems is installed, use require 'nmatrix/lapack_plugin', which will require whichever one of the two is available.

Fast fourier transforms can be conducted with the nmatrix-fftw extension, which is an interface to the FFTW C library. Use require 'nmatrix/fftw' for using this plugin.

Plugin Details¶ ↑

FFTW¶ ↑

This is plugin for interfacing with the FFTW library. It has been tested with FFTW 3.3.4.

It works reliably only with 64 bit numbers (or the NMatrix ‘:float64` or `:complex128` data type). See the docs for more details.

NArray Compatibility¶ ↑

When NArray is installed alongside NMatrix, require 'nmatrix' will inadvertently load NArray’s lib/nmatrix.rb file, usually accompanied by the following error:

uninitialized constant NArray (NameError)

To make sure NMatrix is loaded properly in the presence of NArray, use require 'nmatrix/nmatrix' instead of require 'nmatrix' in your code.

Developers¶ ↑

Read the instructions in CONTRIBUTING.md if you want to help NMatrix.

Features¶ ↑

The following features exist in the current version of NMatrix (0.1.0.rc1):

Matrix and vector storage containers: dense, yale, list (more to come)
Data types: byte (uint8), int8, int16, int32, int64, float32, float64, complex64, complex128, Ruby object
Interconversion between storage and data types
Element-wise and right-hand-scalar operations and comparisons for all matrix types
Matrix-matrix multiplication for dense (with and without ATLAS) and yale
Matrix-vector multiplication for dense (with and without ATLAS)
Lots of enumerators (each, each_with_indices, each_row, each_column, each_rank, map, etc.)
Matrix slicing by copy and reference (for dense, yale, and list)
Native reading and writing of dense and yale matrices
- Optional compression for dense matrices with symmetry or triangularity: symmetric, skew, hermitian, upper, lower
Input/output:
- Matlab .MAT v5 file input
- MatrixMarket file input/output
- Harwell-Boeing and Fortran file input
- Point Cloud Library PCD file input
C and C++ API
BLAS internal implementations (no library) and external (with nmatrix-lapack or nmatrix-atlas) access:
- Level 1: xROT, xROTG (BLAS dtypes only), xASUM, xNRM2, IxAMAX, xSCAL
- Level 2: xGEMV
- Level 3: xGEMM, xTRSM
LAPACK access (with nmatrix-lapack or nmatrix-atlas plugin):
- xGETRF, xGETRI, xGETRS, xGESV (Gaussian elimination)
- xPOTRF, xPOTRI, xPOTRS, xPOSV (Cholesky factorization)
- xGESVD, xGESDD (singular value decomposition)
- xGEEV (eigenvalue decomposition of asymmetric square matrices)
LAPACK-less internal implementations (no plugin or LAPACK needed and working on non-BLAS dtypes):
- xGETRF, xGETRS
LU decomposition
Matrix inversions
Determinant calculation for BLAS dtypes
Traces
Ruby/GSL interoperability (requires SciRuby’s fork of rb-gsl)
slice assignments, e.g.,
```
x[1..3,0..4] = some_other_matrix
```

Planned Features (Short-to-Medium Term)¶ ↑

See the issues tracker for a list of planned features or to request new ones.

License¶ ↑

NMatrix, along with SciRuby, is licensed under the BSD 2-clause license. See LICENSE.txt for details.

Donations¶ ↑

Support a SciRuby Fellow:

ShivamNegi/nmatrix