gecoder 0.8.3 → 0.9.0

data/lib/gecoder/interface/constraints/int_enum/sort.rb

@@ -1,36 +1,60 @@
-module Gecode::Constraints::IntEnum
-  class Expression
-    # Initiates a sort constraint. Beyond the common options the sort constraint
-    # can also take the following options:
+module Gecode::IntEnum
+  class IntEnumConstraintReceiver
+    # Constrains the elements in this enumeration to be sorted in ascending 
+    # order. The following options can be given in addition to the
+    # common constraint options:
     # 
-    # [:as]     Defines a target (must be an int variable enumerable) that will
+    # [:as]     Defines a target (must be an IntEnum) that will
     #           hold the sorted version of the original enumerable. The original
     #           enumerable will not be affected (i.e. will not necessarily be 
     #           sorted)
-    # [:order]  Sets an int variable enumerable that should be used to store the
-    #           order of the original enum's variables when sorted. The original
+    # [:order]  Sets an IntEnum that should be used to store the
+    #           order of the original enum's operands when sorted. The original
     #           enumerable will not be affected (i.e. will not necessarily be 
     #           sorted)
     # 
     # If neither of those options are specified then the original enumerable
     # will be constrained to be sorted (otherwise not). Sort constraints with
     # options do not allow negation.
+    #
+    # ==== Examples 
+    #
+    #   # Constrain +numbers+ to be sorted.
+    #   numbers.must_be.sorted
+    #
+    #   # Constrain +numbers+ to not be sorted.
+    #   numbers.must_not_be.sorted
+    # 
+    #   # Constrain +sorted_numbers+ to be a sorted version of +numbers+. 
+    #   numbers.must_be.sorted(:as => sorted_numbers)
+    #
+    #   # Constrain +order+ to be the order in which +numbers+ has to be
+    #   # ordered to be sorted.
+    #   numbers.must_be.sorted(:order => order)
+    #   
+    #   # Constrain +sorted_numbers+ to be +numbers+ sorted in the order 
+    #   # described by the IntEnum +order+. 
+    #   numbers.must_be.sorted(:as => sorted_numbers, :order => order)
+    #
+    #   # Constrains +numbers+ to be sorted, reifying with the boolean 
+    #   # operand +is_sorted+, while selecting +domain+ as strength.
+    #   numbers.must_be.sorted(:reify => :is_sorted, :strength => :domain)
     def sorted(options = {})
       # Extract and check options.
       target = options.delete(:as)
       order = options.delete(:order)
-      unless target.nil? or target.respond_to? :to_int_var_array
+      unless target.nil? or target.respond_to? :to_int_enum
         raise TypeError, 'Expected int var enum as :as, got ' + 
           "#{target.class}."
       end
-      unless order.nil? or order.respond_to? :to_int_var_array
+      unless order.nil? or order.respond_to? :to_int_enum
         raise TypeError, 'Expected int var enum as :order, got ' + 
           "#{order.class}."
       end
       
       # Extract standard options and convert to constraint.
       reified = !options[:reify].nil?
-      @params.update(Gecode::Constraints::Util.decode_options(options))
+      @params.update(Gecode::Util.decode_options(options))
       if target.nil? and order.nil?
         @model.add_constraint Sort::SortConstraint.new(@model, @params)
       else
@@ -53,33 +77,18 @@ module Gecode::Constraints::IntEnum
 
   # A module that gathers the classes and modules used in sort constraints.
   module Sort #:nodoc:
-    # Describes a sort constraint which constrains a target enumeration of 
-    # integer variables to be the sorted version of another set of integer 
-    # variables. Optionally a third enumeration may be used to define the order
-    # in which the the variables should be sorted.
-    # 
-    # Neither negation nor reification is supported.
-    # 
-    # == Example
-    # 
-    #   # Constrains +sorted_numbers+ to be a sorted version of +numbers+. 
-    #   numbers.must_be.sorted(:as => sorted_numbers)
-    #   
-    #   # Constrains +sorted_numbers+ to be +numbers+ sorted in the order 
-    #   # described by the integer variable enumeration +order+. 
-    #   numbers.must_be.sorted(:as => sorted_numbers, :order => order)
-    class SortConstraintWithOptions < Gecode::Constraints::Constraint
+    class SortConstraintWithOptions < Gecode::Constraint #:nodoc:
       def post
         if @params[:target].nil?
           # We must have a target.
-          lhs = @params[:lhs]
+          lhs = @params[:lhs].to_int_enum
           @params[:target] = @model.int_var_array(lhs.size, lhs.domain_range)
         end
         
         # Prepare the parameters.
         params = @params.values_at(:lhs, :target, :order).map do |param| 
-          if param.respond_to? :to_int_var_array
-            param.to_int_var_array
+          if param.respond_to? :to_int_enum
+            param.to_int_enum.bind_array
           else
             param
           end
@@ -91,19 +100,7 @@ module Gecode::Constraints::IntEnum
       end
     end
     
-    # Describes a sort constraint which constrains an enumeration of integer 
-    # variables to be sorted. Supports reification and negation.
-    # 
-    # == Example
-    # 
-    #   # Constrains the variables in +int_enum+ to be sorted ascendingly.
-    #   int_enum.must_be.sorted
-    #   
-    #   # Reifies the constraint that the variables in +int_enum+ to be sorted 
-    #   # ascendingly with the boolean variable +is_sorted+, while selecting 
-    #   # +domain+ as strength.
-    #   int_enum.must_be.sorted(:reify => :is_sorted, :strength => :domain)
-    class SortConstraint < Gecode::Constraints::ReifiableConstraint
+    class SortConstraint < Gecode::ReifiableConstraint #:nodoc:
       def post
         lhs, strength, kind, reif_var = 
           @params.values_at(:lhs, :strength, :kind, :reif)
@@ -112,9 +109,9 @@ module Gecode::Constraints::IntEnum
         # We translate the constraint into n-1 relation constraints.
         options = {
           :strength => 
-            Gecode::Constraints::Util::PROPAGATION_STRENGTHS.invert[strength],
+            Gecode::Util::PROPAGATION_STRENGTHS.invert[strength],
           :kind => 
-            Gecode::Constraints::Util::PROPAGATION_KINDS.invert[kind]
+            Gecode::Util::PROPAGATION_KINDS.invert[kind]
         }
         if using_reification
           reification_variables = @model.bool_var_array(lhs.size - 1)
@@ -135,4 +132,4 @@ module Gecode::Constraints::IntEnum
       negate_using_reification
     end
   end
-end
+end

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

@@ -1,28 +1,85 @@
-module Gecode
-  module IntEnumMethods
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module containing constraints that have enumerations of integer 
+# operands as left hand side.
+module Gecode::IntEnum #:nodoc:
+  # A IntEnumOperand is a enumeration of IntOperand on which the
+  # constraints defined in IntEnumConstraintReceiver can be placed.
+  #
+  # Enumerations of integer operands can be created either by using
+  # Gecode::Model#int_var_array and Gecode::Model#int_var_matrix, or
+  # by wrapping an existing enumeration containing IntOperand using
+  # Gecode::Model#wrap_enum. The enumerations, no matter how they were
+  # created, all respond to the properties defined by IntEnumOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces an array of five int operands with domain 0..9 inside a 
+  # problem formulation using Gecode::Model#int_var_array:
+  #
+  #   int_enum = int_var_array(5, 0..9)
+  #
+  # Uses Gecode::Model#wrap_enum inside a problem formulation to create
+  # a IntEnumOperand from an existing enumeration containing the
+  # integer operands +int_operand1+ and +int_operand2+:
+  #
+  #   int_enum = wrap_enum([int_operand1, int_operand2])
+  #   
+  #--
+  # Classes that mix in IntEnumOperand must define #model and
+  # #to_int_enum .
+  module IntEnumOperand
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::IntEnum::Dummy.instance_methods.include? method.to_s
+        # Delegate to the int enum.
+        to_int_enum.method(method).call(*args)
+      else
+        super
+      end
+    end
+
     private
-    
-    # Produces an expression for the lhs module.
-    def expression(params)
-      params.update(:lhs => self)
-      Constraints::IntEnum::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      IntEnumConstraintReceiver.new(@model, params)
     end
   end
-  
-  # A module containing constraints that have enumerations of integer 
-  # variables as left hand side.
-  module Constraints::IntEnum
-    # Expressions with int enums as left hand sides.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
-      # Raises TypeError unless the left hand side is an int enum.
-      def initialize(model, params)
-        super
-        
-        unless params[:lhs].respond_to? :to_int_var_array
-          raise TypeError, 'Must have int enum as left hand side.'
-        end
+
+  # IntEnumConstraintReceiver contains all constraints that can be
+  # placed on a IntEnumOperand.
+  #
+  # Constraints are placed by calling IntEnumOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # IntEnumConstraintReceiver from which the desired constraint can be used.
+  #
+  # Some constraint accepts a number of options. See ConstraintReceiver
+  # for more information.
+  #
+  # ==== Examples 
+  #
+  # Constrains the integer operands in +int_enum+ to take on different
+  # values by using IntEnumConstraintReceiver#distinct:
+  #
+  #   int_enum.must_be.distinct
+  #
+  # Constrains +int_enum2+ to have the same elements as +int_enum+, but
+  # sorted in ascending order. Uses IntEnumConstraintReceiver#sorted:
+  #
+  #   int_enum.must_be.sorted(:as => int_enum2)
+  #
+  # The same as above, but specifying that strength :domain should be 
+  # used and that the constraint should be reified with +bool_operand+:
+  #
+  #   int_enum.must_be.sorted(:as => int_enum2, :strength => :domain, :reify => bool_operand)
+  #
+  class IntEnumConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is an int enum
+    # operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_int_enum
+        raise TypeError, 'Must have int enum operand as left hand side.'
       end
     end
   end

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

@@ -1,58 +1,229 @@
-module Gecode
-  class FreeIntVar
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module that deals with the operands, properties and constraints of
+# integer variables.
+module Gecode::Int #:nodoc:
+  # A IntOperand is a combination of variables on which the
+  # constraints defined in IntConstraintReceiver can be placed.
+  #
+  # Integer operands can be created either by using
+  # Gecode::Model#int_var et al, or by using properties that produce
+  # integer operands. The operands, no matter how they were created, 
+  # all respond to the properties defined by IntOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces a single integer operand (more specifically an IntVar) with
+  # domain 0..9 inside a problem formulation, using
+  # Gecode::Model#int_var:
+  #
+  #   int_operand = int_var(0..9)
+  #
+  # Uses the IntOperand#+ property to produce a new integer
+  # operand representing +int_operand1+ plus +int_operand2+:
+  #
+  #   new_int_operand = int_operand1 + int_operand2
+  #
+  # Uses the IntEnumOperand#max property to produce a new
+  # integer operand representing the maximum value of the integer operands
+  # in the enumeration +int_enum+:
+  # 
+  #   new_int_operand = int_enum.max
+  #
+  # Uses the IntEnumOperand#[] property to produce a new integer operand
+  # representing the integer operand at the index decided by
+  # +int_operand+ (which can change during search) in the enumeration
+  # +int_enum+:
+  # 
+  #   new_int_operand = int_enum[int_operand]
+  #
+  # Uses the SetOperand#size property to produce a new integer operand
+  # representing the size of +set_operand+:
+  #
+  #   new_int_operand = set_operand.size
+  #
+  #--
+  # Classes that mix in IntOperand must define #model and #to_int_var .
+  module IntOperand  
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::IntVar.instance_methods.include? method.to_s
+        # Delegate to the int var.
+        to_int_var.method(method).call(*args)
+      else
+        super
+      end
+    end
+
     private
-    
-    # Produces an expression for the lhs module.
-    def expression(params)
+
+    def construct_receiver(params)
+      IntConstraintReceiver.new(model, params)
+    end
+  end
+
+  # An operand that short circuits integer equality.
+  class ShortCircuitEqualityOperand #:nodoc:
+    include Gecode::Int::IntOperand
+    attr :model
+
+    def initialize(model)
+      @model = model
+    end
+
+    def construct_receiver(params)
       params.update(:lhs => self)
-      Constraints::Int::Expression.new(@model, params)
+      receiver = IntConstraintReceiver.new(@model, params)
+      op = self
+      receiver.instance_eval{ @short_circuit = op }
+      class <<receiver
+        alias_method :equality_without_short_circuit, :==
+        def ==(operand, options = {})
+          if !@params[:negate] and options[:reify].nil? and 
+              operand.respond_to? :to_int_var
+            # Short circuit the constraint.
+            @params.update Gecode::Util.decode_options(options)
+            @model.add_constraint(Gecode::BlockConstraint.new(
+                @model, @params) do
+              @short_circuit.constrain_equal(operand, false,
+                @params.values_at(:strength, :kind))
+            end)
+          else
+            equality_without_short_circuit(operand, options)
+          end
+        end
+        alias_comparison_methods
+      end
+
+      return receiver
+    end
+
+    def to_int_var
+      variable = model.int_var
+      options = 
+        Gecode::Util.decode_options({}).values_at(:strength, :kind)
+      model.add_interaction do
+        constrain_equal(variable, true, options)
+      end
+      return variable
+    end
+
+    private
+
+    # Constrains this operand to equal +int_operand+ using the
+    # specified +propagation_options+. If +constrain_domain+ is true
+    # then the method should also attempt to constrain the bounds of the
+    # domain of +int_operand+.
+    def constrain_equal(int_operand, constrain_domain, propagation_options)
+      raise NotImplementedError, 'Abstract method has not been implemented.'
     end
   end
-  
-  # A module containing constraints that have int variables as left hand side
-  # (but not enumerations).
-  module Constraints::Int
-    # Describes an integer expression.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
-    end
-    
-    # A composite expression which is an int expression with a left hand side 
-    # resulting from a previous constraint.
-    class CompositeExpression < Gecode::Constraints::CompositeExpression #:nodoc:
-      # The block given should take three parameters. The first is the variable 
-      # that should be the left hand side, if it's nil then a new one should be
-      # created. The second is the has of parameters. The block should return 
-      # the variable used as left hand side.
-      def initialize(model, params, &block)
-        super(Expression, Gecode::FreeIntVar, lambda{ model.int_var }, model, 
-          params, &block)
+
+  # An operand that short circuits integer relation constraints.
+  class ShortCircuitRelationsOperand #:nodoc:
+    include Gecode::Int::IntOperand
+    attr :model
+
+    def initialize(model)
+      @model = model
+    end
+
+    def construct_receiver(params)
+      receiver = IntConstraintReceiver.new(@model, params)
+      op = self
+      receiver.instance_eval{ @short_circuit = op }
+      class <<receiver
+        Gecode::Util::COMPARISON_ALIASES.keys.each do |comp|
+          eval <<-end_code
+            alias_method :alias_#{comp.to_i}_without_short_circuit, :#{comp}
+            def #{comp}(operand, options = {})
+              if operand.respond_to?(:to_int_var) or operand.kind_of? Fixnum
+                # Short circuit the constraint.
+                @params.update Gecode::Util.decode_options(options)
+                @model.add_constraint(
+                  @short_circuit.relation_constraint(
+                    :#{comp}, operand, @params))
+              else
+                alias_#{comp.to_i}_without_short_circuit(operand, options)
+              end
+            end
+          end_code
+        end
+        alias_comparison_methods
       end
+
+      return receiver
+    end
+
+    def to_int_var
+      variable = model.int_var
+      params = {}
+      params.update Gecode::Util.decode_options({})
+      model.add_constraint relation_constraint(:==, variable, params)
+      return variable
+    end
+
+    # Returns a constraint that constrains this operand to have relation
+    # +relation+ to +int_operand_or_fix+, which is either an integer 
+    # operand or a fixnum, given the specified hash +params+ of parameters.
+    def relation_constraint(relation, int_operand_or_fix, params)
+      raise NotImplementedError, 'Abstract method has not been implemented.'
     end
-    
-    # Describes a stub that produces an int variable, which can then be used 
-    # with the normal int variable constraints. An example would be the element
-    # constraint.
-    #
-    #   int_enum[int_var].must > rhs
-    #
-    # <tt>int_enum[int_var]</tt> produces an int variable which the constraint 
-    # <tt>.must > rhs</tt> is then applied to. In the above case two 
-    # constraints (and one temporary variable) are required, but in the case of 
-    # equality only one constraint is required.
-    # 
-    # Whether a constraint involving a reification stub supports negation, 
-    # reification, strength options and so on depends on the constraint on the
-    # right hand side.
-    class CompositeStub < Gecode::Constraints::CompositeStub
-      def initialize(model, params)
-        super(CompositeExpression, model, params)
+  end
+
+  # IntConstraintReceiver contains all constraints that can be
+  # placed on an IntOperand.
+  #
+  # Constraints are placed by calling IntOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # IntConstraintReceiver from which the desired constraint can be used.
+  #
+  # Each constraint accepts a number of options. See ConstraintReceiver
+  # for more information.
+  #
+  # ==== Examples 
+  #
+  # Constrains +int_operand+ to be strictly greater than 5 using
+  # IntConstraintReceiver#>:
+  #
+  #   int_operand.must > 5
+  #
+  # Constrains +int_operand1+ plus +int_operand2+ to be strictly 
+  # greater than 5 using the IntOperand#+ property and 
+  # IntConstraintReceiver#>:
+  #
+  #   (int_operand1 + int_operand2).must > 5
+  #
+  # Constrains the maximum value of the integer operands in +int_enum+ to
+  # _not_ be in the range 3..7 using the IntEnumOperand#max property and 
+  # IntConstraintReceiver#in:
+  #
+  #   int_enum.max.must_not_be.in 3..7
+  #
+  # Constrains the integer operand at position +int_operand+ in
+  # +int_enum+, an enumeration of integer operands, to be greater than
+  # or equal to +int_operand2+. This uses the IntEnumOperand#[] property 
+  # and IntConstraintReceiver#>=:
+  #
+  #   int_enum[int_operand].must >= int_operand2
+  #
+  # The same as above, but specifying that strength :domain should be 
+  # used and that the constraint should be reified with +bool_operand+:
+  #
+  #   int_enum[int_operand].must_be.greater_or_equal(int_operand2, :strength => :domain, :reify => bool_operand)
+  #
+  class IntConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is an int operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_int_var
+        raise TypeError, 'Must have int operand as left hand side.'
       end
     end
   end
 end
 
+require 'gecoder/interface/constraints/int/relation'
 require 'gecoder/interface/constraints/int/linear'
 require 'gecoder/interface/constraints/int/domain'
 require 'gecoder/interface/constraints/int/arithmetic'