gecoder-with-gecode 0.8.3 → 0.9.0

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'

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

@@ -1,12 +1,12 @@
-module Gecode::Constraints
+module Gecode
   # Base class for all reifiable constraints.
-  class ReifiableConstraint < Constraint
-    # Gets the reification variable of the constraint, nil if none exists.
+  class ReifiableConstraint < Constraint #:nodoc:
+    # Gets the reification operand of the constraint, nil if none exists.
     def reification_var
       @params[:reif]
     end
     
-    # Sets the reification variable of the constraint, nil if none should be
+    # Sets the reification operand of the constraint, nil if none should be
     # used.
     def reification_var=(new_var)
       @params[:reif] = new_var
@@ -15,7 +15,7 @@ module Gecode::Constraints
     # Produces a disjunction of two reifiable constraints, producing a new
     # reifiable constraint.
     def |(constraint)
-      with_reification_variables(constraint) do |b1, b2|
+      with_reification_operands(constraint) do |b1, b2|
         # Create the disjunction constraint.
         (b1 | b2).must_be.true
       end
@@ -24,7 +24,7 @@ module Gecode::Constraints
     # Produces a conjunction of two reifiable constraints, producing a new
     # reifiable constraint.
     def &(constraint)
-      with_reification_variables(constraint) do |b1, b2|
+      with_reification_operands(constraint) do |b1, b2|
         # Create the conjunction constraint.
         (b1 & b2).must_be.true
       end
@@ -32,14 +32,14 @@ module Gecode::Constraints
     
     private
     
-    # Yields two boolean variables to the specified block. The first one is 
-    # self's reification variable and the second one is the reification variable
-    # of the specified constraint. Reuses reification variables if possible,
-    # otherwise creates new ones.
-    def with_reification_variables(constraint, &block)
+    # Yields two boolean operands to the specified block. The first one
+    # is self's reification operand and the second one is the
+    # reification operand of the specified constraint. Reuses
+    # reification operands if possible, otherwise creates new ones.
+    def with_reification_operands(constraint, &block)
       raise TypeError unless constraint.kind_of? ReifiableConstraint
       
-      # Set up the reification variables, using existing variables if they 
+      # Set up the reification operands, using existing operands if they 
       # exist.
       con1_holds = self.reification_var
       con2_holds = constraint.reification_var
@@ -55,7 +55,7 @@ module Gecode::Constraints
     end
     
     # If called the negation of the constraint will be handled using the 
-    # reification variable. This means that the post method (which has to be 
+    # reification operand. This means that the post method (which has to be 
     # defined prior to calling this method) doesn't have to bother about 
     # negation.
     def self.negate_using_reification
@@ -75,4 +75,4 @@ module Gecode::Constraints
       end
     end
   end
-end
+end

data/lib/gecoder/interface/constraints/selected_set/select.rb

@@ -0,0 +1,120 @@
+module Gecode::SelectedSet
+  class SelectedSetOperand
+    # Produces a SetOperand representing the selected sets' union.
+    #
+    # ==== Examples 
+    #
+    #   # The union of all sets selected by +set_enum[set]+.
+    #   set_enum[set].union
+    def union
+      Select::SelectedSetUnionOperand.new(model, self)
+    end
+     
+    # Produces a SetOperand representing the selected sets' intersection.
+    # The option :with can be used to enumerate the elements in the
+    # universe.
+    #
+    # ==== Examples 
+    #
+    #   # The intersection of all sets selected by +set_enum[set]+.
+    #   set_enum[set].intersection
+    #
+    #   # The same intersection as above, but with [3,5,7] as universe.
+    #   set_enum[set].intersection(:with => [3,5,7])
+    def intersection(options = {})
+      universe = nil
+      unless options.empty? 
+        unless options.size == 1 and options.has_key?(:with)
+          raise ArgumentError, "Expected option key :with, got #{options.keys}."
+        else
+          universe = options[:with]
+          unless universe.kind_of?(Enumerable) and 
+              universe.all?{ |element| element.kind_of? Fixnum }
+            raise TypeError, "Expected the universe to be specified as " + 
+              "an enumeration of fixnum, got #{universe.class}."
+          end
+        end
+      end
+      
+      Select::SelectedSetIntersectionOperand.new(model, self, universe)
+    end
+  end
+
+  class SelectedSetConstraintReceiver
+    # Constrains the selected sets to be pairwise disjoint.
+    #
+    # ==== Examples 
+    #
+    #   # Constrains all sets selected by +set_enum[set]+ to be pairwise
+    #   # disjoint.
+    #   set_enum[set].must_be.disjoint 
+    def disjoint(options = {})
+      if @params[:negate]
+        raise Gecode::MissingConstraintError, 'A negated disjoint constraint ' + 
+          'is not implemented.'
+      end
+      if options.has_key? :reify
+        raise ArgumentError, 'The disjoint constraint does not support the ' + 
+          'reification option.'
+      end
+
+      @params.update Gecode::Set::Util.decode_options(options)
+      @model.add_constraint Select::DisjointConstraint.new(@model, @params)
+    end
+  end
+
+  module Select #:nodoc:
+    class SelectedSetUnionOperand < Gecode::Set::ShortCircuitEqualityOperand #:nodoc:
+      def initialize(model, selected_set)
+        super model
+        @selected_set = selected_set
+      end
+
+      def constrain_equal(set_operand, constrain, propagation_options)
+        enum, indices = @selected_set.to_selected_set
+        if constrain
+          set_operand.must_be.subset_of enum.upper_bound_range
+        end
+        
+        Gecode::Raw::selectUnion(@model.active_space, 
+          enum.to_set_enum.bind_array, indices.to_set_var.bind, 
+          set_operand.to_set_var.bind)
+      end
+    end
+    
+    class SelectedSetIntersectionOperand < Gecode::Set::ShortCircuitEqualityOperand #:nodoc:
+      def initialize(model, selected_set, universe)
+        super model
+        @selected_set = selected_set
+        @universe = universe
+      end
+
+      def constrain_equal(set_operand, constrain, propagation_options)
+        enum, indices = @selected_set.to_selected_set
+        universe = @universe
+
+        # We can't do any useful constraining here since the empty intersection
+        # is the universe.
+
+        if universe.nil?
+          Gecode::Raw::selectInter(@model.active_space, 
+            enum.to_set_enum.bind_array, indices.to_set_var.bind, 
+            set_operand.to_set_var.bind)
+        else
+          Gecode::Raw::selectInterIn(@model.active_space,  
+            enum.to_set_enum.bind_array, indices.to_set_var.bind, 
+            set_operand.to_set_var.bind,
+            Gecode::Util.constant_set_to_int_set(universe))
+        end
+      end
+    end
+    
+    class DisjointConstraint < Gecode::Constraint #:nodoc:
+      def post
+        enum, indices = @params[:lhs].to_selected_set
+        Gecode::Raw.selectDisjoint(@model.active_space, 
+          enum.to_set_enum.bind_array, indices.to_set_var.bind)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# A module containing constraints that have set_enum[set] as left hand
+# side.
+module Gecode::SelectedSet #:nodoc:
+  # A SelectedSetOperand is an uncommon operand that results from calling 
+  # SetEnumOperand#[] with a SetOperand. It facilitates placing the 
+  # constraints defined in SelectedSetConstraintReceiver
+  #
+  # ==== Examples 
+  #
+  # Producing a SelectedSetOperand from +set_enum+ and +set_operand+:
+  #
+  #   set_enum[set_operand]
+  #
+  class SelectedSetOperand
+    include Gecode::Operand 
+
+    # Constructs a new selected set operand from +set_enum+ and +set+.
+    def initialize(set_enum, set) #:nodoc:
+      unless set_enum.respond_to? :to_set_enum
+        raise TypeError, "Expected set enum operand, got #{set_enum.class}."
+      end
+      unless set.respond_to? :to_set_var
+        raise TypeError, "Expected set operand, got #{set.class}."
+      end
+
+      @set_enum = set_enum
+      @set = set
+    end
+
+    # Returns the set enum and set that make up the selected set
+    # operand.
+    def to_selected_set #:nodoc:
+      return @set_enum, @set
+    end
+
+    def model #:nodoc:
+      @set_enum.model
+    end
+
+    private
+
+    def construct_receiver(params)
+      SelectedSetConstraintReceiver.new(model, params)
+    end
+  end
+
+  # SelectedSetConstraintReceiver contains all constraints that can be
+  # placed on a SelectedSetOperand.
+  #
+  # Constraints are placed by calling SelectedSetOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # SelectedSetConstraintReceiver from which the desired constraint can 
+  # be used.
+  #
+  # ==== Examples 
+  #
+  # Constrains the sets in +set_enum+ that are selected by +set_operand+ to be
+  # disjoint. This uses SetEnumOperand#[] and
+  # SelectedSetConstraintReceiver#disjoint. 
+  #
+  #   set_enum[set_operand].must_be.disjoint
+  #
+  class SelectedSetConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is a selected set operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_selected_set
+        raise TypeError, 'Must have selected set operand as left hand side.'
+      end
+    end
+  end
+end
+
+require 'gecoder/interface/constraints/selected_set/select'

data/lib/gecoder/interface/constraints/set/cardinality.rb

@@ -1,75 +1,65 @@
-module Gecode
-  class FreeSetVar
-    # Starts a constraint on the size of the set.
+module Gecode::Set
+  module SetOperand
+    # Produces an IntOperand representing the size of the set.
+    #
+    # ==== Examples 
+    #
+    #   # The size of +set+.
+    #   set.size
     def size
-      params = {:lhs => self}
-      Gecode::Constraints::Set::Cardinality::SizeExpressionStub.new(
-        @model, params)
+      Cardinality::SetSizeOperand.new(@model, self)
     end
   end
-end
 
-module Gecode::Constraints::Set
   # A module that gathers the classes and modules used in cardinality 
   # constraints.
   module Cardinality #:nodoc:
     # Describes a cardinality constraint specifically for ranges. This is just
     # a special case which is used instead of the more general composite 
     # constraint when the target cardinality is a range. 
-    class CardinalityConstraint < Gecode::Constraints::Constraint #:nodoc:
+    class CardinalityConstraint < Gecode::Constraint #:nodoc:
       def post
         var, range = @params.values_at(:lhs, :range)
-        Gecode::Raw::cardinality(@model.active_space, var.bind, range.first, 
-          range.last)
-      end
-    end
-    
-    # A custom composite stub to change the composite expression used.
-    class CompositeStub < Gecode::Constraints::CompositeStub #:nodoc:
-      def initialize(model, params)
-        super(Expression, model, params)
+        Gecode::Raw::cardinality(@model.active_space, var.to_set_var.bind, 
+          range.first, range.last)
       end
     end
     
-    # Describes a cardinality expression started with set.size.must .
-    class Expression < Gecode::Constraints::Int::CompositeExpression #:nodoc:
-      def in(range)
-        if range.kind_of?(Range) and !@params[:negate]
-          @params.update(:range => range)
-          @model.add_constraint CardinalityConstraint.new(@model, @params)
-        else
-          super(range)
-        end
+    class SetSizeOperand < Gecode::Int::ShortCircuitEqualityOperand #:nodoc:
+      def initialize(model, set_op)
+        super model
+        @set = set_op
       end
-    end
-    
-    # Describes a CompositeStub for the cardianlity constraint which constrains
-    # the cardianlity (size) of a set.
-    # 
-    # == Example
-    # 
-    #   # The size of +set+ must be within 1..17
-    #   set.size.must_be.in 1..17
-    #   
-    #   # The size must equal the integer variable +size+.
-    #   set.size.must == size
-    #   
-    #   # The size must not be larger than 17
-    #   set.size.must_not > 17
-    #   
-    #   # We reify the above with a boolean variable called +is_not_large+ and 
-    #   # select the strength +domain+.
-    #   set.size.must_not_be.larger_than(17, :reify => is_not_large, 
-    #     :strength => :domain)
-    class SizeExpressionStub < CompositeStub
-      def constrain_equal(variable, params, constrain)
-        lhs = @params[:lhs]
+
+      def constrain_equal(int_operand, constrain, propagation_options)
+        set = @set.to_set_var
         if constrain
-          variable.must_be.in lhs.lower_bound.size..lhs.upper_bound.size
+          int_operand.must_be.in set.lower_bound.size..set.upper_bound.size
         end
         
-        Gecode::Raw::cardinality(@model.active_space, lhs.bind, variable.bind)
+        Gecode::Raw::cardinality(@model.active_space, set.bind, 
+          int_operand.to_int_var.bind)
+      end
+
+      alias_method :pre_cardinality_construct_receiver, :construct_receiver
+      def construct_receiver(params)
+        receiver = pre_cardinality_construct_receiver(params)
+        set = @set
+        receiver.instance_eval{ @set = set }
+        class <<receiver 
+          alias_method :in_without_short_circuit, :in
+          def in(range, options = {})
+            if range.kind_of?(Range) and !@params[:negate] and 
+                !options.has_key?(:reify)
+              @params.update(:lhs => @set, :range => range)
+              @model.add_constraint CardinalityConstraint.new(@model, @params)
+            else
+              in_without_short_circuit(range, options)
+            end
+          end
+        end
+        return receiver
       end
     end
   end
-end
+end