gecoder-with-gecode 0.7.1

data/lib/gecoder/interface/enum_wrapper.rb

@@ -0,0 +1,153 @@
+module Gecode
+  class Model
+    # Wraps a custom enumerable so that constraints can be specified using it.
+    # The argument is altered and returned. 
+    def wrap_enum(enum)
+      unless enum.kind_of? Enumerable
+        raise TypeError, 'Only enumerables can be wrapped.'
+      end
+      elements = enum.to_a
+      if elements.empty?
+        raise ArgumentError, 'Enumerable must not be empty.'
+      end
+      
+      if elements.all?{ |var| var.kind_of? FreeIntVar }
+        class <<enum
+          include Gecode::IntEnumMethods
+        end
+      elsif elements.all?{ |var| var.kind_of? FreeBoolVar }
+        class <<enum
+          include Gecode::BoolEnumMethods
+        end
+      elsif elements.all?{ |var| var.kind_of? FreeSetVar }
+        class <<enum
+          include Gecode::SetEnumMethods
+        end
+      elsif elements.all?{ |var| var.kind_of? Fixnum }
+        class <<enum
+          include Gecode::FixnumEnumMethods
+        end
+      else
+        raise TypeError, "Enumerable doesn't contain variables #{enum.inspect}."
+      end
+      
+      enum.model = self
+      return enum
+    end
+  end
+  
+  # A module containing the methods needed by enumerations containing variables.
+  module EnumMethods
+    attr_accessor :model
+    # Gets the current space of the model the array is connected to.
+    def active_space
+      @model.active_space
+    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 VariableEnumMethods
+  
+    # Returns an int variable array with all the bound variables.
+    def to_int_var_array
+      space = @model.active_space
+      unless @bound_space == space
+        elements = to_a
+        @bound_arr = Gecode::Raw::IntVarArray.new(active_space, elements.size)
+        elements.each_with_index{ |var, index| @bound_arr[index] = var.bind }
+        @bound_space = space
+      end
+      return @bound_arr
+    end
+    alias_method :to_var_array, :to_int_var_array
+    
+    # Returns the smallest range that contains the domains of all integer 
+    # variables involved.
+    def domain_range
+      inject(nil) do |range, var|
+        min = var.min
+        max = var.max
+        next min..max if range.nil?
+        
+        range = min..range.last if min < range.first
+        range = range.first..max if max > range.last
+        range
+      end
+    end
+  end
+  
+  # A module containing the methods needed by enumerations containing boolean
+  # variables. Requires that it's included in an enumerable.
+  module BoolEnumMethods
+    include VariableEnumMethods
+  
+    # Returns a bool variable array with all the bound variables.
+    def to_bool_var_array
+      space = @model.active_space
+      unless @bound_space == space
+        elements = to_a
+        @bound_arr = Gecode::Raw::BoolVarArray.new(active_space, elements.size)
+        elements.each_with_index{ |var, index| @bound_arr[index] = var.bind }
+        @bound_space = space
+      end
+      return @bound_arr
+    end
+    alias_method :to_var_array, :to_bool_var_array
+  end
+  
+  # A module containing the methods needed by enumerations containing set
+  # variables. Requires that it's included in an enumerable.
+  module SetEnumMethods
+    include VariableEnumMethods
+  
+    # Returns a set variable array with all the bound variables.
+    def to_set_var_array
+      space = @model.active_space
+      unless @bound_space == space
+        elements = to_a
+        @bound_arr = Gecode::Raw::SetVarArray.new(active_space, elements.size)
+        elements.each_with_index{ |var, index| @bound_arr[index] = var.bind }
+        @bound_space = space
+      end
+      return @bound_arr
+    end
+    alias_method :to_var_array, :to_set_var_array
+    
+    # Returns the range of the union of the contained sets' upper bounds.
+    def upper_bound_range
+      inject(nil) do |range, var|
+        upper_bound = var.upper_bound
+        min = upper_bound.min
+        max = upper_bound.max
+        next min..max if range.nil?
+        
+        range = min..range.last if min < range.first
+        range = range.first..max if max > range.last
+        range
+      end
+    end
+  end
+  
+  # A module containing the methods needed by enumerations containing fixnums. 
+  # Requires that it's included in an enumerable.
+  module FixnumEnumMethods
+    include EnumMethods
+    
+    # Returns the smallest range that contains the domains of all integer 
+    # variables involved.
+    def domain_range
+      min..max
+    end
+  end
+end

data/lib/gecoder/interface/model.rb

@@ -0,0 +1,251 @@
+module Gecode
+  # Model is the base class that all models must inherit from.
+  class Model
+    # Creates a new integer variable with the specified domain. The domain can
+    # either be a range, a single element, or an enumeration of elements. If no
+    # domain is specified then the largest possible domain is used.
+    def int_var(domain = 
+        Gecode::Raw::Limits::Int::INT_MIN..Gecode::Raw::Limits::Int::INT_MAX)
+      enum = domain_enum(domain)
+      index = variable_creation_space.new_int_vars(enum).first
+      FreeIntVar.new(self, index)
+    end
+    
+    # Creates an array containing the specified number of integer variables 
+    # with the specified domain. The domain can either be a range, a single 
+    # element, or an enumeration of elements. 
+    def int_var_array(count, domain)
+      enum = domain_enum(domain)
+      variables = []
+      variable_creation_space.new_int_vars(enum, count).each do |index|
+        variables << FreeIntVar.new(self, index)
+      end
+      return wrap_enum(variables)
+    end
+    
+    # Creates a matrix containing the specified number rows and columns of 
+    # integer variables with the specified domain. The domain can either be a 
+    # range, a single element, or an enumeration of elements. 
+    def int_var_matrix(row_count, col_count, domain)
+      enum = domain_enum(domain)
+      indices = variable_creation_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|
+          FreeIntVar.new(self, index)
+        end
+      end
+      return wrap_enum(Util::EnumMatrix.rows(rows, false))
+    end
+    
+    # Creates a new boolean variable.
+    def bool_var
+      index = variable_creation_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 = []
+      variable_creation_space.new_bool_vars(count).each do |index|
+        variables << FreeBoolVar.new(self, index)
+      end
+      return wrap_enum(variables)
+    end
+    
+    # Creates a matrix containing the specified number rows and columns of 
+    # boolean variables.
+    def bool_var_matrix(row_count, col_count)
+      indices = variable_creation_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|
+          FreeBoolVar.new(self, index)
+        end
+      end
+      return wrap_enum(Util::EnumMatrix.rows(rows, false))
+    end
+    
+    # Creates a set variable with the specified domain for greatest lower bound
+    # and least upper bound (specified as either a range or enum). If no bounds
+    # are specified then the empty set is used as greates lower bound and the 
+    # universe as least upper bound. A range for the allowed cardinality of the 
+    # set can also be specified, if none is specified, or nil is given, then the
+    # default range (anything) will be used. If only a single Fixnum is 
+    # specified as cardinality_range then it's used as lower bound.
+    def set_var(glb_domain = [], lub_domain = 
+        Gecode::Raw::Limits::Set::INT_MIN..Gecode::Raw::Limits::Set::INT_MAX, 
+        cardinality_range = nil)
+      check_set_bounds(glb_domain, lub_domain)
+      
+      index = variable_creation_space.new_set_vars(glb_domain, lub_domain, 
+        to_set_cardinality_range(cardinality_range)).first
+      FreeSetVar.new(self, index)
+    end
+    
+    # Creates an array containing the specified number of set variables. The
+    # parameters beyond count are the same as for #set_var .
+    def set_var_array(count, glb_domain, lub_domain, cardinality_range = nil)
+      check_set_bounds(glb_domain, lub_domain)
+      
+      variables = []
+      variable_creation_space.new_set_vars(glb_domain, lub_domain, 
+          to_set_cardinality_range(cardinality_range), count).each do |index|
+        variables << FreeSetVar.new(self, index)
+      end
+      return wrap_enum(variables)
+    end
+    
+    # Creates a matrix containing the specified number of rows and columns 
+    # filled with set variables. The parameters beyond row and column counts are
+    # the same as for #set_var .
+    def set_var_matrix(row_count, col_count, glb_domain, lub_domain, 
+        cardinality_range = nil)
+      check_set_bounds(glb_domain, lub_domain)
+      
+      indices = variable_creation_space.new_set_vars(glb_domain, lub_domain, 
+        to_set_cardinality_range(cardinality_range), row_count*col_count)
+      rows = []
+      row_count.times do |i|
+        rows << indices[(i*col_count)...(i.succ*col_count)].map! do |index|
+          FreeSetVar.new(self, index)
+        end
+      end
+      return wrap_enum(Util::EnumMatrix.rows(rows, false))
+    end
+    
+    # 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 #:nodoc:
+      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) #:nodoc:
+      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) #:nodoc:
+      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) #: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.
+      old = @allow_space_access
+      @allow_space_access = true
+      res = yield
+      @allow_space_access = old
+      return res
+    end
+    
+    # Starts tracking a variable that depends on the space. All variables 
+    # created should call this method for their respective models.
+    def track_variable(variable) #:nodoc:
+      (@variables ||= []) << variable
+    end
+    
+    protected
+    
+    # Gets a queue of objects that can be posted to the model's active_space 
+    # (by calling their post method).
+    def gecode_interaction_queue #:nodoc:
+      @gecode_interaction_queue ||= []
+    end
+    
+    private
+    
+    # Returns an enumeration of the specified domain arguments, which can 
+    # either be given as a range, a single number, or an enumerable of elements. 
+    def domain_enum(domain)
+      if domain.respond_to?(:first) and domain.respond_to?(:last) and
+            domain.respond_to?(:exclude_end?)
+        if domain.exclude_end?
+          return domain.first..(domain.last - 1)
+        else
+          return domain
+        end
+      elsif domain.kind_of? Enumerable
+        return domain
+      else
+        return domain..domain
+      end
+    end
+    
+    # Transforms the argument to a set cardinality range, returns nil if the
+    # default range should be used. If arg is a range then that's used, 
+    # otherwise if the argument is a fixnum it's used as lower bound.
+    def to_set_cardinality_range(arg)
+      if arg.kind_of? Fixnum
+        arg..Gecode::Raw::Limits::Set::CARD_MAX
+      else
+        arg
+      end
+    end
+    
+    # Checks whether the specified greatest lower bound is a subset of least 
+    # upper bound. Raises ArgumentError if that is not the case.
+    def check_set_bounds(glb, lub)
+      unless valid_set_bounds?(glb, lub)
+        raise ArgumentError, 
+          "Invalid set bounds: #{glb} is not a subset of #{lub}."
+      end
+    end
+    
+    # Returns whether the greatest lower bound is a subset of least upper 
+    # bound.
+    def valid_set_bounds?(glb, lub)
+      return true if glb.respond_to?(:empty?) and glb.empty? 
+      if glb.kind_of?(Range) and lub.kind_of?(Range)
+        glb.first >= lub.first and glb.last <= lub.last
+      else
+        (glb.to_a - lub.to_a).empty?
+      end
+    end
+    
+    # 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
+    
+    # Retrieves the space that should be used for variable creation.
+    def variable_creation_space
+      @variable_creation_space || selected_space
+    end
+    
+    # Refreshes all cached variables. This should be called if the variables
+    # in an existing space were changed.
+    def refresh_variables
+      @variables.each do |variable|
+        variable.refresh if variable.cached?
+      end
+    end
+  end
+end

data/lib/gecoder/interface/search.rb

@@ -0,0 +1,123 @@
+module Gecode
+  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.
+    def solve!
+      space = dfs_engine.next
+      return nil if space.nil?
+      @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.
+    def reset!
+      @active_space = base_space
+      return self
+    end
+    
+    # Yields the first solution (if any) to the block. If no solution is found
+    # 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
+    end
+    
+    # Yields each solution that the model has.
+    def each_solution(&block)
+      dfs = dfs_engine
+      while not (@active_space = dfs.next).nil?
+        yield self
+      end
+      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)
+      # Execute constraints.
+      perform_queued_gecode_interactions
+
+      # Set the method used for constrain calls by the BAB-search.
+      Model.constrain_proc = lambda do |home_space, best_space|
+        @active_space = best_space
+        @variable_creation_space = home_space
+        yield(self, self)
+        @active_space = home_space
+        @variable_creation_space = nil
+        
+        perform_queued_gecode_interactions
+      end
+
+      # Perform the search.
+      result = Gecode::Raw::bab(selected_space, 
+        Gecode::Raw::Search::Config::MINIMAL_DISTANCE, 
+        Gecode::Raw::Search::Config::ADAPTIVE_DISTANCE, 
+        nil)
+      
+      # Reset the method used constrain calls and return the result.
+      Model.constrain_proc = nil
+      return nil if result.nil?
+      
+      # Refresh the solution.
+      result.refresh
+      refresh_variables
+      @active_space = result
+      return self
+    end
+    
+    class <<self 
+      # Sets the proc that should be used to handle constrain requests.
+      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) #:nodoc:
+        if @constrain_proc.nil?
+          raise NotImplementedError, 'Constrain method not implemented.' 
+        else
+          @constrain_proc.call(home, best)
+        end
+      end
+    end
+    
+    private
+    
+    # Creates a depth first search engine for search, executing any 
+    # unexecuted constraints first.
+    def dfs_engine
+      # Execute constraints.
+      perform_queued_gecode_interactions
+      
+      # Construct the engine.
+      Gecode::Raw::DFS.new(selected_space, 
+        Gecode::Raw::Search::Config::MINIMAL_DISTANCE,
+        Gecode::Raw::Search::Config::ADAPTIVE_DISTANCE, 
+        nil)
+    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