ruby-gsl-ng 0.2.2 → 0.2.3

data/lib/gslng/backend_components/rng.rb

@@ -0,0 +1,22 @@
+module GSLng
+  backend.instance_eval do
+    # memory handling
+    attach_function :gsl_rng_alloc, [ :pointer ], :pointer
+    attach_function :gsl_rng_free, [ :pointer ], :void
+
+    # RNG types
+    algorithms = %w(mt19937 ranlxs0 ranlxs1 ranlxs2 ranlxd1 ranlxd2 ranlux ranlux389 cmrg mrg taus taus2 gfsr4)
+    algorithms.each do |alg|
+      attach_variable :"gsl_rng_#{alg}", :pointer
+    end
+
+    # Uniform
+    attach_function :gsl_ran_flat, [ :pointer, :double, :double ], :double
+    attach_function :gsl_ran_flat_pdf, [ :double, :double, :double ], :double
+
+    # Gaussian
+    attach_function :gsl_ran_gaussian, [ :pointer, :double ], :double
+    attach_function :gsl_ran_gaussian_ziggurat, [ :pointer, :double ], :double
+    attach_function :gsl_ran_gaussian_ratio_method, [ :pointer, :double ], :double
+  end
+end

data/lib/gslng/backend_components/special.rb

@@ -0,0 +1,7 @@
+module GSLng
+  backend.instance_eval do
+    # trigonometric
+    attach_function :gsl_sf_angle_restrict_symm, [ :double ], :double
+    attach_function :gsl_sf_angle_restrict_pos, [ :double ], :double
+  end
+end

data/lib/gslng/backend_components/vector.rb

@@ -1,75 +1,63 @@
-module GSLng
-	backend.instance_eval do
-		# memory handling
-    attach_function :gsl_vector_alloc, [ :size_t ], :pointer
-    attach_function :gsl_vector_calloc, [ :size_t ], :pointer
-    attach_function :gsl_vector_free, [ :pointer ], :void
-
-    # initializing
-    attach_function :gsl_vector_set_all, [ :pointer, :double ], :void
-    attach_function :gsl_vector_set_zero, [ :pointer ], :void
-    attach_function :gsl_vector_set_basis, [ :pointer, :size_t ], :int
-
-    # operations
-    attach_function :gsl_vector_add, [ :pointer, :pointer ], :int
-    attach_function :gsl_vector_sub, [ :pointer, :pointer ], :int
-    attach_function :gsl_vector_mul, [ :pointer, :pointer ], :int
-    attach_function :gsl_vector_div, [ :pointer, :pointer ], :int
-    attach_function :gsl_vector_scale, [ :pointer, :double ], :int
-    attach_function :gsl_vector_add_constant, [ :pointer, :double ], :int
-
-    # element access
-    attach_function :gsl_vector_get, [ :pointer, :size_t ], :double
-    attach_function :gsl_vector_set, [ :pointer, :size_t, :double ], :void
-
-    # properties
-    attach_function :gsl_vector_isnull, [ :pointer ], :int
-    attach_function :gsl_vector_ispos, [ :pointer ], :int
-    attach_function :gsl_vector_isneg, [ :pointer ], :int
-    attach_function :gsl_vector_isnonneg, [ :pointer ], :int
-
-    # max and min
-    attach_function :gsl_vector_max, [ :pointer ], :double
-    attach_function :gsl_vector_min, [ :pointer ], :double
-    attach_function :gsl_vector_minmax, [ :pointer, :buffer_out, :buffer_out ], :void
-    attach_function :gsl_vector_max_index, [ :pointer ], :size_t
-    attach_function :gsl_vector_min_index, [ :pointer ], :size_t
-    attach_function :gsl_vector_minmax_index, [ :pointer, :buffer_out, :buffer_out ], :void
-
-    # copying
-    attach_function :gsl_vector_memcpy, [ :pointer, :pointer ], :int
-
-    # exchanging elements
-    attach_function :gsl_vector_swap_elements, [ :pointer, :size_t, :size_t ], :int
-    attach_function :gsl_vector_reverse, [ :pointer ], :int
-
-    # BLAS functions
-    attach_function :gsl_blas_ddot, [ :pointer, :pointer, :buffer_out ], :int
-    attach_function :gsl_blas_dnrm2, [ :pointer ], :double
-    attach_function :gsl_blas_dasum, [ :pointer ], :double
-    #attach_function :gsl_blas_idamax, [ :pointer ], clbas_index??
-    #attach_function :gsl_blas_dcopy, use this instead of memcpy?
-    attach_function :gsl_blas_daxpy, [ :double, :pointer, :pointer ], :int
-    attach_function :gsl_blas_dscal, [ :double, :pointer ], :void
-
-    # views
-    attach_function :gsl_vector_subvector2, [ :pointer, :size_t, :size_t ], :pointer
-    attach_function :gsl_vector_subvector_with_stride2, [ :pointer, :size_t, :size_t, :size_t ], :pointer
-
-		# From local extension
-		callback :gsl_vector_callback, [ :double ], :double
-		attach_function :gsl_vector_map, [ :pointer, :gsl_vector_callback ], :void
-
-		callback :gsl_vector_index_callback, [ :size_t ], :double
-		attach_function :gsl_vector_map_index, [ :pointer, :gsl_vector_index_callback ], :void
-
-		callback :gsl_vector_each_callback, [ :double ], :void
-		attach_function :gsl_vector_each, [ :pointer, :gsl_vector_each_callback ], :void
-
-		callback :gsl_vector_each_with_index_callback, [ :double, :size_t ], :void
-		attach_function :gsl_vector_each_with_index, [ :pointer, :gsl_vector_each_with_index_callback ], :void
-
-		# Sorting
-		attach_function :gsl_sort_vector, [ :pointer ], :void
-	end
-end
+module GSLng
+  backend.instance_eval do
+    # memory handling
+    attach_function :gsl_vector_alloc, [ :size_t ], :pointer
+    attach_function :gsl_vector_calloc, [ :size_t ], :pointer
+    attach_function :gsl_vector_free, [ :pointer ], :void
+
+    # initializing
+    attach_function :gsl_vector_set_all, [ :pointer, :double ], :void
+    attach_function :gsl_vector_set_zero, [ :pointer ], :void
+    attach_function :gsl_vector_set_basis, [ :pointer, :size_t ], :int
+
+    # operations
+    attach_function :gsl_vector_add, [ :pointer, :pointer ], :int
+    attach_function :gsl_vector_sub, [ :pointer, :pointer ], :int
+    attach_function :gsl_vector_mul, [ :pointer, :pointer ], :int
+    attach_function :gsl_vector_div, [ :pointer, :pointer ], :int
+    attach_function :gsl_vector_scale, [ :pointer, :double ], :int
+    attach_function :gsl_vector_add_constant, [ :pointer, :double ], :int
+
+    # element access
+    attach_function :gsl_vector_get, [ :pointer, :size_t ], :double
+    attach_function :gsl_vector_set, [ :pointer, :size_t, :double ], :void
+
+    # properties
+    attach_function :gsl_vector_isnull, [ :pointer ], :int
+    attach_function :gsl_vector_ispos, [ :pointer ], :int
+    attach_function :gsl_vector_isneg, [ :pointer ], :int
+    attach_function :gsl_vector_isnonneg, [ :pointer ], :int
+
+    # max and min
+    attach_function :gsl_vector_max, [ :pointer ], :double
+    attach_function :gsl_vector_min, [ :pointer ], :double
+    attach_function :gsl_vector_minmax, [ :pointer, :buffer_out, :buffer_out ], :void
+    attach_function :gsl_vector_max_index, [ :pointer ], :size_t
+    attach_function :gsl_vector_min_index, [ :pointer ], :size_t
+    attach_function :gsl_vector_minmax_index, [ :pointer, :buffer_out, :buffer_out ], :void
+
+    # copying
+    attach_function :gsl_vector_memcpy, [ :pointer, :pointer ], :int
+
+    # exchanging elements
+    attach_function :gsl_vector_swap_elements, [ :pointer, :size_t, :size_t ], :int
+    attach_function :gsl_vector_reverse, [ :pointer ], :int
+
+    # BLAS functions
+    attach_function :gsl_blas_ddot, [ :pointer, :pointer, :buffer_out ], :int
+    attach_function :gsl_blas_dnrm2, [ :pointer ], :double
+    attach_function :gsl_blas_dasum, [ :pointer ], :double
+    #attach_function :gsl_blas_idamax, [ :pointer ], clbas_index??
+    #attach_function :gsl_blas_dcopy, use this instead of memcpy?
+    attach_function :gsl_blas_daxpy, [ :double, :pointer, :pointer ], :int
+    attach_function :gsl_blas_dscal, [ :double, :pointer ], :void
+
+    # Sorting
+    attach_function :gsl_sort_vector, [ :pointer ], :void
+    
+    # From local extension
+    # views
+    attach_function :gsl_vector_subvector2, [ :pointer, :size_t, :size_t ], :pointer
+    attach_function :gsl_vector_subvector_with_stride2, [ :pointer, :size_t, :size_t, :size_t ], :pointer
+  end
+end

data/lib/gslng/finalizer.rb

@@ -1,5 +1,9 @@
 module GSLng
-  def GSLng.set_finalizer(obj, func, ptr) # @private
-    ObjectSpace.define_finalizer(obj, lambda {|id| GSLng.backend.send(func, ptr)})
+  def GSLng.define_finalizer(obj, func, ptr) # @private
+    ObjectSpace.define_finalizer(obj, self.get_finalizer(func, ptr))
+  end
+  
+  def GSLng.get_finalizer(func, ptr) # @private
+    lambda {|id| GSLng.backend.send(func, ptr)}
   end
 end

data/lib/gslng/matrix.rb

@@ -2,75 +2,82 @@ module GSLng
   # A fixed-size MxN matrix.
   #
   # =Notes
-  # See Vector notes. Everything applies with the following differences/additions:
-  # * The * operator performs actual matrix-matrix and matrix-vector products. To perform element-by-element
-  #   multiplication use the ^ operator (or multiply method) instead. The rest of the operators work element-by-element.
-  # * Operators can handle matrix-matrix, matrix-vector and matrix-scalar (also in reversed order). See #coerce.
-  # * The [] and []= operators can handle a "wildcard" value for any dimension, just like MATLAB's colon (:).
+  # See Vector notes. Everything applies with the following *differences/additions*:
+  # * The {#*} operator performs actual matrix-matrix and matrix-vector products. To perform element-by-element
+  #   multiplication use the {#^} operator (or {#multiply} method) instead. The rest of the operators work element-by-element.
+  # * Operators can handle matrix-matrix, matrix-vector and matrix-scalar (also in reversed order). See {#coerce}.
+  # * The {#[]} and {#[]=} operators can handle a "wildcard" value for any dimension, just like MATLAB's colon (:).
   class Matrix
-		attr_reader :m, :n, :ptr
+    attr_reader :m, :n    
+    attr_reader :ptr # @private
 
-		alias_method :height, :m
-		alias_method :width, :n
-		alias_method :rows, :m
-		alias_method :columns, :n
+    alias_method :height, :m
+    alias_method :width, :n
+    alias_method :rows, :m
+    alias_method :columns, :n
 
-		# Returns [ #rows, #columns ]
-		def size; [ @m, @n ] end
+    # Shorthand for [{#rows},{#columns}]
+    def size; [ @m, @n ] end
 
     #--------------------- constructors -------------------------#
 
-		# Create a Matrix of m-by-n (rows and columns). If zero is true, the Matrix is initialized with zeros.
+    # Create a Matrix of m-by-n (rows and columns). If zero is true, the Matrix is initialized with zeros.
     # Otherwise, the Matrix will contain garbage.
-		# You can optionally pass a block, in which case #map_index! will be called with it (i.e.: it works like Array.new).
+    # You can optionally pass a block, in which case {#map_index!} will be called with it (i.e.: it works like Array.new).
     def initialize(m, n, zero = false)
       @ptr = (zero ? GSLng.backend::gsl_matrix_calloc(m, n) : GSLng.backend::gsl_matrix_alloc(m, n))
-      GSLng.set_finalizer(self, :gsl_matrix_free, @ptr)
+      GSLng.define_finalizer(self, :gsl_matrix_free, @ptr)
 
       @m,@n = m,n
-			if (block_given?) then self.map_index!(Proc.new) end
+      if (block_given?) then self.map_index!(Proc.new) end
     end
 
     def initialize_copy(other) # @private
       ObjectSpace.undefine_finalizer(self) # TODO: ruby bug?
       @ptr = GSLng.backend::gsl_matrix_alloc(other.m, other.n)
-      GSLng.set_finalizer(self, :gsl_matrix_free, @ptr)
+      GSLng.define_finalizer(self, :gsl_matrix_free, @ptr)
 
       @m,@n = other.size
       GSLng.backend::gsl_matrix_memcpy(@ptr, other.ptr)
     end
 
-		# Same as Matrix.new(m, n, true)
-		def Matrix.zero(m, n); Matrix.new(m, n, true) end
-
-		# Create a matrix from an Array
-    # If array is unidimensional, a row Matrix is created. If it is multidimensional, each sub-array
-    # corresponds to a row of the resulting Matrix. Also, _array_ can be an Array of Ranges, in which case
-    # each Range will correspond to a row.
-		def Matrix.from_array(array)
-			if (array.empty?) then raise "Can't create empty matrix" end
-
-      if (Numeric === array[0]) then
-        Matrix.new(1, array.size) {|i,j| array[j]}
+    # Same as Matrix.new(m, n, true)
+    def Matrix.zero(m, n); Matrix.new(m, n, true) end
+
+    # Create a matrix from an Array
+    # @see Matrix::[]
+    def Matrix.from_array(array)
+      if (array.empty?) then raise "Can't create empty matrix" end
+
+      if (Numeric === array[0])
+        m = Matrix.new(1, array.size)
+        GSLng.backend.gsl_matrix_from_array(m.ptr.to_i, [ array ])
+        return m
+      elsif (Array === array[0])
+        m = Matrix.new(array.size, array[0].size)
+        GSLng.backend.gsl_matrix_from_array(m.ptr.to_i, array)
+        return m
       else
         Matrix.new(array.size, array[0].to_a.size) {|i,j| array[i].to_a[j]}
       end
-		end
+    end
 
-		# Create a Matrix from an Array of Arrays/Ranges (see #from_array). For example:
-    #  Matrix[[1,2],[3,4]]
-    #  Matrix[1,2,3]
-    #  Matrix[[1..2],[5..10]]
-		def Matrix.[](*args)
+    # Create a Matrix from an Array/Array of Arrays/Range
+    # @example
+    #  Matrix[[1,2],[3,4]] => [1.0 2.0; 3.0 4.0]:Matrix
+    #  Matrix[1,2,3] => [1.0 2.0 3.0]:Matrix
+    #  Matrix[[1..3],[5..7]] => [1.0 2.0 3.0; 5.0 6.0 7.0]:Matrix
+    # @see Matrix::from_array    
+    def Matrix.[](*args)
       Matrix.from_array(args)
-		end
+    end
     
     # Generates a Matrix of m by n, of random numbers between 0 and 1.
-    # NOTE: This simply uses Kernel::rand
+    # NOTE: This simply uses {Kernel::rand}
     def Matrix.random(m, n)
-			Matrix.new(m, n).map!{|x| Kernel::rand}
+      Matrix.new(m, n).map!{|x| Kernel::rand}
     end
-		class << self; alias_method :rand, :random end
+    class << self; alias_method :rand, :random end
 
     #--------------------- setting values -------------------------#
 
@@ -87,139 +94,159 @@ module GSLng
 
     #--------------------- set/get -------------------------#
 
-		# Access the element (i,j), which means (row,column). *NOTE*: throws exception if out-of-bounds.
-		# If either i or j are :* or :all, it serves as a wildcard for that dimension, returning all rows or columns,
-		# respectively.
+    # Access the element (i,j), which means (row,column).
+    # Symbols :* or :all can be used as wildcards for both dimensions.
+    # @example If +m = Matrix[[1,2],[3,4]]+
+    #  m[0,0] => 1.0
+    #  m[0,:*] => [1.0, 2.0]:Matrix
+    #  m[:*,0] => [1.0, 3.0]:Matrix
+    #  m[:*,:*] => [1.0, 2.0; 3.0, 4.0]:Matrix
+    # @raise [RuntimeError] if out-of-bounds
+    # @return [Numeric,Matrix] the element/sub-matrix
     def [](i, j = :*)
-			if (Symbol === i && Symbol === j) then return self
-			elsif (Symbol === i)
-				col = Vector.new(@m)
-				GSLng.backend::gsl_matrix_get_col(col.ptr, @ptr, j)
-				return col
-			elsif (Symbol === j)
-				row = Vector.new(@n)
-				GSLng.backend::gsl_matrix_get_row(row.ptr, @ptr, i)
-				return row
-			else
-				GSLng.backend::gsl_matrix_get(@ptr, i, j)
-			end
-		end
-
-		# Set the element (i,j), which means (row,column). *NOTE*: throws exception if out-of-bounds.
-		# Same indexing options as #[].
-    # _value_ can be a single Numeric, a Vector or a Matrix, depending on the indexing.
+      if (Symbol === i && Symbol === j) then return self
+      elsif (Symbol === i)
+        col = Vector.new(@m)
+        GSLng.backend::gsl_matrix_get_col(col.ptr, @ptr, j)
+        return col.to_matrix
+      elsif (Symbol === j)
+        row = Vector.new(@n)
+        GSLng.backend::gsl_matrix_get_row(row.ptr, @ptr, i)
+        return row.to_matrix
+      else
+        GSLng.backend::gsl_matrix_get(@ptr, i, j)
+      end
+    end
+
+    # Set the element (i,j), which means (row,column).
+    # @param [Numeric,Vector,Matrix] value depends on indexing
+    # @raise [RuntimeError] if out-of-bounds
+    # @see #[]
     def []=(i, j, value)
-			if (Symbol === i && Symbol === j) then
-				if (Numeric === value) then self.fill!(value)
+      if (Symbol === i && Symbol === j) then
+        if (Numeric === value) then self.fill!(value)
         else
           x,y = self.coerce(value)
           GSLng.backend::gsl_matrix_memcpy(@ptr, x.ptr)
         end
-			elsif (Symbol === i)
-				col = Vector.new(@m)
+      elsif (Symbol === i)
+        col = Vector.new(@m)
         x,y = col.coerce(value)
-				GSLng.backend::gsl_matrix_set_col(@ptr, j, x.ptr)
-				return col
-			elsif (Symbol === j)
-  			row = Vector.new(@n)
+        GSLng.backend::gsl_matrix_set_col(@ptr, j, x.ptr)
+        return col
+      elsif (Symbol === j)
+        row = Vector.new(@n)
         x,y = row.coerce(value)
-				GSLng.backend::gsl_matrix_set_row(@ptr, i, x.ptr)
-				return row
-			else
-				GSLng.backend::gsl_matrix_set(@ptr, i, j, value)
-			end
+        GSLng.backend::gsl_matrix_set_row(@ptr, i, x.ptr)
+        return row
+      else
+        GSLng.backend::gsl_matrix_set(@ptr, i, j, value)
+      end
 
-			return self
-		end
+      return self
+    end
 
     #--------------------- view -------------------------#
 
-    # Create a Matrix::View from this Matrix.
-    # If either _m_ or _n_ are nil, they're computed from _x_, _y_ and the Matrix's #size
+    # Create a {Matrix::View} from this Matrix.
+    # If either _m_ or _n_ are nil, they're computed from _x_, _y_ and the Matrix's {#size}
+    # @return [Matrix::View]
     def view(x = 0, y = 0, m = nil, n = nil)
       View.new(self, x, y, (m or @m - x), (n or @n - y))
     end
     alias_method :submatrix_view, :view
     
-    # Shorthand for submatrix_view(..).to_matrix.
+    # Shorthand for #submatrix_view(..).to_matrix.
+    # @return [Matrix]
     def submatrix(*args); self.submatrix_view(*args).to_matrix end
 
-    # Creates a Matrix::View for the i-th column
+    # Creates a {Matrix::View} for the i-th column
+    # @return [Matrix::View]
     def column_view(i, offset = 0, size = nil); self.view(offset, i, (size or (@m - offset)), 1) end
 
-    # Analogous to #submatrix
+    # Analogous to {#submatrix}
+    # @return [Matrix]
     def column(*args); self.column_view(*args).to_matrix end
 
-    # Creates a Matrix::View for the i-th row
+    # Creates a {Matrix::View} for the i-th row
+    # @return [Matrix::View]
     def row_view(i, offset = 0, size = nil); self.view(i, offset, 1, (size or (@n - offset))) end
 
-    # Same as #row_view, but returns a Vector::View
+    # Analogous to {#submatrix}
+    # @return [Matrix]
+    def row(*args); self.row_view(*args).to_matrix end
+
+    # Same as {#row_view}, but returns a {Vector::View}
+    # @return [Vector::View]
     def row_vecview(i, offset = 0, size = nil)
       size = (@n - offset) if size.nil?
       ptr = GSLng.backend.gsl_matrix_row_view(self.ptr, i, offset, size)
       Vector::View.new(ptr, self, offset, size)
     end
 
-    # Same as #column_view, but returns a Vector::View
+    # Same as {#column_view}, but returns a {Vector::View}
+    # @return [Vector::View]
     def column_vecview(i, offset = 0, size = nil)
       size = (@m - offset) if size.nil?
       ptr = GSLng.backend.gsl_matrix_column_view(self.ptr, i, offset, size)
       Vector::View.new(ptr, self, offset, size)
     end
 
-    # Analogous to #submatrix
-    def row(*args); self.row_view(*args).to_matrix end
-
+    
     #--------------------- operators -------------------------#
 
     # Add other to self
+    # @return [Matrix] self
     def add!(other)
       case other
       when Numeric; GSLng.backend::gsl_matrix_add_constant(self.ptr, other.to_f)
       when Matrix; GSLng.backend::gsl_matrix_add(self.ptr, other.ptr)
       else
-				x,y = other.coerce(self)
-				x.add!(y)
-			end
-			return self
+        x,y = other.coerce(self)
+        x.add!(y)
+      end
+      return self
     end
 
     # Substract other from self
+    # @return [Matrix] self    
     def substract!(other)
       case other
       when Numeric; GSLng.backend::gsl_matrix_add_constant(self.ptr, -other.to_f)
       when Matrix; GSLng.backend::gsl_matrix_sub(self.ptr, other.ptr)
       else
-				x,y = other.coerce(self)
-				x.substract!(y)
-			end
-			return self
+        x,y = other.coerce(self)
+        x.substract!(y)
+      end
+      return self
     end
     alias_method :sub!, :substract!
 
     # Multiply (element-by-element) other with self
+    # @return [Matrix] self    
     def multiply!(other)
       case other
       when Numeric; GSLng.backend::gsl_matrix_scale(self.ptr, other.to_f)
       when Matrix; GSLng.backend::gsl_matrix_mul_elements(self.ptr, other.ptr)
       else
-				x,y = other.coerce(self)
-				x.multiply!(y)
-			end
-			return self
+        x,y = other.coerce(self)
+        x.multiply!(y)
+      end
+      return self
     end
     alias_method :mul!, :multiply!
 
     # Divide (element-by-element) self by other
+    # @return [Matrix] self    
     def divide!(other)
       case other
       when Numeric; GSLng.backend::gsl_matrix_scale(self.ptr, 1.0 / other)
       when Matrix;  GSLng.backend::gsl_matrix_div_elements(self.ptr, other.ptr)
       else
-				x,y = other.coerce(self)
-				x.divide!(y)
-			end
-			return self
+        x,y = other.coerce(self)
+        x.divide!(y)
+      end
+      return self
     end
     alias_method :div!, :divide!
 
@@ -237,8 +264,10 @@ module GSLng
     alias_method :multiply, :^
     alias_method :mul, :^
 
-    # Matrix Product. self#n should equal other#m (or other#size, if a Vector).
-    # TODO: some cases could be optimized when doing Matrix-Matrix, by using dgemv
+    # Matrix Product. self.n should equal other.m (or other.size, if a Vector).
+    # @example
+    #  Matrix[[1,2],[2,3]] * 2 => [2.0 4.0; 4.0 6.0]:Matrix
+    # @todo some cases could be optimized when doing Matrix-Matrix, by using dgemv
     def *(other)
       case other
       when Numeric
@@ -265,7 +294,10 @@ module GSLng
     # Returns the transpose of self, in a new matrix
     def transpose; matrix = Matrix.new(@n, @m); GSLng.backend::gsl_matrix_transpose_memcpy(matrix.ptr, self.ptr); return matrix end
 
+    # Swap the i-th and j-th columnos
     def swap_columns(i, j); GSLng.backend::gsl_matrix_swap_columns(self.ptr, i, j); return self end
+    
+    # Swap the i-th and j-th rows
     def swap_rows(i, j); GSLng.backend::gsl_matrix_swap_rows(self.ptr, i, j); return self end
     
     # Swap the i-th row with the j-th column. The Matrix must be square.
@@ -281,7 +313,7 @@ module GSLng
 
     #if all elements are strictly negative (<0)
     def negative?; GSLng.backend::gsl_matrix_isneg(@ptr) == 1 ? true : false end
-		
+    
     # if all elements are non-negative (>=0)
     def nonnegative?; GSLng.backend::gsl_matrix_isnonneg(@ptr) == 1 ? true : false end
 
@@ -296,7 +328,7 @@ module GSLng
     # Minimum element of the Matrix
     def min; GSLng.backend::gsl_matrix_min(self.ptr) end
 
-    # Same as Array#minmax
+    # Same as {Array#minmax}
     def minmax
       min = FFI::Buffer.new(:double)
       max = FFI::Buffer.new(:double)
@@ -304,7 +336,7 @@ module GSLng
       return [min[0].get_float64(0),max[0].get_float64(0)]
     end
 
-		# Same as #minmax, but returns the indices to the i-th and j-th min, and i-th and j-th max.
+    # Same as {#minmax}, but returns the indices to the i-th and j-th min, and i-th and j-th max.
     def minmax_index
       i_min = FFI::Buffer.new(:size_t)
       j_min = FFI::Buffer.new(:size_t)
@@ -312,10 +344,10 @@ module GSLng
       j_max = FFI::Buffer.new(:size_t)
       GSLng.backend::gsl_matrix_minmax_index(self.ptr, i_min, j_min, i_max, j_max)
       #return [min[0].get_size_t(0),max[0].get_size_t(0)]
-			return [i_min[0].get_ulong(0),j_min[0].get_ulong(0),i_max[0].get_ulong(0),j_max[0].get_ulong(0)]
+      return [i_min[0].get_ulong(0),j_min[0].get_ulong(0),i_max[0].get_ulong(0),j_max[0].get_ulong(0)]
     end
 
-    # Same as #min, but returns the indices to the i-th and j-th minimum elements
+    # Same as {#min}, but returns the indices to the i-th and j-th minimum elements
     def min_index
       i_min = FFI::Buffer.new(:size_t)
       j_min = FFI::Buffer.new(:size_t)
@@ -323,7 +355,7 @@ module GSLng
       return [i_min[0].get_ulong(0), j_min[0].get_ulong(0)]
     end
 
-    # Same as #max, but returns the indices to the i-th and j-th maximum elements
+    # Same as {#max}, but returns the indices to the i-th and j-th maximum elements
     def max_index
       i_max = FFI::Buffer.new(:size_t)
       j_max = FFI::Buffer.new(:size_t)
@@ -334,54 +366,80 @@ module GSLng
     #--------------------- block handling -------------------------#
 
     # Yields the specified block for each element going row-by-row
-    def each # :yields: elem
+    # @yield [elem]
+    def each 
       @m.times {|i| @n.times {|j| yield(self[i,j]) } }
     end
 
     # Yields the specified block for each element going row-by-row
-    def each_with_index # :yields: elem, i, j
+    # @yield [elem, i, j]
+    def each_with_index 
       @m.times {|i| @n.times {|j| yield(self[i,j], i, j) } }
     end
 
-    # Same as #each, but faster. The catch is that this method returns nothing.
-    def fast_each(block = Proc.new) #:yield: elem
-      GSLng.backend::gsl_matrix_each(self.ptr, block)
+    # Calls the block on each element of the matrix
+    # @yield [elem]
+    # @return [void]
+    def each(block = Proc.new) 
+      GSLng.backend::gsl_matrix_each(self.ptr.to_i, &block)
     end
-
-    # Yields the block for each row *view* (Matrix::View).
+    
+    # @see #each
+    # @yield [elem,i,j]
+    def each_with_index(block = Proc.new) 
+      GSLng.backend::gsl_matrix_each_with_index(self.ptr.to_i, &block)
+    end    
+
+    # Yields the block for each row *view* ({Matrix::View}).
+    # @yield [view]
     def each_row; self.rows.times {|i| yield(row_view(i))} end
 
-    # Same as #each_row, but yields Vector::View's
+    # Same as {#each_row}, but yields {Vector::View}'s
+    # @yield [vector_view]    
     def each_vec_row; self.rows.times {|i| yield(row_vecview(i))} end
 
-    # Same as #each_column, but yields Vector::View's
+    # Same as #each_column, but yields {Vector::View}'s
+    # @yield [vector_view]    
     def each_vec_column; self.columns.times {|i| yield(column_vecview(i))} end
 
-    # Yields the block for each column *view* (Matrix::View).
+    # Yields the block for each column *view* ({Matrix::View}).
+    # @yield [view]    
     def each_column; self.columns.times {|i| yield(column_view(i))} end
 
-		# Efficient map! implementation
-		def map!(block = Proc.new); GSLng.backend::gsl_matrix_map(@ptr, block); return self end
+    # Efficient {#map!} implementation
+    # @yield [elem]
+    def map!(block = Proc.new); GSLng.backend::gsl_matrix_map!(@ptr.to_i, &block); return self end
+
+    # Alternate version of {#map!}, in this case the block receives the index (row, column) as a parameter.
+    # @yield [i,j]
+    def map_index!(block = Proc.new); GSLng.backend::gsl_matrix_map_index!(@ptr.to_i, &block); return self end
 
-		# Alternate version of #map!, in this case the block receives the index as a parameter.
-		def map_index!(block = Proc.new); GSLng.backend::gsl_matrix_map_index(@ptr, block); return self end
+    # Similar to {#map_index!}, in this case it receives both the element and the index to it
+    # @yield [elem,i,j]
+    def map_with_index!(block = Proc.new); GSLng.backend::gsl_matrix_map_with_index!(@ptr.to_i, &block); return self end
 
-		# See #map!. Returns a Matrix.
-		def map(block = Proc.new); self.dup.map!(block) end
+    # @see #map!
+    # @return [Matrix]
+    # @yield [elem]
+    def map(block = Proc.new); self.dup.map!(block) end
 
     #--------------------- conversions -------------------------#
 
-    # Same as Array#join, for example:
+    # Same as {Array#join}
+    # @example
     #  Matrix[[1,2],[2,3]].join => "1.0 2.0 2.0 3.0"
     def join(sep = $,)
-			s = ''
-			GSLng.backend::gsl_matrix_each(@ptr, lambda {|e| s += (s.empty?() ? e.to_s : "#{sep}#{e}")})
-			return s
-		end
+      s = ''
+      self.each do |e|
+        s += (s.empty?() ? e.to_s : "#{sep}#{e}")
+      end
+      return s
+    end
 
-    # Converts the matrix to a String, separating each element with a space and each row with a ';' and a newline:
+    # Converts the matrix to a String, separating each element with a space and each row with a ';' and a newline.
+    # @example
     #  Matrix[[1,2],[2,3]] => "[1.0 2.0;\n 2.0 3.0]"
-		def to_s
+    def to_s
       s = '['
       @m.times do |i|
         s += ' ' unless i == 0
@@ -392,7 +450,14 @@ module GSLng
       end
 
       return s
-		end
+    end
+    
+    # Converts the matrix to an Array (of Arrays).
+    # @example
+    #  Matrix[[1,2],[2,3]] => [[1.0,2.0],[2.0,3.0]]
+    def to_a
+      GSLng.backend.gsl_matrix_to_a(self.ptr.to_i)
+    end
 
     def inspect # @private
       "#{self}:Matrix"
@@ -400,7 +465,7 @@ module GSLng
 
     # Coerces _other_ to be of Matrix class.
     # If _other_ is a scalar (Numeric) a Matrix filled with _other_ values is created.
-    # Vectors are coerced using Vector#to_matrix (which results in a row matrix).
+    # Vectors are coerced using {Vector#to_matrix} (which results in a row matrix).
     def coerce(other)
       case other
       when Matrix