gecoder 0.7.0 → 0.7.1

data/CHANGES

@@ -1,3 +1,9 @@
+== Version 0.7.1
+This release adds boolean linear constraints.
+
+* Set domain constraints now checks illegal parameters when it's added (rather than when the search begins).
+* Added boolean linear constraint.
+
 == Version 0.7.0
 This release adds the set selection and operation constraints.
 

data/README

@@ -33,7 +33,7 @@ instructions.
 generated on (replace the extension in the following commands with whatever 
 extension it's given).
 
-	cd ext
+  cd ext
   ruby extconf.rb
   make
   mv gecode.so ../lib/

data/example/square_tiling.rb

@@ -0,0 +1,84 @@
+require File.dirname(__FILE__) + '/example_helper'
+
+# Solves the square tiling problem. The objective is to pack supplied squares 
+# into a bigger rectangle so that there is no overlap.
+class SquareTiling < Gecode::Model
+  # Takes the width and height of the rectangle to pack the squares into. Then
+  # the sizes of the squares that should be packed into the rectangle. The sizes
+  # must be sorted.
+  def initialize(width, height, square_sizes)
+    @sizes = square_sizes
+    @square_count = @sizes.size
+    
+    # The coordinates of the placed squares.
+    @xs = int_var_array(@square_count, 0..(width - @sizes.min))
+    @ys = int_var_array(@square_count, 0..(height - @sizes.min))
+    
+    # The essential constraints of the problem.
+    @square_count.times do |i|
+      # Each square must be placed within the bounds
+      @xs[i].must <= width - @sizes[i]
+      @ys[i].must <= height - @sizes[i]
+      
+      # Pairwise conditions, no pair of squares may overlap.
+      0.upto(i - 1) do |j|
+        # That the two squares don't overlap means that i is left of j, 
+        # or j is left of i, or i is above j, or j is above i.
+        ((@xs[j] - @xs[i]).must >= @sizes[i]) | 
+          ((@xs[i] - @xs[j]).must >= @sizes[j]) | 
+          ((@ys[j] - @ys[i]).must >= @sizes[i]) | 
+          ((@ys[i] - @ys[j]).must >= @sizes[j])
+      end
+    end
+    
+    # A couple of implied constraints that only serve to make the solving 
+    # faster:
+
+    # The combined size of all squares occupying a column must be equal to the 
+    # total height.
+    occupied_length_must_equal_total_length(height, width, @xs)
+    # The combined size of all squares occupying a row must be equal to the 
+    # total width.
+    occupied_length_must_equal_total_length(width, height, @ys)
+
+    # Symmetry-breaking constraint: Order squares of the same size.
+    @square_count.times do |i|
+      @xs[i].must <= @xs[i+1] if @sizes[i] == @sizes[i+1]
+    end
+
+    # Place the squares left to right on the x-axis first, then the y-axis.
+    branch_on @xs, :variable => :smallest_min, :value => :min
+    branch_on @ys, :variable => :smallest_min, :value => :min
+  end
+  
+  # Constrains the combined length of the squares in the same row or column to
+  # equal +total_length+ in the axis of the specified coordinates +coords+, 
+  # which is +axist_length+ long.
+  def occupied_length_must_equal_total_length(total_length, axis_length, coords)
+    axis_length.times do |i|
+      # We create an array of boolean variables and constrain it so that element
+      # +j+ is true iff square +j+ occupies +i+ (+i+ being a row or column).
+      occupied = bool_var_array(@square_count)
+      occupied.each_with_index do |is_occupying, j|
+        coords[j].must_be.in((i - @sizes[j] + 1)..i, :reify => is_occupying)
+      end
+      
+      # Constrain the combined length of squares that are occupying +i+ to equal
+      # the total length. We multiply the sizes with the boolean variables 
+      # since a boolean in linear equation is 0 if assigned false and 1 if 
+      # assigned true. Hence we will mask out the sizes of any squares not in 
+      # +i+.
+      occupied_sizes = occupied.zip(@sizes).map{ |bool, size| bool*size }
+      occupied_sizes.inject(0){ |sum, x| x + sum }.must.equal(total_length, 
+        :strength => :domain)
+    end
+  end
+  
+  # Displays the corrdinates of the squares.
+  # TODO: Something more impressive. 
+  def to_s
+    @xs.values.zip(@ys.values).map{ |x,y| "(#{x}, #{y})"}.join(', ')
+  end
+end
+
+puts(SquareTiling.new(65, 47, [25, 24, 23, 22, 19, 17, 11, 6, 5, 3]).solve! || 'Failed').to_s		

data/example/sudoku-set.rb

@@ -0,0 +1,107 @@
+require File.dirname(__FILE__) + '/example_helper'
+require 'enumerator'
+
+# Solves the sudoku problem using sets. The model used is a fairly direct 
+# translation of the corresponding Gecode example: 
+# http://www.gecode.org/gecode-doc-latest/sudoku-set_8cc-source.html .
+class SudokuSet < Gecode::Model
+  # Takes a 9x9 matrix of values in the initial sudoku, 0 if the square is 
+  # empty. 
+  def initialize(predefined_values)
+    unless predefined_values.column_size == 9 and 
+        predefined_values.row_size == 9
+      raise ArgumentError, 'The matrix with predefined values must have ' +
+        'dimensions 9x9.'
+    end
+    
+    @size = n = predefined_values.row_size
+    sub_matrix_size = Math.sqrt(n).round
+    
+    # Create one set per assignable number (i.e. 1..9). Each set contains the 
+    # position of all squares that the number is located in. The squares are 
+    # given numbers from 1 to 81. Each set therefore has an empty lower bound 
+    # (since we have no guarantees where a number will end up) and 1..81 as 
+    # upper bound (as it may potentially occurr in any square). We know that
+    # each assignable number must occurr 9 times in a solved sudoku, so we 
+    # set the cardinality to 9..9 .
+    @sets = set_var_array(n, [], 1..n*n, n..n)
+    predefined_values.row_size.times do |i|
+      predefined_values.column_size.times do |j|
+        unless predefined_values[i,j].zero?
+          # We add the constraint that the square position must occurr in the 
+          # set corresponding to the predefined value.
+          @sets[predefined_values[i,j] - 1].must_be.superset_of [i*n + j+1]
+        end
+      end
+    end
+
+    # Build arrays containing the square positions of each row and column.
+    rows = []
+    columns = []
+    n.times do |i|
+      rows << ((i*n + 1)..(i*n + 9))
+      columns << [1, 10, 19, 28, 37, 46, 55, 64, 73].map{ |e| e + i }
+    end
+    
+    # Build arrays containing the square positions of each block.
+    blocks = []
+    sub_matrix_size.times do |i|
+      sub_matrix_size.times do |j|
+        blocks << [1, 2, 3, 10, 11, 12, 19, 20, 21].map{ |e| e + (j*27)+(i*3) }
+      end
+    end
+    
+    # All sets must be pairwise disjoint since two numbers can't be assigned to
+    # the same square.
+    n.times do |i|
+      (i + 1).upto(n - 1) do |j|
+        @sets[i].must_be.disjoint_with @sets[j]
+      end
+    end
+    # The above implies that the sets must be distinct (since cardinality 0 is
+    # not allowed), but we also explicitly add the distinctness constraint.
+    @sets.must_be.distinct(:size => n)
+
+    # The sets must intersect in exactly one element with each row column and
+    # block. I.e. an assignable number must be assigned exactly once in each
+    # row, column and block. We specify the constraint by expressing that the 
+    # intersection must be equal with a set variable with cardinality 1.
+    @sets.each do |set|
+      rows.each do |row|
+        set.intersection(row).must == set_var([], 1..n*n, 1..1)
+      end
+      columns.each do |column|
+        set.intersection(column).must == set_var([], 1..n*n, 1..1)
+      end
+      blocks.each do |block|
+        set.intersection(block).must == set_var([], 1..n*n, 1..1)
+      end
+    end
+
+    # Branching.
+    branch_on @sets, :variable => :none, :value => :min
+  end
+  
+  # Outputs the assigned numbers in a grid.
+  def to_s
+    squares = []
+    @sets.values.each_with_index do |positions, i|
+      positions.each{ |square_position| squares[square_position - 1] = i + 1 }
+    end
+    squares.enum_slice(@size).map{ |slice| slice.join(' ') }.join("\n")
+  end
+end
+
+predefined_squares = Matrix[
+  [0,0,0, 2,0,5, 0,0,0],
+  [0,9,0, 0,0,0, 7,3,0],
+  [0,0,2, 0,0,9, 0,6,0],
+    
+  [2,0,0, 0,0,0, 4,0,9],
+  [0,0,0, 0,7,0, 0,0,0],
+  [6,0,9, 0,0,0, 0,0,1],
+      
+  [0,8,0, 4,0,0, 1,0,0],
+  [0,6,3, 0,0,0, 0,8,0],
+  [0,0,0, 6,0,8, 0,0,0]]
+puts(SudokuSet.new(predefined_squares).solve! || 'Failed').to_s

data/example/sudoku.rb

@@ -1,4 +1,5 @@
 require File.dirname(__FILE__) + '/example_helper'
+require 'enumerator'
 
 # Solves the sudoku problem: http://en.wikipedia.org/wiki/Soduko
 class Sudoku < Gecode::Model
@@ -41,12 +42,7 @@ class Sudoku < Gecode::Model
   
   # Display the solved sudoku in a grid.  
   def to_s
-    separator = '+' << '-' * (3 * @size + (@size - 1)) << "+\n"
-    res = (0...@size).inject(separator) do |s, i|
-      (0...@size).inject(s + '|') do |s, j|
-        s << " #{@squares[i,j].value} |"
-      end << "\n" << separator
-    end
+    @squares.values.enum_slice(@size).map{ |slice| slice.join(' ') }.join("\n")
   end
 end
 

data/lib/gecoder/bindings.rb

@@ -5,7 +5,7 @@ module Gecode
   
   # Describes a layer that delegates to GecodeRaw only after having logged the 
   # call.
-  module LoggingLayer
+  module LoggingLayer #:nodoc:
     require 'logger'
   
     def self.method_missing(name, *args)

data/lib/gecoder/bindings/bindings.rb

@@ -518,6 +518,26 @@ Rust::Bindings::create_bindings Rust::Bindings::LangCxx, "gecode" do |b|
         method.add_parameter "bool", "share"
         method.add_parameter "Gecode::BoolVar", "x"
       end
+      
+      klass.add_operator "+", "Gecode::MiniModel::LinExpr" do |operator|
+        operator.add_parameter("int", "i")
+      end
+      
+      klass.add_operator "-", "Gecode::MiniModel::LinExpr" do |operator|
+        operator.add_parameter("int", "i")
+      end
+      
+      klass.add_operator "*", "Gecode::MiniModel::LinExpr" do |operator|
+        operator.add_parameter("int", "i")
+      end
+      
+      klass.add_operator "!=", "Gecode::MiniModel::LinRel", "different" do |operator|
+        operator.add_parameter("Gecode::IntVar", "other")
+      end
+      
+      klass.add_operator "==", "Gecode::MiniModel::LinRel", "equal" do |operator|
+        operator.add_parameter("Gecode::IntVar", "other")
+      end
     end
     
     ns.add_cxx_class "SetVar" do |klass|

data/lib/gecoder/interface/binding_changes.rb

@@ -6,7 +6,7 @@
 #
 # This layer should be moved to the C++ side instead when possible for better
 # performance.
-module GecodeRaw
+module GecodeRaw #:nodoc: all
   class Space
     # Creates the specified number of integer variables in the space with the
     # specified domain. Returns the indices with which they can then be 
@@ -93,7 +93,7 @@ end
 
 module Gecode
   # Various utility (mainly used to change the behavior of the raw bindings).
-  module Util
+  module Util #:nodoc: all
     # Provides common methods to the variable stores. The stores must provide
     # @next_index, @var_array, @size, ARRAY_IDENTIFIER and #new_storage_array .
     module VarStoreMethods

data/lib/gecoder/interface/branch.rb

@@ -1,52 +1,5 @@
 module Gecode
   class Model
-    private
-    
-    # Maps the names of the supported variable branch strategies for integer and
-    # booleans to the corresponding constant in Gecode. 
-    BRANCH_INT_VAR_CONSTANTS = {
-      :none                 => Gecode::Raw::BVAR_NONE,
-      :smallest_min         => Gecode::Raw::BVAR_MIN_MIN,
-      :largest_min          => Gecode::Raw::BVAR_MIN_MAX, 
-      :smallest_max         => Gecode::Raw::BVAR_MAX_MIN, 
-      :largest_max          => Gecode::Raw::BVAR_MAX_MAX, 
-      :smallest_size        => Gecode::Raw::BVAR_SIZE_MIN, 
-      :largest_size         => Gecode::Raw::BVAR_SIZE_MAX,
-      :smallest_degree      => Gecode::Raw::BVAR_DEGREE_MIN, 
-      :largest_degree       => Gecode::Raw::BVAR_DEGREE_MAX, 
-      :smallest_min_regret  => Gecode::Raw::BVAR_REGRET_MIN_MIN,
-      :largest_min_regret   => Gecode::Raw::BVAR_REGRET_MIN_MAX,
-      :smallest_max_regret  => Gecode::Raw::BVAR_REGRET_MAX_MIN, 
-      :largest_max_regret   => Gecode::Raw::BVAR_REGRET_MAX_MAX
-    }
-    # Maps the names of the supported variable branch strategies for sets to 
-    # the corresponding constant in Gecode. 
-    BRANCH_SET_VAR_CONSTANTS = {
-      :none                 => Gecode::Raw::SETBVAR_NONE,
-      :smallest_cardinality => Gecode::Raw::SETBVAR_MIN_CARD,
-      :largest_cardinality  => Gecode::Raw::SETBVAR_MAX_CARD, 
-      :smallest_unknown     => Gecode::Raw::SETBVAR_MIN_UNKNOWN_ELEM, 
-      :largest_unknown      => Gecode::Raw::SETBVAR_MAX_UNKNOWN_ELEM
-    }
-    
-    # Maps the names of the supported value branch strategies for integers and
-    # booleans to the corresponding constant in Gecode. 
-    BRANCH_INT_VALUE_CONSTANTS = {
-      :min        => Gecode::Raw::BVAL_MIN,
-      :med        => Gecode::Raw::BVAL_MED,
-      :max        => Gecode::Raw::BVAL_MAX,
-      :split_min  => Gecode::Raw::BVAL_SPLIT_MIN,
-      :split_max  => Gecode::Raw::BVAL_SPLIT_MAX
-    }
-    # Maps the names of the supported value branch strategies for sets to the 
-    # corresponding constant in Gecode. 
-    BRANCH_SET_VALUE_CONSTANTS = {
-      :min  => Gecode::Raw::SETBVAL_MIN,
-      :max  => Gecode::Raw::SETBVAL_MAX
-    }
-    
-    public
-  
     # Specifies which variables that should be branched on. One can optionally
     # also select which of the variables that should be used first with the
     # :variable option and which value in that variable's domain that should be 
@@ -111,11 +64,11 @@ module Gecode
     def branch_on(variables, options = {})
       if variables.respond_to? :to_int_var_array or 
           variables.respond_to? :to_bool_var_array
-        add_branch(variables, options, BRANCH_INT_VAR_CONSTANTS, 
-          BRANCH_INT_VALUE_CONSTANTS)
+        add_branch(variables, options, Constants::BRANCH_INT_VAR_CONSTANTS, 
+          Constants::BRANCH_INT_VALUE_CONSTANTS)
       elsif variables.respond_to? :to_set_var_array
-        add_branch(variables, options, BRANCH_SET_VAR_CONSTANTS, 
-          BRANCH_SET_VALUE_CONSTANTS)
+        add_branch(variables, options, Constants::BRANCH_SET_VAR_CONSTANTS, 
+          Constants::BRANCH_SET_VALUE_CONSTANTS)
       else
         raise TypeError, "Unknown type of variable enum #{variables.class}."
       end
@@ -123,6 +76,52 @@ module Gecode
     
     private
     
+    # This is a hack to get RDoc to ignore the constants.
+    module Constants #:nodoc:
+      # Maps the names of the supported variable branch strategies for integer and
+      # booleans to the corresponding constant in Gecode. 
+      BRANCH_INT_VAR_CONSTANTS = {
+        :none                 => Gecode::Raw::BVAR_NONE,
+        :smallest_min         => Gecode::Raw::BVAR_MIN_MIN,
+        :largest_min          => Gecode::Raw::BVAR_MIN_MAX, 
+        :smallest_max         => Gecode::Raw::BVAR_MAX_MIN, 
+        :largest_max          => Gecode::Raw::BVAR_MAX_MAX, 
+        :smallest_size        => Gecode::Raw::BVAR_SIZE_MIN, 
+        :largest_size         => Gecode::Raw::BVAR_SIZE_MAX,
+        :smallest_degree      => Gecode::Raw::BVAR_DEGREE_MIN, 
+        :largest_degree       => Gecode::Raw::BVAR_DEGREE_MAX, 
+        :smallest_min_regret  => Gecode::Raw::BVAR_REGRET_MIN_MIN,
+        :largest_min_regret   => Gecode::Raw::BVAR_REGRET_MIN_MAX,
+        :smallest_max_regret  => Gecode::Raw::BVAR_REGRET_MAX_MIN, 
+        :largest_max_regret   => Gecode::Raw::BVAR_REGRET_MAX_MAX
+      }
+      # Maps the names of the supported variable branch strategies for sets to 
+      # the corresponding constant in Gecode. 
+      BRANCH_SET_VAR_CONSTANTS = { #:nodoc:
+        :none                 => Gecode::Raw::SETBVAR_NONE,
+        :smallest_cardinality => Gecode::Raw::SETBVAR_MIN_CARD,
+        :largest_cardinality  => Gecode::Raw::SETBVAR_MAX_CARD, 
+        :smallest_unknown     => Gecode::Raw::SETBVAR_MIN_UNKNOWN_ELEM, 
+        :largest_unknown      => Gecode::Raw::SETBVAR_MAX_UNKNOWN_ELEM
+      }
+      
+      # Maps the names of the supported value branch strategies for integers and
+      # booleans to the corresponding constant in Gecode. 
+      BRANCH_INT_VALUE_CONSTANTS = { #:nodoc:
+        :min        => Gecode::Raw::BVAL_MIN,
+        :med        => Gecode::Raw::BVAL_MED,
+        :max        => Gecode::Raw::BVAL_MAX,
+        :split_min  => Gecode::Raw::BVAL_SPLIT_MIN,
+        :split_max  => Gecode::Raw::BVAL_SPLIT_MAX
+      }
+      # Maps the names of the supported value branch strategies for sets to the 
+      # corresponding constant in Gecode. 
+      BRANCH_SET_VALUE_CONSTANTS = { #:nodoc:
+        :min  => Gecode::Raw::SETBVAL_MIN,
+        :max  => Gecode::Raw::SETBVAL_MAX
+      }
+    end
+    
     # Adds a branching selection for the specified variable with the specified
     # options. The hashes are used to decode the options into Gecode's 
     # constants.

data/lib/gecoder/interface/constraints.rb

@@ -10,15 +10,15 @@ module Gecode
     # as left hand sides (i.e. the part before must*) when specifying 
     # constraints. Assumes that a method #expression is defined which produces
     # a new expression given the current constraint parameters.
-    module LeftHandSideMethods
-      # Specifies that a constraint must hold for the integer variable enum.
+    module LeftHandSideMethods #:nodoc:
+      # Specifies that a constraint must hold for the keft hand side.
       def must
         expression update_params(:negate => false)
       end
       alias_method :must_be, :must
       
-      # Specifies that the negation of a constraint must hold for the integer 
-      # variable.
+      # Specifies that the negation of a constraint must hold for the left hand 
+      # side.
       def must_not
         expression update_params(:negate => true)
       end
@@ -34,7 +34,7 @@ module Gecode
     end
     
     # A module that provides some utility-methods for constraints.
-    module Util
+    module Util #:nodoc:
       # Maps the name used in options to the value used in Gecode for 
       # propagation strengths.
       PROPAGATION_STRENGTHS = {
@@ -193,7 +193,7 @@ module Gecode
     # 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.
-    class Expression
+    class Expression #:nodoc:
       # Constructs a new expression with the specified parameters. The 
       # parameters shoud at least contain the keys :lhs, and :negate.
       #
@@ -235,7 +235,7 @@ module Gecode
     
     # A composite expression which is a expression with a left hand side 
     # resulting from a previous constraint.
-    class CompositeExpression < Gecode::Constraints::Expression
+    class CompositeExpression < Gecode::Constraints::Expression #:nodoc:
       # The expression class should be the class of the expression delegated to,
       # the variable class the kind of single variable used in the expression.
       # The new var proc should produce a new variable (of the appropriate type)
@@ -300,7 +300,7 @@ module Gecode
     # 
     # The call of with_offsets initiates the constraint as a stub, even though
     # must has not yet been called.
-    class ExpressionStub
+    class ExpressionStub #:nodoc:
       # Constructs a new expression with the specified parameters.
       def initialize(model, params)
         @model = model
@@ -311,7 +311,7 @@ module Gecode
     # Describes an expression stub which includes left hand side methods and
     # just sends models and parameters through a supplied block to construct the
     # resulting expression.
-    class SimpleExpressionStub < ExpressionStub
+    class SimpleExpressionStub < ExpressionStub #:nodoc:
       include Gecode::Constraints::LeftHandSideMethods
     
       # The block provided is executed when the expression demanded by the left
@@ -342,7 +342,7 @@ module Gecode
     # ".must > rhs" 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::ExpressionStub
+    class CompositeStub < Gecode::Constraints::ExpressionStub #:nodoc:
       include Gecode::Constraints::LeftHandSideMethods
       
       # The composite expression class should be the class that the stub uses