Fast Numerical Linear Algebra Library for Ruby
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
provides all core matrix functionality, and requires minimal external
dependencies, making it easy to install. The
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-lapacke gems both provide similar interfaces for using
these advanced features.
NMatrix was inspired by NArray, by Masahiro Tanaka.
To install the latest stable version:
gem install nmatrix
The requirements for NMatrix are:
GCC 4.3 or later
Ruby 1.9.3 or later
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
bundle exec rake install
The commands above build and install only the core
gem. If you want to build one or more of the plugin gems
nmatrix-lapacke) in addition to
the core nmatrix gem, use the
nmatrix_plugins= option, e.g.
rake compile nmatrix_plugins=all,
nmatrix_plugins=atlas,lapacke. Each of these commands apply to the
nmatrix gem and any additional plugin gems specified. For
rake spec nmatrix_plugins=atlas will test both the
nmatrix gem and the
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
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.
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.
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
>> 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
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
'nmatrix/lapacke'. If you don't care which of the two
gems is installed, use
'nmatrix/lapack_plugin', which will require whichever one of
the two is available.
NArray Compatibility¶ ↑
When NArray is installed
'nmatrix' will inadvertently load NArray's
lib/nmatrix.rb file, usually accompanied by the following
uninitialized constant NArray (NameError)
To make sure NMatrix is loaded properly in the
presence of NArray, use
require 'nmatrix' in your code.
Read the instructions in
CONTRIBUTING.md if you want to help
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
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):
Determinant calculation for BLAS dtypes
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.
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.
Support a SciRuby Fellow: