gecoder-with-gecode 0.9.0-x86-mswin32-60

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

@@ -0,0 +1,197 @@
+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. 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
+      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.
+    def reset!
+      self.active_space = base_space
+      @statistics = nil
+      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)
+      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.
+    def each_solution(&block)
+      dfs = dfs_engine
+      next_solution = nil
+      while not (next_solution = dfs.next).nil?
+        self.active_space = next_solution
+        @statistics = dfs.statistics
+        yield self
+      end
+      self.reset!
+    end
+    
+    # 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 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.
+    # [:clones]         The number of clones created.
+    # [:commits]        The number of commit operations performed.
+    # [:memory]         The peak memory allocated to Gecode.
+    def search_stats
+      return nil if @statistics.nil?
+      
+      return {
+        :propagations => @statistics.propagate,
+        :failures     => @statistics.fail,
+        :clones       => @statistics.clone,
+        :commits      => @statistics.commit,
+        :memory       => @statistics.memory
+      }
+    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
+    #
+    # Raises Gecode::NoSolutionError if no solution can be found.
+    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|
+        self.active_space = best_space
+        @variable_creation_space = home_space
+        yield(self, self)
+        self.active_space = home_space
+        @variable_creation_space = nil
+        
+        perform_queued_gecode_interactions
+      end
+
+      # Perform the search.
+      options = Gecode::Raw::Search::Options.new
+      options.c_d = Gecode::Raw::Search::Config::MINIMAL_DISTANCE
+      options.a_d = Gecode::Raw::Search::Config::ADAPTIVE_DISTANCE
+      options.stop = nil
+      bab = Gecode::Raw::BAB.new(selected_space, options)
+      
+      result = nil
+      previous_solution = nil
+      until (previous_solution = bab.next).nil?
+        result = previous_solution
+      end
+      @statistics = bab.statistics
+      
+      # Reset the method used constrain calls and return the result.
+      Model.constrain_proc = nil
+      raise Gecode::NoSolutionError if result.nil?
+      
+      # Switch to the result.
+      self.active_space = result
+      return self
+    end
+    
+    # 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.
+    #
+    #   model.maximize! :profit
+    #
+    # Raises Gecode::NoSolutionError if no solution can be found.
+    def maximize!(var)
+      variable = self.method(var).call
+      unless variable.kind_of? Gecode::IntVar
+        raise ArgumentError.new("Expected integer variable, got #{variable.class}.")
+      end
+      
+      optimize! do |model, best_so_far|
+        model.method(var).call.must > best_so_far.method(var).call.value
+      end
+    end
+    
+    # Finds the solution that minimizes a given integer variable. The name of 
+    # the method that accesses the variable from the model should be given. To 
+    # for instance minimize a variable named "cost", that's accessible through 
+    # the model, one would use the following.
+    #
+    #   model.minimize! :cost
+    #
+    # Raises Gecode::NoSolutionError if no solution can be found.
+    def minimize!(var)
+      variable = self.method(var).call
+      unless variable.kind_of? Gecode::IntVar
+        raise ArgumentError.new("Expected integer variable, got #{variable.class}.")
+      end
+      
+      optimize! do |model, best_so_far|
+        model.method(var).call.must < best_so_far.method(var).call.value
+      end
+    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
+  end
+end

data/lib/gecoder/interface/variables.rb

@@ -0,0 +1,306 @@
+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
+      model.track_variable(self)
+    end
+
+    def inspect
+      if assigned?
+        "#<#{self.class} #{domain_string}>"
+      else
+        "#<#{self.class} #{domain_string}>"
+      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) #:nodoc:
+    clazz = Class.new(FreeVarBase)
+    clazz.class_eval <<-"end_method_definitions"      
+      # 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
+      
+      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
+  
+  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.
+    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
+
+    # 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 range of the variable's domain.
+    def domain_string #:nodoc:
+      if assigned?
+        "range: #{value.to_s}"
+      else
+        "range: #{min}..#{max}"
+      end
+    end
+  end
+  
+  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
+    
+    # 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
+
+    # Returns the receiver.
+    def to_bool_var
+      self
+    end
+  
+    private
+  
+    # Returns a string representation of the the variable's domain.
+    def domain_string
+      if assigned?
+        value.to_s
+      else
+        'unassigned'
+      end
+    end
+  end
+
+  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.
+  #   
+  # 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.
+  #
+  # 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
+      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
+    
+    # Returns the receiver.
+    def to_set_var
+      self
+    end
+    
+    private
+    
+    # Returns a string representation of the the variable's domain.
+    def domain_string
+      if assigned?
+        if lower_bound.size < 100
+          lower_bound.to_a.inspect
+        else
+          "the domain is too large to display"
+        end
+      else
+        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
+  
+  # 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