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.

NMatrix was inspired by NArray, by Masahiro Tanaka.

Installation¶ ↑

To install the latest stable version:

gem install nmatrix

However, you will need to install ATLAS with CBLAS (C interface to BLAS) first. Detailed directions can be found here. The requirements for NMatrix are:

ATLAS
LAPACK, probably (see here for details)
a version of GCC or clang which supports C++0x or C++11
Ruby 1.9+
packable 1.3.5 (used for I/O)

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

git clone https://github.com/SciRuby/nmatrix.git
cd nmatrix/
bundle install
bundle exec rake compile
bundle exec rake repackage
gem install pkg/nmatrix-0.0.9.gem

Detailed instructions are available for Mac and Linux.

Documentation¶ ↑

Carlos Agarie (@agarie) is currently working to improve the documentation. The best way to get help is by posting issues or sending e-mails to our mailing list. You may also email @agarie, or look for ‘agarie` on #sciruby at chat.freenode.net if you want to ask questions or offer suggestions.

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], :int64).pp
  [0, 1, 2]
  [3, 4, 5]
=> nil

Create a new NMatrix using the N shortcut:

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

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.

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

Matrix and vector storage containers: dense, yale, list (more to come)
Data types: byte (uint8), int8, int16, int32, int64, float32, float64, complex64, complex128, rational64, rational128, 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
C and C++ API
BLAS internal implementations (no library) and ATLAS (with library) access:
- Level 1: xROT, xROTG (BLAS dtypes only), xASUM, xNRM2
- Level 2: xGEMV
- Level 3: xGEMM, xTRSM
LAPACK ATLAS access:
- xGETRF, xGETRI, xGETRS, xGESV (Gaussian elimination)
- xPOTRF, xPOTRI, xPOTRS, xPOSV (Cholesky factorization)
- xLASWP, xSCAL, xLAUUM
LAPACK-less internal implementations (no LAPACK needed and working on non-BLAS dtypes):
- xGETRF
- xLASWP, xSCAL
- xLAUUM (no LAPACK needed, but BLAS dtypes only)
LAPACK (non-ATLAS) access:
- xGESVD, xGESDD (singular value decomposition)
- xGEEV (eigenvalue decomposition of a asymmetric square matrices)
LU decomposition
Matrix inversions (requires LAPACK; BLAS dtypes only)
Determinant calculation for BLAS dtypes
Vector 2-norms
Ruby/GSL interoperability (requires [SciRuby’s fork of rb-gsl](github.com/SciRuby/rb-gsl))

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

We are nearly the release of NMatrix 0.1.0, our first beta.

These are features planned for NMatrix 0.2.0:

slice assignments (‘x = some_other_matrix`)
LAPACK-free calculation of determinant, trace, and eigenvalues (characteristic polynomial)
LAPACK-free matrix inversions
tensor products
principal component analysis (PCA)
improved file I/O
- compression of yale symmetries in I/O
optimization of non-BLAS data types on BLAS-like operations (e.g., matrix multiplication for rational numbers)

Warning¶ ↑

Please be aware that SciRuby and NMatrix are alpha status. If you’re thinking of using SciRuby/NMatrix to write mission-critical code, such as for driving a car or flying a space shuttle, you may wish to choose other software for now.

You should also be aware that NMatrix and NArray are incompatible with one another; you should not try to require both at the same time. Unfortunately, that causes problems with Ruby/GSL, which currently depends upon NArray. As such, we have a fork of Ruby/GSL.

License¶ ↑

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

Donations¶ ↑

Support a SciRuby Fellow:

jeffhsu3 / nmatrix