gecoder-with-gecode 0.8.3 → 0.9.0

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

@@ -1,28 +1,79 @@
-module Gecode
-  module BoolEnumMethods
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module containing constraints that have enumerations of boolean 
+# operands as left hand side.
+module Gecode::BoolEnum #:nodoc:
+  # A BoolEnumOperand is a enumeration of BoolOperand on which the
+  # constraints defined in BoolEnumConstraintReceiver can be placed.
+  #
+  # Enumerations of boolean operands can be created either by using
+  # Gecode::Model#bool_var_array and Gecode::Model#bool_var_matrix, or
+  # by wrapping an existing enumeration containing BoolOperand using
+  # Gecode::Model#wrap_enum. The enumerations, no matter how they were
+  # created, all respond to the properties defined by BoolEnumOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces an array of five boolean operands inside a problem formulation
+  # using Gecode::Model#bool_var_array:
+  #
+  #   bool_enum = bool_var_array(5)
+  #
+  # Uses Gecode::Model#wrap_enum inside a problem formulation to create
+  # a BoolEnumOperand from an existing enumeration containing the
+  # boolean operands +bool_operand1+ and +bool_operand2+:
+  #
+  #   bool_enum = wrap_enum([bool_operand1, bool_operand2])
+  #   
+  #--
+  # Classes that mix in BoolEnumOperand must define #model and
+  # #to_bool_enum .
+  module BoolEnumOperand
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::BoolEnum::Dummy.instance_methods.include? method.to_s
+        # Delegate to the bool enum.
+        to_bool_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::BoolEnum::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      BoolEnumConstraintReceiver.new(@model, params)
     end
   end
-  
-  # A module containing constraints that have enumerations of boolean variables 
-  # as left hand side.
-  module Constraints::BoolEnum
-    # Expressions with bool enums as left hand sides.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
-      # Raises TypeError unless the left hand side is a bool enum.
-      def initialize(model, params)
-        super
-        
-        unless params[:lhs].respond_to? :to_bool_var_array
-          raise TypeError, 'Must have bool enum as left hand side.'
-        end
+
+  # BoolEnumConstraintReceiver contains all constraints that can be
+  # placed on a BoolEnumOperand.
+  #
+  # Constraints are placed by calling BoolEnumOperand#must (or any other
+  # of the variations defined in Operand), which produces a
+  # BoolEnumConstraintReceiver from which the desired constraint can be
+  # used.
+  #
+  # ==== Examples 
+  #
+  # Constrains +bool_enum+, with three boolean operands, to take the 
+  # value of the tuples [false, true, false] or [true, false, true] 
+  # using BoolEnumConstraintReceiver#in:
+  #
+  #   bool_enum.must_be.in [[false, true, false], [true, false, true]]
+  #
+  # Constrains +bool_enum+ to channel +int_operand+ using 
+  # BoolEnumConstraintReceiver#channel:
+  #
+  #   bool_enum.must.channel int_operand
+  #
+  class BoolEnumConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is an bool enum
+    # operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_bool_enum
+        raise TypeError, 'Must have bool enum operand as left hand side.'
       end
     end
   end

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

@@ -1,72 +1,151 @@
-module Gecode
-  class FreeBoolVar
-    include Gecode::Constraints::LeftHandSideMethods
-    
+# A module that deals with the operands, properties and constraints of
+# boolean operands.
+module Gecode::Bool #:nodoc:
+  # A BoolOperand is a combination of variables on which the
+  # constraints defined in BoolConstraintReceiver can be placed.
+  #
+  # Boolean operands can be created either by using
+  # Gecode::Model#bool_var et al, or by using properties that produce
+  # boolean operands. The operands, no matter how they were created, 
+  # all respond to the properties defined by BoolOperand.
+  #
+  # ==== Examples 
+  #
+  # Produces a single boolean operand (more specifically a BoolVar)
+  # inside a problem formulation, using Gecode::Model#bool_var:
+  #
+  #   bool_operand = bool_var
+  #
+  # Uses the BoolOperand#& property to produce a new boolean
+  # operand representing +bool_operand1+ AND +bool_operand2+:
+  #
+  #   new_bool_operand = bool_operand1 & bool_operand2
+  #
+  # Uses the BoolEnumOperand#conjunction property to produce a new
+  # boolean operand representing the conjunction of all boolean operands
+  # in the enumeration +bool_enum+:
+  #
+  #   new_bool_operand = bool_enum.conjunction
+  #
+  #--
+  # Classes that mix in BoolOperand must define #model and #to_bool_var .
+  module BoolOperand  
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::BoolVar.instance_methods.include? method.to_s
+        # Delegate to the bool var.
+        to_bool_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::Bool::Expression.new(@model, params)
+
+    def construct_receiver(params)
+      BoolConstraintReceiver.new(@model, params)
     end
   end
-  
-  # A module containing constraints that have int variables as left hand side
-  # (but not enumerations).
-  module Constraints::Bool
-    # Describes a boolean expression.
-    class Expression < Gecode::Constraints::Expression #:nodoc:
-    end
-    
-    # A composite expression which is an bool 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::FreeBoolVar, lambda{ model.bool_var }, model,
-          params, &block)
-      end
-      
-      # Override to also deal with constant booleans.
-      def true(options = {})
-        # We don't need any additional constraints.
-        @params.update Gecode::Constraints::Util.decode_options(options)
-        @model.add_interaction do
-          @constrain_equal_proc.call(!@params[:negate], @params)
-        end
+
+  # BoolConstraintReceiver contains all constraints that can be
+  # placed on a BoolOperand.
+  #
+  # Constraints are placed by calling BoolOperand#must (or any other
+  # of the variations defined in Operand), which produces a 
+  # BoolConstraintReceiver from which the desired constraint can be used.
+  #
+  # Each constraint accepts a number of options. See ConstraintReceiver
+  # for more information.
+  #
+  # ==== Examples 
+  #
+  # Constrains +bool_operand+ to be true using
+  # BoolConstraintReceiver#true:
+  #
+  #   bool_operand.must_be.true
+  #
+  # Constrains +bool_operand1+ AND +bool_operand2+ to be true using 
+  # the BoolOperand#& property and BoolConstraintReceiver#true:
+  #
+  #   (bool_operand1 & bool_operand2).must_be.true
+  #
+  # Constrains the conjunction of all boolean operands in +bool_enum+ to
+  # _not_ imply +bool_operand+ using the 
+  # BoolEnumOperand#conjunction property and BoolConstraintReceiver#imply:
+  #
+  #   bool_enum.conjunction.must_not.imply bool_operand
+  #
+  # The same as above, but specifying that strength :domain should be 
+  # used and that the constraint should be reified with +bool_operand2+:
+  #
+  #   bool_enum.conjunction.must_not.imply(bool_operand, :strength => :domain, :reify => bool_operand2)
+  #
+  class BoolConstraintReceiver < Gecode::ConstraintReceiver
+    # Raises TypeError unless the left hand side is an bool operand.
+    def initialize(model, params) #:nodoc:
+      super
+
+      unless params[:lhs].respond_to? :to_bool_var
+        raise TypeError, 'Must have bool operand as left hand side.'
       end
-      
-      # Override to also deal with constant booleans.
-      def false(options = {})
-        # We don't need any additional constraints.
-        @params.update Gecode::Constraints::Util.decode_options(options)
-        @model.add_interaction do
-          @constrain_equal_proc.call(@params[:negate], @params)
+    end
+  end
+
+  # An operand that short circuits boolean equality.
+  class ShortCircuitEqualityOperand #:nodoc:
+    include Gecode::Bool::BoolOperand
+    attr :model
+
+    def initialize(model)
+      @model = model
+    end
+
+    def construct_receiver(params)
+      params.update(:lhs => self)
+      receiver = BoolConstraintReceiver.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_bool_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
-    
-    # Describes a stub that produces an int variable, which can then be used 
-    # with the normal int variable constraints. An example would be the 
-    # conjunction constraint.
-    #
-    #   bools.conjunction.must == b1 | b2
-    #
-    # <tt>bools.conjunction</tt> produces a boolean variable which the 
-    # constraint <tt>.must == b1 | b2</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)
+
+    def to_bool_var
+      variable = model.bool_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 +bool_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 +bool_operand+.
+    def constrain_equal(bool_operand, constrain_domain, propagation_options)
+      raise NotImplementedError, 'Abstract method has not been implemented.'
     end
   end
 end

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

@@ -5,7 +5,7 @@ module Gecode
     # omitted then no upper bound is placed. If both +at_least+ and
     # +at_most+ are omitted then no bounds are placed.
     #
-    # See Constraints::IntEnum::Extensional::RegexpConstraint for the
+    # See IntEnum::Extensional::RegexpConstraint for the
     # allowed syntax of +regexp+.
     def repeat(regexp, at_least = nil, at_most = nil)
       unless at_least.nil? or at_least.kind_of? Fixnum
@@ -17,7 +17,7 @@ module Gecode
           "Expected the at_most argument to be a Fixnum, got #{at_most.class}"
       end
 
-      reg = Constraints::Util::Extensional.parse_regexp regexp
+      reg = Util::Extensional.parse_regexp regexp
       if at_most.nil?
         if at_least.nil?
           reg.send '*'
@@ -48,12 +48,12 @@ module Gecode
     # Matches any of the specified +regexps+.
     def any(*regexps)
       regexps.inject(Gecode::Raw::REG.new) do |result, regexp|
-        result | Constraints::Util::Extensional.parse_regexp(regexp)
+        result | Util::Extensional.parse_regexp(regexp)
       end
     end
   end
 
-  module Constraints::Util::Extensional
+  module Util::Extensional
     module_function
 
     # Parses a regular expression over the integer domain, returning

data/lib/gecoder/interface/constraints/fixnum_enum/element.rb

@@ -0,0 +1,63 @@
+module Gecode::FixnumEnum
+  module FixnumEnumOperand
+    # 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(enum_mod) #:nodoc:
+      enum_mod.module_eval do
+        # Now we enter the module FixnumEnumOperands is mixed into.
+        class << self
+          alias_method :pre_element_included, :included
+          def included(mod) #:nodoc:
+            mod.module_eval do
+              if instance_methods.include? '[]'
+                alias_method :pre_element_access, :[]
+              end
+          
+              # Produces an IntOperand representing the
+              # i:th constant integer in the enumeration, where i is the
+              # value of the integer operand used as index. Think of it
+              # as array access in the world of constraint programming.
+              # 
+              # ==== Examples 
+              # 
+              #   # The price of +selected_item+ as described by +prices+ .
+              #   prices = wrap_enum([500, 24, 4711, 412, 24])
+              #   prices[selected_item]
+              # 
+              def [](*vars)
+                if vars.first.respond_to? :to_int_var
+                  return Element::ElementIntOperand.new(
+                    self, vars.first, model)
+                else
+                  pre_element_access(*vars) if respond_to? :pre_element_access
+                end
+              end
+            end
+            pre_element_included(mod)
+          end
+        end
+      end
+    end
+  end
+
+  module Element #:nodoc:
+    class ElementIntOperand < Gecode::Int::ShortCircuitEqualityOperand #:nodoc:
+      def initialize(enum_op, position_int_var_op, model)
+        super model
+        @enum = enum_op
+        @position = position_int_var_op
+      end
+
+      def constrain_equal(int_operand, constrain, propagation_options)
+        if constrain
+          int_operand.must_be.in @enum
+        end
+
+        Gecode::Raw::element(@model.active_space, @enum, 
+          @position.to_int_var.bind, int_operand.to_int_var.bind, 
+          *propagation_options)
+      end
+    end
+  end
+end

data/lib/gecoder/interface/constraints/fixnum_enum/operation.rb

@@ -0,0 +1,65 @@
+module Gecode::FixnumEnum
+  module FixnumEnumOperand
+    # Produces a new SetOperand representing the union between this operand, 
+    # interpreted as a constant set, and +set_operand+.
+    #
+    # ==== Examples 
+    #
+    #   # The union between +fixnum_enum+ and +set+.
+    #   fixnum_enum.union set
+    def union(set_operand)
+      set_operation(:union, set_operand)
+    end
+
+    # Produces a new SetOperand representing the disjoint union between
+    # this operand, interpreted as a constant set, and
+    # +set_operand+. The disjoint union is the union of
+    # the disjoint parts of the sets.
+    #
+    # ==== Examples 
+    #
+    #   # The disjoint union between +fixnum_enum+ and +set+.
+    #   fixnum_enum.disjoint_union set
+    def disjoint_union(set_operand)
+      set_operation(:disjoint_union, set_operand)
+    end
+
+    # Produces a new SetOperand representing the intersection between
+    # this operand, interpreted as a constant set, and
+    # +set_operand+. 
+    #
+    # ==== Examples 
+    #
+    #   # The intersection between +fixnum_enum+ and +set+.
+    #   fixnum_enum.intersection set
+    def intersection(set_operand)
+      set_operation(:intersection, set_operand)
+    end
+
+    # Produces a new SetOperand representing this operand, interpreted
+    # as a constant set, minus +set_operand+. 
+    #
+    # ==== Examples 
+    #
+    #   # +fixnum_enum+ minus +set+.
+    #   fixnum_enum.minus set
+    def minus(set_operand)
+      set_operation(:minus, set_operand)
+    end
+
+    private 
+
+    # Starts a constraint on this set #{name} the specified set.
+    def set_operation(operator, operand2)
+      unless operand2.respond_to? :to_set_var
+        raise TypeError, 'Expected set operand as ' + 
+          "operand, got \#{operand2.class}."
+      end
+
+      return Operation::OperationSetOperand.new(model, self, 
+        operator, operand2)
+    end
+  end
+
+  Operation = Gecode::Set::Operation
+end

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

@@ -0,0 +1,42 @@
+# A module containing constraints that have enumerations of instances of
+# Fixnum as left hand side.
+module Gecode::FixnumEnum #:nodoc:
+  # A FixnumEnumOperand is a enumeration of Fixnum on which the
+  # constraints defined in FixnumEnumConstraintReceiver can be placed.
+  # They typically service as constant arrays or constant sets.
+  #
+  # The fixnum enumeration operands are created by wrapping an enumeration 
+  # of fixnum Gecode::Model#wrap_enum. The enumerations created that way
+  # all respond to the properties defined by FixnumEnumOperand.
+  #
+  # ==== Examples 
+  #
+  # Uses Gecode::Model#wrap_enum inside a problem formulation to create
+  # a FixnumEnumOperand from an existing enumeration of Fixnum:
+  #
+  #   fixnum_enum = wrap_enum([3, 5, 7])
+  #   
+  #--
+  # Classes that mix in FixnumEnumOperand must define #model.
+  module FixnumEnumOperand
+    include Gecode::Operand 
+
+    def method_missing(method, *args) #:nodoc:
+      if Gecode::FixnumEnum::Dummy.instance_methods.include? method.to_s
+        # Delegate to the fixnum enum.
+        to_fixnum_enum.method(method).call(*args)
+      else
+        super
+      end
+    end
+
+    private
+  
+    def construct_receiver(params)
+      raise NotImplementedError, 'Fixnum enums do not have constraints.'
+    end
+  end
+end
+
+require 'gecoder/interface/constraints/fixnum_enum/element'
+require 'gecoder/interface/constraints/fixnum_enum/operation'