nmatrix 0.0.3 → 0.0.4

data/.gitignore

@@ -15,6 +15,9 @@ tmp/
 test.c
 spec/*.mtx
 *.so
+*.bundle
+*.bundle.dSYM
+*.log
 /tags
 *.gem
 

data/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+NMatrix is part of SciRuby, a collaborative effort to bring scientific computation to Ruby. If you want to help, please do so!
+
+This guide covers ways in which you can contribute to the development of SciRuby and, more specifically, NMatrix.
+
+## How to help
+
+There are various ways to help NMatrix: bug reports, coding and documentation. All of them are important.
+
+First, you can help implement new features or bug fixes. To do that, visit our [roadmap](https://github.com/SciRuby/nmatrix/wiki/Roadmap) or our [issue tracker][2]. If you find something that you can tackle, post it in the issue or on our [mailing list][1].
+
+You need to send tests together with your code. No exceptions. You can ask what's our opinion, but we won't accept patches without a good spec coverage.
+
+We use RSpec for testing. If you aren't familiar with it, there's a good [guide to better specs with RSpec](http://betterspecs.org/) that shows a bit of the syntax and how to use it properly. However, the best resource is probably the specs that already exist - so just read them.
+
+And don't forget to write documentation. It's necessary to allow others to know what's available in the library. There's a section on it later in this guide. Ah, we use RDoc.
+
+We only accept bug reports and pull requests in GitHub. You'll need to create a new (free) account if you don't have one already. To learn how to create a pull request, please see the [this guide on collaborating](https://help.github.com/categories/63/articles).
+
+If you have a question about how to use NMatrix or SciRuby in general or a feature/change in mind, please ask the [sciruby-dev mailing list][1].
+
+Thanks!
+
+## Coding
+
+To start helping with the code, you need to have all the dependencies in place:
+
+- ATLAS and LAPACK
+- GCC 4.3+
+- git
+- Ruby 1.9+
+- `bundler` gem
+
+Now, you need to clone the git repository:
+
+    git clone git://github.com/SciRuby/nmatrix.git
+		cd nmatrix
+		bundle install
+		rake compile
+		rake spec
+
+This will install all dependencies, compile the extension and run the specs. 
+
+As of now (12/31/2012), there should be 25 specs failing, in elementwise\_spec, lapack\_spec and math\_spec. If you see more than 25 or from different specs, please report on the [mailing list][1] or on the [issue tracker][2].
+
+If everything's fine until now, you can create a new branch to work on your feature:
+
+    git branch new-feature
+    git checkout new-feature
+
+Before commiting any code, please read our
+[Contributor Agreement](http://github.com/SciRuby/sciruby/wiki/Contributor-Agreement).
+
+## Documentation
+
+There are two ways in which NMatrix is being documented: guides and comments, which are converted with RDoc into the documentation seen in [sciruby.com](http://sciruby.com).
+
+If you want to write a guide on how to use NMatrix to solve some problem or simply showing how to use one of its features, write it as a wiki page and send an e-mail on the [mailing list][1]. We're working to improve this process.
+
+If you aren't familiar with RDoc syntax, [this is the official documentation](http://docs.seattlerb.org/rdoc/RDoc/Markup.html).
+
+## Conclusion
+
+This guide was heavily based on the [Contributing to Ruby on Rails guide](http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html).
+
+[1]: https://groups.google.com/forum/?fromgroups#!forum/sciruby-dev
+[2]: https://github.com/sciruby/nmatrix/issues?sort=created&state=open

data/Gemfile

@@ -1,5 +1,5 @@
 # Gemfile
-source "http://rubygems.org"
+source 'http://rubygems.org'
 gemspec
 
 gem 'packable', ">= 1.3.5"  # for Matlab IO

data/History.txt

@@ -10,19 +10,23 @@
 
   * Second alpha release
 
-  * Rewrote NMatrix in C++0x and C++11 using templates, namespaces; removed Ruby generators and CAST parser
+  * Rewrote NMatrix in C++0x and C++11 using templates, namespaces;
+    removed Ruby generators and CAST parser
 
   * Added preliminary C API
 
-  * Slicing and referencing support for dense and list matrices (by @flipback)
+  * Slicing and referencing support for dense and list matrices (by
+    @flipback)
 
   * BLAS level-3 xTRSM algorithm added for rationals and BLAS types
 
-  * LAPACK support added, including partially working xGETRF subroutine
+  * LAPACK support added, including partially working xGETRF
+    subroutine
 
   * Element-wise comparisons now return byte-matrices
 
-  * Element-wise operations on list matrices may alter the default value of the return matrix
+  * Element-wise operations on list matrices may alter the default
+    value of the return matrix
 
   * Element-wise division behaves like Ruby division
 
@@ -30,7 +34,8 @@
 
   * clang support
 
-  * `==` operator now used for matrix equality, `=~` and `!~` for element-wise comparisons
+  * `==` operator now used for matrix equality, `=~` and `!~` for
+    element-wise comparisons
 
   * Dense `each` returns an Enumerator when called without a block
 
@@ -48,20 +53,73 @@
 
   * Shortcuts for matrix creation (by @agarie)
 
-  * Access to most ATLAS-implemented LAPACK functions for those with ATLAS' CLAPACK interface: xGETRF, xGETRI, xGETRS, xGESV, xPOTRF, xPOTRI, xPOTRS, xPOSV, xLASWP, xSCAL, xLAUUM
+  * Access to most ATLAS-implemented LAPACK functions for those
+    with ATLAS' CLAPACK interface: xGETRF, xGETRI, xGETRS, xGESV,
+    xPOTRF, xPOTRI, xPOTRS, xPOSV, xLASWP, xSCAL, xLAUUM
 
-  * Access to additional ATLAS-implemented BLAS functions: xTRMM, xSYRK, xHERK, xROT, xROTG
+  * Access to additional ATLAS-implemented BLAS functions: xTRMM,
+    xSYRK, xHERK, xROT, xROTG
 
-  * Non-ATLAS versions of CLAPACK functions: xLASWP, xSCAL, xLAUUM, xROT
+  * Non-ATLAS versions of CLAPACK functions: xLASWP, xSCAL, xLAUUM,
+    xROT
 
   * Matrix inversion (LU and Cholesky; requires CLAPACK)
 
   * LU factoring with and without CLAPACK
 
-  * Native matrix I/O for dense (supporting upper, lower, hermitian, skew, symmetric, and general) and yale (general only); excludes Ruby objects currently
+  * Native matrix I/O for dense (supporting upper, lower, hermitian,
+    skew, symmetric, and general) and yale (general only); excludes
+    Ruby objects currently
 
 * 2 bug fixes:
 
   * Yale-to-list casting
 
-  * Now requires packable-1.3.5 or higher, fixing a problem with MATLAB .mat v5 file I/O (specific to doubles)
+  * Now requires packable-1.3.5 or higher, fixing a problem with MATLAB
+    .mat v5 file I/O (specific to doubles)
+
+=== 0.0.4 / 2013-??-??
+
+* 3 major enhancements
+
+  * Added a more user-friendly interface for cblas_rot in the form of
+    NMatrix::BLAS::rot
+
+  * Added to_hash for Yale matrices
+
+  * Improved source code documentation (by @agarie)
+
+* 4 minor enhancements
+
+  * Spec clean-up (by @masaomi)
+
+  * Made it possible to request a different itype internally for Yale
+    matrices
+
+  * Improved space usage of Yale slice-by-copying, which was requesting
+    more space than needed
+
+  * Improved compile-time Mac OS X and Ubuntu library searching
+
+* 8 bug fixes:
+
+  * NMatrix::BLAS::gemv segfaults
+
+  * Fixed Yale matrix slice-by-copy write error where default itypes
+    (which are based on shape) differ, and a separate problem where
+    incorrect IJA and A entries were written.
+
+  * NVector-scalar operations and NVector-NVector element-wise options
+    now return an NVector instead of an NMatrix
+
+  * Addressed problems with segmentation faults during iteration (by
+    @cjfuller)
+
+  * Addressed Ubuntu/Debian installation problems (incompatibility with
+    apt-supplied atlas)
+
+  * Fixed transpose behavior following slice-by-reference (by @cjfuller)
+
+  * Fixed gem install command in Rakefile (by @jpmckinney)
+
+  * Fixed Spanish language compile issue (by @imcsk8 and @agarie)

data/LICENSE.txt

@@ -7,9 +7,9 @@ You *must* read the Contributor Agreement before contributing code to the SciRub
 
 * http://github.com/sciruby/sciruby/wiki/Contributor-Agreement
 
---
+-----
 
-Copyright (c) 2010 - 2011, Ruby Science Foundation
+Copyright (c) 2010 - 2013, Ruby Science Foundation
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

data/Manifest.txt

@@ -2,9 +2,11 @@ History.txt
 Manifest.txt
 README.rdoc
 LICENSE.txt
+CONTRIBUTING.md
 Rakefile
 Gemfile
 Guardfile
+nmatrix.gemspec
 spec/io_spec.rb
 spec/math_spec.rb
 spec/nmatrix_spec.rb

data/README.rdoc

@@ -1,33 +1,93 @@
 = NMatrix
 
-http://sciruby.com
+Fast Numerical Linear Algebra Library for Ruby
 
-* {Project homepage: sciruby.com}[http://sciruby.com]
-* {SciRuby on Google+}[https://plus.google.com/109304769076178160953/posts]
+* {sciruby.com}[http://sciruby.com]
+* {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 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 and based heavily upon {NArray}[http://narray.rubyforge.org], by Masahiro Tanaka.
+NMatrix was inspired by {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]
+== Installation
 
-=== WARNING:
+To install the latest stable version:
 
-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).
+    gem install nmatrix
 
-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].
+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] ]
+    => #<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}[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.2):
+The following features exist in the current version of NMatrix (0.0.4):
 
 * Matrix storage containers: dense, yale, list (more to come)
 * Data types: uint8, int8, int16, int32, int64, float32, float64, complex64, complex128, rational64, rational128
@@ -56,12 +116,13 @@ The following features exist in the current version of NMatrix (0.0.2):
 * LU decomposition
 * Matrix inversions (requires LAPACK; BLAS dtypes only)
 * Determinant calculation for BLAS dtypes
+* 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) (0.1.0)
+* calculation of determinant (LAPACK-free), trace, and eigenvalues (characteristic polynomial)
 * exponentials and square roots
 * matrix inversions (LAPACK-free)
 * matrix decomposition/factorization
@@ -73,70 +134,30 @@ These are features planned for NMatrix 0.1.0, our first beta.
 * 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
+=== Warning
 
-However, you will need to install ATLAS with CBLAS first. Those directions can be found at our website.
+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 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].
+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:
+== License
 
-Copyright (c) 2012--13, The Ruby Science Foundation.
+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:
+== Donations
 
 Support a SciRuby Fellow:
 
-{<img src=https://www.pledgie.com/campaigns/15783.png?skin_name=chrome>}[http://www.pledgie.com/campaigns/15783]
+{<img src=http://pledgie.com/campaigns/15783.png?skin_name=chrome>}[http://www.pledgie.com/campaigns/15783]

data/Rakefile

@@ -26,7 +26,7 @@ Rake::GemPackageTask.new(gemspec).define
 
 desc "install the gem locally"
 task :install => [:package] do
-  sh %{gem install pkg/nmatrix-#{NMatrix::VERSION}}
+  sh %{gem install pkg/nmatrix-#{NMatrix::VERSION}.gem}
 end
 
 require 'rspec/core/rake_task'
@@ -43,7 +43,8 @@ VALGRIND_OPTIONS = [
         "--num-callers=50",
         "--error-limit=no",
         "--partial-loads-ok=yes",
-        "--undef-value-errors=no",
+        "--undef-value-errors=no" #,
+        #"--dsymutil=yes"
 ]
 VALGRIND_MEMORYFILL_OPTIONS = [
         "--freelist-vol=100000000",
@@ -104,17 +105,25 @@ namespace :spec do
 
   desc "Run specs under GDB."
   task :gdb => [ :compile ] do |task|
-          cmd = [ 'gdb' ] + GDB_OPTIONS
-          cmd += [ '--args' ]
-          cmd += RSPEC_CMD
-          run( *cmd )
+    cmd = [ 'gdb' ] + GDB_OPTIONS
+    cmd += [ '--args' ]
+    cmd += RSPEC_CMD
+    run( *cmd )
+  end
+
+  desc "Run specs under cgdb."
+  task :cgdb => [ :compile ] do |task|
+    cmd = [ 'cgdb' ] + GDB_OPTIONS
+    cmd += [ '--args' ]
+    cmd += RSPEC_CMD
+    run( *cmd )
   end
 
   desc "Run specs under Valgrind."
   task :valgrind => [ :compile ] do |task|
-          cmd = [ 'valgrind' ] + VALGRIND_OPTIONS
-          cmd += RSPEC_CMD
-          run( *cmd )
+    cmd = [ 'valgrind' ] + VALGRIND_OPTIONS
+    cmd += RSPEC_CMD
+    run( *cmd )
   end
 end