gecoder 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