gecoder-with-gecode 0.7.1

data/README

@@ -0,0 +1,45 @@
+== Gecode/R
+
+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 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
+
+Gecode/R requires Gecode 1.3.1, which can be downloaded from 
+http://www.gecode.org/download.html . See 
+http://www.gecode.org/gecode-doc-latest/PageComp.html for the installation
+instructions.
+
+=== Installing from gem
+
+  gem install gecoder
+
+=== Installing from source using gem
+
+  rake gem
+  gem install pkg/gecoder-0.x.x.gem
+
+=== Installing from source without using gem
+
+"gecode.so" might have another extension depending on which platform it's 
+generated on (replace the extension in the following commands with whatever 
+extension it's given).
+
+  cd ext
+  ruby extconf.rb
+  make
+  mv gecode.so ../lib/
+
+== Running the tests
+
+  rake specs
+
+Requires RSpec (1.0.5, but other version should hopefully work).

data/Rakefile

@@ -0,0 +1,13 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+require 'tasks/all_tasks'
+task :default => [:verify_rcov]
+
+desc 'Performs the tasks necessary when releasing'
+task :release => [:publish_website, :publish_packages, :tag]
+
+desc 'Runs all the tests'
+task :test => :specs

data/example/example_helper.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/../lib/gecoder'

data/example/magic_sequence.rb

@@ -0,0 +1,43 @@
+require File.dirname(__FILE__) + '/example_helper'
+
+# Solves the magic sequence problem.
+class MagicSequence < Gecode::Model
+  # n is the length of the sequence.
+  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)
+    
+    # The basic requirement to qualify as a magic sequence.
+    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 
+    # quicker.
+    
+    # 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
+    
+    # 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
+    
+    branch_on @sequence, :variable => :smallest_degree, :value => :split_max
+  end
+  
+  def to_s
+    @sequence.values.join(', ')
+  end
+end
+
+class Array
+  # Sums all the elements in the array using #+ .
+  def sum
+    inject{ |sum, element| sum + element }
+  end
+end
+
+puts((MagicSequence.new(500).solve! || 'Failed').to_s)

data/example/queens.rb

@@ -0,0 +1,43 @@
+require File.dirname(__FILE__) + '/example_helper'
+
+# Solves the n-queens problem: http://en.wikipedia.org/wiki/Nqueens . No attempt
+# to break the involved symmetries is made.
+class NQueens < Gecode::Model
+  def initialize(n)
+    @size = n
+  
+    # 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)
+    
+    # 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
+    # Queens must not be in the same diagonal (positive slope).
+    @queen_rows.with_offsets((0...n).to_a.reverse).must_be.distinct
+    # Queens must not be in the same row.
+    @queen_rows.must_be.distinct
+    
+    # Branching, we use first-fail heuristic.
+    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
+  
+    separator = '+' << '-' * (3 * @size + (@size - 1)) << "+\n"
+    res = (0...@size).inject(separator) do |s, i|
+      (0...@size).inject(s + '|') do |s, j|
+        s << " #{rows[j] == i ? 'x' : ' '} |"
+      end << "\n" << separator
+    end
+  end
+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 }
+

data/example/raw_bindings.rb

@@ -0,0 +1,42 @@
+require File.dirname(__FILE__) + '/example_helper'
+
+# An example of using the raw bindings. Solves the send+more=money problem.
+
+# Variables
+space = Gecode::Raw::Space.new
+letters = Gecode::Raw::IntVarArray.new(space, 8, 0, 9)
+space.own(letters, 'letters')
+s, e, n, d, m, o, r, y = (0..7).to_a.map{ |i| letters.at(i) }
+
+# Constraints
+Gecode::Raw::post(space, (s * 1000 + e * 100 + n * 10  + d   + 
+                     m * 1000 + o * 100 + r * 10  + e).
+            equal(m * 10000 + o * 1000 + n * 100 + e * 10  + y ), 
+            Gecode::Raw::ICL_DEF)
+Gecode::Raw::rel(space, s, Gecode::Raw::IRT_NQ, 0, Gecode::Raw::ICL_DEF)
+Gecode::Raw::rel(space, m, Gecode::Raw::IRT_NQ, 0, Gecode::Raw::ICL_DEF)
+Gecode::Raw::distinct(space, letters, Gecode::Raw::ICL_DEF)
+
+# Branching.
+Gecode::Raw::branch(space, letters, 
+  Gecode::Raw::BVAR_SIZE_MIN, Gecode::Raw::BVAL_MIN)
+
+# Search
+COPY_DIST = 16
+ADAPTATION_DIST = 4 
+dfs = Gecode::Raw::DFS.new(space, COPY_DIST, ADAPTATION_DIST, 
+  Gecode::Raw::Search::Stop.new)
+
+space = dfs.next
+if space.nil?
+  puts 'Failed'
+else
+  puts 'Solution:'
+  correct_letters = space.intVarArray('letters')
+  arr = []
+  correct_letters.size.times do |i|
+    arr << correct_letters.at(i).val
+  end
+  puts arr.join(' ')
+end
+

data/example/send_more_money.rb

@@ -0,0 +1,43 @@
+require File.dirname(__FILE__) + '/example_helper'
+
+# Solves the send+more=money problem: 
+# http://en.wikipedia.org/wiki/Send%2Bmore%3Dmoney
+class SendMoreMoney < Gecode::Model
+  def initialize
+    # Set up the variables, 8 letters with domain 0..9.
+    s,e,n,d,m,o,r,y = @letters = int_var_array(8, 0..9)
+
+    # 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
+
+    # Set the branching.
+    branch_on @letters, :variable => :smallest_size, :value => :min
+  end
+
+  def to_s
+    %w{s e n d m o r y}.zip(@letters).map do |text, letter|
+      "#{text}: #{letter.value}" 
+    end.join(', ')
+  end
+
+  private
+
+  # 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
+end
+
+puts SendMoreMoney.new.solve!.to_s

data/example/send_most_money.rb

@@ -0,0 +1,58 @@
+require File.dirname(__FILE__) + '/example_helper'
+
+# Solves the cryptarithmetic send+most=money problem while maximizing the value
+# of "money".
+class SendMoreMoney < Gecode::Model
+  attr :money
+
+  def initialize
+    # Set up the variables, 9 letters with domain 0..9.
+    s,e,n,d,m,o,s,t,y = @letters = int_var_array(9, 0..9)
+    @money = wrap_enum([m,o,n,e,y])
+    
+    # Set up the constraints.
+    # The equation must hold.
+    (equation_row(s, e, n, d) + equation_row(m, o, s, t)).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
+
+    # Set the branching.
+    branch_on @letters, :variable => :smallest_size, :value => :min
+  end
+
+  def to_s
+    %w{s e n d m o s t y}.zip(@letters).map do |text, letter|
+      "#{text}: #{letter.value}" 
+    end.join(', ')
+  end
+  
+  private
+
+  # 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.to_number
+  end
+end
+
+class Array
+  # Computes a number of the specified base using the array's elements as 
+  # digits.
+  def to_number(base = 10)
+    inject{ |result, variable| variable + result * base }
+  end
+end
+
+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}"

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,110 @@
+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)
+    # Verify that the input is of a valid size.
+    @size = n = predefined_values.row_size
+    block_size = Math.sqrt(n).round
+    unless predefined_values.square? and block_size**2 == n
+      raise ArgumentError, 'Incorrect value matrix size.'
+    end
+    sub_count = block_size
+    
+    # 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 + n))
+      columns << (0...n).map{ |e| e*n + 1 + i }
+    end
+    
+    # Build arrays containing the square positions of each block.
+    blocks = []
+    # The square numbers of the first block.
+    first_block = (0...block_size).map do |e| 
+      ((n*e+1)..(n*e+block_size)).to_a 
+    end.flatten
+    block_size.times do |i|
+      block_size.times do |j| 
+        blocks << first_block.map{ |e| e + (j*n*block_size)+(i*block_size) }
+      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