redshift 1.3.15 → 1.3.16

data/lib/redshift/util/tracer.rb

@@ -0,0 +1,113 @@
+# Records values of variables over time.
+#
+# A Tracer manages a two-tier system typical of simulations: Object and
+# Variable. The Object tier is really a hash on arbitrary keys. The keys can be
+# simulation objects, or they can be strings, symbols, etc.
+#
+# The values of this hash are the the Variable tier. More precisely, each value
+# is another hash mapping variable name to Tracer::Var instances.
+#
+# The Tracer::Var class provides the primary per-variable functionality, and it
+# can be used without the Tracer class. For example, it could be attched
+# directly to the simulation object itself.
+#
+# The two-tier structure permits add/remove operations at the Object tier, which
+# is convenient when objects enter or leave a simulation. Keeping the Tracer
+# tiers separate from simulation objects makes it easier to run those objects
+# without tracing, or to change the tracing strategy.
+#
+class Tracer
+  require 'redshift/util/tracer/var'
+
+  attr_reader :var_map, :default_opts
+
+  # Construct a Tracer which passes the +default_opts+ on to each
+  # var, overridden by the opts passed to #add.
+  def initialize default_opts = {}
+    @var_map = {}
+    @default_opts = default_opts
+  end
+
+  # Adds an item to the list of things to be recorded during #run!.
+  #
+  # If no block is given, the +key+ must be an object which has an
+  # attribute +name+.
+  #
+  # If a block is given, then it is called during #run! to determine
+  # the value that is stored in the Tracer. The +key+ and +name+ can be
+  # anything and are significant only for looking up traces in the Tracer.
+  # If the block accepts an argument, the associated +Var+ object is passed.
+  #
+  def add key, name, opts={}, &block
+    @var_map[key] ||= {}
+    var = Var.new(key, name, default_opts.merge(opts), &block)
+    @var_map[key][name] = var
+  end
+
+  # If +name+ is given, remove the trace of that variable
+  # associated with +key+. If name is not given, remove all traces
+  # associated with +key+. The removed Tracer::Var or hash of such objects
+  # is returned.
+  def remove key, name = nil
+    if name
+      h = @var_map[key]
+      r = h.delete name
+      @var_map.delete key if h.empty?
+      r
+    else
+      @var_map.delete key
+    end
+  end
+
+  # Called during a sumulation to record traces. In RedShift, typically called
+  # in the evolve {..} block, or in action clauses of transitions, or in
+  # hook methods.
+  def run!
+    @var_map.each do |key, h|
+      h.each do |name, var|
+        var.run!
+      end
+    end
+  end
+
+  # Convenience method to get a Var or a hash of Vars. Returns +nil+ if not
+  # found.
+  def [](key, name = nil)
+    if name
+      h = @var_map[key]
+      h && h[name]
+    else
+      @var_map[key]
+    end
+  end
+
+  class MissingVariableError < StandardError; end
+  class MissingKeyError < StandardError; end
+
+  # Yield once for each var associated with the +key+, or just once if
+  # +name+ given.
+  def each_var(key, name = nil)
+    if name
+      var = self[key, name] or
+        raise MissingVariableError, "No such var, #{key}.#{name}"
+      yield var
+    else
+      h = @var_map[key] or
+        raise MissingKeyError, "No such key, #{key}"
+      h.each do |name, var|
+        yield var
+      end
+    end
+  end
+
+  # Make a variable (or all vars of a key) inactive. No data will be traced
+  # unti #start is called.
+  def stop(key, name = nil)
+    each_var(key, name) {|var| var.active = false}
+  end
+
+  # Make a variable (or all vars of a key) active.
+  def start(key, name = nil)
+    each_var(key, name) {|var| var.active = true}
+  end
+end

data/lib/redshift/util/tracer/trace.rb

@@ -0,0 +1,145 @@
+class Tracer
+  begin
+    require 'narray'
+
+  rescue LoadError
+    warn "Can't find narray lib;" +
+      " using Array instead of NVector for trace storage."
+    class Trace < Array
+      def initialize(*); super(); end
+    end
+
+  else
+    # A Trace is a linear store. Usually, the type of the stored data is
+    # homogenous and numeric. It is optimized for appending new data at the
+    # end of the store. Insertions are not efficient.
+    #
+    # If we have NArray, the we can use it for more compact storage than an
+    # array of ruby objects. The Trace class manages a list of fixed-size
+    # NVectors. Otherwise, if NArray is not available, Trace is just a ruby
+    # array.
+    class Trace
+      include Enumerable
+      
+      DEFAULT_TYPE = "float"
+
+      DEFAULT_CHUNK_SIZE = 128
+
+      # The +opts+ is a hash of the form:
+      #
+      #   { :type => t, :dims => nil or [d1,d2,...], :chunk_size => s }
+      #
+      # Strings may be used instead of symbols as the keys.
+      #
+      # The +type+ is passed to NVector.new. The +chunk_size+ is the size of
+      # each NVector. The +dims+ is the dimensions of each entry; default is
+      # +nil+, which means scalar entries, as does an empty array.
+      def initialize opts = {}
+        @type = (opts[:type] || opts["type"] || DEFAULT_TYPE).to_s
+        @chunk_size = opts[:chunk_size] || opts["chunk_size"] ||
+          DEFAULT_CHUNK_SIZE
+        @dims = opts[:dims] || opts["dims"] || []
+        @index_template = @dims.map {|d| true}
+        @index_template << nil
+        @nvector_new_args = [@type, *@dims] << @chunk_size
+        clear
+      end
+      
+      # Clear the trace. Does not affect any state of the Var, such as
+      # the period counter.
+      def clear
+        @chunk_list = []
+        @index = @chunk_size # index of next insertion
+      end
+
+      # Iterate over values. (Note that this iteration yields the complete
+      # data structure for a point in time, whereas NVector#each iterates over
+      # individual numbers.)
+      def each
+        last = @chunk_list.last
+        it = @index_template.dup
+        @chunk_list.each do |chunk|
+          if chunk == last and @index < @chunk_size
+            @chunk_size.times do |i|
+              break if i == @index
+              it[-1] = i
+              yield chunk[*it]
+            end
+          else
+            @chunk_size.times do |i|
+              it[-1] = i
+              yield chunk[*it]
+            end
+          end
+        end
+      end
+      
+      def size
+        (@chunk_list.size - 1) * @chunk_size + @index
+      end
+      
+      alias length size
+
+      def << item
+        if @index == @chunk_size
+          @chunk_list << NVector.new(*@nvector_new_args)
+          @index = 0
+        end
+        @index_template[-1] = @index
+        @chunk_list.last[*@index_template] = item
+        @index += 1
+        self
+      end
+      
+      alias push <<
+      
+      # This is an inefficient, but sometimes convenient, implementation
+      # of #[]. For efficiency, use the Enumerable methods, if possible, or 
+      # use #to_vector. This implementation does support negative indices.
+      def [](i)
+        if i.abs >= size
+          raise IndexError, "index out of range"
+        end
+        
+        i %= size
+        it = @index_template.dup
+        it[-1] = i % @chunk_size
+        @chunk_list[i / @chunk_size][*it]
+      end
+      
+      # This is the most efficient way to manipulate the data if Enumerable
+      # methods are not enough. It returns a copy of the trace data as a
+      # NVector, which supports a complete set of indexed collection methods and
+      # algebraic operations, including slicing, sorting, reshaping, statistics,
+      # and scalar and vector math. See NArray docs for details.
+      # Note that #[] works differently on NArray than the one defined above..
+      def to_vector
+        nva = @nvector_new_args.dup
+        nva[-1] = size
+        v = NVector.new(*nva)
+        last = @chunk_list.last
+        cs = @chunk_size
+        it = @index_template.dup
+        @chunk_list.each_with_index do |chunk, ci|
+          base = ci * @chunk_size
+          if chunk == last and @index < @chunk_size
+            it[-1] = base...base+@index
+            v[*it] = chunk[true, 0...@index]
+          else
+            it[-1] = base...base+cs
+            v[*it] = chunk
+          end
+        end
+        v
+      end
+      
+      def inspect
+        to_vector.inspect
+      end
+      
+      def to_s
+        entries.to_s
+      end
+    end
+  end
+end

data/lib/redshift/util/tracer/var.rb

@@ -0,0 +1,112 @@
+require 'sci/tracer/trace'
+
+class Tracer
+  # Represents the various options and controls associated with a variable
+  # being traced. The #trace attr holds the actual data. The Var object
+  # references the original object, and will therefore keep it from being GC-ed.
+  # If you want to retain the data without the object, keep only the #trace.
+  class Var
+    # Type affects precision and storage size. Can be any of the following
+    # strings, which are the same as the NArray scalar types:
+    #
+    #   "byte"   ::   1 byte unsigned integer
+    #   "sint"   ::   2 byte signed integer
+    #   "int"    ::   4 byte signed integer
+    #   "sfloat" ::   single precision float
+    #   "float"  ::   double precision float
+    #
+    attr_reader :type
+
+    # Chunk size is the size of the chunks (in values, not bytes) in which
+    # memory is allocated. Each chunk is a +Vector+; the list of chunks is
+    # a ruby array. This only needs to be adjusted for performance tuning.
+    attr_reader :chunk_size
+    
+    # Dimensions of each entry. A vlaue of +nil+ means scalar entries, as
+    # does an empty array. A value of [d1, d2...] indicates multidimensional
+    # data.
+    attr_reader :dims
+
+    # Is this var currently recording? See Tracer#stop and Tracer#start.
+    attr_accessor :active
+
+    # How many calls to #run! before trace is updated? A period of 0, 1, or
+    # nil means trace is updated on each call.
+    attr_accessor :period
+
+    # Counter to check for period expiration.
+    attr_accessor :counter
+
+    # Optional code to compute value, rather than use +name+. During #run!, the
+    # code will be called; if it accepts an arg, it will be passed the Var, from
+    # which #key and #name can be read. If code returns nil/false, no data is
+    # added to the trace.
+    attr_accessor :value_getter
+
+    # The +key+ can be either an object that has a named variable (accessed by
+    # the #name attr) or some arbitrary object (in which case a value_getter
+    # must be provided to compute the value).
+    attr_reader :key
+
+    # The name of the variable to access in the object.
+    attr_reader :name
+
+    # Stores the trace as a list of Vectors
+    attr_reader :trace
+
+    DEFAULT_TYPE = "float"
+
+    DEFAULT_CHUNK_SIZE = 128
+
+    DEFAULT_PERIOD = nil
+
+    # The +opts+ is a hash of the form:
+    #
+    #   { :type => t, :chunk_size => s,:dims => nil or [d1,d2,...],
+    #     :period => p }
+    #
+    # Strings may be used instead of symbols as the keys.
+    #
+    def initialize key, name, opts={}, &value_getter
+      @key, @name, @value_getter = key, name, value_getter
+
+      @type = (opts[:type] || opts["type"] || DEFAULT_TYPE).to_s
+      @chunk_size = opts[:chunk_size] || opts["chunk_size"] ||
+        DEFAULT_CHUNK_SIZE
+      @dims = opts[:dims] || opts["dims"] || []
+      @period = opts[:period] || opts["period"] || DEFAULT_PERIOD
+
+      @period = nil unless @period.kind_of?(Integer) and @period > 1
+      @counter = 0
+      @active = true
+      @trace = Trace.new(
+        :type => type, :chunk_size => chunk_size, :dims => dims)
+    end
+
+    def run!
+      return unless @active
+      
+      if @period
+        @counter += 1
+        return if @counter < @period
+        @counter = 0
+      end
+
+      result =
+        if (vg=@value_getter)
+          case vg.arity
+          when 0; vg.call
+          when 1,-1; vg.call(self)
+          else raise ArgumentError,
+            "value_getter for #{@key}.#{@name} must take 0 or 1 arguments"
+          end
+        else
+          @key.send @name
+        end
+
+      if result
+        @trace << result
+      end
+    end
+  end
+end

data/rakefile

@@ -25,10 +25,10 @@ END
 
   history_file    'RELEASE-NOTES'
   changes         File.read(history_file)[/^\w.*?(?=^\w)/m]
-  (rdoc.dir       File.readlink(rdoc.dir)) rescue nil
+  rdoc.dir        "rdoc" ## Note: doc dir has original content files
 
   spec.opts << '--color'
-  test.files = Dir["test/test-*.rb"]
+  test.files = Dir["test/test_*.rb"]
 }
 
 task :release => ["rubyforge:release", "rubyforge:doc_release"]

data/test/test_flow_trans.rb

@@ -1,24 +1,25 @@
 #!/usr/bin/env ruby
 
 require 'redshift'
-require 'sci/random'
-require 'isaac'
+require 'redshift/util/random'
+### TODO: add pure ruby ISAAC to util
+#require 'isaac'
 
-# Adaptor class to use ISAAC with sci/random distributions.
-class ISAACGenerator < ISAAC
-  def initialize(*seeds)
-    super()
-    if seeds.compact.empty?
-      seeds = [Random::Sequence.random_seed]
-    end
-    @seeds = seeds
-    srand(seeds)
-  end
-  
-  attr_reader :seeds
-
-  alias next rand
-end
+# Adaptor class to use ISAAC with redshift/util/random distributions.
+#class ISAACGenerator < ISAAC
+#  def initialize(*seeds)
+#    super()
+#    if seeds.compact.empty?
+#      seeds = [Random::Sequence.random_seed]
+#    end
+#    @seeds = seeds
+#    srand(seeds)
+#  end
+#  
+#  attr_reader :seeds
+#
+#  alias next rand
+#end
 
 include RedShift
 
@@ -69,13 +70,14 @@ class Flow_Transition < FlowTestComponent
   setup do
     self.x = 0
     @alarm_time = 0
-    @alarm_seq = Random::Exponential.new \
-      :generator => ISAACGenerator,
-      :seed => nil, # 614822716,
+    @alarm_seq = Random::Exponential.new(
+      #:generator => ISAACGenerator,
+      :seed => 614822716,
       :mean => 0.5
-    @state_seq = Random::Discrete.new \
-      :generator => ISAACGenerator,
-      :seed => nil, # 3871653669,
+    )
+    @state_seq = Random::Discrete.new(
+      #:generator => ISAACGenerator,
+      :seed => 3871653669, ## doesn't make sense to re-seed the same global gen
       :distrib =>
         {
           Alg   => 100,
@@ -83,9 +85,10 @@ class Flow_Transition < FlowTestComponent
           Euler => 100,
           Empty => 100
         }
+    )
     puts "\n\n  Flow_Transition used the following seeds:"
-    puts "  alarm seed = #{@alarm_seq.generator.seeds}"
-    puts "  state seed = #{@state_seq.generator.seeds}"
+    puts "  alarm seed = #{@alarm_seq.generator.seeds rescue @alarm_seq.generator.seed}"
+    puts "  state seed = #{@state_seq.generator.seeds rescue @state_seq.generator.seed}"
   end
   
   transition Enter => Switch,