gecoder 0.8.1 → 0.8.2

data/CHANGES

@@ -1,3 +1,13 @@
+== Version 0.8.2
+This release adds search statistics along with some new arithmetic constraints 
+and channel constraints between boolean and integer variables.
+
+* Wrapping an enumerable that is already wrapped is no longer allowed.
+* Added search statistics.
+* Added squared value and square root constraints.
+* Added channel constraints between single integer variables and boolean variables.
+* Added channel constraints between enumerations of boolean variables and single integer variables.
+
 == Version 0.8.1
 This release adds tuple constraints along with a couple of minor features. It 
 also fixes a bug introduced in the previous version.

data/lib/gecoder/bindings/bindings.rb

@@ -908,6 +908,22 @@ Rust::Bindings::create_bindings Rust::Bindings::LangCxx, "gecode" do |b|
       func.add_parameter "Gecode::PropKind", "pk"
     end
     
+    ns.add_function "sqr" do |func|
+      func.add_parameter "Gecode::MSpace *", "home"
+      func.add_parameter "Gecode::IntVar", "x0"
+      func.add_parameter "Gecode::IntVar", "x1"
+      func.add_parameter "Gecode::IntConLevel", "icl"
+      func.add_parameter "Gecode::PropKind", "pk"
+    end
+    
+    ns.add_function "sqrt" do |func|
+      func.add_parameter "Gecode::MSpace *", "home"
+      func.add_parameter "Gecode::IntVar", "x0"
+      func.add_parameter "Gecode::IntVar", "x1"
+      func.add_parameter "Gecode::IntConLevel", "icl"
+      func.add_parameter "Gecode::PropKind", "pk"
+    end
+    
     ns.add_function "branch" do |func|
       func.add_parameter "Gecode::MSpace *", "home"
       func.add_parameter "Gecode::MIntVarArray *", "iva" do |param|
@@ -955,6 +971,25 @@ Rust::Bindings::create_bindings Rust::Bindings::LangCxx, "gecode" do |b|
       func.add_parameter "Gecode::PropKind", "pk"
     end
     
+    ns.add_function "channel" do |func|
+      func.add_parameter "Gecode::MSpace*", "home"
+      func.add_parameter "Gecode::IntVar", "x0"
+      func.add_parameter "Gecode::BoolVar", "x1"
+      func.add_parameter "Gecode::IntConLevel", "icl"
+      func.add_parameter "Gecode::PropKind", "pk"
+    end
+    
+    ns.add_function "channel" do |func|
+      func.add_parameter "Gecode::MSpace*", "home"
+      func.add_parameter "Gecode::MBoolVarArray *", "x" do |param|
+        param.custom_conversion = "*ruby2Gecode_MBoolVarArrayPtr(argv[1], 2)->ptr()"
+      end
+      func.add_parameter "Gecode::IntVar", "y"
+      func.add_parameter "int", "o"
+      func.add_parameter "Gecode::IntConLevel", "icl"
+      func.add_parameter "Gecode::PropKind", "pk"
+    end
+    
     ns.add_function "count" do |func|
       func.add_parameter "Gecode::MSpace*", "home"
       func.add_parameter "Gecode::MIntVarArray *", "x" do |param|

data/lib/gecoder/interface/constraints/bool/boolean.rb

@@ -26,6 +26,13 @@ module Gecode
     # Describes a boolean expression (following after must*).
     class Expression #:nodoc:
       def ==(expression, options = {})
+        unless expression.kind_of?(ExpressionTree) or 
+            expression.kind_of?(Gecode::FreeBoolVar) or 
+            expression.kind_of?(TrueClass) or expression.kind_of?(FalseClass) or
+            expression.respond_to?(:to_minimodel_lin_exp)
+          raise TypeError, 'Invalid right hand side of boolean equation.'
+        end
+        
         @params.update Gecode::Constraints::Util.decode_options(options)
         @model.add_constraint BooleanConstraint.new(@model, 
           @params.update(:rhs => expression))

data/lib/gecoder/interface/constraints/bool/channel.rb

@@ -0,0 +1,23 @@
+module Gecode::Constraints::Bool
+  class Expression
+    alias_method :pre_channel_equals, :==
+    
+    # Constrains the boolean variable to be equal to the specified integer 
+    # variable.
+    def ==(int, options = {})
+      unless @params[:lhs].kind_of?(Gecode::FreeBoolVar) and 
+          int.kind_of?(Gecode::FreeIntVar)
+        return pre_channel_equals(int, options)
+      end
+      
+      # Provide commutivity to the corresponding int variable constraint.
+      if @params[:negate]
+        int.must_not.equal(@params[:lhs], options)
+      else
+        int.must.equal(@params[:lhs], options)
+      end
+    end
+    
+    alias_comparison_methods
+  end
+end

data/lib/gecoder/interface/constraints/bool_enum/channel.rb

@@ -0,0 +1,59 @@
+module Gecode::Constraints::BoolEnum
+  class Expression
+    # Adds a channel constraint on the variables in the enum with the specified
+    # integer variable. Beyond the common options the channel constraint can
+    # also take the following option:
+    #
+    # [:offset]  Specifies an offset for the integer variable. If the offset is
+    #            set to k then the integer variable takes value i+k exactly 
+    #            when the variable at index i in the boolean enumration is true 
+    #            and the rest are false.
+    def channel(int_var, options = {})
+      if @params[:negate]
+        raise Gecode::MissingConstraintError, 'A negated channel constraint ' + 
+          'is not implemented.'
+      end
+      if options.has_key? :reify
+        raise ArgumentError, 'The channel constraint does not support the ' + 
+          'reification option.'
+      end
+      unless int_var.kind_of? Gecode::FreeIntVar
+        raise TypeError, "Expected an integer variable, got #{int_var.class}."
+      end
+      
+      @params.update(:rhs => int_var, :offset => options.delete(:offset) || 0)
+      @params.update(Gecode::Constraints::Util.decode_options(options))
+      @model.add_constraint Channel::ChannelConstraint.new(@model, @params)
+    end
+  end
+  
+  # A module that gathers the classes and modules used in channel constraints
+  # involving one boolean enum and one integer variable.
+  module Channel #:nodoc:
+    # Describes a channel constraint that "channels" an enumerations of 
+    # boolean variables with an integer variable. This constrains the integer
+    # variable to take value i exactly when the variable at index i in the 
+    # boolean enumeration is true and the others are false.
+    # 
+    # Neither reification nor negation is supported.
+    #
+    # == Examples
+    #
+    # # Constrains the enumeration called +selected_option+ to be false in the
+    # # first four positions and have exactly one true variable in the other. 
+    # selected_option.must.channel selected_option_index 
+    # selected_option_index.must_be > 3
+    #
+    # # Constrains the enumeration called +selected_option+ to be false in the
+    # # first five positions and have exactly one true variable in the other. 
+    # selected_option.must.channel(selected_option_index, :offset => 1) 
+    # selected_option_index.must_be > 3
+    class ChannelConstraint < Gecode::Constraints::Constraint
+      def post
+        lhs, rhs, offset = @params.values_at(:lhs, :rhs, :offset)
+        Gecode::Raw::channel(@model.active_space, lhs.to_bool_var_array, 
+          rhs.bind, offset, *propagation_options)
+      end
+    end
+  end
+end

data/lib/gecoder/interface/constraints/bool_enum/extensional.rb

@@ -10,16 +10,17 @@ module Gecode::Constraints::BoolEnum
         raise ArgumentError, 'Reification is not supported by the tuple ' + 
           'constraint.'
       end
-      unless tuples.respond_to?(:each) and 
-          tuples.all?{ |tuple| tuple.respond_to?(:each) }
-        raise TypeError, 'Expected an enumeration with tuples, got ' + 
-          "#{tuples.class}."
-      end
-      unless tuples.all?{ |tuple| 
-          tuple.all?{ |x| x.kind_of?(TrueClass) or x.kind_of?(FalseClass) }}
-        raise TypeError, 'All tuples must contain booleans.'
+      
+      util = Gecode::Constraints::Util
+      
+      # Check that the tuples are correct.
+      expected_size = @params[:lhs].size
+      util::Extensional.perform_tuple_checks(tuples, expected_size) do |tuple|
+        unless tuple.all?{ |x| x.kind_of?(TrueClass) or x.kind_of?(FalseClass) }
+          raise TypeError, 'All tuples must contain booleans.'
+        end
       end
-    
+      
       @params[:tuples] = tuples
       @model.add_constraint Extensional::TupleConstraint.new(@model, 
         @params.update(Gecode::Constraints::Util.decode_options(options)))

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

@@ -30,3 +30,4 @@ end
 
 require 'gecoder/interface/constraints/bool_enum/relation'
 require 'gecoder/interface/constraints/bool_enum/extensional'
+require 'gecoder/interface/constraints/bool_enum/channel'

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

@@ -73,3 +73,4 @@ end
 
 require 'gecoder/interface/constraints/bool/boolean'
 require 'gecoder/interface/constraints/bool/linear'
+require 'gecoder/interface/constraints/bool/channel'

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

@@ -4,6 +4,20 @@ class Gecode::FreeIntVar
     Gecode::Constraints::Int::Arithmetic::AbsExpressionStub.new(@model, 
       :lhs => self)
   end
+  
+  # Initiates an arithmetic squared value constraint.
+  def squared
+    Gecode::Constraints::Int::Arithmetic::SquaredExpressionStub.new(@model, 
+      :lhs => self)
+  end
+
+  # Initiates an arithmetic squared root constraint.
+  def sqrt
+    Gecode::Constraints::Int::Arithmetic::SquareRootExpressionStub.new(@model, 
+      :lhs => self)
+  end
+  alias_method :square_root, :sqrt
+
 
   alias_method :pre_arith_mult, :* if instance_methods.include? '*'
   
@@ -52,7 +66,7 @@ module Gecode::Constraints::Int::Arithmetic #:nodoc:
   #   # The value of +x*y+ must be equal to their sum.
   #   (x*y).must == x + y
   #   
-  #   # The valye of +x*y+ must be less than 17, with +bool+ as reification 
+  #   # The value of +x*y+ must be less than 17, with +bool+ as reification 
   #   # variable and +domain+ as strength.
   #   (x*y).must_be.less_than(17, :reify => bool, :strength => :domain)
   class MultExpressionStub < Gecode::Constraints::Int::CompositeStub
@@ -69,4 +83,67 @@ module Gecode::Constraints::Int::Arithmetic #:nodoc:
         variable.bind, *propagation_options)
     end
   end
+  
+  # Describes a CompositeStub for the squared constraint, which constrain
+  # the squared value of the variable.
+  # 
+  # == Examples
+  #   
+  #   # The value of +x*x+ must be equal to y.
+  #   x.squared.must == y
+  #   
+  #   # The value of +x*x+ must be less than or equal to 16, with +bool+ as 
+  #   # reification variable and +domain+ as strength.
+  #   x.squared.must_be.less_or_equal(16, :reify => bool, :strength => :domain)
+  class SquaredExpressionStub < Gecode::Constraints::Int::CompositeStub
+    def constrain_equal(variable, params, constrain)
+      lhs = @params[:lhs]
+      if constrain
+        min = lhs.min; max = lhs.max
+        products = [min*max, min*min, max*max]
+        variable.must_be.in products.min..products.max
+      end
+
+      Gecode::Raw::sqr(@model.active_space, lhs.bind, variable.bind, 
+        *propagation_options)
+    end
+  end
+  
+  # Describes a CompositeStub for the square root constraint, which constrain
+  # the rounded down square root of the variable.
+  # 
+  # == Examples
+  #   
+  #   # The square root of +x+, rounded down, must equal y.
+  #   x.square_root.must == y   
+  #
+  #   # The square root of +x+, rounded down, must be larger than 17, with 
+  #   # +bool+ as reification variable and +domain+ as strength.
+  #   x.square_root.must_be.larger_than(17, :reify => bool, :strength => :domain)
+  class SquareRootExpressionStub < Gecode::Constraints::Int::CompositeStub
+    def constrain_equal(variable, params, constrain)
+      lhs = @params[:lhs]
+      if constrain
+        max = lhs.max
+        if max < 0
+          # The left hand side does not have a real valued square root.
+          upper_bound = 0
+        else
+          upper_bound = Math.sqrt(max).floor;
+        end
+        
+        min = lhs.min
+        if min < 0
+          lower_bound = 0
+        else
+          lower_bound = Math.sqrt(min).floor;
+        end
+        
+        variable.must_be.in lower_bound..upper_bound
+      end
+
+      Gecode::Raw::sqrt(@model.active_space, lhs.bind, variable.bind, 
+        *propagation_options)
+    end
+  end
 end

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

@@ -0,0 +1,73 @@
+module Gecode::Constraints::Int
+  class Expression
+    alias_method :pre_channel_equals, :==
+    
+    # Constrains the integer variable to be equal to the specified boolean 
+    # variable. I.e. constrains the integer variable to be 1 when the boolean
+    # variable is true and 0 if the boolean variable is false.
+    def ==(bool, options = {})
+      unless @params[:lhs].kind_of?(Gecode::FreeIntVar) and 
+          bool.kind_of?(Gecode::FreeBoolVar)
+        return pre_channel_equals(bool, options)
+      end
+      
+      if @params[:negate]
+        raise Gecode::MissingConstraintError, 'A negated channel constraint ' +
+          'is not implemented.'
+      end
+      unless options[:reify].nil?
+        raise ArgumentError, 'Reification is not supported by the channel ' + 
+          'constraint.'
+      end
+      
+      @params.update(Gecode::Constraints::Util.decode_options(options))
+      @params[:rhs] = bool
+      @model.add_constraint Channel::ChannelConstraint.new(@model, @params)
+    end
+    
+    alias_comparison_methods
+    
+    # Adds a channel constraint on the integer variable and the variables in 
+    # the specifed enum of boolean variables. Beyond the common options the 
+    # channel constraint can also take the following option:
+    #
+    # [:offset]  Specifies an offset for the integer variable. If the offset is
+    #            set to k then the integer variable takes value i+k exactly 
+    #            when the variable at index i in the boolean enumration is true 
+    #            and the rest are false.
+    def channel(bool_enum, options = {})
+      unless bool_enum.respond_to? :to_bool_var_array
+        raise TypeError, 'Expected an enumration of boolean variables, got ' + 
+          "#{bool_enum.class}."
+      end
+      
+      # Just provide commutivity with the boolean enum channel constraint.
+      if @params[:negate]
+        bool_enum.must_not.channel(@params[:lhs], options)
+      else
+        bool_enum.must.channel(@params[:lhs], options)
+      end
+    end
+  end
+  
+  # A module that gathers the classes and modules used in channel constraints
+  # involving a single integer variable.
+  module Channel #:nodoc:
+    # Describes a channel constraint that constrains an integer variable to be 
+    # 1 if a boolean variable is true, and 0 when the boolean variable is false. 
+    # Does not support negation nor reification.
+    #
+    # == Examples
+    #
+    #   # The integer variable +x+ must be one exactly when the boolean 
+    #   # variable +bool+ is true.
+    #   x.must == bool
+    class ChannelConstraint < Gecode::Constraints::Constraint
+      def post
+        lhs, rhs = @params.values_at(:lhs, :rhs)
+        Gecode::Raw::channel(@model.active_space, lhs.bind, rhs.bind,
+          *propagation_options)
+      end
+    end
+  end
+end

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

@@ -11,8 +11,16 @@ module Gecode::Constraints::IntEnum
           enum.respond_to?(:to_set_var_array)
         raise TypeError, "Expected int or set enum, got #{enum.class}."
       end
+      if enum.respond_to? :to_set_var_array
+        if options.has_key? :reify
+          raise ArgumentError, 'The channel constraints does not support the ' +
+            'reification option.'
+        end
+        @params.update(Gecode::Constraints::Set::Util.decode_options(options))
+      else
+        @params.update(Gecode::Constraints::Util.decode_options(options))
+      end
       
-      @params.update(Gecode::Constraints::Util.decode_options(options))
       @params.update(:rhs => enum)
       @model.add_constraint Channel::ChannelConstraint.new(@model, @params)
     end
@@ -91,7 +99,7 @@ module Gecode::Constraints::IntEnum
           Gecode::Raw::channel(@model.active_space, lhs, rhs.to_int_var_array,
             *propagation_options)
         else
-          # Set var array, no strength.
+          # Set var array, no propagation options.
           Gecode::Raw::channel(@model.active_space, lhs, rhs.to_set_var_array)
         end
       end

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

@@ -1,6 +1,7 @@
 module Gecode::Constraints::IntEnum
   class Expression
-    # Posts an equality constraint on the variables in the enum.
+    # Posts a tuple constraint on the variables in the enum, constraining them
+    # to equal one of the specified tuples.
     def in(tuples, options = {})
       if @params[:negate]
         raise Gecode::MissingConstraintError, 'A negated tuple constraint is ' +
@@ -10,18 +11,20 @@ module Gecode::Constraints::IntEnum
         raise ArgumentError, 'Reification is not supported by the tuple ' + 
           'constraint.'
       end
-      unless tuples.respond_to?(:each) and 
-          tuples.all?{ |tuple| tuple.respond_to?(:each) }
-        raise TypeError, 'Expected an enumeration with tuples, got ' + 
-          "#{tuples.class}."
-      end
-      unless tuples.all?{ |tuple| tuple.all?{ |x| x.kind_of? Fixnum }}
-        raise TypeError, 'All tuples must contain Fixnum.'
+      
+      util = Gecode::Constraints::Util
+      
+      # Check that the tuples are correct.
+      expected_size = @params[:lhs].size
+      util::Extensional.perform_tuple_checks(tuples, expected_size) do |tuple|
+        unless tuple.all?{ |x| x.kind_of? Fixnum }
+          raise TypeError, 'All tuples must contain Fixnum.'
+        end
       end
     
       @params[:tuples] = tuples
       @model.add_constraint Extensional::TupleConstraint.new(@model, 
-        @params.update(Gecode::Constraints::Util.decode_options(options)))
+        @params.update(util.decode_options(options)))
     end
   end
   

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

@@ -56,3 +56,4 @@ end
 require 'gecoder/interface/constraints/int/linear'
 require 'gecoder/interface/constraints/int/domain'
 require 'gecoder/interface/constraints/int/arithmetic'
+require 'gecoder/interface/constraints/int/channel'

data/lib/gecoder/interface/constraints.rb

@@ -217,6 +217,40 @@ module Gecode
       end
     end
     
+    # A module that contains utility-methods for extensional constraints.
+    module Util::Extensional #:nodoc:
+      module_function
+      
+      # Checks that the specified enumeration is an enumeration containing 
+      # one or more tuples of the specified size. It also allows the caller
+      # to define additional tests by providing a block, which is given each
+      # tuple. If a test fails then an appropriate error is raised.
+      def perform_tuple_checks(tuples, expected_size, &additional_test)
+        unless tuples.respond_to?(:each)
+          raise TypeError, 'Expected an enumeration with tuples, got ' + 
+            "#{tuples.class}."
+        end
+        
+        if tuples.empty?
+          raise ArgumentError, 'One or more tuples must be specified.'
+        end
+        
+        tuples.each do |tuple|
+          unless tuple.respond_to?(:each)
+            raise TypeError, 'Expected an enumeration containing enumeraions, ' +
+              "got #{tuple.class}."
+          end
+          
+          unless tuple.size == expected_size
+            raise ArgumentError, 'All tuples must be of the same size as the ' + 
+              'number of variables in the array.'
+          end
+          
+          yield tuple
+        end
+      end
+    end
+    
     # Describes a constraint expressions. An expression is produced by calling
     # some form of must on a left hand side. The expression waits for a right 
     # hand side so that it can post the corresponding constraint.

data/lib/gecoder/interface/enum_wrapper.rb

@@ -6,6 +6,9 @@ module Gecode
       unless enum.kind_of? Enumerable
         raise TypeError, 'Only enumerables can be wrapped.'
       end
+      if enum.kind_of? Gecode::EnumMethods
+        raise ArgumentError, 'The enumration is already wrapped.'
+      end
       elements = enum.to_a
       if elements.empty?
         raise ArgumentError, 'Enumerable must not be empty.'

data/lib/gecoder/interface/search.rb

@@ -4,7 +4,9 @@ module Gecode
     # to that solution. Returns the model if a solution was found, nil 
     # otherwise.
     def solve!
-      space = dfs_engine.next
+      dfs = dfs_engine
+      space = dfs.next
+      @statistics = dfs.statistics
       return nil if space.nil?
       self.active_space = space
       return self
@@ -14,6 +16,7 @@ module Gecode
     # might have been performed). Returns the reset model.
     def reset!
       self.active_space = base_space
+      @statistics = nil
       return self
     end
     
@@ -33,11 +36,33 @@ module Gecode
       next_solution = nil
       while not (next_solution = dfs.next).nil?
         self.active_space = next_solution
+        @statistics = dfs.statistics
         yield self
       end
       self.reset!
     end
     
+    # Returns search statistics providing various information from Gecode about
+    # the search that resulted in the model's current variable state. If the 
+    # model's variables have not undegone any search then nil is returned. The 
+    # statistics is a hash with the following keys:
+    # [:propagations]   The number of propagation steps performed.
+    # [:failures]       The number of failed nodes in the search tree.
+    # [:clones]         The number of clones created.
+    # [:commits]        The number of commit operations performed.
+    # [:memory]         The peak memory allocated to Gecode.
+    def search_stats
+      return nil if @statistics.nil?
+      
+      return {
+        :propagations => @statistics.propagate,
+        :failures     => @statistics.fail,
+        :clones       => @statistics.clone,
+        :commits      => @statistics.commit,
+        :memory       => @statistics.memory
+      }
+    end
+    
     # Finds the optimal solution. Optimality is defined by the provided block
     # which is given one parameter, a solution to the problem. The block should
     # constrain the solution so that that only "better" solutions can be new 
@@ -70,7 +95,14 @@ module Gecode
       options.c_d = Gecode::Raw::Search::Config::MINIMAL_DISTANCE
       options.a_d = Gecode::Raw::Search::Config::ADAPTIVE_DISTANCE
       options.stop = nil
-      result = Gecode::Raw::bab(selected_space, options)
+      bab = Gecode::Raw::BAB.new(selected_space, options)
+      
+      result = nil
+      previous_solution = nil
+      until (previous_solution = bab.next).nil?
+        result = previous_solution
+      end
+      @statistics = bab.statistics
       
       # Reset the method used constrain calls and return the result.
       Model.constrain_proc = nil

data/lib/gecoder/version.rb

@@ -1,4 +1,4 @@
 module GecodeR
   # A string representation of the Gecode/R version.
-  VERSION = '0.8.1'
+  VERSION = '0.8.2'
 end