nmatrix 0.0.3 → 0.0.4

data/lib/nmatrix/blas.rb

@@ -1,70 +1,196 @@
-module NMatrix::BLAS
+#--
+# = NMatrix
+#
+# A linear algebra library for scientific computation in Ruby.
+# NMatrix is part of SciRuby.
+#
+# NMatrix was originally inspired by and derived from NArray, by
+# Masahiro Tanaka: http://narray.rubyforge.org
+#
+# == Copyright Information
+#
+# SciRuby is Copyright (c) 2010 - 2013, Ruby Science Foundation
+# NMatrix is Copyright (c) 2013, Ruby Science Foundation
+#
+# Please see LICENSE.txt for additional copyright notices.
+#
+# == Contributing
+#
+# By contributing source code to SciRuby, you agree to be bound by
+# our Contributor Agreement:
+#
+# * https://github.com/SciRuby/sciruby/wiki/Contributor-Agreement
+#
+# == blas.rb
+#
+# This file contains the safer accessors for the BLAS functions
+# supported by NMatrix.
+#++
 
+module NMatrix::BLAS
   class << self
-
+    #
+    # call-seq:
+    #     gemm(a, b) -> NMatrix
+    #     gemm(a, b, c) -> NMatrix
+    #     gemm(a, b, c, alpha, beta) -> NMatrix
+    #
+    # Updates the value of C via the matrix multiplication
+    #   C = (alpha * A * B) + (beta * C)
+    # where +alpha+ and +beta+ are scalar values.
+    #
+    # * *Arguments* :
+    #   - +a+ -> Matrix A.
+    #   - +b+ -> Matrix B.
+    #   - +c+ -> Matrix C.
+    #   - +alpha+ -> A scalar value that multiplies A * B.
+    #   - +beta+ -> A scalar value that multiplies C.
+    #   - +transpose_a+ ->
+    #   - +transpose_b+ ->
+    #   - +m+ ->
+    #   - +n+ ->
+    #   - +k+ ->
+    #   - +lda+ ->
+    #   - +ldb+ ->
+    #   - +ldc+ ->
+    # * *Returns* :
+    #   - A NMatrix equal to (alpha * A * B) + (beta * C).
+    # * *Raises* :
+    #   - +ArgumentError+ -> +a+ and +b+ must be dense matrices.
+    #   - +ArgumentError+ -> +c+ must be +nil+ or a dense matrix.
+    #   - +ArgumentError+ -> The dtype of the matrices must be equal.
+    #
     def gemm(a, b, c = nil, alpha = 1.0, beta = 0.0, transpose_a = false, transpose_b = false, m = nil, n = nil, k = nil, lda = nil, ldb = nil, ldc = nil)
-    	raise ArgumentError, 'Expected dense NMatrices as first two arguments.' unless a.is_a?(NMatrix) and b.is_a?(NMatrix) and a.stype == :dense and b.stype == :dense
-    	raise ArgumentError, 'Expected nil or dense NMatrix as third argument.' unless c.nil? or (c.is_a?(NMatrix) and c.stype == :dense)
-    	raise ArgumentError, 'NMatrix dtype mismatch.'													unless a.dtype == b.dtype and (c ? a.dtype == c.dtype : true)
-
-    	# First, set m, n, and k, which depend on whether we're taking the
-    	# transpose of a and b.
-    	if c
-    		m ||= c.shape[0]
-    		n ||= c.shape[1]
-    		k ||= transpose_a ? a.shape[0] : a.shape[1]
-
-    	else
-    		if transpose_a
-    			# Either :transpose or :complex_conjugate.
-    			m ||= a.shape[1]
-    			k ||= a.shape[0]
-
-    		else
-    			# No transpose.
-    			m ||= a.shape[0]
-    			k ||= a.shape[1]
-    		end
-
-    		n ||= transpose_b ? b.shape[0] : b.shape[1]
-    		c		= NMatrix.new([m, n], a.dtype)
-    	end
-
-    	# I think these are independent of whether or not a transpose occurs.
-    	lda ||= a.shape[1]
-    	ldb ||= b.shape[1]
-    	ldc ||= c.shape[1]
-
-    	# NM_COMPLEX64 and NM_COMPLEX128 both require complex alpha and beta.
-    	if a.dtype == :complex64 or a.dtype == :complex128
-    		alpha = Complex(1.0, 0.0) if alpha == 1.0
-    		beta  = Complex(0.0, 0.0) if beta  == 0.0
-    	end
-
-    	# For argument descriptions, see: http://www.netlib.org/blas/dgemm.f
-    	::NMatrix::BLAS.cblas_gemm(:row, transpose_a, transpose_b, m, n, k, alpha, a, lda, b, ldb, beta, c, ldc)
-
-    	return c
+      raise ArgumentError, 'Expected dense NMatrices as first two arguments.' unless a.is_a?(NMatrix) and b.is_a?(NMatrix) and a.stype == :dense and b.stype == :dense
+      raise ArgumentError, 'Expected nil or dense NMatrix as third argument.' unless c.nil? or (c.is_a?(NMatrix) and c.stype == :dense)
+      raise ArgumentError, 'NMatrix dtype mismatch.'													unless a.dtype == b.dtype and (c ? a.dtype == c.dtype : true)
+
+      # First, set m, n, and k, which depend on whether we're taking the
+      # transpose of a and b.
+      if c
+        m ||= c.shape[0]
+        n ||= c.shape[1]
+        k ||= transpose_a ? a.shape[0] : a.shape[1]
+
+      else
+        if transpose_a
+          # Either :transpose or :complex_conjugate.
+          m ||= a.shape[1]
+          k ||= a.shape[0]
+
+        else
+          # No transpose.
+          m ||= a.shape[0]
+          k ||= a.shape[1]
+        end
+
+        n ||= transpose_b ? b.shape[0] : b.shape[1]
+        c		= NMatrix.new([m, n], a.dtype)
+      end
+
+      # I think these are independent of whether or not a transpose occurs.
+      lda ||= a.shape[1]
+      ldb ||= b.shape[1]
+      ldc ||= c.shape[1]
+
+      # NM_COMPLEX64 and NM_COMPLEX128 both require complex alpha and beta.
+      if a.dtype == :complex64 or a.dtype == :complex128
+        alpha = Complex(1.0, 0.0) if alpha == 1.0
+        beta  = Complex(0.0, 0.0) if beta  == 0.0
+      end
+
+      # For argument descriptions, see: http://www.netlib.org/blas/dgemm.f
+      ::NMatrix::BLAS.cblas_gemm(:row, transpose_a, transpose_b, m, n, k, alpha, a, lda, b, ldb, beta, c, ldc)
+
+      return c
     end
 
+    #
+    # call-seq:
+    #     gemv(a, x) -> NVector
+    #     gemv(a, x, y) -> NVector
+    #     gemv(a, x, y, alpha, beta) -> NVector
+    #
+    # Implements matrix-vector product via
+    #   y = (alpha * A * x) + (beta * y)
+    # where +alpha+ and +beta+ are scalar values.
+    #
+    # * *Arguments* :
+    #   - +a+ -> Matrix A.
+    #   - +x+ -> Vector x.
+    #   - +y+ -> Vector y.
+    #   - +alpha+ -> A scalar value that multiplies A * x.
+    #   - +beta+ -> A scalar value that multiplies y.
+    #   - +transpose_a+ ->
+    #   - +m+ ->
+    #   - +n+ ->
+    #   - +lda+ ->
+    #   - +incx+ ->
+    #   - +incy+ ->
+    # * *Returns* :
+    #   -
+    # * *Raises* :
+    #   - ++ ->
+    #
     def gemv(a, x, y = nil, alpha = 1.0, beta = 0.0, transpose_a = false, m = nil, n = nil, lda = nil, incx = nil, incy = nil)
-    	m ||= transpose_a ? a.shape[1] : a.shape[0]
-    	n ||= transpose_a ? a.shape[0] : a.shape[1]
+      raise ArgumentError, 'Expected dense NMatrices as first two arguments.' unless a.is_a?(NMatrix) and x.is_a?(NMatrix) and a.stype == :dense and x.stype == :dense
+      raise ArgumentError, 'Expected nil or dense NMatrix as third argument.' unless y.nil? or (y.is_a?(NMatrix) and y.stype == :dense)
+      raise ArgumentError, 'NMatrix dtype mismatch.'													unless a.dtype == x.dtype and (y ? a.dtype == y.dtype : true)
 
-    	lda		||= a.shape[1]
-    	incx	||= 1
-    	incy	||= 1
+      m ||= transpose_a ? a.shape[1] : a.shape[0]
+      n ||= transpose_a ? a.shape[0] : a.shape[1]
 
-    	# NM_COMPLEX64 and NM_COMPLEX128 both require complex alpha and beta.
-    	if a.dtype == :complex64 or a.dtype == :complex128
-    		alpha = Complex(1.0, 0.0) if alpha == 1.0
-    		beta  = Complex(0.0, 0.0) if beta  == 0.0
-    	end
+      lda		||= a.shape[1]
+      incx	||= 1
+      incy	||= 1
 
-    	::NMatrix::BLAS.cblas_gemv(transpose_a, m, n, alpha, a, lda, x, incx, beta, y, incy)
+      # NM_COMPLEX64 and NM_COMPLEX128 both require complex alpha and beta.
+      if a.dtype == :complex64 or a.dtype == :complex128
+        alpha = Complex(1.0, 0.0) if alpha == 1.0
+        beta  = Complex(0.0, 0.0) if beta  == 0.0
+      end
 
-    	return y
+      y ||= NMatrix.new([m, n], a.dtype)
+
+      ::NMatrix::BLAS.cblas_gemv(transpose_a, m, n, alpha, a, lda, x, incx, beta, y, incy)
+
+      return y
     end
 
+    #
+    # call-seq:
+    #     rot(x, y, c, s)
+    #
+    # Apply plane rotation.
+    #
+    # * *Arguments* :
+    #   - +x+ ->
+    #   - +y+ ->
+    #   - +s+ ->
+    #   - +c+ ->
+    #   - +incx+ ->
+    #   - +incy+ ->
+    #   - +n+ ->
+    # * *Returns* :
+    #   - Array with the results, in the format [xx, yy]
+    # * *Raises* :
+    #   - +ArgumentError+ -> Expected dense NMatrices as first two arguments.
+    #   - +ArgumentError+ -> Nmatrix dtype mismatch.
+    #   - +ArgumentError+ -> Need to supply n for non-standard incx, incy values.
+    #
+    def rot(x, y, c, s, incx = 1, incy = 1, n = nil)
+      raise ArgumentError, 'Expected dense NMatrices as first two arguments.' unless x.is_a?(NMatrix) and y.is_a?(NMatrix) and x.stype == :dense and y.stype == :dense
+      raise ArgumentError, 'NMatrix dtype mismatch.'													unless x.dtype == y.dtype
+      raise ArgumentError, 'Need to supply n for non-standard incx, incy values' if n.nil? && incx != 1 && incx != -1 && incy != 1 && incy != -1
+
+      n ||= x.size > y.size ? y.size : x.size
+
+      xx = x.clone
+      yy = y.clone
+
+      ::NMatrix::BLAS.cblas_rot(n, xx, incx, yy, incy, c, s)
+
+      return [xx,yy]
+    end
   end
 end

data/lib/nmatrix/io/market.rb

@@ -1,3 +1,4 @@
+#--
 # = NMatrix
 #
 # A linear algebra library for scientific computation in Ruby.
@@ -24,22 +25,33 @@
 #
 # MatrixMarket reader and writer.
 #
+#++
+
 module NMatrix::IO::Market
   CONVERTER_AND_DTYPE = {
-      :real => [:to_f, :float64],
-      :complex => [:to_c, :complex128],
-      :integer => [:to_i, :int64],
-      :pattern => [:to_i, :byte]
+    :real => [:to_f, :float64],
+    :complex => [:to_c, :complex128],
+    :integer => [:to_i, :int64],
+    :pattern => [:to_i, :byte]
   }
 
   ENTRY_TYPE = {
-      :byte => :integer, :int8 => :integer, :int16 => :integer, :int32 => :integer, :int64 => :integer,
-      :float32 => :real, :float64 => :real, :complex64 => :complex, :complex128 => :complex
+    :byte => :integer, :int8 => :integer, :int16 => :integer, :int32 => :integer, :int64 => :integer,
+    :float32 => :real, :float64 => :real, :complex64 => :complex, :complex128 => :complex
   }
 
   class << self
+    #
+    # call-seq:
+    #     load(filename) ->
+    #
+    # * *Arguments* :
+    #   - +filename+ -> String with the filename to be saved.
+    # * *Raises* :
+    #   - +IOError+ -> expected type code line beginning with '%%MatrixMarket matrix'
+    #
     # Load a MatrixMarket file. Requires a filename as an argument.
-    def load filename
+    def load(filename)
 
       f = File.new(filename, "r")
 
@@ -60,12 +72,24 @@ module NMatrix::IO::Market
       end
     end
 
-
-    # Can optionally set :symmetry to :general, :symmetric, :hermitian; and can set :pattern => true if you're writing
-    # a sparse matrix and don't want values stored.
-    def save matrix, filename, options = {}
+    #
+    # call-seq:
+    #     save(matrix, filename, options = {}) -> true
+    #
+    # Can optionally set :symmetry to :general, :symmetric, :hermitian; and can
+    # set :pattern => true if you're writing a sparse matrix and don't want
+    # values stored.
+    #
+    # * *Arguments* :
+    #   - +matrix+ -> NMatrix with the data to be saved.
+    #   - +filename+ -> String with the filename to be saved.
+    # * *Raises* :
+    #   - +DataTypeError+ -> MatrixMarket does not support rational or Ruby objects.
+    #   - +ArgumentError+ -> Expected two-dimensional NMatrix.
+    #
+    def save(matrix, filename, options = {})
       options = {:pattern => false,
-                 :symmetry => :general}.merge(options)
+        :symmetry => :general}.merge(options)
 
       mode = matrix.stype == :dense ? :array : :coordinate
       if [:rational32,:rational64,:rational128,:object].include?(matrix.dtype)
@@ -91,7 +115,7 @@ module NMatrix::IO::Market
     end
 
 
-  protected
+    protected
 
     def save_coordinate matrix, file, symmetry, pattern
       # Convert to a hash in order to store
@@ -224,4 +248,4 @@ module NMatrix::IO::Market
       mat
     end
   end
-end
+end

data/lib/nmatrix/io/mat5_reader.rb

@@ -1,3 +1,4 @@
+#--
 # = NMatrix
 #
 # A linear algebra library for scientific computation in Ruby.
@@ -24,14 +25,16 @@
 #
 # Matlab version 5 .mat file reader (and eventually writer too).
 #
+#++
 
-
-require_relative 'mat_reader.rb'
+require_relative './mat_reader.rb'
 
 module NMatrix::IO::Matlab
-	# Reader (and eventual writer) for a version 5 .mat file.
-	class Mat5Reader < MatReader
-		attr_reader :file_header, :first_tag_field, :first_data_field
+  #
+  # Reader (and eventual writer) for a version 5 .mat file.
+  #
+  class Mat5Reader < MatReader
+    attr_reader :file_header, :first_tag_field, :first_data_field
 
     class Compressed
       include Packable
@@ -39,6 +42,15 @@ module NMatrix::IO::Matlab
 
       attr_reader :byte_order
 
+      #
+      # call-seq:
+      #     new(stream = nil, byte_order = nil, content_or_bytes = nil) -> Mat5Reader::Compressed
+      #
+      # * *Arguments* :
+      #   - ++ ->
+      # * *Raises* :
+      #   - ++ ->
+      #
       def initialize(stream = nil, byte_order = nil, content_or_bytes = nil)
         @stream			= stream
         @byte_order	= byte_order
@@ -48,35 +60,69 @@ module NMatrix::IO::Matlab
 
         elsif content_or_bytes.is_a?(Fixnum)
           @padded_bytes = content_or_bytes
-        #else
-        #  raise ArgumentError, "Need a content string or a number of bytes; content_or_bytes is #{content_or_bytes.class.to_s}."
+          #else
+          #  raise ArgumentError, "Need a content string or a number of bytes; content_or_bytes is #{content_or_bytes.class.to_s}."
         end
       end
 
+      #
+      # call-seq:
+      #     compressed ->
+      #
       def compressed
         require "zlib"
         # [2..-5] removes headers
         @compressed ||= Zlib::Deflate.deflate(content)
       end
 
+      #
+      # call-seq:
+      #     content ->
+      #
       def content
         @content ||= extract
       end
 
+      #
+      # call-seq:
+      #     padded_bytes ->
+      #
       def padded_bytes
         @padded_bytes ||= content.size % 4 == 0 ? content.size : (content.size / 4 + 1) * 4
       end
 
-      def write_packed(packedio, options)
+      #
+      # call-seq:
+      #     write_packed(packedio, options = {}) ->
+      #
+      # * *Arguments* :
+      #   - ++ ->
+      # * *Returns* :
+      #   -
+      #
+      def write_packed(packedio, options = {})
         packedio << [compressed, {:bytes => padded_bytes}.merge(options)]
       end
 
+      #
+      # call-seq:
+      #     read_packed(packedio, options = {}) ->
+      #
+      # * *Arguments* :
+      #   - ++ ->
+      # * *Returns* :
+      #   -
+      #
       def read_packed(packedio, options)
         @compressed = (packedio >> [String, options]).first
         content
       end
 
       protected
+      #
+      # call-seq:
+      #     extract ->
+      #
       def extract
         require 'zlib'
 
@@ -90,26 +136,43 @@ module NMatrix::IO::Matlab
     end
 
     MatrixDataStruct = Struct.new(
-      :cells, :logical, :global, :complex, :nonzero_max,
-      :matlab_class, :dimensions, :matlab_name, :real_part,
-      :imaginary_part, :row_index, :column_index)
+                                  :cells, :logical, :global, :complex, :nonzero_max,
+                                  :matlab_class, :dimensions, :matlab_name, :real_part,
+                                  :imaginary_part, :row_index, :column_index)
 
     class MatrixData < MatrixDataStruct
       include Packable
 
+      #
+      # call-seq:
+      #     write_packed(packedio, options) ->
+      #
+      # * *Arguments* :
+      #   - ++ ->
+      # * *Returns* :
+      #   -
+      #
       def write_packed(packedio, options)
         raise NotImplementedError
         packedio << [info, {:bytes => padded_bytes}.merge(options)]
       end
 
-      # Figure out the appropriate Ruby type to convert to, and do it. There are basically two possible types: NMatrix
-      # and Ruby Array. This function is recursive, so an Array is going to contain other Arrays and/or NMatrix objects.
+      #
+      # call-seq:
+      #     to_ruby -> NMatrix or Array
+      #
+      # Figure out the appropriate Ruby type to convert to, and do it. There
+      # are basically two possible types: +NMatrix+ and +Array+. This method
+      # is recursive, so an +Array+ is going to contain other +Array+s and/or
+      # +NMatrix+ objects.
       #
       # mxCELL types (cells) will be converted to the Array type.
       #
-      # mxSPARSE and other types will be converted to NMatrix, with the appropriate stype (:yale or :dense, respectively).
+      # mxSPARSE and other types will be converted to NMatrix, with the
+      # appropriate stype (:yale or :dense, respectively).
       #
       # See also to_nm, which is responsible for NMatrix instantiation.
+      #
       def to_ruby
         case matlab_class
         when :mxSPARSE	then	return to_nm
@@ -118,9 +181,15 @@ module NMatrix::IO::Matlab
         end
       end
 
+      #
+      # call-seq:
+      #     guess_dtype_from_mdtype -> Symbol
+      #
       # Try to determine what dtype and such to use.
       #
-      # TODO: Needs to be verified that unsigned MATLAB types are being converted to the correct NMatrix signed dtypes.
+      # TODO: Needs to be verified that unsigned MATLAB types are being
+      # converted to the correct NMatrix signed dtypes.
+      #
       def guess_dtype_from_mdtype
         dtype = MatReader::MDTYPE_TO_DTYPE[self.real_part.tag.data_type]
 
@@ -129,10 +198,16 @@ module NMatrix::IO::Matlab
         dtype == :float32 ? :complex64 : :complex128
       end
 
+      #
+      # call-seq:
+      #     unpacked_data(real_mdtype = nil, imag_mdtype = nil) ->
+      #
       # Unpacks data without repacking it.
       #
-      # Used only for dense matrix creation. Yale matrix creation uses repacked_data.
-      def unpacked_data real_mdtype=nil, imag_mdtype=nil
+      # Used only for dense matrix creation. Yale matrix creation uses
+      # repacked_data.
+      #
+      def unpacked_data(real_mdtype = nil, imag_mdtype = nil)
         # Get Matlab data type and unpack args
         real_mdtype ||= self.real_part.tag.data_type
         real_unpack_args = MatReader::MDTYPE_UNPACK_ARGS[real_mdtype]
@@ -153,22 +228,30 @@ module NMatrix::IO::Matlab
 
       end
 
+      #
+      # call-seq:
+      #     repacked_data(to_dtype = nil) ->
+      #
       # Unpacks and repacks data into the appropriate format for NMatrix.
       #
-      # If data is already in the appropriate format, does not unpack or repack, just returns directly.
+      # If data is already in the appropriate format, does not unpack or
+      # repack, just returns directly.
       #
-      # Complex is always unpacked and repacked, as the real and imaginary components must be merged together (MATLAB
-      # stores them separately for some crazy reason).
+      # Complex is always unpacked and repacked, as the real and imaginary
+      # components must be merged together (MATLAB stores them separately for
+      # some crazy reason).
       #
       # Used only for Yale storage creation. For dense, see unpacked_data.
       #
-      # This function calls repack and complex_merge, which are both defined in io.cpp.
+      # This function calls repack and complex_merge, which are both defined in
+      # io.cpp.
       def repacked_data(to_dtype = nil)
 
         real_mdtype = self.real_part.tag.data_type
 
-        # Figure out what dtype to use based on the MATLAB data-types (mdtypes). They could be different for real and
-        # imaginary, so call upcast to figure out what to use.
+        # Figure out what dtype to use based on the MATLAB data-types
+        # (mdtypes). They could be different for real and imaginary, so call
+        # upcast to figure out what to use.
 
         components = [] # real and imaginary parts or just the real part
 
@@ -208,10 +291,15 @@ module NMatrix::IO::Matlab
          to_dtype]
       end
 
-
+      #
+      # call-seq:
+      #     repacked_indices(to_itype) ->
+      #
       # Unpacks and repacks index data into the appropriate format for NMatrix.
       #
-      # If data is already in the appropriate format, does not unpack or repack, just returns directly.
+      # If data is already in the appropriate format, does not unpack or
+      # repack, just returns directly.
+      #
       def repacked_indices(to_itype)
         return [row_index.data, column_index.data] if to_itype == :uint32 # No need to re-pack -- already correct
 
@@ -222,18 +310,27 @@ module NMatrix::IO::Matlab
         [repacked_row_indices, repacked_col_indices]
       end
 
-
+      #
+      # call-seq:
+      #     to_nm(dtype = nil) -> NMatrix
+      #
       # Create an NMatrix from a MATLAB .mat (v5) matrix.
       #
-      # This function matches the storage type exactly. That is, a regular matrix in MATLAB will be a dense NMatrix, and
-      # a sparse (old Yale) matrix in MATLAB will be a :yale (new Yale) matrix in NMatrix.
+      # This function matches the storage type exactly. That is, a regular
+      # matrix in MATLAB will be a dense NMatrix, and a sparse (old Yale) one
+      # in MATLAB will be a :yale (new Yale) matrix in NMatrix.
+      #
+      # Note that NMatrix has no old Yale type, so this uses a semi-hidden
+      # version of the NMatrix constructor to pass in --- as directly as
+      # possible -- the stored bytes in a MATLAB sparse matrix. This
+      # constructor should also be used for other IO formats that want to
+      # create sparse matrices from IA and JA vectors (e.g., SciPy).
       #
-      # Note that NMatrix has no old Yale type, so this uses a semi-hidden version of the NMatrix constructor to pass in
-      # -- as directly as possible -- the stored bytes in a MATLAB sparse matrix. This constructor should also be used
-      # for other IO formats that want to create sparse matrices from IA and JA vectors (e.g., SciPy).
+      # This is probably not the fastest code. An ideal solution would be a C
+      # plugin of some sort for reading the MATLAB .mat file. However, .mat v5
+      # is a really complicated format, and lends itself to an object-oriented
+      # solution.
       #
-      # This is probably not the fastest code. An ideal solution would be a C plugin of some sort for reading the MATLAB
-      # .mat file. However, .mat v5 is a really complicated format, and lends itself to an object-oriented solution.
       def to_nm(dtype = nil)
         # Hardest part is figuring out from_dtype, from_index_dtype, and dtype.
         dtype			||= guess_dtype_from_mdtype
@@ -261,6 +358,15 @@ module NMatrix::IO::Matlab
         end
       end
 
+      #
+      # call-seq:
+      #     read_packed(packedio, options) ->
+      #
+      # * *Arguments* :
+      #   - ++ ->
+      # * *Returns* :
+      #   -
+      #
       def read_packed(packedio, options)
         flags_class, self.nonzero_max = packedio.read([Element, options]).data
 
@@ -313,255 +419,264 @@ module NMatrix::IO::Matlab
         end
       end
 
-      def ignore_padding packedio, bytes
+      #
+      # call-seq:
+      #     ignore_padding(packedio, bytes) ->
+      #
+      # * *Arguments* :
+      #   - ++ ->
+      # * *Returns* :
+      #   -
+      #
+      def ignore_padding(packedio, bytes)
         packedio.read([Integer, {:unsigned => true, :bytes => bytes}]) if bytes > 0
       end
     end
 
 
-		MDTYPE_UNPACK_ARGS =
-		MatReader::MDTYPE_UNPACK_ARGS.merge({
-			:miCOMPRESSED	=> [Compressed, {}],
-			:miMATRIX			=> [MatrixData, {}]
-		})
-		# include TaggedDataEnumerable
-		
-		FIRST_TAG_FIELD_POS = 128
-		
-		####################
-		# Instance Methods #
-		####################
-
-		def initialize(stream, options = {})
-			super(stream, options)
-			@file_header = seek_and_read_file_header
-		end
-
-		def to_a
-			returning(Array.new) do |ary|
-				self.each { |el| ary << el }
-			end
-		end
-
-		def to_ruby
-			ary = self.to_a
-			
-			if ary.size == 1
-				ary.first.to_ruby 
-			else
-				ary.collect { |item| item.to_ruby }
-			end
-		end
-
-		def guess_byte_order
-			stream.seek(Header::BYTE_ORDER_POS)
-			mi = stream.read(Header::BYTE_ORDER_LENGTH)
-			stream.seek(0)
-			mi == 'IM' ? :little : :big
-		end
-
-		def seek_and_read_file_header
-			stream.seek(0)
-			stream.read(FIRST_TAG_FIELD_POS).unpack(Header, {:endian => byte_order})
-		end
-
-		def each(&block)
-			stream.each(Element, {:endian => byte_order}) do |element|
-				if element.data.is_a?(Compressed)
-					StringIO.new(element.data.content, 'rb').each(Element, {:endian => byte_order}) do |compressed_element|
-						yield compressed_element.data
-					end
-					
-				else
-					yield element.data
-				end
-			end
-			
-			# Go back to the beginning in case we want to do it again.
-			stream.seek(FIRST_TAG_FIELD_POS)
-			
-			self
-		end
-		
-		####################
-		# Internal Classes #
-		####################
-		
-		class Header < Struct.new(:desc, :data_offset, :version, :endian)
-
-			include Packable
-
-			BYTE_ORDER_LENGTH		= 2
-			DESC_LENGTH					= 116
-			DATA_OFFSET_LENGTH	= 8
-			VERSION_LENGTH			= 2
-			BYTE_ORDER_POS			= 126
-
-			## TODO: TEST WRITE.
-			def write_packed(packedio, options)
-				packedio <<	[desc,				{:bytes => DESC_LENGTH				}] <<
-                    [data_offset,	{:bytes => DATA_OFFSET_LENGTH	}] <<
-                    [version,			{:bytes => VERSION_LENGTH			}] <<
-                    [byte_order,	{:bytes => BYTE_ORDER_LENGTH	}]
-			end
-
-			def read_packed(packedio, options)
-				self.desc, self.data_offset, self.version, self.endian = packedio >>
+    MDTYPE_UNPACK_ARGS =
+      MatReader::MDTYPE_UNPACK_ARGS.merge({
+                                            :miCOMPRESSED	=> [Compressed, {}],
+                                            :miMATRIX			=> [MatrixData, {}]
+                                          })
+    # include TaggedDataEnumerable
+
+    FIRST_TAG_FIELD_POS = 128
+
+    ####################
+    # Instance Methods #
+    ####################
+
+    def initialize(stream, options = {})
+      super(stream, options)
+      @file_header = seek_and_read_file_header
+    end
+
+    def to_a
+      returning(Array.new) do |ary|
+        self.each { |el| ary << el }
+      end
+    end
+
+    def to_ruby
+      ary = self.to_a
+
+      if ary.size == 1
+        ary.first.to_ruby
+      else
+        ary.collect { |item| item.to_ruby }
+      end
+    end
+
+    def guess_byte_order
+      stream.seek(Header::BYTE_ORDER_POS)
+      mi = stream.read(Header::BYTE_ORDER_LENGTH)
+      stream.seek(0)
+      mi == 'IM' ? :little : :big
+    end
+
+    def seek_and_read_file_header
+      stream.seek(0)
+      stream.read(FIRST_TAG_FIELD_POS).unpack(Header, {:endian => byte_order})
+    end
+
+    def each(&block)
+      stream.each(Element, {:endian => byte_order}) do |element|
+        if element.data.is_a?(Compressed)
+          StringIO.new(element.data.content, 'rb').each(Element, {:endian => byte_order}) do |compressed_element|
+            yield compressed_element.data
+          end
+
+        else
+          yield element.data
+        end
+      end
+
+      # Go back to the beginning in case we want to do it again.
+      stream.seek(FIRST_TAG_FIELD_POS)
+
+      self
+    end
+
+    ####################
+    # Internal Classes #
+    ####################
+
+    class Header < Struct.new(:desc, :data_offset, :version, :endian)
+
+      include Packable
+
+      BYTE_ORDER_LENGTH		= 2
+      DESC_LENGTH					= 116
+      DATA_OFFSET_LENGTH	= 8
+      VERSION_LENGTH			= 2
+      BYTE_ORDER_POS			= 126
+
+      ## TODO: TEST WRITE.
+      def write_packed(packedio, options)
+        packedio <<	[desc,				{:bytes => DESC_LENGTH				}] <<
+          [data_offset,	{:bytes => DATA_OFFSET_LENGTH	}] <<
+          [version,			{:bytes => VERSION_LENGTH			}] <<
+          [byte_order,	{:bytes => BYTE_ORDER_LENGTH	}]
+      end
+
+      def read_packed(packedio, options)
+        self.desc, self.data_offset, self.version, self.endian = packedio >>
           [String,	{:bytes => DESC_LENGTH																	}] >>
-					[String,	{:bytes => DATA_OFFSET_LENGTH														}] >>
-					[Integer,	{:bytes => VERSION_LENGTH, :endian => options[:endian]	}] >>
-					[String,	{:bytes => 2																						}]
-				
-				self.desc.strip!
-				self.data_offset.strip!
-				self.data_offset = nil if self.data_offset.empty?
-				
-				self.endian == 'IM' ? :little : :big
-			end
-		end
-		
-		class Tag < Struct.new(:data_type, :raw_data_type, :bytes, :small)
-			include Packable
-			
-			DATA_TYPE_OPTS = BYTES_OPTS = {:bytes => 4, :signed => false}
-			LENGTH = DATA_TYPE_OPTS[:bytes] + BYTES_OPTS[:bytes]
-			
-			## TODO: TEST WRITE.
-			def write_packed packedio, options
-				packedio << [data_type, DATA_TYPE_OPTS] << [bytes, BYTES_OPTS]
-			end
-			
-			def small?
-				self.bytes > 0 and self.bytes <= 4
-			end
-			
-			def size
-				small? ? 4 : 8
-			end
-			
-			def read_packed packedio, options
-				self.raw_data_type = packedio.read([Integer, DATA_TYPE_OPTS.merge(options)])
-				
-				# Borrowed from a SciPy patch
-				upper = self.raw_data_type >> 16
-				lower = self.raw_data_type & 0xFFFF
-				
-				if upper > 0
-					# Small data element format
-					raise IOError, 'Small data element format indicated, but length is more than 4 bytes!' if upper > 4
-					
-					self.bytes					= upper
-					self.raw_data_type	= lower
-					
-				else
-					self.bytes = packedio.read([Integer, BYTES_OPTS.merge(options)])
-				end
-				
-				self.data_type = MatReader::MDTYPES[self.raw_data_type]
-			end
-
-			def inspect
-				"#<#{self.class.to_s} data_type=#{data_type}[#{raw_data_type}][#{raw_data_type.to_s(2)}] bytes=#{bytes} size=#{size}#{small? ? ' small' : ''}>"
-			end
-		end
-
-
-		class ElementDataIOError < IOError
-			attr_reader :tag
-			
-			def initialize(tag = nil, msg = nil)
-				@tag = tag
-				super msg
-			end
-
-			def to_s
-				@tag.inspect + "\n" + super
-			end
-		end
-
-
-		class Element < Struct.new(:tag, :data)
-			include Packable
-
-			def write_packed packedio, options
-				packedio << [tag, {}] << [data, {}]
-			end
-
-			def read_packed(packedio, options)
-				raise(ArgumentError, 'Missing mandatory option :endian.') unless options.has_key?(:endian)
-				
-				tag = packedio.read([Tag, {:endian => options[:endian]}])
-				#STDERR.puts tag.inspect
-				data_type = MDTYPE_UNPACK_ARGS[tag.data_type]
-				
-				self.tag = tag
-				#STDERR.puts self.tag.inspect
-				
-				raise ElementDataIOError.new(tag, "Unrecognized Matlab type #{tag.raw_data_type}") if data_type.nil?
-
-				if tag.bytes == 0
-					self.data = []
-					
-				else
-					number_of_reads = data_type[1].has_key?(:bytes) ? tag.bytes / data_type[1][:bytes] : 1
-					data_type[1].merge!({:endian => options[:endian]})
-
-					if number_of_reads == 1
-						self.data = packedio.read(data_type)
-						
-					else
-						self.data =
-						returning(Array.new) do |ary|
-							number_of_reads.times { ary << packedio.read(data_type) }
-						end
-					end
-				
-					begin
-						ignore_padding(packedio, (tag.bytes + tag.size) % 8) unless [:miMATRIX, :miCOMPRESSED].include?(tag.data_type)
-						
-					rescue EOFError
-						STDERR.puts self.tag.inspect
-						raise(ElementDataIOError.new(tag, "Ignored too much"))
-					end
-				end
-			end
-
-			def ignore_padding(packedio, bytes)
-				if bytes > 0
-					#STDERR.puts "Ignored #{8 - bytes} on #{self.tag.data_type}"
-					ignored = packedio.read(8 - bytes)
-					ignored_unpacked = ignored.unpack("C*")
-					raise(IOError, "Nonzero padding detected: #{ignored_unpacked}") if ignored_unpacked.any? { |i| i != 0 }
-				end
-			end
-
-			def to_ruby
-				data.to_ruby
-			end
-		end
-
-		# Doesn't unpack the contents of the element, e.g., if we want to handle
-		# manually, or pass the raw string of bytes into NMatrix.
-		class RawElement < Element
-			def read_packed(packedio, options)
-				raise(ArgumentError, 'Missing mandatory option :endian.') unless options.has_key?(:endian)
-
-				self.tag	= packedio.read([Tag,			{:endian => options[:endian]											}])
-				self.data	= packedio.read([String,	{:endian => options[:endian], :bytes => tag.bytes	}])
-
-				begin
-					ignore_padding(packedio, (tag.bytes + tag.size) % 8) unless [:miMATRIX, :miCOMPRESSED].include?(tag.data_type)
-					
-				rescue EOFError
-					STDERR.puts self.tag.inspect
-					raise ElementDataIOError.new(tag, 'Ignored too much.')
-				end
-			end
-		end
-		
-		#####################
-		# End of Mat5Reader #
-		#####################
-		
-	end
+          [String,	{:bytes => DATA_OFFSET_LENGTH														}] >>
+          [Integer,	{:bytes => VERSION_LENGTH, :endian => options[:endian]	}] >>
+          [String,	{:bytes => 2																						}]
+
+        self.desc.strip!
+        self.data_offset.strip!
+        self.data_offset = nil if self.data_offset.empty?
+
+        self.endian == 'IM' ? :little : :big
+      end
+    end
+
+    class Tag < Struct.new(:data_type, :raw_data_type, :bytes, :small)
+      include Packable
+
+      DATA_TYPE_OPTS = BYTES_OPTS = {:bytes => 4, :signed => false}
+      LENGTH = DATA_TYPE_OPTS[:bytes] + BYTES_OPTS[:bytes]
+
+      ## TODO: TEST WRITE.
+      def write_packed packedio, options
+        packedio << [data_type, DATA_TYPE_OPTS] << [bytes, BYTES_OPTS]
+      end
+
+      def small?
+        self.bytes > 0 and self.bytes <= 4
+      end
+
+      def size
+        small? ? 4 : 8
+      end
+
+      def read_packed packedio, options
+        self.raw_data_type = packedio.read([Integer, DATA_TYPE_OPTS.merge(options)])
+
+        # Borrowed from a SciPy patch
+        upper = self.raw_data_type >> 16
+        lower = self.raw_data_type & 0xFFFF
+
+        if upper > 0
+          # Small data element format
+          raise IOError, 'Small data element format indicated, but length is more than 4 bytes!' if upper > 4
+
+          self.bytes					= upper
+          self.raw_data_type	= lower
+
+        else
+          self.bytes = packedio.read([Integer, BYTES_OPTS.merge(options)])
+        end
+
+        self.data_type = MatReader::MDTYPES[self.raw_data_type]
+      end
+
+      def inspect
+        "#<#{self.class.to_s} data_type=#{data_type}[#{raw_data_type}][#{raw_data_type.to_s(2)}] bytes=#{bytes} size=#{size}#{small? ? ' small' : ''}>"
+      end
+    end
+
+
+    class ElementDataIOError < IOError
+      attr_reader :tag
+
+      def initialize(tag = nil, msg = nil)
+        @tag = tag
+        super msg
+      end
+
+      def to_s
+        @tag.inspect + "\n" + super
+      end
+    end
+
+
+    class Element < Struct.new(:tag, :data)
+      include Packable
+
+      def write_packed packedio, options
+        packedio << [tag, {}] << [data, {}]
+      end
+
+      def read_packed(packedio, options)
+        raise(ArgumentError, 'Missing mandatory option :endian.') unless options.has_key?(:endian)
+
+        tag = packedio.read([Tag, {:endian => options[:endian]}])
+        #STDERR.puts tag.inspect
+        data_type = MDTYPE_UNPACK_ARGS[tag.data_type]
+
+        self.tag = tag
+        #STDERR.puts self.tag.inspect
+
+        raise ElementDataIOError.new(tag, "Unrecognized Matlab type #{tag.raw_data_type}") if data_type.nil?
+
+        if tag.bytes == 0
+          self.data = []
+
+        else
+          number_of_reads = data_type[1].has_key?(:bytes) ? tag.bytes / data_type[1][:bytes] : 1
+          data_type[1].merge!({:endian => options[:endian]})
+
+          if number_of_reads == 1
+            self.data = packedio.read(data_type)
+
+          else
+            self.data =
+              returning(Array.new) do |ary|
+              number_of_reads.times { ary << packedio.read(data_type) }
+            end
+          end
+
+          begin
+            ignore_padding(packedio, (tag.bytes + tag.size) % 8) unless [:miMATRIX, :miCOMPRESSED].include?(tag.data_type)
+
+          rescue EOFError
+            STDERR.puts self.tag.inspect
+            raise(ElementDataIOError.new(tag, "Ignored too much"))
+          end
+        end
+      end
+
+      def ignore_padding(packedio, bytes)
+        if bytes > 0
+          #STDERR.puts "Ignored #{8 - bytes} on #{self.tag.data_type}"
+          ignored = packedio.read(8 - bytes)
+          ignored_unpacked = ignored.unpack("C*")
+          raise(IOError, "Nonzero padding detected: #{ignored_unpacked}") if ignored_unpacked.any? { |i| i != 0 }
+        end
+      end
+
+      def to_ruby
+        data.to_ruby
+      end
+    end
+
+    # Doesn't unpack the contents of the element, e.g., if we want to handle
+    # manually, or pass the raw string of bytes into NMatrix.
+    class RawElement < Element
+      def read_packed(packedio, options)
+        raise(ArgumentError, 'Missing mandatory option :endian.') unless options.has_key?(:endian)
+
+        self.tag	= packedio.read([Tag,			{:endian => options[:endian]											}])
+        self.data	= packedio.read([String,	{:endian => options[:endian], :bytes => tag.bytes	}])
+
+        begin
+          ignore_padding(packedio, (tag.bytes + tag.size) % 8) unless [:miMATRIX, :miCOMPRESSED].include?(tag.data_type)
+
+        rescue EOFError
+          STDERR.puts self.tag.inspect
+          raise ElementDataIOError.new(tag, 'Ignored too much.')
+        end
+      end
+    end
+
+    #####################
+    # End of Mat5Reader #
+    #####################
+
+  end
 end