= NMatrix Fast Numerical Linear Algebra Library for Ruby * {sciruby.com}[http://sciruby.com] * {Google+}[https://plus.google.com/109304769076178160953/posts] * {Installation guide}[http://sciruby.com/docs#installation] == 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}[http://narray.rubyforge.org], by Masahiro Tanaka. == Installation To install the latest stable version: gem install nmatrix However, you will need to install {ATLAS}[http://math-atlas.sourceforge.net/] with CBLAS (C interface to {BLAS}[http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms]) first. Those directions can be found {here}[https://github.com/SciRuby/nmatrix/wiki/Installation]. The requirements for NMatrix are: * ATLAS * LAPACK, probably * a version of GCC or clang which supports C++0x or C++11 * Ruby 1.9+ * {packable}[http://github.com/marcandre/packable] 1.3.5 (used for I/O) If you want to obtain the latest (development)code, you should do: git clone https://github.com/SciRuby/nmatrix.git cd nmatrix/ rake compile rake repackage gem install pkg/nmatrix-0.0.5.gem If you get errors about clapack.h or cblas.h, determine 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. == Documentation Carlos Agarie (@agarie) is currently working to improve the documentation. The best way to get help is by posting {issues}[https://github.com/SciRuby/nmatrix/issues] or sending e-mails to our {mailing list}[https://groups.google.com/forum/?fromgroups#!forum/sciruby-dev]. 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}[http://sciruby.com/nmatrix/docs/]. == 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] ] => # >> 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}[https://github.com/SciRuby/nmatrix/wiki/How-to-create-a-NMatrix]. Again, you can find the complete API documentation {on our website}[http://sciruby.com/nmatrix/docs/]. == 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.4): * Matrix and vector 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), 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) * 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](http://github.com/SciRuby/rb-gsl)) === 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) * exponentials and square roots * matrix inversions (LAPACK-free) * matrix decomposition/factorization * calculation of additional 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) === 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]. You can find the most recent version in {the work branch of Masaomi's fork}[https://github.com/masaomi/rb-gsl/tree/work] (not currently compiling as of this writing). == License Copyright (c) 2010--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: {}[http://www.pledgie.com/campaigns/15783]