= NMatrix

http://sciruby.com

* {Project homepage: sciruby.com}[http://sciruby.com]
* {SciRuby on Google+}[https://plus.google.com/109304769076178160953/posts]
* {Installation guide}[http://sciruby.com/docs#installation]

== Description

NMatrix is an experimental linear algebra library for Ruby, written mostly in C and C++. It can be used with or without
SciRuby, but is part of the SciRuby project.

NMatrix was inspired by and based heavily upon {NArray}[http://narray.rubyforge.org], by Masahiro Tanaka.

{<img src=https://www.pledgie.com/campaigns/15783.png?skin_name=chrome>}[http://www.pledgie.com/campaigns/15783]

=== 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}[https://github.com/SciRuby/rb-gsl].

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

== SYNOPSIS:

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.

You can typically get the developer's build using 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}[http://github.com/marcandre/packable] 1.3.5 (used for I/O)

== INSTALLATION:

See Synopsis (above) for now. Gem coming later.

More detailed installation instructions are available at {here}[http://sciruby.com/docs#installation]

== DEVELOPERS:

Code in the master branch of SciRuby/nmatrix on github should compile and link, but is not necessarily stable. You might
also check out the dev branch if master hasn't been updated in some time.

    git clone https://github.com/mohawkjohn/nmatrix.git

Before commiting any code, you *MUST* read our
{Contributor Agreement}[http://github.com/SciRuby/sciruby/wiki/Contributor-Agreement].

== LICENSE:

Copyright (c) 2012--13, The Ruby Science Foundation.

All rights reserved.

NMatrix, along with SciRuby, is licensed under the BSD 2-clause license. See
{LICENSE.txt}[https://github.com/SciRuby/sciruby/wiki/License] for details.

== DONATIONS:

Support a SciRuby Fellow:

{<img src=https://www.pledgie.com/campaigns/15783.png?skin_name=chrome>}[http://www.pledgie.com/campaigns/15783]