gecoder 0.8.3 → 0.9.0

data/lib/gecoder/interface/model_sugar.rb

@@ -0,0 +1,84 @@
+module Gecode
+  # Provides a convenient way to construct a model and then find a
+  # solution. The model constructed uses the specified block as 
+  # initialization method. The first solution to the model is then
+  # returned.
+  #
+  # For instance
+  #
+  #   solution = Gecode.solve do
+  #     # Do something
+  #   end
+  # 
+  # is equivalent to
+  # 
+  #   class Foo < Gecode::Model
+  #     def initialize
+  #       # Do something
+  #     end
+  #   end
+  #   solution = Foo.new.solve!
+  def self.solve(&block)
+    create_model(&block).solve!
+  end
+
+  # Provides a convenient way to construct a model and then find the
+  # solution that maximizes a given variable. The model constructed 
+  # uses the specified block as initialization method. The solution
+  # that maximizes the specified variable is then returned.
+  #
+  # For instance
+  #
+  #   solution = Gecode.maximize :variable_bar do
+  #     # Do something
+  #   end
+  # 
+  # is equivalent to
+  # 
+  #   class Foo < Gecode::Model
+  #     def initialize
+  #       # Do something
+  #     end
+  #   end
+  #   solution = Foo.new.maximize :variable_bar
+  def self.maximize(variable_to_maximize, &block)
+    create_model(&block).maximize! variable_to_maximize
+  end
+
+  # Provides a convenient way to construct a model and then find the
+  # solution that minimizes a given variable. The model constructed 
+  # uses the specified block as initialization method. The solution
+  # that minimizes the specified variable is then returned.
+  #
+  # For instance
+  #
+  #   solution = Gecode.minimize :variable_bar do
+  #     # Do something
+  #   end
+  # 
+  # is equivalent to
+  # 
+  #   class Foo < Gecode::Model
+  #     def initialize
+  #       # Do something
+  #     end
+  #   end
+  #   solution = Foo.new.minimize :variable_bar
+  def self.minimize(variable_to_minimize, &block)
+    create_model(&block).minimize! variable_to_minimize
+  end
+
+  private
+
+  # Creates an instance of a class that subclasses Model and uses the 
+  # specified block as initialization method.
+  def self.create_model(&block)
+    model = Class.new(Gecode::Model)
+    model.class_eval do
+      def initialize(&init_block) #:nodoc:
+        instance_eval &init_block
+      end
+    end
+    model.new(&block)
+  end
+end

data/lib/gecoder/interface/search.rb

@@ -1,19 +1,27 @@
 module Gecode
+  # An exception raised when a search failed because there are no
+  # solutions.
+  class NoSolutionError < RuntimeError
+    def initialize #:nodoc:
+      super('No solution could be found.')
+    end
+  end
+
   class Model
     # Finds the first solution to the modelled problem and updates the variables
-    # to that solution. Returns the model if a solution was found, nil 
-    # otherwise.
+    # to that solution. The found solution is also returned. Raises
+    # Gecode::NoSolutionError if no solution can be found.
     def solve!
       dfs = dfs_engine
       space = dfs.next
       @statistics = dfs.statistics
-      return nil if space.nil?
+      raise Gecode::NoSolutionError if space.nil?
       self.active_space = space
       return self
     end
     
-    # Returns to the original state, before any search was made (but propagation 
-    # might have been performed). Returns the reset model.
+    # Returns to the original state, before any search was made (but 
+    # propagation might have been performed). Returns the reset model.
     def reset!
       self.active_space = base_space
       @statistics = nil
@@ -24,10 +32,14 @@ module Gecode
     # then the block is not used. Returns the result of the block (nil in case
     # the block wasn't run). 
     def solution(&block)
-      solution = self.solve!
-      res = yield solution unless solution.nil?
-      self.reset!
-      return res
+      begin
+        solution = self.solve!
+        res = yield solution
+        self.reset!
+        return res
+      rescue Gecode::NoSolutionError
+        return nil
+      end
     end
     
     # Yields each solution that the model has.
@@ -44,7 +56,7 @@ module Gecode
     
     # Returns search statistics providing various information from Gecode about
     # the search that resulted in the model's current variable state. If the 
-    # model's variables have not undegone any search then nil is returned. The 
+    # model's variables have not undergone any search then nil is returned. The 
     # statistics is a hash with the following keys:
     # [:propagations]   The number of propagation steps performed.
     # [:failures]       The number of failed nodes in the search tree.
@@ -74,7 +86,7 @@ module Gecode
     #     model.price.must < best_so_far.price.val
     #   end
     #
-    # Returns nil if there is no solution.
+    # Raises Gecode::NoSolutionError if no solution can be found.
     def optimize!(&block)
       # Execute constraints.
       perform_queued_gecode_interactions
@@ -106,7 +118,7 @@ module Gecode
       
       # Reset the method used constrain calls and return the result.
       Model.constrain_proc = nil
-      return nil if result.nil?
+      raise Gecode::NoSolutionError if result.nil?
       
       # Switch to the result.
       self.active_space = result
@@ -115,15 +127,15 @@ module Gecode
     
     # Finds the solution that maximizes a given integer variable. The name of 
     # the method that accesses the variable from the model should be given. To 
-    # for instance maximize a variable named "profit", that's accessible through 
-    # the model, one would use the following.
+    # for instance maximize a variable named "profit", that's accessible 
+    # through the model, one would use the following.
     #
     #   model.maximize! :profit
     #
-    # Returns nil if there is no solution.
+    # Raises Gecode::NoSolutionError if no solution can be found.
     def maximize!(var)
       variable = self.method(var).call
-      unless variable.kind_of? Gecode::FreeIntVar
+      unless variable.kind_of? Gecode::IntVar
         raise ArgumentError.new("Expected integer variable, got #{variable.class}.")
       end
       
@@ -139,10 +151,10 @@ module Gecode
     #
     #   model.minimize! :cost
     #
-    # Returns nil if there is no solution.
+    # Raises Gecode::NoSolutionError if no solution can be found.
     def minimize!(var)
       variable = self.method(var).call
-      unless variable.kind_of? Gecode::FreeIntVar
+      unless variable.kind_of? Gecode::IntVar
         raise ArgumentError.new("Expected integer variable, got #{variable.class}.")
       end
       

data/lib/gecoder/interface/variables.rb

@@ -13,9 +13,9 @@ module Gecode
 
     def inspect
       if assigned?
-        "#<#{self.class} #{domain}>"
+        "#<#{self.class} #{domain_string}>"
       else
-        "#<#{self.class} #{domain}>"
+        "#<#{self.class} #{domain_string}>"
       end
     end
     
@@ -36,11 +36,11 @@ module Gecode
   
   # 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)
+  def Gecode::FreeVar(bound_class, space_bind_method) #:nodoc:
     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.
+      # Binds the variable to the currently active space of the model, 
+      # returning the bound variable.
       def bind
         active_space.method(:#{space_bind_method}).call(@index)
       end
@@ -64,12 +64,25 @@ module Gecode
     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
+  IntVar = FreeVar(Gecode::Raw::IntVar, :int_var)
+  # Describes an integer variable. 
+  #
+  # An integer variable can take the value of any integer in its 
+  # domain, which is specified upon constructing the variable and
+  # further constrained by placing constraints on the variable.
+  # 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.
+  #
+  # Integer variables are integer operands and hence respond to
+  # everything that Gecode::Int::IntOperand responds to.
+  # Any constraint found in
+  # Gecode::Int::IntConstraintReceiver can thereby be 
+  # placed on integer variables.
+  class IntVar
+    include Gecode::Int::IntOperand
+    attr :model
+
     # Gets the minimum value still in the domain of the variable.
     delegate :min
     # Gets the maximum value still in the domain of the variable.
@@ -97,11 +110,27 @@ module Gecode
       raise 'No value is assigned.' unless assigned?
       send_bound(:val)
     end
+
+    # Returns the receiver.
+    def to_int_var
+      self
+    end
     
+    # Returns an enumeration corresponding to the domain.
+    def domain
+      if range?
+        min..max
+      else
+        (min..max).select do |i|
+          include? i
+        end
+      end
+    end
+
     private
     
-    # Returns a string representation of the the range of the variable's domain.
-    def domain #:nodoc:
+    # Returns a string representation of the range of the variable's domain.
+    def domain_string #:nodoc:
       if assigned?
         "range: #{value.to_s}"
       else
@@ -110,10 +139,20 @@ module Gecode
     end
   end
   
-  FreeBoolVar = FreeVar(Gecode::Raw::BoolVar, :bool_var)
-  # Describes a boolean variable. A boolean variable can be either true or 
-  # false.
-  class FreeBoolVar
+  BoolVar = FreeVar(Gecode::Raw::BoolVar, :bool_var)
+  # Describes a boolean variable. 
+  #
+  # A boolean variable can be either true or false.
+  #
+  # Boolean variables are boolean operands and hence respond to
+  # everything that Gecode::Bool::BoolOperand responds to.
+  # Any constraint found in
+  # Gecode::Bool::BoolConstraintReceiver can thereby be 
+  # placed on boolean variables.
+  class BoolVar
+    include Gecode::Bool::BoolOperand
+    attr :model
+
     # Checks whether the variable has been assigned.
     delegate :assigned?, :assigned
     
@@ -123,11 +162,16 @@ module Gecode
       raise 'No value is assigned.' unless assigned?
       send_bound(:val) == 1
     end
+
+    # Returns the receiver.
+    def to_bool_var
+      self
+    end
   
     private
   
     # Returns a string representation of the the variable's domain.
-    def domain
+    def domain_string
       if assigned?
         value.to_s
       else
@@ -136,24 +180,37 @@ module Gecode
     end
   end
 
-  FreeSetVar = FreeVar(Gecode::Raw::SetVar, :set_var)
+  SetVar = 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.
+  # 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}. 
+  # 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
+  # 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.
+  #
+  # Set variables are set operands and hence respond to everything that
+  # Gecode::Set::SetOperand responds to.  Any constraint
+  # found in Gecode::Set::SetConstraintReceiver can thereby
+  # be placed on set variables.
+  class SetVar
+    include Gecode::Set::SetOperand
+    attr :model
+
     # Checks whether the variable has been assigned.
     delegate :assigned?, :assigned
-    
+    # Checks whether a value is included in the set.
+    delegate :in_lower_bound?, :contains
+    # Checks whether a value is not included in the set.
+    delegate :not_in_upper_bound?, :notContains
+
     # Gets all the elements located in the greatest lower bound of the set (an 
     # Enumerable).
     def lower_bound
@@ -185,14 +242,27 @@ module Gecode
       send_bound(:cardMin)..send_bound(:cardMax)
     end
     
+    # Returns the receiver.
+    def to_set_var
+      self
+    end
+    
     private
     
     # Returns a string representation of the the variable's domain.
-    def domain
+    def domain_string
       if assigned?
-        lower_bound.to_a.inspect
+        if lower_bound.size < 100
+          lower_bound.to_a.inspect
+        else
+          "the domain is too large to display"
+        end
       else
-        "glb-range: #{lower_bound.to_a.inspect}, lub-range: #{upper_bound.to_a.inspect}"
+        if upper_bound.size < 100
+          "glb-range: #{lower_bound.to_a.inspect}, lub-range: #{upper_bound.to_a.inspect}"
+        else
+          "the domain is too large to display"
+        end
       end
     end
   end

data/lib/gecoder/version.rb

@@ -1,4 +1,4 @@
-module GecodeR
+module GecodeR #:nodoc:
   # A string representation of the Gecode/R version.
-  VERSION = '0.8.3'
+  VERSION = '0.9.0'
 end

data/specs/bool_var.rb

@@ -1,4 +1,5 @@
 require File.dirname(__FILE__) + '/spec_helper'
+require File.dirname(__FILE__) + '/constraints/property_helper'
 
 describe 'non-empty bool variable', :shared => true do
   it 'should give a NoMethodError when calling a method that doesn\'t exist' do
@@ -6,10 +7,10 @@ describe 'non-empty bool variable', :shared => true do
   end
 end
 
-describe Gecode::FreeBoolVar, '(not assigned)' do
+describe Gecode::BoolVar, '(not assigned)' do
   before do
-    model = Gecode::Model.new
-    @var = model.bool_var
+    @model = Gecode::Model.new
+    @operand = @var = @model.bool_var
   end
   
   it_should_behave_like 'non-empty bool variable'
@@ -25,14 +26,16 @@ describe Gecode::FreeBoolVar, '(not assigned)' do
   it 'should raise error when trying to access assigned value' do
     lambda{ @var.value }.should raise_error(RuntimeError)
   end
+
+  it_should_behave_like 'bool var operand'
 end
 
-describe Gecode::FreeBoolVar, '(assigned true)' do
+describe Gecode::BoolVar, '(assigned true)' do
   before do
-    model = Gecode::Model.new
-    @var = model.bool_var
+    @model = Gecode::Model.new
+    @operand = @var = @model.bool_var
     @var.must_be.true
-    model.solve!
+    @model.solve!
   end
   
   it_should_behave_like 'non-empty bool variable'
@@ -48,14 +51,16 @@ describe Gecode::FreeBoolVar, '(assigned true)' do
   it "should say that it's true when inspecting" do
     @var.inspect.should include('true')
   end
+  
+  it_should_behave_like 'bool var operand'
 end
 
-describe Gecode::FreeBoolVar, '(assigned false)' do
+describe Gecode::BoolVar, '(assigned false)' do
   before do
-    model = Gecode::Model.new
-    @var = model.bool_var
+    @model = Gecode::Model.new
+    @operand = @var = @model.bool_var
     @var.must_be.false
-    model.solve!
+    @model.solve!
   end
   
   it_should_behave_like 'non-empty bool variable'
@@ -71,4 +76,6 @@ describe Gecode::FreeBoolVar, '(assigned false)' do
   it "should say that it's false when inspecting" do
     @var.inspect.should include('false')
   end
-end
+
+  it_should_behave_like 'bool var operand'
+end