gecoder 0.8.3 → 0.9.0

data/CHANGES

@@ -1,3 +1,18 @@
+== Version 0.9.0
+This release adds a generous amount of sugar designed to cut down on often 
+repeated code. It also adds the ability to freely combine constraints
+without needing temporary variables.
+
+* Variables that should be accessible from outside the model can now easily be created by calling "<variable_name>_is_a <variable>" where "<variable_name>" is the desired name of the variable and "<variable>" is the variable (e.g. "int_var(17)"). Take a look at the examples to see it in action.
+* Gecode.solve, Gecode.maximize and Gecode.minimize can now be used to solve a problem without first having to explicitly create a class for the model.
+* An exception (Gecode::NoSolutionError) is now thrown if a solution can not be found when using Model#solve!, Model#minimize!, Model#maximize! and Model#optimize! (rather than returning nil). This change breaks backwards compatibility. If you feel that this is a bad change then please tell the mailing list.
+* The offset option to the distinct constraint is now given as "int_enum.must_be.distinct(:offset => offsets)" rather than the previous "int_enum.with_offsets(offsets).must_be.distinct".
+* Complex combinations of several constraints such as "(set1.size + set2.size).must > int.abs - 3" can now be used. The underlying code has been changed quite a bit, but it should remain backwards compatible except for above mentioned exception. The change also brings about some changed terminology, which mostly aims to remove the concept of "composite constraints" and replace them with the more general "operands" (see the documentation for further details).
+* [#21578] Fixed a bug that caused options given to the boolean "false" domain constraint to not be processed.
+* [#21579] Fixed a bug that caused the integer enumeration equality constraint to not work at all (threw an exception).
+* [#21580] Fixed a bug that caused ranges that use three dots to not be correctly interpreted by the negated integer domain constraint.
+* [#21581] Fixed a bug that caused the abs constraint to prune away valid solutions in some cases.
+
 == Version 0.8.3 
 This release adds regular expression constraints, the last channel
 constraint and various minor convenience improvements. It also fixes a

data/README

@@ -1,9 +1,13 @@
-== Gecode/R
+= Gecode/R
+
+Website: http://gecoder.org
 
 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.
 
+See Gecode::Model to get started.
+
 == Warning
 
 Gecode/R is still in a development stage, the syntax is by no means final
@@ -47,7 +51,7 @@ extension it's given).
   make
   mv gecode.so ../lib/
 
-== Running the tests
+=== Running the tests
 
   rake specs
 

data/example/equation_system.rb

@@ -0,0 +1,15 @@
+require File.dirname(__FILE__) + '/example_helper'
+
+class EquationProblem < Gecode::Model
+  def initialize
+    x, y, z = vars_is_an int_var_array(3, 0..9)
+
+    (x + y).must == z
+    x.must == y - 3
+
+    branch_on vars
+  end
+end
+
+puts 'x y z'
+puts EquationProblem.new.solve!.vars.values.join(' ')

data/example/magic_sequence.rb

@@ -6,10 +6,10 @@ class MagicSequence < Gecode::Model
   def initialize(n)
     # The i:th variable represents the value of the i:th element in the 
     # sequence.
-    @sequence = int_var_array(n, 0...n)
+    sequence_is_an int_var_array(n, 0...n)
     
     # The basic requirement to qualify as a magic sequence.
-    n.times{ |i| @sequence.count(i).must == @sequence[i] }
+    n.times{ |i| sequence.count(i).must == sequence[i] }
   
     # The following are implied constraints. They do not affect which 
     # assignments are solutions, but they do help prune the search space 
@@ -18,18 +18,18 @@ class MagicSequence < Gecode::Model
     # The sum must be n. This follows from that there are exactly n elements and
     # that the sum of all elements are the number of occurrences in total, i.e. 
     # the number of elements.
-    @sequence.sum.must == n
+    sequence.sum.must == n
     
     # sum(seq[i] * (i-1)) must equal 0 because sum(seq[i]) = n as seen above
     # and sum(i*seq[i]) is just another way to compute sum(seq[i]). So we get 
     # sum(seq[i] * (i-1)) = sum(seq[i]) - sum(i*seq[i]) = n - n = 0
-    @sequence.zip((-1...n).to_a).map{ |element, c| element*c }.sum.must == 0
+    sequence.zip((-1...n).to_a).map{ |element, c| element*c }.sum.must == 0
     
-    branch_on @sequence, :variable => :smallest_degree, :value => :split_max
+    branch_on sequence, :variable => :smallest_degree, :value => :split_max
   end
   
   def to_s
-    @sequence.values.join(', ')
+    sequence.values.join(', ')
   end
 end
 
@@ -40,4 +40,4 @@ class Array
   end
 end
 
-puts((MagicSequence.new(500).solve! || 'Failed').to_s)
+puts MagicSequence.new(500).solve!.to_s

data/example/money.rb

@@ -0,0 +1,36 @@
+require 'rubygems'
+require 'gecoder'
+
+solution = Gecode.solve do
+  # A helper to make the linear equation a bit tidier. Takes a number of
+  # variables and computes the linear combination as if the variable
+  # were digits in a base 10 number. E.g. x,y,z becomes
+  # 100*x + 10*y + z .
+  def equation_row(*variables)
+    variables.inject{ |result, variable| variable + result*10 }
+  end
+
+  # Set up the variables. 
+  # Let "letters" be an array of 8 integer variables with domain 0..9.
+  # The elements represents the letters s, e, n, d, m, o, r and y.
+  letters_is_an int_var_array(8, 0..9)
+  s,e,n,d,m,o,r,y = letters
+
+  # Set up the constraints.
+  # The equation must hold.
+  (equation_row(s, e, n, d) + equation_row(m, o, r, e)).must ==
+    equation_row(m, o, n, e, y)
+
+  # The initial letters may not be 0.
+  s.must_not == 0
+  m.must_not == 0
+
+  # All letters must be assigned different digits.
+  letters.must_be.distinct
+
+  # Tell Gecode what variables we want to know the values of.
+  branch_on letters, :variable => :smallest_size, :value => :min
+end
+
+puts 's e n d m o r y'
+puts solution.letters.values.join(' ')

data/example/queens.rb

@@ -9,23 +9,23 @@ class NQueens < Gecode::Model
     # The row number that the queen in the i:th column has. By using this as
     # our variables we already make sure that no two queens are in the same
     # column.
-    @queen_rows = int_var_array(n, 0...n)
+    queen_rows_is_an int_var_array(n, 0...n)
     
     # Set up the constraints
     # Queens must not be in the same diagonal (negative slope).
-    @queen_rows.with_offsets((0...n).to_a).must_be.distinct
+    queen_rows.must_be.distinct(:offsets => (0...n).to_a)
     # Queens must not be in the same diagonal (positive slope).
-    @queen_rows.with_offsets((0...n).to_a.reverse).must_be.distinct
+    queen_rows.must_be.distinct(:offsets => (0...n).to_a.reverse)
     # Queens must not be in the same row.
-    @queen_rows.must_be.distinct
+    queen_rows.must_be.distinct
     
     # Branching, we use first-fail heuristic.
-    branch_on @queen_rows, :variable => :smallest_size, :value => :min
+    branch_on queen_rows, :variable => :smallest_size, :value => :min
   end
   
   # Displays the assignment as a chessboard with queens denoted by 'x'.
   def to_s
-    rows = @queen_rows.values
+    rows = queen_rows.values
   
     separator = '+' << '-' * (3 * @size + (@size - 1)) << "+\n"
     res = (0...@size).inject(separator) do |s, i|
@@ -39,5 +39,4 @@ end
 # Print the first solution. Note that there are 92 solutions, but only 12 
 # are rotationally distinct. For any serious use one should place additional
 # constraints to eliminate those symmetries.
-NQueens.new( (ARGV[0] || 8).to_i ).solution{ |sol| puts sol.to_s }
-
+puts NQueens.new((ARGV[0] || 8).to_i).solve!.to_s

data/example/send_most_money.rb

@@ -55,4 +55,4 @@ solution = SendMoreMoney.new.optimize! do |model, best_so_far|
   model.money.to_number.must > best_so_far.money.values.to_number
 end
 puts solution.to_s
-puts "money: #{solution.money.values.to_number}"
+puts "money: #{solution.money.values.to_number}"

data/example/square_tiling.rb

@@ -74,11 +74,11 @@ class SquareTiling < Gecode::Model
     end
   end
   
-  # Displays the corrdinates of the squares.
+  # Displays the coordinates 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		
+puts SquareTiling.new(65, 47, [25, 24, 23, 22, 19, 17, 11, 6, 5, 3]).solve!.to_s

data/example/sudoku-set.rb

@@ -23,13 +23,13 @@ class SudokuSet < Gecode::Model
     # 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)
+    sets_is_an 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]
+          sets[predefined_values[i,j] - 1].must_be.superset_of [i*n + j+1]
         end
       end
     end
@@ -58,34 +58,33 @@ class SudokuSet < Gecode::Model
     # the same square.
     n.times do |i|
       (i + 1).upto(n - 1) do |j|
-        @sets[i].must_be.disjoint_with @sets[j]
+        sets[i].must_be.disjoint_with sets[j]
       end
     end
 
     # 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|
+    # row, column and block. 
+    sets.each do |set|
       rows.each do |row|
-        set.intersection(row).must == set_var([], 1..n*n, 1..1)
+        set.intersection(row).size.must == 1
       end
       columns.each do |column|
-        set.intersection(column).must == set_var([], 1..n*n, 1..1)
+        set.intersection(column).size.must == 1
       end
       blocks.each do |block|
-        set.intersection(block).must == set_var([], 1..n*n, 1..1)
+        set.intersection(block).size.must == 1
       end
     end
 
     # Branching.
-    branch_on @sets, :variable => :none, :value => :min
+    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|
+    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")
@@ -104,4 +103,4 @@ predefined_squares = Matrix[
   [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
+puts SudokuSet.new(predefined_squares).solve!.to_s

data/example/sudoku.rb

@@ -2,51 +2,9 @@ require File.dirname(__FILE__) + '/example_helper'
 require 'enumerator'
 
 # Solves the sudoku problem: http://en.wikipedia.org/wiki/Soduko
-class Sudoku < Gecode::Model
-  # Takes a matrix of values in the initial sudoku, 0 if the square is empty. 
-  # The matrix must be square with a square size. 
-  def initialize(values)
-    # Verify that the input is of a valid size.
-    @size = n = values.row_size
-    sub_matrix_size = Math.sqrt(n).round
-    unless values.square? and sub_matrix_size**2 == n
-      raise ArgumentError, 'Incorrect value matrix size.'
-    end
-    sub_count = sub_matrix_size
-    
-    # Create the squares and initialize them.
-    @squares = int_var_matrix(n, n, 1..n)
-    values.row_size.times do |i|
-      values.column_size.times do |j|
-        @squares[i,j].must == values[i,j] unless values[i,j] == 0
-      end
-    end
-    
-    # Constraints.
-    n.times do |i|
-      # All rows must contain distinct numbers.
-      @squares.row(i).must_be.distinct(:strength => :domain)
-      # All columns must contain distinct numbers.
-      @squares.column(i).must_be.distinct(:strength => :domain)
-      # All sub-matrices must contain distinct numbers.
-      @squares.minor(
-        (i % sub_count) * sub_matrix_size, 
-        sub_matrix_size, 
-        (i / sub_count) * sub_matrix_size, 
-        sub_matrix_size).must_be.distinct(:strength => :domain)
-    end
-    
-    # Branching, we use first-fail heuristic.
-    branch_on @squares, :variable => :smallest_size, :value => :min
-  end
-  
-  # Display the solved sudoku in a grid.  
-  def to_s
-    @squares.values.enum_slice(@size).map{ |slice| slice.join(' ') }.join("\n")
-  end
-end
 
-given_squares = Matrix[
+# The sudoku we want to solve (0 represents that the square is empty).
+sudoku = 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],
@@ -58,4 +16,41 @@ given_squares = Matrix[
   [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 Sudoku.new(given_squares).solve!.to_s
+
+solution = Gecode.solve do
+  # Verify that the input is of a valid size.
+  @size = n = sudoku.row_size
+  sub_matrix_size = Math.sqrt(n).round
+  unless sudoku.square? and sub_matrix_size**2 == n
+    raise ArgumentError, 'Incorrect value matrix size.'
+  end
+  sub_count = sub_matrix_size
+    
+  # Create the squares and initialize them.
+  squares_is_an int_var_matrix(n, n, 1..n)
+  sudoku.row_size.times do |i|
+    sudoku.column_size.times do |j|
+      squares[i,j].must == sudoku[i,j] unless sudoku[i,j] == 0
+    end
+  end
+  
+  # Constraints.
+  n.times do |i|
+    # All rows must contain distinct numbers.
+    squares.row(i).must_be.distinct(:strength => :domain)
+    # All columns must contain distinct numbers.
+    squares.column(i).must_be.distinct(:strength => :domain)
+    # All sub-matrices must contain distinct numbers.
+    squares.minor(
+      (i % sub_count) * sub_matrix_size, 
+      sub_matrix_size, 
+      (i / sub_count) * sub_matrix_size, 
+      sub_matrix_size).must_be.distinct(:strength => :domain)
+  end
+  
+  # Branching, we use first-fail heuristic.
+  branch_on squares, :variable => :smallest_size, :value => :min
+end.squares.values
+
+# Output the solved sudoku in a grid.
+puts solution.enum_slice(sudoku.row_size).map{ |slice| slice.join(' ') }.join($/)

data/lib/gecoder/bindings.rb

@@ -1,3 +1,45 @@
+# Problems can be formulated and solved either through defining a new
+# class that inherits from Gecode::Model or by using Gecode#solve et al.
+# Gecode::Model describes how to formulate problems.
+#
+# ==== Examples 
+#
+# The following two examples show how to solve the following equation 
+# system, using both ways to define and solve a problem.
+#
+# Equation system:
+#   x + y = z
+#   x = y - 3
+#   0 <= x,y,z <= 9
+#
+# === Inheriting from Gecode::Model
+#
+#   class EquationProblem < Gecode::Model
+#     def initialize
+#       variables_is_an int_var_array(3, 0..9)
+#       x, y, z = variables
+#
+#       (x + y).must == z
+#       x.must == y - 3
+#
+#       branch_on variables
+#     end
+#   end
+#   puts EquationProblem.new.solve!.variables.join(' ')
+#
+# === Using Gecode#solve
+#
+#   solution = Gecode.solve do
+#     variables_is_an int_var_array(3, 0..9)
+#     x, y, z = variables
+#
+#     (x + y).must == z
+#     x.must == y - 3
+#
+#     branch_on variables
+#   end
+#   puts solution.variables.values.join(' ')
+# 
 module Gecode
   # Loads the binding libraries. This is done as a method in order to be easier
   # to test. 

data/lib/gecoder/bindings/bindings.rb

@@ -735,6 +735,11 @@ Rust::Bindings::create_bindings Rust::Bindings::LangCxx, "gecode" do |b|
       ['Gecode::IntVar', 'Gecode::BoolVar'].each do |template_type|
         minimodelns.add_cxx_class "LinExpr<#{template_type}>" do |klass|
           klass.add_constructor
+
+          klass.add_constructor do |method|
+            method.add_parameter "#{template_type}&", "x"
+            method.add_parameter "int", "a", true
+          end
         
           klass.add_method "post" do |method|
             method.add_parameter "Gecode::MSpace *", "home"
@@ -1175,6 +1180,7 @@ Rust::Bindings::create_bindings Rust::Bindings::LangCxx, "gecode" do |b|
       func.add_parameter "Gecode::IntVar", "y0"
       func.add_parameter "Gecode::IntVar", "y1"
       func.add_parameter "Gecode::IntConLevel", "icl"
+      func.add_parameter "Gecode::PropKind", "pk"
     end
     
     ns.add_function "linear", "void" do |func|
@@ -1377,6 +1383,16 @@ Rust::Bindings::create_bindings Rust::Bindings::LangCxx, "gecode" do |b|
       func.add_parameter "Gecode::IntConLevel", "icl"
       func.add_parameter "Gecode::PropKind", "pk"
     end
+
+    ns.add_function "rel" do |func|
+      func.add_parameter "Gecode::MSpace*", "home"
+      func.add_parameter "Gecode::MIntVarArray *", "x" do |param|
+        param.custom_conversion = "*ruby2Gecode_MIntVarArrayPtr(argv[1], 2)->ptr()"
+      end
+      func.add_parameter "Gecode::IntRelType", "r"
+      func.add_parameter "Gecode::IntConLevel", "icl"
+      func.add_parameter "Gecode::PropKind", "pk"
+    end
     
     ns.add_function "rel" do |func|
       func.add_parameter "Gecode::MSpace*", "home"

data/lib/gecoder/interface.rb

@@ -1,8 +1,9 @@
 require 'gecoder/interface/binding_changes'
-require 'gecoder/interface/variables'
 require 'gecoder/interface/enum_matrix'
 require 'gecoder/interface/model'
 require 'gecoder/interface/search'
 require 'gecoder/interface/constraints'
+require 'gecoder/interface/variables'
 require 'gecoder/interface/enum_wrapper'
 require 'gecoder/interface/branch'
+require 'gecoder/interface/model_sugar'