gecoder-with-gecode 0.8.3 → 0.9.0

data/lib/gecoder/interface/enum_matrix.rb

@@ -1,8 +1,8 @@
 require 'matrix'
 
-module Gecode::Util
+module Gecode::Util #:nodoc:
   # Methods that make a matrix an enumerable.
-  module MatrixEnumMethods
+  module MatrixEnumMethods #:nodoc:
     include Enumerable
   
     # Iterates over every element in the matrix.
@@ -16,7 +16,7 @@ module Gecode::Util
   end
 
   # Extends Matrix so that it's an enumerable.
-  class EnumMatrix < Matrix
+  class EnumMatrix < Matrix #:nodoc:
     include MatrixEnumMethods
     
     def row(i)
@@ -61,4 +61,4 @@ module Gecode::Util
       end
     end
   end
-end
+end

data/lib/gecoder/interface/enum_wrapper.rb

@@ -14,15 +14,18 @@ module Gecode
         raise ArgumentError, 'Enumerable must not be empty.'
       end
       
-      if elements.all?{ |var| var.kind_of? FreeIntVar }
+      if elements.all?{ |var| var.respond_to? :to_int_var }
+        elements.map!{ |var| var.to_int_var }
         class <<enum
           include Gecode::IntEnumMethods
         end
-      elsif elements.all?{ |var| var.kind_of? FreeBoolVar }
+      elsif elements.all?{ |var| var.respond_to? :to_bool_var }
+        elements.map!{ |var| var.to_bool_var }
         class <<enum
           include Gecode::BoolEnumMethods
         end
-      elsif elements.all?{ |var| var.kind_of? FreeSetVar }
+      elsif elements.all?{ |var| var.respond_to? :to_set_var }
+        elements.map!{ |var| var.to_set_var }
         class <<enum
           include Gecode::SetEnumMethods
         end
@@ -31,7 +34,7 @@ module Gecode
           include Gecode::FixnumEnumMethods
         end
       else
-        raise TypeError, "Enumerable doesn't contain variables #{enum.inspect}."
+        raise TypeError, "Enumerable doesn't contain operands #{enum.inspect}."
       end
       
       enum.model = self
@@ -39,8 +42,9 @@ module Gecode
     end
   end
   
-  # A module containing the methods needed by enumerations containing variables.
-  module EnumMethods
+  # A module containing the methods needed by enumerations containing
+  # operands.
+  module EnumMethods #:nodoc:
     attr_accessor :model
     # Gets the current space of the model the array is connected to.
     def active_space
@@ -48,22 +52,23 @@ module Gecode
     end
   end
   
-  module VariableEnumMethods
+  module VariableEnumMethods #:nodoc:
     include EnumMethods
     
-    # Gets the values of all the variables in the enum.
+    # Gets the values of all the operands 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
+  # operands. Requires that it's included in an enumerable.
+  module IntEnumMethods #:nodoc:
+    include IntEnum::IntEnumOperand
     include VariableEnumMethods
   
     # Returns an int variable array with all the bound variables.
-    def to_int_var_array
+    def bind_array
       space = @model.active_space
       unless @bound_space == space
         elements = to_a
@@ -73,7 +78,11 @@ module Gecode
       end
       return @bound_arr
     end
-    alias_method :to_var_array, :to_int_var_array
+
+    # Returns the receiver.
+    def to_int_enum
+      self
+    end
     
     # Returns the smallest range that contains the domains of all integer 
     # variables involved.
@@ -89,14 +98,21 @@ module Gecode
       end
     end
   end
+
+  # A dummy class that just shows what methods an int enum responds to.
+  class IntEnum::Dummy < Array #:nodoc:
+    include IntEnum::IntEnumOperand
+    include VariableEnumMethods
+  end
   
   # A module containing the methods needed by enumerations containing boolean
-  # variables. Requires that it's included in an enumerable.
-  module BoolEnumMethods
+  # operands. Requires that it's included in an enumerable.
+  module BoolEnumMethods #:nodoc:
+    include BoolEnum::BoolEnumOperand
     include VariableEnumMethods
   
     # Returns a bool variable array with all the bound variables.
-    def to_bool_var_array
+    def bind_array
       space = @model.active_space
       unless @bound_space == space
         elements = to_a
@@ -106,16 +122,27 @@ module Gecode
       end
       return @bound_arr
     end
-    alias_method :to_var_array, :to_bool_var_array
+
+    # Returns the receiver.
+    def to_bool_enum
+      self
+    end
+  end
+
+  # A dummy class that just shows what methods a bool enum responds to.
+  class BoolEnum::Dummy < Array #:nodoc:
+    include BoolEnum::BoolEnumOperand
+    include VariableEnumMethods
   end
   
   # A module containing the methods needed by enumerations containing set
-  # variables. Requires that it's included in an enumerable.
-  module SetEnumMethods
+  # operands. Requires that it's included in an enumerable.
+  module SetEnumMethods #:nodoc:
+    include SetEnum::SetEnumOperand
     include VariableEnumMethods
   
     # Returns a set variable array with all the bound variables.
-    def to_set_var_array
+    def bind_array
       space = @model.active_space
       unless @bound_space == space
         elements = to_a
@@ -125,8 +152,12 @@ module Gecode
       end
       return @bound_arr
     end
-    alias_method :to_var_array, :to_set_var_array
     
+    # Returns the receiver.
+    def to_set_enum
+      self
+    end
+
     # Returns the range of the union of the contained sets' upper bounds.
     def upper_bound_range
       inject(nil) do |range, var|
@@ -141,16 +172,34 @@ module Gecode
       end
     end
   end
+
+  # A dummy class that just shows what methods a set enum responds to.
+  class SetEnum::Dummy < Array #:nodoc:
+    include SetEnum::SetEnumOperand
+    include VariableEnumMethods
+  end
   
   # A module containing the methods needed by enumerations containing fixnums. 
   # Requires that it's included in an enumerable.
-  module FixnumEnumMethods
+  module FixnumEnumMethods #:nodoc:
+    include FixnumEnum::FixnumEnumOperand
     include EnumMethods
     
+    # Returns the receiver.
+    def to_fixnum_enum
+      self
+    end
+
     # Returns the smallest range that contains the domains of all integer 
     # variables involved.
     def domain_range
       min..max
     end
   end
-end
+  
+  # A dummy class that just shows what methods a fixnum enum responds to.
+  class FixnumEnum::Dummy < Array #:nodoc:
+    include FixnumEnum::FixnumEnumOperand
+    include VariableEnumMethods
+  end
+end

data/lib/gecoder/interface/model.rb

@@ -1,5 +1,113 @@
 module Gecode
   # Model is the base class that all models must inherit from.
+  #
+  # == Formulating problems
+  #
+  # Models are used to formulate the problems that Gecode should solve.
+  # Below is an example of a model that formulates the problem of finding
+  # a solution to the following equation system.
+  #
+  # Equation system:
+  #   x + y = z
+  #   x = y - 3
+  #   0 <= x,y,z <= 9
+  #
+  # Model:
+  #   class EquationProblem < Gecode::Model
+  #     attr :vars
+  #
+  #     def initialize
+  #       x, y, z = @vars = int_var_array(3, 0..9)
+  #
+  #       (x + y).must == z
+  #       x.must == y - 3
+  #
+  #       branch_on @vars
+  #     end
+  #   end
+  # 
+  # A model typically consists of three main parts:
+  # [Variables] Variables specify how to view the problem. A solution is an 
+  #             assignment of the variables. In the example above we created 
+  #             an array of three integer variables with domains 0..9 and gave 
+  #             it the name +variables+.
+  #
+  #             There are three types of variables: integer variables
+  #             (Gecode::IntVar, can be assigned one of many
+  #             possible integer values), boolean variables
+  #             (Gecode::BoolVar, can be assigned either true or
+  #             false) and set variables (Gecode::SetVar, can be
+  #             assigned a set of integers).  Variables of the different
+  #             types are constructed using #int_var, #int_var_array,
+  #             #int_var_matrix, #bool_var, #bool_var_array,
+  #             #bool_var_matrix, #set_var, #set_var_array and
+  #             #set_var_matrix .
+  #
+  #             The various variables all have the functionality of Operand 
+  #             and have many properties depending on their type. For 
+  #             instance integer variables have the properties defined
+  #             in Gecode::Int::IntOperand and
+  #             enumerations of integer variables (such as the array
+  #             +variables+ we used) have the properties defined in  
+  #             Gecode::IntEnum::IntEnumOperand .
+  #             
+  # [Constraints] Constraints are placed on the variables to ensure that a 
+  #               valid assignment of the variables must also be a solution.
+  #               In the example above we constrained the variables so
+  #               that all equations were satisfied (which is exactly when
+  #               we have found a solution).
+  #
+  #               The various constraints that can be placed on the various
+  #               kinds of operands are found in the respective
+  #               constraint receivers. For instance, the constraints
+  #               that can be placed on integer operands are found in 
+  #               Gecode::Int::IntConstraintReceiver and
+  #               the constraints that can be placed on enumerations of
+  #               integer operands are found in 
+  #               Gecode::IntEnum::IntEnumConstraintReceiver .
+  #
+  # [Branching] "branch_on variables" in the example tells Gecode that
+  #             it should explore the search space until it has assigned
+  #             +variables+ (or exhausted the search space). It also
+  #             tells Gecode in what order the search space should be
+  #             explore, which can have a big effect on the search
+  #             performance. See #branch_on for details.
+  #
+  # == Finding solutions
+  #
+  # Solutions to a formulated problem are found are found by using
+  # methods such as #solve!, #solution, #each_solution . If one wants to
+  # find a solution that optimizes a certain quantity (i.e. maximizes a
+  # certain variable) then one should have a look at #maximize!,
+  # #minimize! and #optimize! .
+  #
+  # The first solution to the example above could for instance be found
+  # using
+  #
+  #   puts EquationProblem.new.solve!.vars.values.join(', ')
+  #
+  # which would find the first solution to the problem, access the
+  # assigned values of +variables+ and print them (in order x, y, z).
+  #
+  # == Shorter ways of formulating problems
+  #
+  # Problems can also be formulated without defining a new class by
+  # using Gecode#solve et al.
+  #
+  # Additionally one can use "foo_is_an ..." to create an accessor of 
+  # name foo, without having to use instance variables. The above
+  # problem becomes
+  #   class EquationProblem < Gecode::Model
+  #     def initialize
+  #       x, y, z = vars_is_an int_var_array(3, 0..9)
+  #
+  #       (x + y).must == z
+  #       x.must == y - 3
+  #
+  #       branch_on vars
+  #     end
+  #   end
+  #
   class Model
     # The largest integer allowed in the domain of an integer variable.
     MAX_INT = Gecode::Raw::IntLimits::MAX
@@ -25,7 +133,7 @@ module Gecode
     # domain is specified then the largest possible domain is used.
     def int_var(domain = LARGEST_INT_DOMAIN)
       args = domain_arguments(domain)
-      FreeIntVar.new(self, variable_creation_space.new_int_var(*args))
+      IntVar.new(self, variable_creation_space.new_int_var(*args))
     end
     
     # Creates an array containing the specified number of integer variables 
@@ -35,7 +143,7 @@ module Gecode
     def int_var_array(count, domain = LARGEST_INT_DOMAIN)
       args = domain_arguments(domain)
       build_var_array(count) do
-        FreeIntVar.new(self, variable_creation_space.new_int_var(*args))
+        IntVar.new(self, variable_creation_space.new_int_var(*args))
       end
     end
     
@@ -46,19 +154,19 @@ module Gecode
     def int_var_matrix(row_count, col_count, domain = LARGEST_INT_DOMAIN)
       args = domain_arguments(domain)
       build_var_matrix(row_count, col_count) do
-        FreeIntVar.new(self, variable_creation_space.new_int_var(*args))
+        IntVar.new(self, variable_creation_space.new_int_var(*args))
       end
     end
     
     # Creates a new boolean variable.
     def bool_var
-      FreeBoolVar.new(self, variable_creation_space.new_bool_var)
+      BoolVar.new(self, variable_creation_space.new_bool_var)
     end
     
     # Creates an array containing the specified number of boolean variables.
     def bool_var_array(count)
       build_var_array(count) do
-        FreeBoolVar.new(self, variable_creation_space.new_bool_var)
+        BoolVar.new(self, variable_creation_space.new_bool_var)
       end
     end
     
@@ -66,7 +174,7 @@ module Gecode
     # boolean variables.
     def bool_var_matrix(row_count, col_count)
       build_var_matrix(row_count, col_count) do
-        FreeBoolVar.new(self, variable_creation_space.new_bool_var)
+        BoolVar.new(self, variable_creation_space.new_bool_var)
       end
     end
     
@@ -82,7 +190,7 @@ module Gecode
     def set_var(glb_domain = [], lub_domain = LARGEST_SET_BOUND,
         cardinality_range = nil)
       args = set_bounds_to_parameters(glb_domain, lub_domain, cardinality_range)
-      FreeSetVar.new(self, variable_creation_space.new_set_var(*args))
+      SetVar.new(self, variable_creation_space.new_set_var(*args))
     end
     
     # Creates an array containing the specified number of set variables. The
@@ -91,7 +199,7 @@ module Gecode
         cardinality_range = nil)
       args = set_bounds_to_parameters(glb_domain, lub_domain, cardinality_range)
       build_var_array(count) do
-        FreeSetVar.new(self, variable_creation_space.new_set_var(*args))
+        SetVar.new(self, variable_creation_space.new_set_var(*args))
       end
     end
     
@@ -102,7 +210,7 @@ module Gecode
         lub_domain = LARGEST_SET_BOUND, cardinality_range = nil)
       args = set_bounds_to_parameters(glb_domain, lub_domain, cardinality_range)
       build_var_matrix(row_count, col_count) do
-        FreeSetVar.new(self, variable_creation_space.new_set_var(*args))
+        SetVar.new(self, variable_creation_space.new_set_var(*args))
       end
     end
     
@@ -157,7 +265,54 @@ module Gecode
     def track_variable(variable) #:nodoc:
       (@variables ||= []) << variable
     end
-    
+
+    # Wraps method missing to handle #foo_is_a and #foo_is_an . 
+    #
+    # "<variable_name>_is_a <variable>" or "<variable_name>_is_an <variable>", 
+    # replacing "<variable_name>" with the variable's name and 
+    # "<variable>" with the variable, adds an instance variable and 
+    # accessor with the specified name.
+    #
+    # The method also returns the variable given.
+    #
+    # ==== Example
+    #
+    #   # Add an instance variable and accessor named "foo" that return
+    #   # the integer variable.
+    #   foo_is_an int_var(0..9)
+    #
+    #   # Add an instance variable and accessor named "bar" that return
+    #   # the boolean variable array.
+    #   bar_is_a bool_var_array(2)
+    def method_missing(name_symbol, *args)
+      name = name_symbol.to_s
+      if name =~ /._is_an?$/
+        name.sub!(/_is_an?$/, '')
+        unless args.size == 1
+          raise ArgumentError, "Wrong number of argmuments (#{args.size} for 1)."
+        end 
+        if respond_to? name
+          raise ArgumentError, "Method with name #{name} already exists."
+        end
+        if instance_variable_defined? "@#{name}"
+          raise ArgumentError, 
+            "Instance variable with name @#{name} already exists."
+        end
+
+        # We use the meta class to avoid defining the variable in all
+        # other instances of the class.
+        eval <<-"end_eval"
+          @#{name} = args.first
+          class <<self
+            attr :#{name}
+          end
+        end_eval
+        return args.first
+      else
+        super
+      end
+    end
+
     protected
     
     # Gets a queue of objects that can be posted to the model's active_space 
@@ -231,8 +386,8 @@ module Gecode
     def set_bounds_to_parameters(glb_domain, lub_domain, cardinality_range)
       check_set_bounds(glb_domain, lub_domain)
       args = []
-      args << Gecode::Constraints::Util.constant_set_to_int_set(glb_domain)
-      args << Gecode::Constraints::Util.constant_set_to_int_set(lub_domain)
+      args << Gecode::Util.constant_set_to_int_set(glb_domain)
+      args << Gecode::Util.constant_set_to_int_set(lub_domain)
       card_range = to_set_cardinality_range(cardinality_range)
       if card_range.nil?
         card_range = 0..Gecode::Raw::SetLimits::CARD

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