gecoder 0.7.0 → 0.7.1

data/lib/gecoder/interface/constraints/set_var_constraints.rb

@@ -15,11 +15,11 @@ module Gecode
   # (but not enumerations).
   module Constraints::Set
     # An expression with a set as left hand side.
-    class Expression < Gecode::Constraints::Expression
+    class Expression < Gecode::Constraints::Expression #:nodoc:
     end
     
     # Utility methods for sets.
-    module Util
+    module Util #:nodoc:
       module_function
       def decode_options(options)
         if options.has_key? :strength
@@ -32,7 +32,7 @@ module Gecode
     
     # A composite expression which is an set expression with a left hand side 
     # resulting from a previous constraint.
-    class CompositeExpression < Gecode::Constraints::CompositeExpression
+    class CompositeExpression < Gecode::Constraints::CompositeExpression #:nodoc:
       # The block given should take three parameters. The first is the variable 
       # that should be the left hand side, if it's nil then a new one should be
       # created. The second is the has of parameters. The block should return 
@@ -45,14 +45,18 @@ module Gecode
     
     # Describes a stub that produces a set variable, which can then be used with 
     # the normal set variable constraints. An example of a set composite 
-    # constraints would be set selection.
+    # constraints would be set selection constraint.
     #
     #   sets[int_var].must_be.subset_of(another_set)
     # 
-    # "sets[int_var]" produces a bool variable which the constraint 
-    # ".must_be.subset_of(another_set)" is then applied to.In the above case 
-    # two constraints (and one temporary variable) are required, but in the 
+    # <tt>sets[int_var]</tt> produces a set variable which the constraint 
+    # <tt>.must_be.subset_of(another_set)</tt> is then applied to.In the above 
+    # case two constraints (and one temporary variable) are required, but in the 
     # case of equality only one constraint is required.
+    # 
+    # Whether a constraint involving a reification stub supports negation and 
+    # reification depends on the constraint on the right hand side (none 
+    # support the strength option as no set constraints do).
     class CompositeStub < Gecode::Constraints::CompositeStub
       def initialize(model, params)
         super(CompositeExpression, model, params)

data/lib/gecoder/interface/model.rb

@@ -120,7 +120,7 @@ module Gecode
     #
     # The space returned by this method should never be stored, it should be
     # rerequested from the model every time that it's needed.
-    def active_space
+    def active_space #:nodoc:
       unless @allow_space_access
         raise 'Space access is restricted and the permission to access the ' + 
           'space has not been given.'
@@ -130,7 +130,7 @@ module Gecode
     
     # Adds the specified constraint to the model. Returns the newly added 
     # constraint.
-    def add_constraint(constraint)
+    def add_constraint(constraint) #:nodoc:
       add_interaction do
         constraint.post
       end
@@ -139,7 +139,7 @@ module Gecode
     
     # Adds a block containing something that interacts with Gecode to a queue
     # where it is potentially executed.
-    def add_interaction(&block)
+    def add_interaction(&block) #:nodoc:
       gecode_interaction_queue << block
     end
     
@@ -149,7 +149,7 @@ module Gecode
     # the block ends.
     #
     # Returns the result of the block.
-    def allow_space_access(&block)
+    def allow_space_access(&block) #:nodoc:
       # We store the old value so that nested calls don't become a problem, i.e.
       # access is allowed as long as one call to this method is still on the 
       # stack.
@@ -162,7 +162,7 @@ module Gecode
     
     # Starts tracking a variable that depends on the space. All variables 
     # created should call this method for their respective models.
-    def track_variable(variable)
+    def track_variable(variable) #:nodoc:
       (@variables ||= []) << variable
     end
     
@@ -170,7 +170,7 @@ module Gecode
     
     # Gets a queue of objects that can be posted to the model's active_space 
     # (by calling their post method).
-    def gecode_interaction_queue
+    def gecode_interaction_queue #:nodoc:
       @gecode_interaction_queue ||= []
     end
     

data/lib/gecoder/interface/search.rb

@@ -43,9 +43,9 @@ module Gecode
     # (accessible from the model) to be as low as possible then one should write
     # the following.
     #
-    # model.optimize! do |model, best_so_far|
-    #   model.price.must < best_so_far.price.val
-    # end
+    #   model.optimize! do |model, best_so_far|
+    #     model.price.must < best_so_far.price.val
+    #   end
     #
     # Returns nil if there is no solution.
     def optimize!(&block)
@@ -80,14 +80,14 @@ module Gecode
       return self
     end
     
-    class <<self
+    class <<self 
       # Sets the proc that should be used to handle constrain requests.
-      def constrain_proc=(proc)
+      def constrain_proc=(proc) #:nodoc:
         @constrain_proc = proc
       end
     
       # Called by spaces when they want to constrain as part of BAB-search.
-      def constrain(home, best)
+      def constrain(home, best) #:nodoc:
         if @constrain_proc.nil?
           raise NotImplementedError, 'Constrain method not implemented.' 
         else

data/lib/gecoder/interface/variables.rb

@@ -1,6 +1,7 @@
 module Gecode
-  # An variable that is bound to a model, but not to a particular space.  
-  class FreeVarBase
+  # 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.
@@ -81,26 +82,44 @@ module Gecode
     return clazz
   end
   
-  # Int variables.
   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).
+    # 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
+    def domain #:nodoc:
       if assigned?
         "range: #{value.to_s}"
       else
@@ -109,17 +128,22 @@ module Gecode
     end
   end
   
-  # Bool variables.
   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).
+    # 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?
@@ -130,12 +154,26 @@ module Gecode
     end
   end
 
-  # Set variables.
   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.
+    # 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)
@@ -144,7 +182,8 @@ module Gecode
       end
     end
     
-    # Gets all the elements located in the least upper bound of the set.
+    # 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)
@@ -164,6 +203,8 @@ module Gecode
       send_bound(:cardMin)..send_bound(:cardMax)
     end
     
+    private
+    
     # Returns a string representation of the the variable's domain.
     def domain
       if assigned?
@@ -175,9 +216,12 @@ module Gecode
   end
   
   # Describes an immutable view of an enumerable.
-  class EnumerableView
+  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
     
@@ -191,7 +235,7 @@ module Gecode
       @enum = nil
     end
 
-    # Used by Enumerable.
+    # Iterates over every element in the view.
     def each(&block)
       enum.each(&block)
     end

data/lib/gecoder/version.rb

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

data/specs/constraints/linear.rb

@@ -14,6 +14,31 @@ class LinearSampleProblem < Gecode::Model
   end
 end
 
+class BoolLinearSampleProblem < Gecode::Model
+  attr :x
+  attr :y
+  attr :z
+  
+  def initialize
+    @x = self.bool_var
+    @y = self.bool_var
+    @z = self.bool_var
+    branch_on wrap_enum([@x, @y, @z])
+  end
+end
+
+class TrueClass
+  def to_i
+    1
+  end
+end
+
+class FalseClass
+  def to_i
+    0
+  end
+end
+
 describe Gecode::Constraints::Int::Linear do
   before do
     @x_dom = 0..2
@@ -163,4 +188,145 @@ describe Gecode::Constraints::Int::Linear do
   end
   
   it_should_behave_like 'constraint with options'
-end
+end
+
+describe Gecode::Constraints::Int::Linear, '(with booleans)' do
+  before do
+    @model = BoolLinearSampleProblem.new
+    @x = @model.x
+    @y = @model.y
+    @z = @model.z
+    
+    # For constraint option spec.
+    @invoke_options = lambda do |hash| 
+      (@x + @y).must_be.greater_than(@z, hash)
+      @model.solve!
+    end
+    @expect_options = lambda do |strength, reif_var|
+      # TODO: this is hard to spec from this level.
+    end
+  end
+
+  it 'should handle addition with a variable' do
+    (@x + @y).must == 0
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    (x + y).should be_zero
+  end
+  
+  it 'should handle addition with multiple variables' do
+    (@x + @y + @z).must == 0
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    z = sol.z.value.to_i
+    (x + y + z).should be_zero
+  end
+  
+  it 'should handle subtraction with a variable' do
+    (@x - @y).must == 0
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    (x - y).should be_zero
+  end
+  
+  it 'should handle non-zero constants as right hand side' do
+    (@x + @y).must == 1
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    (x + y).should equal(1)
+  end
+  
+  it 'should handle variables as right hand side' do
+    (@x + @y).must == @z
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    z = sol.z.value.to_i
+    (x + y).should equal(z)
+  end
+  
+  it 'should handle linear expressions as right hand side' do
+    (@x + @y).must == @z + @y
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    z = sol.z.value.to_i
+    (x + y).should equal(z + y)
+  end
+  
+  it 'should raise error on invalid right hand sides' do
+    lambda{ ((@x + @y).must == 'z') }.should raise_error(TypeError) 
+  end
+  
+  it 'should handle coefficients other than 1' do
+    (@x * 2 + @y).must == 0
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    (2*x + y).should equal(0)
+  end
+  
+  it 'should handle addition with constants' do
+    (@y + 1).must == 1
+    sol = @model.solve!
+    y = sol.y.value.to_i
+    (y + 1).should equal(1)
+  end
+  
+  it 'should handle subtraction with a constant' do
+    (@x - 1).must == 0
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    (x - 1).should be_zero
+  end
+
+  it 'should handle parenthesis' do
+    (@x - (@y + @z)).must == 1
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    z = sol.z.value.to_i
+    (x - (y + z)).should equal(1)
+  end
+  
+  it 'should handle multiplication of parenthesis' do
+    (((@x + @y*10)*10 + @z)*10).must == 0
+    sol = @model.solve!
+    x = sol.x.value.to_i
+    y = sol.y.value.to_i
+    z = sol.z.value.to_i
+    (((x + y*10)*10 + z)*10).should equal(0)
+  end
+  
+  relations = ['>', '>=', '<', '<=', '==']
+  
+  relations.each do |relation|
+    it "should handle #{relation} with constant integers" do
+      (@x + @y).must.send(relation, 1)
+      sol = @model.solve!
+      sol.should_not be_nil
+      (sol.x.value.to_i + sol.y.value.to_i).should.send(relation, 1)
+    end
+  end
+  
+  relations.each do |relation|
+    it "should handle negated #{relation} with constant integers" do
+      (@x + @y).must_not.send(relation, 1)
+      sol = @model.solve!
+      sol.should_not be_nil
+      (sol.x.value.to_i + sol.y.value.to_i).should_not.send(relation, 1)
+    end
+  end
+  
+  it 'should not interfere with other defined multiplication methods' do
+    (@x * :foo).should be_nil
+  end
+  
+  it_should_behave_like 'constraint with options'
+end
+
+