numru-misc 0.1.1

data/lib/numru/misc/md_iterators.rb

@@ -0,0 +1,180 @@
+=begin
+=module NumRu::Misc::MD_Iterators
+
+A Mixin.
+To be included in a class with multi-dimension indexing support
+(such as NArray).
+
+==Index
+
+* ((<each_subary_at_dims>))
+* ((<each_subary_at_dims_with_index>))
+
+==Methods
+---each_subary_at_dims( *dims )
+
+    Iterator for each sub-array (not each element) specified by dimensions.
+
+    ARGUMENT
+    * ((|dims|)) (integers) : specifies subsets at dimensions 
+      specified here with the beginning-to-end selection. 
+      For example, [0, 1] to specify the first 2 dimensions 
+      (subsets will be 2D then), and [2] to specify the 3rd 
+      dimension (subsets will be 1D). Duplication has no effect, 
+      so [0,0] and [0] are the same. Also, its order has no effect.
+      See EXAMPLE below for more.
+
+    RETURN VALUE
+    * self
+
+    POSSIBLE EXCEPTIONS
+    * exception is raised if ( dims.min<0 || dims.max>=self.rank ).
+
+    EXAMPLE
+
+    * Suppose that you want to do something with 2D sub-arrays in a
+      multi-dimension NArray. First, you include this module as follows:
+
+        require "narray"
+        class NArray
+           include NumRu::Misc::MD_Iterators
+        end
+
+      And prepare the array if you have not (here, it is 4D):
+
+        na = NArray.int(10,2,5,2).indgen!
+
+      Then you do the job like this:
+
+        na.each_subary_at_dims(0,2){ |sub|
+          ...  # do whatever with sub
+        }
+
+      This is equivalent to the following:
+
+        (0...na.shape[3]).each{|j|
+          (0...na.shape[1]).each{|i|
+            sub = na[0..-1, i, 0..-1, j]
+            ...  # do whatever with sub
+          }
+        }
+
+      Note that the loop must be nested 3 times when (('na')) is a 5D array,
+      if the latter approach is used. On the other hand, it will still 
+      require the same single loop with the former.      
+
+---each_subary_at_dims_with_index( *dims )
+    Like ((<each_subary_at_dims>)) but the block takes two arguments:
+    subset and the subset specifier (index).
+
+    EXAMPLE
+    * Suppose the example above in ((<each_subary_at_dims>)) (EXAMPLE).
+      And suppose that you want to overwrite (('na')) with the result
+      you get. You can do it like this:
+
+        na.each_subary_at_dims_with_index(0,2){ |sub,idx|
+          result = (sub + 10) / 2
+          na[*idx] = result
+        }
+
+      Here, (('idx')) is an Array to be fed in the []= or [] methods
+      with asterisk (ungrouping).
+=end
+
+module NumRu
+  module Misc
+    module MD_Iterators
+
+      def each_subary_at_dims( *dims )
+	if dims.min<0 || dims.max>=rank
+	  raise ArguemntError,"Invalid dims #{dims.inspect} for #{rank}D array"
+	end
+
+	loopdims = Array.new
+	sh = Array.new
+	len = 1
+	(0...rank).each{|i| 
+	  if !dims.include?(i)
+	    loopdims.push(i) 
+	    sh.push(shape[i])
+	    len *= shape[i]
+	  end
+	}
+	if loopdims.length == 0
+	  yield(self)
+	  return self
+	end
+	cs = [1]
+	(1...sh.length).each{|i| cs[i] = sh[i-1]*cs[i-1]}
+	idx = Array.new
+	all = 0..-1
+	for i in 0...len do
+	  loopdims.each_with_index{|d,j| idx[d] = ( (i/cs[j])%sh[j] )}
+	  dims.each{|d| idx[d] = all}
+	  sub = self[ *idx ]
+	  yield(sub)
+	end
+	self
+      end
+
+      def each_subary_at_dims_with_index( *dims )
+	if dims.min<0 || dims.max>=rank
+	  raise ArguemntError,"Invalid dims #{dims.inspect} for #{rank}D array"
+	end
+
+	loopdims = Array.new
+	sh = Array.new
+	len = 1
+	(0...rank).each{|i| 
+	  if !dims.include?(i)
+	    loopdims.push(i) 
+	    sh.push(shape[i])
+	    len *= shape[i]
+	  end
+	}
+	if loopdims.length == 0
+	  yield(self, false)
+	  return self
+	end
+	cs = [1]
+	(1...sh.length).each{|i| cs[i] = sh[i-1]*cs[i-1]}
+	idx = Array.new
+	all = 0..-1
+	for i in 0...len do
+	  loopdims.each_with_index{|d,j| idx[d] = ( (i/cs[j])%sh[j] )}
+	  dims.each{|d| idx[d] = all}
+	  sub = self[ *idx ]
+	  yield(sub, idx)
+	end
+	self
+      end
+
+    end
+  end
+end
+
+##################################
+
+if __FILE__ == $0
+  require "narray"
+  class NArray
+    include NumRu::Misc::MD_Iterators
+  end
+  na = NArray.int(10,2,2,2).indgen!
+  puts "** test A **"
+  na.each_subary_at_dims(0,1){ |sub|
+    p sub
+  }
+  puts "** test B **"
+  na.each_subary_at_dims(0,3){ |sub|
+    p sub
+  }
+  puts "** test C **"
+  na.each_subary_at_dims(2,1,0){ |sub|     # same as (0,1,2)
+    p sub
+  }
+  puts "** test C **"
+  na.each_subary_at_dims(0,1,2,3){ |sub|
+    p sub
+  }
+end

data/lib/numru/misc/misc.rb

@@ -0,0 +1,196 @@
+=begin
+= module NumRu::Misc
+
+== Overview
+
+Miscellaneous functions and classes to facilitate programming.
+
+== Index
+
+CLASSES
+
+* ((<class KeywordOpt|URL:keywordopt.html>))
+  to support keyward arguments with default values.
+* ((<class NArray (enhancement of NArray made by M Tanaka)|URL:narray_ext.html>))
+
+MODULES
+
+* ((<module MD_Iterators|URL:md_iterators.html>)) A Mixin for classes with
+  multi-dimension indexing support (such as NArray).
+* ((<module EMath|URL:emath.html>)) 
+  To be included instead of the Math predefined module (or NMath in NArray).
+  Unlike Math and NMath, EMath handles unknown classes by calling its
+  native instance method (assuming the same name).
+
+
+MODULE FUNCTIONS
+
+* ((<check_shape_consistency>))
+
+== Module functions
+---check_shape_consistency(cshapes, *args)
+     Check the consistency of array shapes (multi-dim such as NArray).
+     Exception is raised if inconsistent.
+
+     ARGUMENTS
+     * cshapes (String) : description of the shapes of the args.
+       Delimited by one-or-more spaces between arrays,
+       and the shape of each array is delimited by a comma. The lengths are 
+       expressed with string names as identifiers (in that case, length 
+       values are unquestioned) or specified as positive integers.
+       Use '..' or '...' for repetition of the last shape.
+       See EXAMPLES below.
+
+     * args (multi-dim arrays such as NArray): arrays to be checked
+
+     RETURN VALUE
+     * nil
+
+     POSSIBLE EXCEPTIONS
+     * exception is raised if cshapes and args are inconsistent:
+       
+       * RuntimeError, if the arrays do not have shapes specified by cshapes.
+
+       * ArgeumentError, if the number of args are inconsistent with cshapes. 
+         This is likely a coding error of the user.
+
+     EXAMPLES
+
+     *  to check whether three arrays u, v, and w are shaped as
+        u[nx], v[ny], and w[nx,ny], where nx and ny are any integer:
+
+           NumRu::Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
+
+        Or equivalently,
+
+           NumRu::Misc.check_shape_consistency('m  n  m,n',u,v,w)
+
+        because actual strings does not matter.
+
+     * To specify fixed lengths, use integers instead of names:
+
+           NumRu::Misc.check_shape_consistency('4  n  4,n',u,v,w)
+
+       In this case, u,v,w must have shapes [4], [ny], and [4,ny],
+       where ny is any length.
+
+     * Use '..' or '...' to repeat the same shape:
+
+           NumRu::Misc.check_shape_consistency('nx,ny ...',u,v,w)
+
+       This ensures that u, v, and w are 2D arrays with the same shape.
+       Note: '..' and '...' are the same, so you can use whichever you like.
+
+=end
+
+require "narray"
+
+module NumRu
+   module Misc
+      module_function
+
+      def check_shape_consistency(cshapes, *args)
+	 ranks = Array.new
+	 elm2idx = Hash.new
+	 spl = cshapes.split(' +')
+	 if spl.length >= 2 && /^\.\.\.?$/ =~ spl[-1]  # '..' or '...'
+            ((spl.length-1)...args.length).each{|i|
+	       spl[i]=spl[i-1]
+	    }	       
+	 end
+	 if spl.length != args.length
+	    raise ArgumentError,"# of the argument (#{args.length}) is inconsistent with the 1st arg '#{cshapes}'"
+	 end
+         spl.each_with_index{|csh,i| 
+	    sh = csh.split(',')
+	    ranks.push( sh.length )
+	    sh.each_with_index{|tag,j|
+	       elm2idx[tag] = Array.new if !elm2idx[tag]
+	       elm2idx[tag].push([i,j])
+	    }
+	 }
+	 ranks.each_with_index{|len,i|
+	    if args[i].rank != len
+	       raise "(#{i+1}th arg) unexepected rank #{args[i].rank} for #{len}"
+	    end
+	 }
+	 elm2idx.each{|tag,ary|
+	    if tag.to_i > 0   # numeric (positive integer)
+	       size = tag.to_i
+	       start = 0
+	    else              # alphabet
+	       size = args[ary[0][0]].shape[ary[0][1]]
+	       start = 1
+	    end
+	    (start...ary.length).each{|i|
+	       if args[ary[i][0]].shape[ary[i][1]] != size
+		  if start == 0
+		     raise "length of dim #{ary[i][1]} of #{ary[i][0]+1}th "+
+                           "arg is unexpected " +
+                           "(#{args[ary[i][0]].shape[ary[i][1]]} for #{size})"
+		  else
+		     raise "Dimension lengths inconsistent between "+
+			"dim #{ary[0][1]} of #{ary[0][0]+1}th arg and " +
+		        "dim #{ary[i][1]} of #{ary[i][0]+1}th arg"
+		  end
+	       end
+	    }
+	 }
+	 nil
+      end
+
+   end
+end
+
+if __FILE__ == $0
+   include NumRu
+
+   puts '* test A *'
+   u = NArray.float(3)
+   v = NArray.float(5)
+   w = NArray.float(3,5)
+   Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
+   puts ' OK'
+   Misc.check_shape_consistency('3 ny 3,ny',u,v,w)
+   puts ' OK'
+   begin
+      Misc.check_shape_consistency('6 ny 6,ny',u,v,w)
+   rescue
+      puts "  exception raised as expected\n"+$!
+      puts ' OK'
+   end
+
+   puts '* test B *'
+   Misc.check_shape_consistency('nx,ny ...',w,w,w,w)
+   puts ' OK'
+
+   puts '* test C *'
+   begin
+      u = NArray.float(4)
+      v = NArray.float(5)
+      w = NArray.float(3,5)
+      Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
+   rescue
+      puts "  exception raised as expected\n"+$!
+      puts ' OK'
+   end
+
+   puts '* test D *'
+   begin
+      u = NArray.float(3,5)
+      v = NArray.float(5)
+      w = NArray.float(3,5)
+      Misc.check_shape_consistency('nx ny nx,ny',u,v,w)
+   rescue
+      puts "  exception raised as expected\n"+$!
+      puts ' OK'
+   end
+
+   puts '* test E *'
+   u = NArray.float(3,5,7)
+   v = NArray.float(5)
+   w = NArray.float(3,5)
+   1000.times{ Misc.check_shape_consistency('nx,ny,nz ny nx,ny',u,v,w) }
+   puts ' OK'
+
+end

data/makedoc.csh

@@ -0,0 +1,6 @@
+#!/bin/csh
+rd2 lib/numru/misc/misc.rb >! doc/misc.html
+\cp -pf doc/misc.html doc/index.html
+rd2 lib/numru/misc/keywordopt.rb >! doc/keywordopt.html
+rd2 lib/numru/misc/md_iterators.rb >! doc/md_iterators.html
+rd2 lib/numru/misc/emath.rb >! doc/emath.html

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification 
+name: numru-misc
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Takeshi Horinouchi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-02-20 00:00:00 +09:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: narray
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: Miscellaneous functions and classes to help Ruby programming. To be used in other NumRu libraries.
+email: 
+- eriko@gfd-dennou.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- install.rb
+- LICENSE.txt
+- ChangeLog
+- makedoc.csh
+- lib/numru/misc/keywordopt.rb
+- lib/numru/misc/md_iterators.rb
+- lib/numru/misc/misc.rb
+- lib/numru/misc/emath.rb
+- lib/numru/misc.rb
+- doc/emath.html
+- doc/md_iterators.html
+- doc/keywordopt.html
+- doc/misc.html
+- doc/index.html
+has_rdoc: true
+homepage: http://www.gfd-dennou.org/arch/ruby/products/numru-misc/
+licenses: 
+- Takeshi Horinouchi
+- GFD Dennou Club
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 1
+      - 6
+      version: "1.6"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Collection of miscellaneous functions and classes to facilitate programming.
+test_files: []
+