Prototype numeric matrix library for Ruby via SciRuby
C++ C Ruby Shell
Pull request Compare This branch is 1291 commits behind SciRuby:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
ext/nmatrix
lib
scripts
spec
.gitignore
.rspec
CONTRIBUTING.md
Gemfile
Guardfile
History.txt
LICENSE.txt
Manifest.txt
README.rdoc
Rakefile
nmatrix.gemspec

README.rdoc

NMatrix

Fast Numerical Linear Algebra Library for Ruby

Description

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

NMatrix was inspired by and based heavily upon NArray, by Masahiro Tanaka.

INSTALLATION

For full instructions, please see sciruby.com/nmatrix. Generally, you should be able to do

gem install nmatrix

However, you will need to install ATLAS with CBLAS first. Those directions can be found at our website.

NOTE: The above command will not give you 0.0.2, which is not yet complete. To obtain the latest code, you should use the following sequence of commands:

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

If you get errors about clapack.h or cblas.h, figure out where your ATLAS headers are using:

locate clapack.h

If you're a Mac user, we recommend you search for cblas.h instead.

Then, tell your system:

export C_INCLUDE_PATH=/usr/local/atlas/include
export CPLUS_INCLUDE_PATH=/usr/local/atlas/include

Finally, try compiling again.

REQUIREMENTS

  • ATLAS

  • LAPACK, probably

  • GCC 4.3

  • Ruby 1.9

  • packable 1.3.5 (used for I/O)

EXAMPLES

Create a new NMatrix from a ruby array:

>> 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.

We will add more examples here soon. :)

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

  • Matrix storage containers: dense, yale, list (more to come)

  • Data types: uint8, int8, int16, int32, int64, float32, float64, complex64, complex128, rational64, rational128 (incomplete)

  • Conversion between storage and data types (except from-complex, and from-float-to-rational)

  • Element-wise operations and comparisons for dense and yale

  • Matrix-matrix multiplication for dense (using ATLAS) and yale

  • Matrix-vector multiplication for dense (using ATLAS)

  • Dense and list matrix slicing and referencing

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

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

  • LU decomposition

  • Matrix inversions (requires LAPACK; BLAS dtypes only)

  • Determinant calculation for BLAS dtypes

Planned Features (Short-to-Medium Term)

These are features planned for NMatrix 0.1.0, our first beta.

  • calculation of determinant (LAPACK-free), trace, and eigenvalues (characteristic polynomial) (0.1.0)

  • exponentials and square roots

  • matrix inversions (LAPACK-free)

  • matrix decomposition/factorization

  • calculation of norms

  • tensor products

  • principal component analysis (PCA)

  • improved file I/O

    • compression of yale symmetries in I/O

  • operation scheduling

  • parallelization of some types of operations

  • optimization of non-BLAS data types on BLAS-like operations (e.g., matrix multiplication for rational numbers)

  • Ruby/GSL interoperability

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 are working on a patch for Ruby/GSL.

LICENSE

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