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:

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

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.

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

Planned Features (Short-to-Medium Term)

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

License

Copyright © 2012–15, John Woods and the Ruby Science Foundation.

All rights reserved.

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

Donations

Support a SciRuby Fellow: