gecoder 0.6.1 → 0.7.0

data/CHANGES

@@ -1,3 +1,10 @@
+== Version 0.7.0
+This release adds the set selection and operation constraints.
+
+* Added set selection constraints (set array access, select union, select intersection (optionally with specified universe) and select disjoint).
+* Added set operation constraints (union, minus, disjoint_union and intersection) on pairs of set variables or set constants with variable or constant right hand side.
+* Added set operation constraints on enumerations of sets.
+
 == Version 0.6.1
 This release fixes various bugs introduced in 0.6.0 and changes the way that
 int variable domains are specified (breaking backward-compatibility).

data/README

@@ -1,15 +1,15 @@
 == Gecode/R
 
-Gecode/R is a Ruby interface to Gecode, an open, free and efficient environment 
-for developing constraint-based systems and applications.
+Gecode/R is a Ruby interface to the Gecode constraint programming library. 
+Gecode/R is intended for people with no previous experience of constraint 
+programming, aiming to be easy to pick up and use.
 
 == Warning
 
-Gecode/R is still in an early development stage, the syntax is by no means 
-final and backwards compatibility will be broken time and time again until 
-later in the development process. Don’t use Gecode/R in production-code yet, 
-it’s merely available this early to allow people to play with it and give 
-feedback.
+Gecode/R is still in a development stage, the syntax is by no means final
+and backwards compatibility will be broken time and time again. Don't use 
+Gecode/R in production-code yet, it's merely available at this point to allow 
+people to play with it and give feedback.
 
 == Installation
 

data/lib/gecoder/interface/constraints.rb

@@ -75,6 +75,14 @@ module Gecode
       NEGATED_SET_RELATION_TYPES = {
         :== => Gecode::Raw::SRT_NQ
       }
+      # Maps the names of the methods to the corresponding set operation type in 
+      # Gecode.
+      SET_OPERATION_TYPES = { 
+        :union          => Gecode::Raw::SOT_UNION,
+        :disjoint_union => Gecode::Raw::SOT_DUNION,
+        :intersection   => Gecode::Raw::SOT_INTER,
+        :minus          => Gecode::Raw::SOT_MINUS
+      }
       
       # Various method aliases for comparison methods. Maps the original 
       # (symbol) name to an array of aliases.
@@ -134,18 +142,52 @@ module Gecode
       #   other enumerations.
       # * Enumeration of integers (set contaning all numbers in set).
       def constant_set_to_params(constant_set)
+        unless constant_set?(constant_set)
+          raise TypeError, "Expected a constant set, got: #{constant_set}."
+        end
+      
         if constant_set.kind_of? Range
           return constant_set.first, constant_set.last
         elsif constant_set.kind_of? Fixnum
           return constant_set
         else
           constant_set = constant_set.to_a
-          unless constant_set.all?{ |e| e.kind_of? Fixnum }
-            raise TypeError, "Not a constant set: #{constant_set}."
-          end
           return Gecode::Raw::IntSet.new(constant_set, constant_set.size)
         end
       end
+      
+      # Converts the different ways to specify constant sets in the interface
+      # to an instance of Gecode::Raw::IntSet. The different forms accepted are:
+      # * Single instance of Fixnum (singleton set).
+      # * Range (set containing all numbers in range), treated differently from
+      #   other enumerations.
+      # * Enumeration of integers (set contaning all numbers in set).
+      def constant_set_to_int_set(constant_set)
+        unless constant_set?(constant_set)
+          raise TypeError, "Expected a constant set, got: #{constant_set}."
+        end
+        
+        if constant_set.kind_of? Range
+          return Gecode::Raw::IntSet.new(constant_set.first, constant_set.last)
+        elsif constant_set.kind_of? Fixnum
+          return Gecode::Raw::IntSet.new([constant_set], 1)
+        else
+          constant_set = constant_set.to_a
+          return Gecode::Raw::IntSet.new(constant_set, constant_set.size)
+        end
+      end
+      
+      # Checks whether the specified expression is regarded as a constant set.
+      # Returns true if it is, false otherwise.
+      def constant_set?(expression)
+        return (
+           expression.kind_of?(Range) &&        # It's a range.
+           expression.first.kind_of?(Fixnum) &&
+           expression.last.kind_of?(Fixnum)) ||
+          expression.kind_of?(Fixnum) ||        # It's a single fixnum.
+          (expression.kind_of?(Enumerable) &&   # It's an enum of fixnums.
+           expression.all?{ |e| e.kind_of? Fixnum })
+      end
     end
     
     # Describes a constraint expressions. An expression is produced by calling

data/lib/gecoder/interface/constraints/int/domain.rb

@@ -38,10 +38,9 @@ module Gecode::Constraints::Int
       
         var, domain, reif_var, strength = @params.values_at(:lhs, :domain, 
           :reif, :strength)
-        domain = domain.to_a
         
         (params = []) << var.bind
-        params << Gecode::Raw::IntSet.new(domain, domain.size)
+        params << Gecode::Constraints::Util.constant_set_to_int_set(domain)
         params << reif_var.bind if reif_var.respond_to? :bind
         params << strength
         Gecode::Raw::dom(space, *params)

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

@@ -5,8 +5,10 @@ module Gecode::Constraints::IntEnum::Element
   class ExpressionStub < Gecode::Constraints::Int::CompositeStub
     def constrain_equal(variable, params, constrain)
       enum, position, strength = @params.values_at(:lhs, :position, :strength)
-      variable.must_be.in enum.domain_range
-
+      if constrain
+        variable.must_be.in enum.domain_range
+      end
+      
       # The enum can be a constant array.
       enum = enum.to_int_var_array if enum.respond_to? :to_int_var_array
       Gecode::Raw::element(@model.active_space, enum, 

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

@@ -0,0 +1,101 @@
+module Gecode
+  class FreeSetVar
+    Gecode::Constraints::Util::SET_OPERATION_TYPES.each_pair do |name, type|
+      module_eval <<-"end_code"
+        # Starts a constraint on this set #{name} the specified set.
+        def #{name}(operand)
+          unless operand.kind_of?(Gecode::FreeSetVar) or 
+              Gecode::Constraints::Util::constant_set?(operand)
+            raise TypeError, 'Expected set variable or constant set as ' + 
+              "operand, got \#{operand.class}."
+          end
+
+          params = {:lhs => self, :op2 => operand, :operation => #{type}}
+          Gecode::Constraints::SimpleExpressionStub.new(@model, params) do |m, ps|
+            Gecode::Constraints::Set::Operation::Expression.new(m, ps)
+          end
+        end
+      end_code
+    end
+  end
+  
+  module FixnumEnumMethods
+    Gecode::Constraints::Util::SET_OPERATION_TYPES.each_pair do |name, type|
+      module_eval <<-"end_code"
+        # Starts a constraint on this set union the specified set.
+        def #{name}(operand)
+          unless operand.kind_of?(Gecode::FreeSetVar) or 
+              Gecode::Constraints::Util::constant_set?(operand)
+            raise TypeError, 'Expected set variable or constant set as ' + 
+              "operand, got \#{operand.class}."
+          end
+
+          params = {:lhs => self, :op2 => operand, :operation => #{type}}
+          Gecode::Constraints::SimpleExpressionStub.new(@model, params) do |m, ps|
+            Gecode::Constraints::Set::Operation::Expression.new(m, ps)
+          end
+        end
+      end_code
+    end
+  end
+end
+
+module Gecode::Constraints::Set
+  # A module that gathers the classes and modules used in operation constraints.
+  module Operation
+    # An expression with a set operand and two operands followed by must.
+    class Expression < Gecode::Constraints::Expression
+      Gecode::Constraints::Util::SET_RELATION_TYPES.each_pair do |name, type|
+        module_eval <<-"end_code"
+          # Creates an operation constraint using the specified expression.
+          def #{name}(expression)
+            if @params[:negate]
+              # We do not allow negation.
+              raise Gecode::MissingConstraintError, 'A negated set operation ' + 
+                'constraint is not implemented.'
+            end
+            unless expression.kind_of?(Gecode::FreeSetVar) or 
+                Gecode::Constraints::Util::constant_set?(expression)
+              raise TypeError, 'Expected set variable or constant set, got ' + 
+                "\#{expression.class}."
+            end
+            
+            @params[:rhs] = expression
+            @params[:relation] = #{type}
+            unless @params.values_at(:lhs, :op2, :rhs).any?{ |element| 
+                element.kind_of? Gecode::FreeSetVar}
+              # At least one variable must be involved in the constraint.
+              raise ArgumentError, 'At least one variable must be involved ' +
+                'in the constraint, but all given were constants.'
+            end
+            
+            @model.add_constraint OperationConstraint.new(@model, @params)
+          end
+        end_code
+      end
+      alias_set_methods
+    end
+    
+    # Describes a constraint involving a set operator operating on two set 
+    # operands.
+    class OperationConstraint < Gecode::Constraints::Constraint
+      def post
+        op1, op2, operation, relation, rhs, negate = @params.values_at(:lhs, 
+          :op2, :operation, :relation, :rhs, :negate)
+
+        op1, op2, rhs = [op1, op2, rhs].map do |expression|
+          # The expressions can either be set variables or constant sets, 
+          # convert them appropriately.
+          if expression.respond_to? :bind
+            expression.bind
+          else
+            Gecode::Constraints::Util::constant_set_to_int_set(expression)
+          end
+        end
+
+        Gecode::Raw::rel(@model.active_space, op1, operation, op2, relation, 
+          rhs)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+module Gecode::SetEnumMethods
+  Gecode::Constraints::Util::SET_OPERATION_TYPES.each_pair do |name, type|
+    next if type == Gecode::Raw::SOT_MINUS # Does not support this constraint?
+    
+    module_eval <<-"end_code"
+      # Starts a constraint on the #{name} of the sets.
+      def #{name}
+        params = {:lhs => self, :operation => #{type}}
+        Gecode::Constraints::SetEnum::Operation::ExpressionStub.new(
+          @model, params)
+      end
+    end_code
+  end
+end
+
+# A module that gathers the classes and modules used by operation constaints.
+module Gecode::Constraints::SetEnum::Operation
+  # Describes a stub started with a set enumeration followed by a set operation.
+  class ExpressionStub < Gecode::Constraints::Set::CompositeStub
+    def constrain_equal(variable, params, constrain)
+      enum, operation = @params.values_at(:lhs, :operation)
+    
+      if constrain
+        if operation == Gecode::Raw::SOT_INTER or 
+            operation == Gecode::Raw::SOT_MINUS
+          variable.must_be.subset_of enum.first.upper_bound
+        else
+          variable.must_be.subset_of enum.upper_bound_range
+        end
+      end
+      
+      Gecode::Raw::rel(@model.active_space, operation, enum.to_set_var_array,
+        variable.bind)
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+module Gecode::SetEnumMethods
+  # 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)
+    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
+    
+      def [](*vars)
+        # Hook in an element constraint if a variable is used for array 
+        # access.
+        if vars.first.kind_of? Gecode::FreeIntVar
+          params = {:lhs => self, :index => vars.first}
+          Gecode::Constraints::SetEnum::Selection::SelectExpressionStub.new(
+            @model, params)
+        elsif vars.first.kind_of? Gecode::FreeSetVar
+          params = {:lhs => self, :indices => vars.first}
+          Gecode::Constraints::SetEnum::Selection::SetAccessStub.new(
+            @model, params)
+        else
+          pre_selection_access(*vars) if respond_to? :pre_selection_access
+        end
+      end
+    end
+  end
+end
+
+# A module that gathers the classes and modules used by selection constraints.
+module Gecode::Constraints::SetEnum::Selection
+  # Describes an expression stub started with a set var enum following with an 
+  # array access using an integer variable.
+  class SelectExpressionStub < Gecode::Constraints::Set::CompositeStub
+    def constrain_equal(variable, params, constrain)
+      enum, index = @params.values_at(:lhs, :index)
+      if constrain
+        variable.must_be.subset_of enum.upper_bound_range
+      end
+
+      Gecode::Raw::selectSet(@model.active_space, enum.to_set_var_array, 
+        index.bind, variable.bind)
+    end
+  end
+  
+  # Describes an expression stub started with a set var enum followed with an
+  # array access using a set variable.
+  class SetAccessStub < Gecode::Constraints::ExpressionStub
+    include Gecode::Constraints::LeftHandSideMethods
+    
+    # Starts a union selection constraint on the selected sets.
+    def union
+      UnionExpressionStub.new(@model, @params)
+    end
+    
+    # Starts a intersection selection constraint on the selected sets. The 
+    # option :with may optionally be specified, in which case the value should
+    # be an enumeration of the elements in the universe.
+    def intersection(options = {})
+      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
+          @params.update(:universe => universe)
+        end
+      end
+      
+      IntersectionExpressionStub.new(@model, @params)
+    end
+    
+    private
+    
+    # Produces an expression with position for the lhs module.
+    def expression(params)
+      SetAccessExpression.new(@model, @params.update(params))
+    end
+  end
+  
+  # Describes an expression stub started with a set var enum following with an 
+  # array access using a set variable followed by #union.
+  class UnionExpressionStub < Gecode::Constraints::Set::CompositeStub
+    def constrain_equal(variable, params, constrain)
+      enum, indices = @params.values_at(:lhs, :indices)
+      if constrain
+        variable.must_be.subset_of enum.upper_bound_range
+      end
+      
+      Gecode::Raw::selectUnion(@model.active_space, enum.to_set_var_array,
+        indices.bind, variable.bind)
+    end
+  end
+  
+  # Describes an expression stub started with a set var enum following with an 
+  # array access using a set variable followed by #intersection.
+  class IntersectionExpressionStub < Gecode::Constraints::Set::CompositeStub
+    def constrain_equal(variable, params, constrain)
+      enum, indices, universe = @params.values_at(:lhs, :indices, :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_var_array,
+          indices.bind, variable.bind)
+      else
+        Gecode::Raw::selectInterIn(@model.active_space, enum.to_set_var_array,
+          indices.bind, variable.bind, 
+          Gecode::Constraints::Util.constant_set_to_int_set(universe))
+      end
+    end
+  end
+  
+  # Describes an expression that starts with an set variable enum followed with
+  # an array access using a set variable followed by some form of must.
+  class SetAccessExpression < Gecode::Constraints::Set::Expression
+    # Constrains the selected sets to be disjoint.
+    def disjoint
+      if @params[:negate]
+        raise Gecode::MissingConstraintError, 'A negated set selection ' + 
+          'disjoint is not implemented.'
+      end
+      
+      @model.add_constraint DisjointConstraint.new(@model, @params)
+    end
+  end
+  
+  # Describes a disjoint constraint produced by sets[set].must_be.disjoint .
+  class DisjointConstraint < Gecode::Constraints::Constraint
+    def post
+      enum, indices = @params.values_at(:lhs, :indices)
+      Gecode::Raw.selectDisjoint(@model.active_space, enum.to_set_var_array,
+        indices.bind)
+    end
+  end
+end

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

@@ -30,3 +30,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/operation'

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

@@ -29,6 +29,35 @@ module Gecode
         Gecode::Constraints::Util.decode_options(options)
       end
     end
+    
+    # A composite expression which is an set expression with a left hand side 
+    # resulting from a previous constraint.
+    class CompositeExpression < Gecode::Constraints::CompositeExpression
+      # 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
+    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.
+    #
+    #   sets[int_var].must_be.subset_of(another_set)
+    # 
+    # "sets[int_var]" produces a bool variable which the constraint 
+    # ".must_be.subset_of(another_set)" 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.
+    class CompositeStub < Gecode::Constraints::CompositeStub
+      def initialize(model, params)
+        super(CompositeExpression, model, params)
+      end
+    end
   end
 end
 
@@ -36,3 +65,4 @@ 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/operation'