gecoder 0.8.3 → 0.9.0

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

@@ -0,0 +1,79 @@
+module Gecode::SetEnum
+  module SetEnumOperand
+    # This adds the adder for the methods in the modules including it. The 
+    # reason for doing it so indirect is that the first #[] won't be defined 
+    # before the module that this is mixed into is mixed into an enum.
+    def self.included(mod) #:nodoc:
+      mod.module_eval do
+        # Now we enter the module SetEnumOperands is mixed into.
+        class << self
+          alias_method :pre_selection_included, :included
+          def included(mod) #:nodoc:
+            mod.module_eval do
+              # Now we enter the module that the module possibly defining #[] 
+              # is mixed into.
+              if instance_methods.include?('[]') and 
+                  not instance_methods.include?('pre_selection_access')
+                alias_method :pre_selection_access, :[]
+              end
+            
+              # Produces a SetOperand representing the i:th set
+              # operand in the enumeration, where i is the value of the
+              # int operand used as index. 
+              #
+              # A set can also be used as index, in which case a
+              # SelectedSetOperand is produced.
+              #
+              # ==== Examples 
+              # 
+              #   # The set operand at the +x+:th position in +set_enum+,
+              #   # where +x+ is a int operand.  
+              #   set_enum[x]
+              #
+              #   # The SelectedSetOperand representing sets at positions
+              #   # included in the value of +set+ in +set_enum+,
+              #   set_enum[set]
+              #
+              def [](*vars)
+                # Hook in an element constraint if a operand is used for array 
+                # access.
+                if vars.first.respond_to? :to_int_var
+                  Select::SelectSetOperand.new(
+                    model, self, vars.first)
+                elsif vars.first.respond_to? :to_set_var
+                  Gecode::SelectedSet::SelectedSetOperand.new(
+                    self, vars.first)
+                else
+                  if respond_to? :pre_selection_access
+                    pre_selection_access(*vars) 
+                  end
+                end
+              end
+            end
+            pre_selection_included(mod)
+          end
+        end
+      end
+    end
+  end
+
+  module Select #:nodoc:
+    class SelectSetOperand < Gecode::Set::ShortCircuitEqualityOperand #:nodoc:
+      def initialize(model, enum_op, position_int_op)
+        super model
+        @enum = enum_op
+        @position = position_int_op
+      end
+
+      def constrain_equal(set_operand, constrain, propagation_options)
+        enum = @enum.to_set_enum
+        if constrain
+          set_operand.must_be.subset_of enum.upper_bound_range
+        end
+
+        Gecode::Raw::selectSet(@model.active_space, enum.bind_array, 
+          @position.to_int_var.bind, set_operand.to_set_var.bind)
+      end
+    end
+  end 
+end

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

@@ -1,28 +1,78 @@
-module Gecode
-  module SetEnumMethods
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module containing constraints that have enumerations of set operands as 
+# left hand side.
+module Gecode::SetEnum #:nodoc:
+  # A SetEnumOperand is a enumeration of SetOperand on which the
+  # constraints defined in SetEnumConstraintReceiver can be placed.
+  #
+  # Enumerations of set operands can be created either by using
+  # Gecode::Model#set_var_array and Gecode::Model#set_var_matrix, or
+  # by wrapping an existing enumeration containing SetOperand using
+  # Gecode::Model#wrap_enum. The enumerations, no matter how they were
+  # created, all respond to the properties defined by SetEnumOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces an array of five set operands, with greatest lower bound
+  # {0} and least upper bound {0, 1, 2}, inside a problem formulation
+  # using Gecode::Model#set_var_array:
+  #
+  #   set_enum = set_var_array(5, 0, 1..2)
+  #
+  # Uses Gecode::Model#wrap_enum inside a problem formulation to create
+  # a SetEnumOperand from an existing enumeration containing the
+  # set operands +set_operand1+ and +set_operand2+:
+  #
+  #   set_enum = wrap_enum([set_operand1, set_operand2])
+  #   
+  #--
+  # Classes that mix in SetEnumOperand must define #model and
+  # #to_set_enum .
+  module SetEnumOperand
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::SetEnum::Dummy.instance_methods.include? method.to_s
+        # Delegate to the set enum.
+        to_set_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::SetEnum::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      Gecode::SetEnum::SetEnumConstraintReceiver.new(@model, params)
     end
   end
-  
-  # A module containing constraints that have enumerations of set variables as 
-  # left hand side.
-  module Constraints::SetEnum
-    # Expressions with set enums as left hand sides.
-    class Expression < Gecode::Constraints::Expression
-      # Raises TypeError unless the left hand side is a set enum.
-      def initialize(model, params)
-        super
-        
-        unless params[:lhs].respond_to? :to_set_var_array
-          raise TypeError, 'Must have set enum as left hand side.'
-        end
+
+  # SetEnumConstraintReceiver contains all constraints that can be
+  # placed on a SetEnumOperand.
+  #
+  # Constraints are placed by calling SetEnumOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # SetEnumConstraintReceiver from which the desired constraint can be used.
+  #
+  # ==== Examples 
+  #
+  # Constrains +set_enum+ to channel +int_enum+ by using 
+  # SetEnumConstraintReceiver#channel:
+  #
+  #   set_enum.must.channel set_enum
+  #
+  # Constrains each pair of set operands in +set_enum+ to at most share
+  # one element. Also constrains each set to have size 17. Uses 
+  # SetEnumConstraintReceiver#at_most_share_one_element.
+  #
+  #   set_enum.must.at_most_share_one_element(:size => 17)
+  #
+  class SetEnumConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is a set enum operand.
+    def initialize(model, params) #:nodoc:
+      super
+      
+      unless params[:lhs].respond_to? :to_set_enum
+        raise TypeError, 'Must have set enum operand as left hand side.'
       end
     end
   end
@@ -30,5 +80,5 @@ end
 
 require 'gecoder/interface/constraints/set_enum/channel'
 require 'gecoder/interface/constraints/set_enum/distinct'
-require 'gecoder/interface/constraints/set_enum/selection'
+require 'gecoder/interface/constraints/set_enum/select'
 require 'gecoder/interface/constraints/set_enum/operation'

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

@@ -1,71 +1,235 @@
-module Gecode
-  class FreeSetVar
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module containing constraints that have set operands as left hand side
+# (but not enumerations).
+module Gecode::Set #:nodoc:
+  # A SetOperand is a combination of operands on which the
+  # constraints defined in SetConstraintReceiver can be placed.
+  #
+  # Set operands can be created either by using Gecode::Model#set_var et
+  # al, or by using properties that produce set operands. The operands,
+  # no matter how they were created, all respond to the properties
+  # defined by SetOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces a single set operand (more specifically a SetVar), with
+  # greatest lower bound {0} and least upper bound {0, 1, 2}, inside a
+  # problem formulation, using Gecode::Model#set_var:
+  #
+  #   set_operand = set_var(0, 0..2)
+  #
+  # Uses the SetOperand#union property to produce a new set operand
+  # representing the union between +set_operand1+ and +set_operand2+: 
+  #
+  #   new_set_operand = set_operand1.union(set_operand2)
+  #
+  # Uses the SetEnumOperand#union property to produce a new set operand
+  # representing the union of the set operands in the enumeration
+  # +set_enum+:
+  # 
+  #   new_set_operand = set_enum.union
+  #
+  # Uses the SetEnumOperand#[] property to produce a new set operand
+  # representing the set operand at the index decided by
+  # +int_operand+ (which can change during search) in the enumeration
+  # +set_enum+:
+  # 
+  #   new_set_operand = set_enum[int_operand]
+  #
+  #--
+  # Classes that mix in SetOperand must define #model and #to_set_var .
+  module SetOperand  
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::SetVar.instance_methods.include? method.to_s
+        # Delegate to the set var.
+        to_set_var.method(method).call(*args)
+      else
+        super
+      end
+    end
+
     private
-    
-    # Produces an expression for the lhs module.
-    def expression(params)
-      params.update(:lhs => self)
-      Constraints::Set::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      SetConstraintReceiver.new(model, params)
     end
   end
-  
-  # A module containing constraints that have set variables as left hand side
-  # (but not enumerations).
-  module Constraints::Set
-    # An expression with a set as left hand side.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
+
+  # An operand that short circuits set equality.
+  class ShortCircuitEqualityOperand #:nodoc:
+    include Gecode::Set::SetOperand
+    attr :model
+
+    def initialize(model)
+      @model = model
     end
-    
-    # Utility methods for sets.
-    module Util #:nodoc:
-      module_function
-      def decode_options(options)
-        if options.has_key? :strength
-          raise ArgumentError, 'Set constraints do not support the strength ' +
-            'option.'
+
+    def construct_receiver(params)
+      params.update(:lhs => self)
+      receiver = SetConstraintReceiver.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.has_key?(:reify) and 
+              operand.respond_to? :to_set_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
-        if options.has_key? :kind
-          raise ArgumentError, 'Set constraints do not support the kind ' +
-            'option.'
+        alias_comparison_methods
+      end
+
+      return receiver
+    end
+
+    def to_set_var
+      variable = model.set_var
+      options = 
+        Gecode::Set::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 +set_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 +set_operand+.
+    def constrain_equal(set_operand, constrain_domain, propagation_options)
+      raise NotImplementedError, 'Abstract method has not been implemented.'
+    end
+  end
+
+  # An operand that short circuits set non-negated and non-reified versions 
+  # of the relation constraints.
+  class ShortCircuitRelationsOperand #:nodoc:
+    include Gecode::Set::SetOperand
+    attr :model
+
+    def initialize(model)
+      @model = model
+    end
+
+    def construct_receiver(params)
+      params.update(:lhs => self)
+      receiver = SetConstraintReceiver.new(@model, params)
+      op = self
+      receiver.instance_eval{ @short_circuit = op }
+      class <<receiver
+        Gecode::Util::SET_RELATION_TYPES.keys.each do |comp|
+          eval <<-end_code
+            alias_method :alias_#{comp.to_i}_without_short_circuit, :#{comp}
+            def #{comp}(operand, options = {})
+              if !@params[:negate] && !options.has_key?(:reify) && 
+                  (operand.respond_to?(:to_set_var) or 
+                  Gecode::Util::constant_set?(operand))
+                # Short circuit the constraint.
+                @params.update Gecode::Set::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
-        
-        Gecode::Constraints::Util.decode_options(options)
+        alias_comparison_methods
       end
+
+      return receiver
+    end
+
+    def to_set_var
+      variable = model.set_var
+      params = {:lhs => self}
+      params.update Gecode::Set::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 +set_operand_or_constant_set+, which is either a set
+    # operand or a constant set, given the specified hash +params+ of 
+    # parameters. The constraints are never negated nor reified.
+    def relation_constraint(relation, set_operand_or_constant_set, params)
+      raise NotImplementedError, 'Abstract method has not been implemented.'
     end
-    
-    # A composite expression which is an set 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::FreeSetVar, lambda{ model.set_var }, model,
-          params, &block)
+  end
+
+  # SetConstraintReceiver contains all constraints that can be
+  # placed on a SetOperand.
+  #
+  # Constraints are placed by calling SetOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # SetConstraintReceiver from which the desired constraint can be used.
+  #
+  # Most constraint accept :reify option. See ConstraintReceiver for
+  # more information.
+  #
+  # ==== Examples 
+  #
+  # Constrains +set_operand+ to be a subset of {0, 1, 2} using
+  # an alias of SetConstraintReceiver#subset:
+  #
+  #   set_operand.must_be.subset_of 0..2
+  #
+  # Constrains the union of +set_operand1+ and +set_operand2+ to a
+  # subset of {0, 1, 2} using the SetOperand#union property and
+  # SetConstraintReceiver#subset:
+  #
+  #   set_operand1.union(set_operand2).must_be.subset_of 0..2
+  #
+  # Constrains the union of the set operands in +set_enum+ to _not_ 
+  # equal {0, 1, 2} by using the SetEnumOperand#union property and 
+  # an alias of SetConstraintReceiver#==:
+  #
+  #   set_enum.union.must_not == 0..2
+  #
+  # The same as above, but alsa specifying that the constraint should be 
+  # reified with +bool_operand+:
+  #
+  #   set_enum.union.must_not.equal(0..2, :reify => bool_operand)
+  #
+  class SetConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is a set operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_set_var
+        raise TypeError, 'Must have set operand as left hand side.'
       end
     end
-    
-    # Describes a stub that produces a set variable, which can then be used with 
-    # the normal set variable constraints. An example of a set composite 
-    # constraints would be set selection constraint.
-    #
-    #   sets[int_var].must_be.subset_of(another_set)
-    # 
-    # <tt>sets[int_var]</tt> produces a set variable which the constraint 
-    # <tt>.must_be.subset_of(another_set)</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 and 
-    # reification depends on the constraint on the right hand side (none 
-    # support the strength option as no set constraints do).
-    class CompositeStub < Gecode::Constraints::CompositeStub
-      def initialize(model, params)
-        super(CompositeExpression, model, params)
+  end
+
+  # Utility methods for sets.
+  module Util #:nodoc:
+    module_function
+    def decode_options(options)
+      if options.has_key? :strength
+        raise ArgumentError, 'Set constraints do not support the strength ' +
+          'option.'
+      end
+      if options.has_key? :kind
+        raise ArgumentError, 'Set constraints do not support the kind ' +
+          'option.'
       end
+      
+      Gecode::Util.decode_options(options)
     end
   end
 end
@@ -74,5 +238,6 @@ require 'gecoder/interface/constraints/set/domain'
 require 'gecoder/interface/constraints/set/relation'
 require 'gecoder/interface/constraints/set/cardinality'
 require 'gecoder/interface/constraints/set/connection'
+require 'gecoder/interface/constraints/set/include'
 require 'gecoder/interface/constraints/set/operation'
 require 'gecoder/interface/constraints/set/channel'