gecoder 0.5.0 → 0.6.0

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

@@ -0,0 +1,32 @@
+module Gecode
+  module SetEnumMethods
+    include Gecode::Constraints::LeftHandSideMethods
+    
+    private
+    
+    # Produces an expression for the lhs module.
+    def expression(params)
+      params.update(:lhs => self)
+      Constraints::SetEnum::Expression.new(@model, params)
+    end
+  end
+  
+  # A module containing constraints that have enumerations of set variables as 
+  # left hand side.
+  module Constraints::SetEnum
+    # Expressions with set enums as left hand sides.
+    class Expression < Gecode::Constraints::Expression
+      # Raises TypeError unless the left hand side is a set enum.
+      def initialize(model, params)
+        super
+        
+        unless params[:lhs].respond_to? :to_set_var_array
+          raise TypeError, 'Must have set enum as left hand side.'
+        end
+      end
+    end
+  end
+end
+
+require 'gecoder/interface/constraints/set_enum/channel'
+require 'gecoder/interface/constraints/set_enum/distinct'

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

@@ -35,3 +35,4 @@ end
 require 'gecoder/interface/constraints/set/domain'
 require 'gecoder/interface/constraints/set/relation'
 require 'gecoder/interface/constraints/set/cardinality'
+require 'gecoder/interface/constraints/set/connection'

data/lib/gecoder/interface/enum_wrapper.rb

@@ -45,10 +45,19 @@ module Gecode
     end
   end
   
+  module VariableEnumMethods
+    include EnumMethods
+    
+    # Gets the values of all the variables in the enum.
+    def values
+      map{ |var| var.value }
+    end
+  end
+  
   # A module containing the methods needed by enumerations containing int 
   # variables. Requires that it's included in an enumerable.
   module IntEnumMethods
-    include EnumMethods
+    include VariableEnumMethods
   
     # Returns an int variable array with all the bound variables.
     def to_int_var_array
@@ -80,7 +89,7 @@ module Gecode
   # A module containing the methods needed by enumerations containing boolean
   # variables. Requires that it's included in an enumerable.
   module BoolEnumMethods
-    include EnumMethods
+    include VariableEnumMethods
   
     # Returns a bool variable array with all the bound variables.
     def to_bool_var_array
@@ -99,7 +108,7 @@ module Gecode
   # A module containing the methods needed by enumerations containing set
   # variables. Requires that it's included in an enumerable.
   module SetEnumMethods
-    include EnumMethods
+    include VariableEnumMethods
   
     # Returns a set variable array with all the bound variables.
     def to_set_var_array

data/lib/gecoder/interface/model.rb

@@ -1,15 +1,12 @@
 module Gecode
   # Model is the base class that all models must inherit from.
   class Model
-    attr :constraints
-    protected :constraints
-  
     # Creates a new integer variable with the specified domain. The domain can
     # either be a range or a number of elements. 
     def int_var(*domain_args)
-      range = domain_range(*domain_args)
-      index = active_space.new_int_vars(range.begin, range.end).first
-      construct_int_var(index, *domain_args)
+      enum = domain_enum(*domain_args)
+      index = selected_space.new_int_vars(enum).first
+      FreeIntVar.new(self, index)
     end
     
     # Creates an array containing the specified number of integer variables 
@@ -18,10 +15,10 @@ module Gecode
     def int_var_array(count, *domain_args)
       # TODO: Maybe the custom domain should be specified as an array instead? 
       
-      range = domain_range(*domain_args)
+      enum = domain_enum(*domain_args)
       variables = []
-      active_space.new_int_vars(range.begin, range.end, count).each do |index|
-        variables << construct_int_var(index, *domain_args)
+      selected_space.new_int_vars(enum, count).each do |index|
+        variables << FreeIntVar.new(self, index)
       end
       return wrap_enum(variables)
     end
@@ -32,13 +29,12 @@ module Gecode
     def int_var_matrix(row_count, col_count, *domain_args)
       # TODO: Maybe the custom domain should be specified as an array instead? 
       
-      range = domain_range(*domain_args)
-      indices = active_space.new_int_vars(range.begin, range.end, 
-        row_count*col_count)
+      enum = domain_enum(*domain_args)
+      indices = selected_space.new_int_vars(enum, row_count*col_count)
       rows = []
       row_count.times do |i|
         rows << indices[(i*col_count)...(i.succ*col_count)].map! do |index|
-          construct_int_var(index, *domain_args)
+          FreeIntVar.new(self, index)
         end
       end
       return wrap_enum(Util::EnumMatrix.rows(rows, false))
@@ -46,14 +42,14 @@ module Gecode
     
     # Creates a new boolean variable.
     def bool_var(*domain_args)
-      index = active_space.new_bool_vars.first
+      index = selected_space.new_bool_vars.first
       FreeBoolVar.new(self, index)
     end
     
     # Creates an array containing the specified number of boolean variables.
     def bool_var_array(count)
       variables = []
-      active_space.new_bool_vars(count).each do |index|
+      selected_space.new_bool_vars(count).each do |index|
         variables << FreeBoolVar.new(self, index)
       end
       return wrap_enum(variables)
@@ -62,7 +58,7 @@ module Gecode
     # Creates a matrix containing the specified number rows and columns of 
     # boolean variables.
     def bool_var_matrix(row_count, col_count)
-      indices = active_space.new_bool_vars(row_count*col_count)
+      indices = selected_space.new_bool_vars(row_count*col_count)
       rows = []
       row_count.times do |i|
         rows << indices[(i*col_count)...(i.succ*col_count)].map! do |index|
@@ -81,7 +77,7 @@ module Gecode
     def set_var(glb_domain, lub_domain, cardinality_range = nil)
       check_set_bounds(glb_domain, lub_domain)
       
-      index = active_space.new_set_vars(glb_domain, lub_domain, 
+      index = selected_space.new_set_vars(glb_domain, lub_domain, 
         to_set_cardinality_range(cardinality_range)).first
       FreeSetVar.new(self, index)
     end
@@ -92,7 +88,7 @@ module Gecode
       check_set_bounds(glb_domain, lub_domain)
       
       variables = []
-      active_space.new_set_vars(glb_domain, lub_domain, 
+      selected_space.new_set_vars(glb_domain, lub_domain, 
           to_set_cardinality_range(cardinality_range), count).each do |index|
         variables << FreeSetVar.new(self, index)
       end
@@ -106,7 +102,7 @@ module Gecode
         cardinality_range = nil)
       check_set_bounds(glb_domain, lub_domain)
       
-      indices = active_space.new_set_vars(glb_domain, lub_domain, 
+      indices = selected_space.new_set_vars(glb_domain, lub_domain, 
         to_set_cardinality_range(cardinality_range), row_count*col_count)
       rows = []
       row_count.times do |i|
@@ -117,53 +113,83 @@ module Gecode
       return wrap_enum(Util::EnumMatrix.rows(rows, false))
     end
     
-    # Retrieves the currently active space (the one which variables refer to).
+    # Retrieves the currently used space. Calling this method is only allowed 
+    # when sanctioned by the model beforehand, e.g. when the model asks a 
+    # constraint to post itself. Otherwise an RuntimeError is raised.
+    #
+    # 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
-      @active_space ||= base_space
-    end
-    
-    # Retrieves the base from which searches are made. 
-    def base_space
-      @base_space ||= Gecode::Raw::Space.new
+      unless @allow_space_access
+        raise 'Space access is restricted and the permission to access the ' + 
+          'space has not been given.'
+      end
+      selected_space
     end
     
     # Adds the specified constraint to the model. Returns the newly added 
     # constraint.
     def add_constraint(constraint)
-      constraints << constraint
+      add_interaction do
+        constraint.post
+      end
       return constraint
     end
     
+    # Adds a block containing something that interacts with Gecode to a queue
+    # where it is potentially executed.
+    def add_interaction(&block)
+      gecode_interaction_queue << block
+    end
+    
+    # Allows the model's active space to be accessed while the block is 
+    # executed. Don't use this unless you know what you're doing. Anything that
+    # the space is used for (such as bound variables) must be released before
+    # the block ends.
+    #
+    # Returns the result of the block.
+    def allow_space_access(&block)
+      # 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.
+      old = @allow_space_access
+      @allow_space_access = true
+      res = yield
+      @allow_space_access = old
+      return res
+    end
+    
     protected
     
-    def constraints
-      @constraints ||= []
+    # Gets a queue of objects that can be posted to the model's active_space 
+    # (by calling their post method).
+    def gecode_interaction_queue
+      @gecode_interaction_queue ||= []
     end
     
     private
     
-    # Returns the range of the specified domain arguments, which can either be
-    # given as a range or a number of elements. Raises ArgumentError if no 
-    # arguments have been specified. 
-    def domain_range(*domain_args)
-      min = max = nil
+    # Returns an enumeration of the specified domain arguments, which can 
+    # either be given as a range or a number of elements. Raises ArgumentError 
+    # if no arguments have been specified. 
+    def domain_enum(*domain_args)
       if domain_args.empty?
         raise ArgumentError, 'A domain has to be specified.'
       elsif domain_args.size > 1
-        min = domain_args.min
-        max = domain_args.max
+        return domain_args
       else
         element = domain_args.first
-        if element.respond_to?(:begin) and element.respond_to?(:end) and
+        if element.respond_to?(:first) and element.respond_to?(:last) and
             element.respond_to?(:exclude_end?)
-          min = element.begin
-          max = element.end
-          max -= 1 if element.exclude_end?
+          if element.exclude_end?
+            return element.first..(element.last - 1)
+          else
+            return element
+          end
         else
-          min = max = element
+          return element..element
         end
       end
-      return min..max
     end
     
     # Transforms the argument to a set cardinality range, returns nil if the
@@ -196,20 +222,15 @@ module Gecode
       end
     end
     
-    # Creates an integer variable from the specified index and domain. The 
-    # domain can either be given as a range or as a number of elements.
-    def construct_int_var(index, *domain_args)
-      var = FreeIntVar.new(self, index)
-      
-      if domain_args.size > 1
-        # Place an additional domain constraint on the variable with the 
-        # arguments as domain. We post it directly since there's no reason not
-        # to and the user might otherwise get unexpected domains when inspecting
-        # the variable before solving.
-        constraint = var.must_be.in domain_args
-        @constraints.delete(constraint).post
-      end
-      return var
+    # Retrieves the base from which searches are made. 
+    def base_space
+      @base_space ||= Gecode::Raw::Space.new
+    end
+    
+    # Retrieves the currently selected space, the one which constraints and 
+    # variables should be bound to.
+    def selected_space
+      @active_space ||= base_space
     end
   end
 end

data/lib/gecoder/interface/search.rb

@@ -36,20 +36,89 @@ module Gecode
       self.reset!
     end
     
+    # Finds the optimal solution. Optimality is defined by the provided block
+    # which is given one parameter, a solution to the problem. The block should
+    # constrain the solution so that that only "better" solutions can be new 
+    # solutions. For instance if one wants to optimize a variable named price
+    # (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
+    #
+    # Returns nil if there is no solution.
+    def optimize!(&block)
+      next_space = nil
+      best_space = nil
+      bab = bab_engine
+      
+      Model.constrain_proc = lambda do |home_space, best_space|
+        @active_space = best_space
+        yield(self, self)
+        @active_space = home_space
+        perform_queued_gecode_interactions
+      end
+      
+      while not (next_space = bab.next).nil?
+        best_space = next_space
+      end
+      Model.constrain_proc = nil
+      return nil if best_space.nil?
+      return self
+    end
+    
+    class <<self
+      def constrain_proc=(proc)
+        @constrain_proc = proc
+      end
+    
+      def constrain(home, best)
+        if @constrain_proc.nil?
+          raise NotImplementedError, 'Constrain method not implemented.' 
+        else
+          @constrain_proc.call(home, best)
+        end
+      end
+    end
+    
     private
     
-    # Creates an DFS engine for the search, executing any unexecuted 
-    # constraints first.
+    # Creates a depth first search engine for search, executing any 
+    # unexecuted constraints first.
     def dfs_engine
       # Execute constraints.
-      constraints.each{ |con| con.post }
-      constraints.clear # Empty the queue.
+      perform_queued_gecode_interactions
+      
+      # Construct the engine.
+      stop = Gecode::Raw::Search::Stop.new
+      Gecode::Raw::DFS.new(selected_space, 
+        Gecode::Raw::Search::Config::MINIMAL_DISTANCE,
+        Gecode::Raw::Search::Config::ADAPTIVE_DISTANCE, 
+        stop)
+    end
     
+    # Creates a branch and bound engine for optimization search, executing any 
+    # unexecuted constraints first.
+    def bab_engine
+      # Execute constraints.
+      perform_queued_gecode_interactions
+      
+      # Construct the engine.
       stop = Gecode::Raw::Search::Stop.new
-      Gecode::Raw::DFS.new(active_space, 
+      Gecode::Raw::BAB.new(selected_space, 
         Gecode::Raw::Search::Config::MINIMAL_DISTANCE,
         Gecode::Raw::Search::Config::ADAPTIVE_DISTANCE, 
         stop)
     end
+    
+    # Executes any interactions with Gecode still waiting in the queue 
+    # (emptying the queue) in the process.
+    def perform_queued_gecode_interactions
+      allow_space_access do
+        gecode_interaction_queue.each{ |con| con.call }
+        gecode_interaction_queue.clear # Empty the queue.
+      end
+    end
   end
 end

data/lib/gecoder/interface/variables.rb

@@ -22,16 +22,7 @@ module Gecode
   # 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"
-      # Delegate methods we can't handle to the bound int variable if possible.
-      def method_missing(name, *args)
-        if #{bound_class}.instance_methods.include? name.to_s
-          bind.send(name, *args)
-        else
-          super
-        end
-      end
-      
+    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
@@ -51,6 +42,29 @@ module Gecode
           "#<\#{self.class} \#{domain}>"
         end
       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
+      
+      # 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_method_definitions
     return clazz
   end
@@ -58,10 +72,25 @@ module Gecode
   # Int variables.
   FreeIntVar = FreeVar(Gecode::Raw::IntVar, :int_var)
   class FreeIntVar
+    delegate :min
+    delegate :max
+    delegate :size
+    delegate :width
+    delegate :degree
+    delegate :range?, :range
+    delegate :assigned?, :assigned
+    delegate :include?, :in
+    
+    # Gets the value of the assigned integer variable (a fixnum).
+    def value
+      raise 'No value is assigned.' unless assigned?
+      send_bound(:val)
+    end
+    
     # Returns a string representation of the the range of the variable's domain.
     def domain
       if assigned?
-        "range: #{val.to_s}"
+        "range: #{value.to_s}"
       else
         "range: #{min}..#{max}"
       end
@@ -71,25 +100,98 @@ module Gecode
   # Bool variables.
   FreeBoolVar = FreeVar(Gecode::Raw::BoolVar, :bool_var)
   class FreeBoolVar
+    delegate :assigned?, :assigned
+    
+    # Gets the values in the assigned boolean variable (true or false).
+    def value
+      raise 'No value is assigned.' unless assigned?
+      send_bound(:val) == 1
+    end
+  
     # Returns a string representation of the the variable's domain.
     def domain
       if assigned?
-        true?.to_s
+        value.to_s
       else
         'unassigned'
       end
     end
   end
-  
+
   # Set variables.
   FreeSetVar = FreeVar(Gecode::Raw::SetVar, :set_var)
   class FreeSetVar
+    delegate :assigned?, :assigned
+    
+    # Gets all the elements located in the greatest lower bound of the set.
+    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.
+    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
+    
     # Returns a string representation of the the variable's domain.
     def domain
       if assigned?
-        "#{glb_min}..#{lub_min}"
+        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
+    attr :size
+    attr :min
+    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
+
+    # Used by Enumerable.
+    def each(&block)
+      enum.each(&block)
+    end
+    
+    private
+    
+    # Gets the enumeration being viewed.
+    def enum
+      if @enum.nil?
+        @enum = @constructor.call
       else
-        "glb-range: #{glb_min}..#{glb_max}, lub-range: #{lub_min}..#{lub_max}"
+        return @enum
       end
     end
   end