gecoder-with-gecode 0.7.1

data/lib/gecoder/interface/variables.rb

@@ -0,0 +1,254 @@
+module Gecode
+  # Describes a variable that is bound to a model, but not to a particular 
+  # space.  
+  class FreeVarBase #:nodoc:
+    attr_accessor :model
+  
+    # Creates an int variable with the specified index.
+    def initialize(model, index)
+      @model = model
+      @index = index
+      @bound_space = @bound_var = nil
+      model.track_variable(self)
+    end
+    
+    # Checks whether the variable is cached, i.e. whether it needs to be 
+    # rebound after changes to a space.
+    def cached?
+      not @bound_space.nil?
+    end
+    
+    # Forces the variable to refresh itself.
+    def refresh
+      @bound_space = nil
+    end
+    
+    def inspect
+      if assigned?
+        "#<#{self.class} #{domain}>"
+      else
+        "#<#{self.class} #{domain}>"
+      end
+    end
+    
+    private
+    
+    # Returns the space that the int variable should bind to when needed.
+    def active_space
+      @model.active_space
+    end
+    
+    # Sends the specified method name and arguments to the bound variable.
+    def send_bound(method_name, *args)
+      @model.allow_space_access do
+        bind.send(method_name, *args)
+      end
+    end
+  end
+  
+  # Creates a class for a free variable that can be bound into the specified
+  # class using the specified method in a space.
+  def Gecode::FreeVar(bound_class, space_bind_method)
+    clazz = Class.new(FreeVarBase)
+    clazz.class_eval <<-"end_method_definitions"      
+      # Binds the int variable to the currently active space of the model, 
+      # returning the bound int variable.
+      def bind
+        space = active_space
+        unless @bound_space == space
+          # We have not bound the variable to this space, so we do it now.
+          @bound = space.method(:#{space_bind_method}).call(@index)
+          @bound_space = space
+        end
+        return @bound
+      end
+      
+      private
+      
+      # Delegates the method with the specified name to a method with the 
+      # specified name when the variable is bound. If the bound method's name
+      # is nil then the same name as the new method's name is assumed.
+      def self.delegate(method_name, bound_method_name = nil)
+        bound_method_name = method_name if bound_method_name.nil?
+        module_eval <<-"end_code"
+          def \#{method_name}(*args)
+            @model.allow_space_access do
+              bind.method(:\#{bound_method_name}).call(*args)
+            end
+          end
+        end_code
+      end
+    end_method_definitions
+    return clazz
+  end
+  
+  FreeIntVar = FreeVar(Gecode::Raw::IntVar, :int_var)
+  # Describes an integer variable. Each integer variable has a domain of several
+  # integers which represent the possible values that the variable may take. 
+  # An integer variable is said to be assigned once the domain only contains a
+  # single element, at which point #value can be used to retrieve the value.
+  class FreeIntVar
+    # Gets the minimum value still in the domain of the variable.
+    delegate :min
+    # Gets the maximum value still in the domain of the variable.
+    delegate :max
+    # Gets the number of elements still in the domain of the variable.
+    delegate :size
+    # Gets the width of the variable's domain, i.e. the distance between the
+    # maximum and minimum values.
+    delegate :width
+    # Gets the degree of the variable. The degree is the number of constraints
+    # that are affected by the variable. So if the variable is used in two
+    # constraints then the value will be 2.
+    delegate :degree
+    # Checks whether the domain is a range, i.e. doesn't contain any holes.
+    delegate :range?, :range
+    # Checks whether the variable has been assigned, i.e. its domain only 
+    # contains one element.
+    delegate :assigned?, :assigned
+    # Checks whether a specified integer is in the variable's domain.
+    delegate :include?, :in
+    
+    # Gets the value of the assigned integer variable (a Fixnum). The variable
+    # must be assigned, if it isn't then a RuntimeError is raised.
+    def value
+      raise 'No value is assigned.' unless assigned?
+      send_bound(:val)
+    end
+    
+    private
+    
+    # Returns a string representation of the the range of the variable's domain.
+    def domain #:nodoc:
+      if assigned?
+        "range: #{value.to_s}"
+      else
+        "range: #{min}..#{max}"
+      end
+    end
+  end
+  
+  FreeBoolVar = FreeVar(Gecode::Raw::BoolVar, :bool_var)
+  # Describes a boolean variable. A boolean variable can be either true or 
+  # false.
+  class FreeBoolVar
+    # Checks whether the variable has been assigned.
+    delegate :assigned?, :assigned
+    
+    # Gets the values in the assigned boolean variable (true or false). The 
+    # variable must be assigned, if it isn't then a RuntimeError is raised.
+    def value
+      raise 'No value is assigned.' unless assigned?
+      send_bound(:val) == 1
+    end
+  
+    private
+  
+    # Returns a string representation of the the variable's domain.
+    def domain
+      if assigned?
+        value.to_s
+      else
+        'unassigned'
+      end
+    end
+  end
+
+  FreeSetVar = FreeVar(Gecode::Raw::SetVar, :set_var)
+  # Describes a set variable. 
+  # 
+  # A set variable's domain, i.e. possible values that it can take, are 
+  # represented with a greatest lower bound (GLB) and a least upper bound (LUB).
+  # The set variable may then take any set value S such that S is a subset of
+  # the least upper bound and the greatest lower bound is a subset of S.
+  #   
+  # If for instance the set has a greatest lower bound {1} and least upper bound
+  # {1,3,5} then the assigned set may be any of the following four sets: {1}, 
+  # {1,3}, {1,5}, {1,3,5}. 
+  # 
+  # The domain of a set variable may also specify the cardinality of the set, 
+  # i.e. the number of elements that the set may contains.
+  class FreeSetVar
+    # Checks whether the variable has been assigned.
+    delegate :assigned?, :assigned
+    
+    # Gets all the elements located in the greatest lower bound of the set (an 
+    # Enumerable).
+    def lower_bound
+      min = send_bound(:glbMin)
+      max = send_bound(:glbMax)
+      EnumerableView.new(min, max, send_bound(:glbSize)) do
+        (min..max).to_a.delete_if{ |e| not send_bound(:contains, e) }
+      end
+    end
+    
+    # Gets all the elements located in the least upper bound of the set (an 
+    # Enumerable).
+    def upper_bound
+      min = send_bound(:lubMin)
+      max = send_bound(:lubMax)
+      EnumerableView.new(min, max, send_bound(:lubSize)) do
+        (min..max).to_a.delete_if{ |e| send_bound(:notContains, e) }
+      end
+    end
+    
+    # Gets the values in the assigned set variable (an enumerable).
+    def value
+      raise 'No value is assigned.' unless assigned?
+      lower_bound
+    end
+    
+    # Returns a range containing the allowed values for the set's cardinality.
+    def cardinality
+      send_bound(:cardMin)..send_bound(:cardMax)
+    end
+    
+    private
+    
+    # Returns a string representation of the the variable's domain.
+    def domain
+      if assigned?
+        lower_bound.to_a.inspect
+      else
+        "glb-range: #{lower_bound.to_a.inspect}, lub-range: #{upper_bound.to_a.inspect}"
+      end
+    end
+  end
+  
+  # Describes an immutable view of an enumerable.
+  class EnumerableView #:nodoc:
+    # Gets the number of elements in the view.
+    attr :size
+    # Gets the minimum element of the view.
+    attr :min
+    # Gets the maximum element of the view.
+    attr :max
+    include Enumerable
+    
+    # Constructs a view with the specified minimum, maximum and size. The block 
+    # should construct an enumerable containing the elements of the set.
+    def initialize(min, max, size, &enum_constructor)
+      @min = min
+      @max = max
+      @size = size
+      @constructor = enum_constructor
+      @enum = nil
+    end
+
+    # Iterates over every element in the view.
+    def each(&block)
+      enum.each(&block)
+    end
+    
+    private
+    
+    # Gets the enumeration being viewed.
+    def enum
+      if @enum.nil?
+        @enum = @constructor.call
+      else
+        return @enum
+      end
+    end
+  end
+end

data/lib/gecoder/version.rb

@@ -0,0 +1,4 @@
+module GecodeR
+  # A string representation of the Gecode/R version.
+  VERSION = '0.7.1'
+end

data/specs/binding_changes.rb

@@ -0,0 +1,76 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe 'Space', :shared => true do
+  it 'should give different indices when creating int variables' do
+    @space.new_int_vars([0, 17]).should_not equal(@space.new_int_vars([0, 17]))
+  end
+  
+  it 'should give different indices when creating bool variables' do
+    @space.new_bool_vars().should_not equal(@space.new_bool_vars())
+  end
+  
+  it 'should give different indices when creating multiple int variables' do
+    @space.new_int_vars([0, 17], 17).uniq.size.should equal(17)
+  end
+  
+  it 'should give different indices when creating multiple bool variables' do
+    @space.new_bool_vars(17).uniq.size.should equal(17)
+  end
+  
+  it 'should not return nil for created int variables' do
+    @space.new_int_vars([0, 17], 4).each do |i|
+      @space.int_var(i).should_not be_nil
+    end
+  end
+  
+  it 'should not return nil for created int variables' do
+    @space.new_bool_vars(4).each do |i|
+      @space.bool_var(i).should_not be_nil
+    end
+  end
+  
+  it 'should return nil when requesting int variables with negative indices' do
+    @space.int_var(-1).should be_nil
+  end
+  
+  it 'should return nil when requesting bool variables with negative indices' do
+    @space.bool_var(-1).should be_nil
+  end
+  
+  it 'should raise an error if given a domain of incorrect type' do
+    lambda{ @space.new_int_vars(17) }.should raise_error(TypeError)
+  end
+end
+
+describe Gecode::Raw::Space, ' (new)' do
+  before do
+    @space = Gecode::Raw::Space.new
+  end
+  
+  it 'should return nil when requesting int variables' do
+    @space.int_var(0).should be_nil
+  end
+  
+  it 'should return nil when requesting bool variables' do
+    @space.bool_var(0).should be_nil
+  end
+  
+  it_should_behave_like 'Space'
+end
+
+describe Gecode::Raw::Space, ' (with items)' do
+  before do
+    @space = Gecode::Raw::Space.new
+    @first = @space.new_int_vars([1, 4]).first
+    @second = @space.new_int_vars([-5, 5]).first
+  end
+  
+  it_should_behave_like 'Space'
+  
+  it 'should give int variables with the correct domains' do
+    @space.int_var(@first).min.should equal(1)
+    @space.int_var(@first).max.should equal(4)
+    @space.int_var(@second).min.should equal(-5)
+    @space.int_var(@second).max.should equal(5)
+  end
+end

data/specs/bool_var.rb

@@ -0,0 +1,74 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe 'non-empty bool variable', :shared => true do
+  it 'should give a NoMethodError when calling a method that doesn\'t exist' do
+    lambda{ @var.this_method_does_not_exists }.should raise_error(NoMethodError)
+  end
+end
+
+describe Gecode::FreeBoolVar, '(not assigned)' do
+  before do
+    model = Gecode::Model.new
+    @var = model.bool_var
+  end
+  
+  it_should_behave_like 'non-empty bool variable'
+  
+  it 'should not be assigned' do
+    @var.should_not be_assigned
+  end
+  
+  it "should say that it's not assigned when inspecting" do
+    @var.inspect.should include('unassigned')
+  end
+  
+  it 'should raise error when trying to access assigned value' do
+    lambda{ @var.value }.should raise_error(RuntimeError)
+  end
+end
+
+describe Gecode::FreeBoolVar, '(assigned true)' do
+  before do
+    model = Gecode::Model.new
+    @var = model.bool_var
+    @var.must_be.true
+    model.solve!
+  end
+  
+  it_should_behave_like 'non-empty bool variable'
+  
+  it 'should be assigned' do
+    @var.should be_assigned
+  end
+  
+  it 'should have valye true' do
+    @var.value.should be_true
+  end
+  
+  it "should say that it's true when inspecting" do
+    @var.inspect.should include('true')
+  end
+end
+
+describe Gecode::FreeBoolVar, '(assigned false)' do
+  before do
+    model = Gecode::Model.new
+    @var = model.bool_var
+    @var.must_be.false
+    model.solve!
+  end
+  
+  it_should_behave_like 'non-empty bool variable'
+  
+  it 'should be assigned' do
+    @var.should be_assigned
+  end
+  
+  it 'should have value false ' do
+    @var.value.should_not be_true
+  end
+  
+  it "should say that it's false when inspecting" do
+    @var.inspect.should include('false')
+  end
+end

data/specs/branch.rb

@@ -0,0 +1,170 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+class BranchSampleProblem < Gecode::Model
+  attr :vars
+  attr :bools
+  attr :sets
+  
+  def initialize
+    @vars = int_var_array(2, 0..3)
+    @sets = set_var_array(2, [], 0..4)
+    @bools = bool_var_array(2)
+  end
+end
+
+describe Gecode::Model, ' (integer branch)' do
+  before do
+    @model = BranchSampleProblem.new
+    @vars = @model.vars
+    @bools = @model.bools
+  end
+
+  it 'should default to :none and :min' do
+    Gecode::Raw.should_receive(:branch).once.with(
+      an_instance_of(Gecode::Raw::Space), 
+      anything, Gecode::Raw::BVAR_NONE, Gecode::Raw::BVAL_MIN)
+    @model.branch_on @vars
+    @model.solve!
+  end
+  
+  it 'should ensure that branched int variables are assigned in a solution' do
+    @model.branch_on @vars
+    @model.solve!.vars.each{ |var| var.should be_assigned }
+  end
+  
+  it 'should ensure that branched bool variables are assigned in a solution' do
+    @model.branch_on @bools
+    @model.solve!.bools.each{ |var| var.should be_assigned }
+  end
+
+  supported_var_selectors = {
+    :none                 => Gecode::Raw::BVAR_NONE,
+    :smallest_min         => Gecode::Raw::BVAR_MIN_MIN,
+    :largest_min          => Gecode::Raw::BVAR_MIN_MAX, 
+    :smallest_max         => Gecode::Raw::BVAR_MAX_MIN, 
+    :largest_max          => Gecode::Raw::BVAR_MAX_MAX, 
+    :smallest_size        => Gecode::Raw::BVAR_SIZE_MIN, 
+    :largest_size         => Gecode::Raw::BVAR_SIZE_MAX,
+    :smallest_degree      => Gecode::Raw::BVAR_DEGREE_MIN, 
+    :largest_degree       => Gecode::Raw::BVAR_DEGREE_MAX, 
+    :smallest_min_regret  => Gecode::Raw::BVAR_REGRET_MIN_MIN,
+    :largest_min_regret   => Gecode::Raw::BVAR_REGRET_MIN_MAX,
+    :smallest_max_regret  => Gecode::Raw::BVAR_REGRET_MAX_MIN, 
+    :largest_max_regret   => Gecode::Raw::BVAR_REGRET_MAX_MAX
+  }.each_pair do |name, gecode_const|
+    it "should support #{name} as variable selection strategy" do
+      Gecode::Raw.should_receive(:branch).once.with(
+        an_instance_of(Gecode::Raw::Space),
+        anything, gecode_const, an_instance_of(Numeric))
+      @model.branch_on @vars, :variable => name
+      @model.solve!
+    end
+  end
+
+  supported_val_selectors = {
+    :min        => Gecode::Raw::BVAL_MIN,
+    :med        => Gecode::Raw::BVAL_MED,
+    :max        => Gecode::Raw::BVAL_MAX,
+    :split_min  => Gecode::Raw::BVAL_SPLIT_MIN,
+    :split_max  => Gecode::Raw::BVAL_SPLIT_MAX
+  }.each_pair do |name, gecode_const|
+    it "should support #{name} as value selection strategy" do
+      Gecode::Raw.should_receive(:branch).once.with(
+        an_instance_of(Gecode::Raw::Space), 
+        anything, an_instance_of(Numeric), gecode_const)
+      @model.branch_on @vars, :value => name
+      @model.solve!
+    end
+  end
+
+  it 'should raise errors for unrecognized var selection strategies' do
+    lambda do 
+      @model.branch_on @vars, :variable => :foo 
+    end.should raise_error(ArgumentError)
+  end
+  
+  it 'should raise errors for unrecognized val selection strategies' do
+    lambda do 
+      @model.branch_on @vars, :value => :foo 
+    end.should raise_error(ArgumentError)
+  end
+
+  it 'should raise errors for unrecognized options' do
+    lambda do
+      @model.branch_on @vars, :foo => 5 
+    end.should raise_error(ArgumentError)
+  end
+  
+  it 'should raise errors for unrecognized enumerations' do
+    lambda do
+      @model.branch_on [1,2,3]
+    end.should raise_error(TypeError)
+  end
+end
+
+describe Gecode::Model, ' (set branch)' do
+  before do
+    @model = BranchSampleProblem.new
+    @sets = @model.sets
+  end
+
+  it 'should default to :none and :min' do
+    Gecode::Raw.should_receive(:branch).once.with(
+      an_instance_of(Gecode::Raw::Space), 
+      anything, Gecode::Raw::SETBVAR_NONE, Gecode::Raw::SETBVAL_MIN)
+    @model.branch_on @sets
+    @model.solve!
+  end
+  
+  it 'should ensure that branched set variables are assigned in a solution' do
+    @model.branch_on @sets
+    @model.solve!.sets.each{ |var| var.should be_assigned }
+  end
+
+  supported_var_selectors = {
+    :none                 => Gecode::Raw::SETBVAR_NONE,
+    :smallest_cardinality => Gecode::Raw::SETBVAR_MIN_CARD,
+    :largest_cardinality  => Gecode::Raw::SETBVAR_MAX_CARD, 
+    :smallest_unknown     => Gecode::Raw::SETBVAR_MIN_UNKNOWN_ELEM, 
+    :largest_unknown      => Gecode::Raw::SETBVAR_MAX_UNKNOWN_ELEM
+  }.each_pair do |name, gecode_const|
+    it "should support #{name} as variable selection strategy" do
+      Gecode::Raw.should_receive(:branch).once.with(
+        an_instance_of(Gecode::Raw::Space),
+        anything, gecode_const, an_instance_of(Numeric))
+      @model.branch_on @sets, :variable => name
+      @model.solve!
+    end
+  end
+
+  supported_val_selectors = {
+    :min  => Gecode::Raw::SETBVAL_MIN,
+    :max  => Gecode::Raw::SETBVAL_MAX
+  }.each_pair do |name, gecode_const|
+    it "should support #{name} as value selection strategy" do
+      Gecode::Raw.should_receive(:branch).once.with(
+        an_instance_of(Gecode::Raw::Space), 
+        anything, an_instance_of(Numeric), gecode_const)
+      @model.branch_on @sets, :value => name
+      @model.solve!
+    end
+  end
+
+  it 'should raise errors for unrecognized var selection strategies' do
+    lambda do 
+      @model.branch_on @sets, :variable => :foo 
+    end.should raise_error(ArgumentError)
+  end
+  
+  it 'should raise errors for unrecognized val selection strategies' do
+    lambda do 
+      @model.branch_on @sets, :value => :foo 
+    end.should raise_error(ArgumentError)
+  end
+
+  it 'should raise errors for unrecognized options' do
+    lambda do
+      @model.branch_on @sets, :foo => 5 
+    end.should raise_error(ArgumentError)
+  end
+end