Project

nmatrix

0.39
No release in over 3 years
Low commit activity in last 3 years
NMatrix is a linear algebra library for Ruby, written mostly in C and C++.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies

Development

~> 1.6
~> 0.10
~> 10.3
>= 4.0.1, ~> 4.0
~> 2.14

Runtime

>= 1.3.5, ~> 1.3
 Project Readme

NMatrix¶ ↑

Join the chat at https://gitter.im/SciRuby/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++ (and with experimental JRuby support). It is part of the SciRuby project.

NMatrix was inspired by NArray, by Masahiro Tanaka.

Several gems are provided in this repository:

  • nmatrix

  • nmatrix-java

  • nmatrix-atlas

  • nmatrix-lapacke

  • nmatrix-fftw

Installation¶ ↑

To install the latest stable version:

gem install nmatrix

NMatrix was originally written in C/C++, but an experimental JRuby version is also included (see instructions below for JRuby). For the MRI (C/C++) version, you need:

  • Ruby 2.0 or later

  • a compiler supporting C++11 (clang or GCC)

To install the nmatrix-atlas or nmatrix-lapacke extensions, 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¶ ↑

ATLAS and LAPACKE¶ ↑

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.

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¶ ↑

Copyright © 2012–17, 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: