fathom 0.1.0 → 0.2.0

data/.gitignore

@@ -3,3 +3,4 @@
 coverage
 rdoc
 pkg
+*.gemspec

data/README.md

@@ -26,7 +26,8 @@ Usage
 =====
 
 Enrico Fermi [said](http://www.lucidcafe.com/library/95sep/fermi.html):
-    There are two possible outcomes: if the result confirms the hypothesis, then you've made a measurement. If the result is contrary to the hypothesis, then you've made a discovery. 
+    There are two possible outcomes: if the result confirms the hypothesis, then you've made a measurement. 
+    If the result is contrary to the hypothesis, then you've made a discovery. 
 
 To put together a hypothesis, we gather what we know about our problem: 
 

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/fathom.rb

@@ -7,23 +7,9 @@ $:.unshift(File.dirname(__FILE__))
 $:.unshift(File.expand_path(File.join(File.dirname(__FILE__), 'fathom')))
 
 require "gsl"
-require 'ostruct'
 require 'options_hash'
 
-# Fix a few bugs in OpenStruct
-class OpenStruct
-  def table
-    @table
-  end
-  
-  def values
-    @table.values
-  end
-  
-  def keys
-    @table.keys
-  end
-end
+require 'ext/open_struct'
 
 module Fathom
   lib = File.expand_path(File.dirname(__FILE__))
@@ -55,10 +41,19 @@ module Fathom
   autoload :SQLiteImport, 'import/sqlite_import'
   
   autoload :NodeUtilities, 'node_utilities'
+  
+  autoload :Simulation, 'simulation'
+  autoload :TickMethods, 'simulation/tick_methods'
+  autoload :TickSimulation, 'simulation/tick_simulation'
+
+  autoload :Agent, 'agent'
+  autoload :Properties, 'agent/properties'
+  autoload :AgentCluster, 'agent/agent_cluster'
 
   def knowledge_base
     @knowledge_base ||= KnowledgeBase.new
   end
+  alias :kb :knowledge_base
 end
 
 # Temporary

data/lib/fathom/agent.rb

@@ -0,0 +1,49 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'fathom'))
+class Fathom::Agent
+
+  # =================
+  # = Class Methods =
+  # =================
+  class << self
+    def define_node_accessor(name, node)
+      method_name = ("node_for_" + name.to_s.downcase.gsub(/\s+/, '_')).to_sym
+      define_method(method_name) do
+        node
+      end
+    end
+  end
+  
+  include Properties
+  
+  def initialize(opts={})
+    self.class.define_property_states
+    assert_node_accessors(opts)
+  end
+  
+  def states
+    @states ||= self.class.properties.inject({}) do |h, state_method_name|
+      h[state_method_name] = nil
+      h
+    end
+  end
+  
+  def callbacks
+    @callbacks ||= (self.methods - Object.methods).grep(/^on_(\w+)/)
+  end
+  
+  protected
+    def assert_node_accessors(nodes)
+      nodes.each do |name, node|
+        next unless self.class.properties.include?(name)
+        states[name] = node.respond_to?(:rand) ? node.rand : node
+        self.class.define_node_accessor(name, node)
+      end
+    end
+  
+end
+
+if __FILE__ == $0
+  include Fathom
+  # TODO: Is there anything you want to do to run this file on its own?
+  # Agent.new
+end

data/lib/fathom/agent/agent_cluster.rb

@@ -0,0 +1,23 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'fathom'))
+
+=begin
+  This class is designed to hold a cluster of agents in memory.  It runs the  simulation locally and
+  speaks to other clusters via EventMachine.  In this way, we don't need a Ruby runtime/thread/fiber
+  for each agent, just one per dozen/hundred/thousand agents, depending on what balances the 
+  simulation.
+=end
+class Fathom::AgentCluster
+  
+  attr_reader :agents
+  
+  def initialize(*agents)
+    @agents = agents
+  end
+  
+end
+
+if __FILE__ == $0
+  include Fathom
+  # TODO: Is there anything you want to do to run this file on its own?
+  # AgentCluster.new
+end

data/lib/fathom/agent/properties.rb

@@ -0,0 +1,48 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'fathom'))
+module Fathom
+  module Properties
+    
+    def self.included(base)
+      base.send(:extend, ClassMethods)
+    end
+    
+    module ClassMethods
+      
+      def properties
+        @properties ||= []
+      end
+      
+      def property(name, opts={})
+        self.properties << name_sym(name)
+      end
+      
+      def define_property_states
+        return true if @property_states_defined
+        self.properties.each do |state_method_name|
+          unless self.instance_methods.include?(state_method_name.to_s)
+            define_method(state_method_name) do
+              states[state_method_name]
+            end
+          end
+          
+          state_method_writer = "#{state_method_name}=".to_sym
+          unless self.instance_methods.include?(state_method_writer.to_s)
+            define_method(state_method_writer) do |value|
+              states[state_method_name] = value
+            end
+          end
+        end
+        
+        @property_states_defined = true
+      end
+
+      protected
+        def name_sym(name)
+          name.to_s.downcase.gsub(/\s+/, '_').to_sym
+        end
+        
+    end
+  end
+end
+
+

data/lib/fathom/ext/faster_csv.rb

@@ -0,0 +1 @@
+FasterCSV::HeaderConverters[:strip] = lambda{|h| h.strip}

data/lib/fathom/ext/open_struct.rb

@@ -0,0 +1,17 @@
+require 'ostruct'
+
+# Fix a few bugs in OpenStruct
+class OpenStruct
+  def table
+    @table
+  end
+  
+  def values
+    @table.values
+  end
+  
+  def keys
+    @table.keys
+  end
+end
+

data/lib/fathom/import.rb

@@ -35,6 +35,13 @@ require File.expand_path(File.join(File.dirname(__FILE__), '..', 'fathom'))
 =end  
 class Fathom::Import
   
+  class << self
+    def import(opts={})
+      importer = new(opts)
+      importer.import
+    end
+  end
+  
   attr_reader :content, :options
   
   def initialize(opts={})
@@ -47,7 +54,8 @@ class Fathom::Import
     import_methods.each do |method|
       klass, initialization_data = self.send(method.to_sym)
       initialization_data.each do |values|
-        results << extract_nodes(klass, values)
+        node = extract_nodes(klass, values)
+        results << node if node
       end
     end
     results
@@ -55,10 +63,15 @@ class Fathom::Import
   
   protected
   
+    # Just blankly try to initiate a node.  If it fails, silently fail for now.
     def extract_nodes(klass, values)
-      node = klass.new(values)
-      Fathom.knowledge_base[node.name] = node
-      node
+      begin
+        node = klass.new(values)
+        Fathom.knowledge_base[node.name] = node
+        node
+      rescue
+        nil
+      end
     end
     
     def import_methods

data/lib/fathom/import/csv_import.rb

@@ -4,6 +4,7 @@ require 'open-uri'
 
 # TODO: Work this out with Ruby 1.9.  We don't need to load this for all Rubies.
 require 'fastercsv'
+require 'ext/faster_csv'
  
 module Fathom
   class CSVImport < Import
@@ -23,7 +24,7 @@ module Fathom
     def parse_options
       return @parse_options if @parse_options
       @parse_options = @options[:parse_options]
-      @parse_options ||= {:converters => [:all], :headers => true, :skip_blanks => true}
+      @parse_options ||= {:converters => [:all], :headers => true, :skip_blanks => true, :header_converters => [:strip, :symbol]}
       @parse_options
     end
     

data/lib/fathom/import/yaml_import.rb

@@ -1,5 +1,6 @@
 require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'fathom'))
 require 'open-uri'
+require 'yaml'
 
 class Fathom::YAMLImport < Import
   def import_plausible_ranges
@@ -31,7 +32,8 @@ class Fathom::YAMLImport < Import
         name, value = array.first, array.last
         if value.is_a?(Hash)
           value = OptionsHash.new(value)
-          list << value.merge(:name => name) if value[:min] and value[:max]
+          # list << value.merge(:name => name) if value[:min] and value[:max]
+          list << value.merge(:name => name)
         end
         list 
       end

data/lib/fathom/knowledge_base.rb

@@ -1,17 +1,29 @@
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'fathom'))
 class Fathom::KnowledgeBase
   
+  attr_reader :data_store
+  
   def initialize(opts={})
     opts = OptionsHash.new(opts)
-    @data_store = {}
+    @data_store = OpenStruct.new
   end
   
   def []=(key, value)
-    @data_store[key] = value
+    @data_store.table[key] = value
   end
   
   def [](key)
-    @data_store[key]
+    @data_store.table[key]
+  end
+  
+  # This is temporary, but useful for now.  After we have the persisted KnowledgeBase, 
+  # we'll create explicit accessor methods or a find syntax.
+  def method_missing(sym, *args, &block)
+    if @data_store.table.keys.include?(sym)
+      @data_store.send(sym)
+    else
+      super
+    end
   end
   
 end

data/lib/fathom/plausible_range.rb

@@ -52,7 +52,11 @@ module Fathom
     
     # Not using specific distributions yet
     def rand
-      rng.gaussian(std) + midpoint
+      value = get_rand
+      until is_bounded?(value) do
+        value= get_rand
+      end
+      value
     end
     
     def array_of_random_values(n=10)
@@ -66,6 +70,22 @@ module Fathom
     alias :to_v :vector_of_random_values
     
     protected
+    
+      def is_bounded?(value)
+        return true unless hard_lower_bound or hard_upper_bound
+        if hard_lower_bound and hard_upper_bound
+          value >= hard_lower_bound and value <= hard_upper_bound
+        elsif hard_lower_bound
+          value >= hard_lower_bound
+        elsif hard_upper_bound
+          value <= hard_upper_bound
+        end
+      end
+    
+      def get_rand
+        rng.gaussian(std) + midpoint
+      end
+      
       def rng
         @rng ||= GSL::Rng.alloc
       end

data/lib/fathom/simulation.rb

@@ -0,0 +1,59 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'fathom'))
+class Fathom::Simulation
+  
+  class << self
+    
+    # Expects a symbol for the callback to define on the simulation.
+    def define_callback_accessor(callback, obj)
+      call_method = callback.to_s.scan(/^on_(\w+)/).flatten.compact.first
+      raise ArgumentError, "Callback doesn't appear to be a callback: #{callback}" unless call_method
+      return true if self.respond_to?(call_method)
+      define_method(call_method) do
+        callbacks[callback].each do |agent|
+          agent.send(callback, obj)
+        end
+      end
+      
+      agent_lookup_method = "agents_using_#{call_method}".to_sym
+      return true if self.respond_to?(agent_lookup_method)
+      define_method(agent_lookup_method) do
+        callbacks[callback]
+      end
+      
+    end
+  end
+  
+  attr_reader :agents
+  
+  def initialize(*agents)
+    @agents = agents
+    assert_callbacks
+  end
+  
+  def callbacks
+    @callbacks ||= {}
+  end
+  
+  protected
+    def assert_callbacks
+      self.agents.each do |agent|
+        assert_agent(agent)
+      end
+    end
+    
+    def assert_agent(agent)
+      return false unless agent.respond_to?(:callbacks)
+      agent.callbacks.each do |callback|
+        callback_sym = callback.to_sym
+        self.callbacks[callback_sym] ||= []
+        self.callbacks[callback_sym] << agent
+        self.class.define_callback_accessor(callback_sym, self)
+      end
+    end
+end
+
+if __FILE__ == $0
+  include Fathom
+  # TODO: Is there anything you want to do to run this file on its own?
+  # Simulation.new
+end

data/lib/fathom/simulation/tick_methods.rb

@@ -0,0 +1,25 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'fathom'))
+module Fathom
+  module TickMethods
+    def initialize(*agents)
+      super(*agents)
+    end
+    
+    attr_reader :ticks_designed, :ticks_executed
+    
+    def process(n)
+      @ticks_designed = n
+      @ticks_executed = 0
+      n.times do
+        self.tick(self)
+        @ticks_executed += 1
+      end
+    end
+  end
+end
+
+if __FILE__ == $0
+  include Fathom
+  # TODO: Is there anything you want to do to run this file on its own?
+  # TicksSimulation.new
+end

data/lib/fathom/simulation/tick_simulation.rb

@@ -0,0 +1,12 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'fathom'))
+module Fathom
+  class TickSimulation < Simulation
+    include TickMethods
+  end
+end
+
+if __FILE__ == $0
+  include Fathom
+  # TODO: Is there anything you want to do to run this file on its own?
+  # TickSimulator.new
+end

data/spec/fathom/agent/agent_cluster_spec.rb

@@ -0,0 +1,17 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+include Fathom
+
+describe AgentCluster do
+  
+  before do
+    @agent = double()
+    @agents = [@agent]
+  end
+  
+  it "should initialize with a set of agents" do
+    @ac = AgentCluster.new @agent
+    @ac.agents.should eql(@agents)
+  end
+  
+end

data/spec/fathom/agent_spec.rb

@@ -0,0 +1,51 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+include Fathom
+
+describe Agent do
+  
+  before do
+    @pr1 = PlausibleRange.new(:min => 1, :max => 2)
+    @pr2 = PlausibleRange.new(:min => 10, :max => 11)
+    @da = DemoAgent.new(:field1 => @pr1, :field2 => @pr2)
+  end
+  
+  it "should be have a list of properties" do
+    DemoAgent.properties.should eql([:field1, :field2])
+  end
+  
+  it "should be able to set a seed node for each property defined in the class" do
+    @da.node_for_field1.should eql(@pr1)
+    @da.node_for_field2.should eql(@pr2)
+  end
+  
+  it "should not set a seed node for a node that doesn't have a property" do
+    da = DemoAgent.new(:field1 => @pr1, :field2 => @pr2, :field3 => :should_not_be_found)
+    da.should_not be_respond_to(:node_for_field3)
+  end
+  
+  it "should have a state accessor for each property" do
+    @da.should be_respond_to(:field1)
+    @da.should be_respond_to(:field1=)
+    @da.should be_respond_to(:field2)
+    @da.should be_respond_to(:field2=)
+  end
+  
+  it "should set the initial state of each property from the seed node, if defined" do
+    @pr1.should_receive(:rand).and_return(1.5)
+    @pr2.should_not_receive(:rand)
+    @da = DemoAgent.new(:field1 => @pr1)
+    @da.field1.should eql(1.5)
+    @da.field2.should be_nil
+  end
+  
+  it "should be able to send a hard parameter and save it in a property" do
+    @da = DemoAgent.new(:field1 => 2)
+    @da.field1.should eql(2)
+  end
+  
+  it "should expose the callbacks, those methods starting with on_" do
+    @da.callbacks.should eql(["on_tick"])
+  end
+  
+end

data/spec/fathom/import/csv_import_spec.rb

@@ -33,4 +33,14 @@ describe CSVImport do
     @result[2].values.should eql([3,6,9])
   end
   
+  it "should store the imported values in the knowledge base" do
+    Fathom.knowledge_base[:this].should be_a(DataNode)
+    Fathom.kb[:this].values.should eql([1,4,7])
+  end
+
+  it "should import from the class level" do
+    CSVImport.import(@opts)
+    Fathom.knowledge_base[:this].should be_a(DataNode)
+    Fathom.kb[:this].values.should eql([1,4,7])
+  end
 end

data/spec/fathom/import/yaml_import_spec.rb

@@ -37,4 +37,15 @@ describe YAMLImport do
     data_node.values.should eql([10,20,30])
   end
   
+  it "should store the imported values in the knowledge base" do
+    Fathom.knowledge_base['CO2 Emissions'].should be_a(PlausibleRange)
+    Fathom.kb['CO2 Emissions'].min.should eql(1_000_000)
+  end
+  
+  it "should import from the class level" do
+    YAMLImport.import(@opts)
+    Fathom.knowledge_base['CO2 Emissions'].should be_a(PlausibleRange)
+    Fathom.kb['CO2 Emissions'].min.should eql(1_000_000)
+  end
+  
 end

data/spec/fathom/import_spec.rb

@@ -11,7 +11,7 @@ describe Import do
     @values = [1,2,3,4,5]
   end
   
-  it "should initialize with a optional content" do
+  it "should initialize with optional content" do
     @i.content.should eql(@content)
   end
 
@@ -19,4 +19,8 @@ describe Import do
     @i.options.should eql(@options)
   end
   
+  it "should have a class-level import method" do
+    Import.should be_respond_to(:import)
+  end
+  
 end

data/spec/fathom/plausible_range_spec.rb

@@ -127,4 +127,26 @@ describe PlausibleRange do
     pr.name_sym.should eql(:demo_node)
   end
   
+  it "should not exceed the lower bound if it is set", :slow => true do
+    pr = PlausibleRange.new(:max => 100, :hard_lower_bound => 0)
+    1_000.times do
+      (pr.rand >= 0).should eql(true)
+    end
+  end
+  
+  it "should not exceed the upper bound if it is set", :slow => true do
+    pr = PlausibleRange.new(:min => 0, :hard_upper_bound => 100)
+    1_000.times do
+      (pr.rand <= 100).should eql(true)
+    end
+  end
+  
+  it "should not exceed the lower bound or upper bound if both are set", :slow => true do
+    pr = PlausibleRange.new(:hard_upper_bound => 100, :hard_lower_bound => 0)
+    1_000.times do
+      r = pr.rand
+      (r >= 0 and r <= 100).should eql(true)
+    end
+  end
+  
 end

data/spec/fathom/simulation/tick_simulation_spec.rb

@@ -0,0 +1,32 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+
+include Fathom
+
+describe TickSimulation do
+  
+  before do
+    @da = DemoAgent.new
+  end
+  
+  it "should process with n ticks" do
+    @da.should_receive(:on_tick).exactly(3).times.and_return(true)
+    s = TickSimulation.new(@da)
+    s.process(3)
+  end
+  
+  it "should expose the number of ticks designed and executed after processing" do
+    s = TickSimulation.new(@da)
+    s.process(4)
+    s.ticks_designed.should eql(4)
+    s.ticks_executed.should eql(4)
+  end
+  
+  # Any calls coming top down (from the simulator or the agent cluster), will need a standard signature to 
+  # make things interchangeable.  We use the simulator itself, which is a bit fat, but will work for the short
+  # term.
+  it "should pass the simulator on tick" do
+    s = TickSimulation.new(@da)
+    @da.should_receive(:on_tick).with(s)
+    s.process(1)
+  end
+end

data/spec/fathom/simulation_spec.rb

@@ -0,0 +1,24 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+include Fathom
+
+describe Simulation do
+  before do
+    @da = DemoAgent.new
+    @s = Simulation.new(@da)
+  end
+
+  it "should initialize with a list of agents" do
+    s = Simulation.new(1,2,3)
+    s.agents.should eql([1,2,3])
+  end
+  
+  it "should register agent callbacks for simpler execution" do
+    @da.should_receive(:on_tick).and_return(true)
+    @s.tick
+  end
+  
+  it "should publish agent subscription to various callbacks to facilitate agent-to-agent communication" do
+    @s.agents_using_tick.should eql([@da])
+  end
+end

data/spec/fathom_spec.rb

@@ -5,4 +5,12 @@ describe "Fathom" do
     Fathom.included_modules.should_not be_include(GSL)
     lambda{GSL}.should_not raise_error
   end
+  
+  it "should have a knowledge base" do
+    Fathom.knowledge_base.should be_a(KnowledgeBase)
+  end
+  
+  it "should alias kb for knowledge_base" do
+    Fathom.kb.should eql(Fathom.knowledge_base)
+  end
 end

data/spec/support/demo.yml

@@ -1,6 +1,6 @@
 CO2 Emissions:
-  min: 1_000_000
-  max: 1_000_000_000
+  min: 1000000
+  max: 1000000000
   
 Invalid Hash:
   different: signature

data/spec/support/demo_agent.rb

@@ -0,0 +1,8 @@
+class DemoAgent < Agent
+  property :field1
+  property :field2
+  
+  def on_tick(simulation)
+  end
+  
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: fathom
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - David
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-05 00:00:00 -06:00
+date: 2010-11-07 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -53,7 +53,11 @@ files:
 - Rakefile
 - VERSION
 - autotest/discover.rb
+- fathom.gemspec
 - lib/fathom.rb
+- lib/fathom/agent.rb
+- lib/fathom/agent/agent_cluster.rb
+- lib/fathom/agent/properties.rb
 - lib/fathom/archive/conditional_probability_matrix.rb
 - lib/fathom/archive/n2.rb
 - lib/fathom/archive/n3.rb
@@ -65,6 +69,8 @@ files:
 - lib/fathom/combined_plausibilities.rb
 - lib/fathom/concept.rb
 - lib/fathom/data_node.rb
+- lib/fathom/ext/faster_csv.rb
+- lib/fathom/ext/open_struct.rb
 - lib/fathom/import.rb
 - lib/fathom/import/csv_import.rb
 - lib/fathom/import/yaml_import.rb
@@ -73,10 +79,15 @@ files:
 - lib/fathom/monte_carlo_set.rb
 - lib/fathom/node_utilities.rb
 - lib/fathom/plausible_range.rb
+- lib/fathom/simulation.rb
+- lib/fathom/simulation/tick_methods.rb
+- lib/fathom/simulation/tick_simulation.rb
 - lib/fathom/value_aggregator.rb
 - lib/fathom/value_description.rb
 - lib/fathom/value_multiplier.rb
 - lib/options_hash.rb
+- spec/fathom/agent/agent_cluster_spec.rb
+- spec/fathom/agent_spec.rb
 - spec/fathom/data_node_spec.rb
 - spec/fathom/import/csv_import_spec.rb
 - spec/fathom/import/yaml_import_spec.rb
@@ -84,10 +95,13 @@ files:
 - spec/fathom/knowledge_base_spec.rb
 - spec/fathom/monte_carlo_set_spec.rb
 - spec/fathom/plausible_range_spec.rb
+- spec/fathom/simulation/tick_simulation_spec.rb
+- spec/fathom/simulation_spec.rb
 - spec/fathom/value_description_spec.rb
 - spec/fathom_spec.rb
 - spec/spec_helper.rb
 - spec/support/demo.yml
+- spec/support/demo_agent.rb
 has_rdoc: true
 homepage: http://github.com/davidrichards/fathom
 licenses: []
@@ -123,6 +137,8 @@ signing_key:
 specification_version: 3
 summary: Decision Support in Ruby
 test_files: 
+- spec/fathom/agent/agent_cluster_spec.rb
+- spec/fathom/agent_spec.rb
 - spec/fathom/data_node_spec.rb
 - spec/fathom/import/csv_import_spec.rb
 - spec/fathom/import/yaml_import_spec.rb
@@ -130,6 +146,9 @@ test_files:
 - spec/fathom/knowledge_base_spec.rb
 - spec/fathom/monte_carlo_set_spec.rb
 - spec/fathom/plausible_range_spec.rb
+- spec/fathom/simulation/tick_simulation_spec.rb
+- spec/fathom/simulation_spec.rb
 - spec/fathom/value_description_spec.rb
 - spec/fathom_spec.rb
 - spec/spec_helper.rb
+- spec/support/demo_agent.rb