combinatorial_puzzle_solver 0.1.0

data/example_puzzles/medium

@@ -0,0 +1,12 @@
+000|301|000
+009|000|000
+080|000|030
+---+---+---
+000|004|980
+007|120|500
+200|090|170
+---+---+---
+050|012|000
+090|007|000
+300|405|008
+

data/example_puzzles/simple

@@ -0,0 +1,9 @@
+906813540
+201045063
+040000000
+000620009
+009000200
+700034000
+000000090
+590360104
+027459306

data/exe/solve_sudoku

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+require 'optparse'
+require 'combinatorial_puzzle_solver'
+
+def parse_options(argv)
+  options = { :stderr => $stderr }
+
+  option_parser = OptionParser.new { |opts|
+    opts.banner = "Usage: solve_sudoku [options] [files]"
+
+    options[:dimension] = 3
+
+    opts.on("-4", "--4x4", "Assume puzzles are 4x4 instead of 9x9") {|dimension|
+      options[:dimension] = 2
+    }
+
+    opts.on("-c", "--clues [NUM=1]", Integer,
+            "Abort after NUM steps, don't solve entire puzzle.") {|clues|
+      options[:clues] = clues || 1
+    }
+
+    opts.on("-r", "--resolution-only", "Avoid trial and error",
+            "Might not reach a complete solution.") {|res|
+      options[:resolution] = res
+    }
+
+    opts.separator ""
+    opts.separator "Output:"
+
+    opts.on("-i", "--print-input", "Print the parsed input puzzles."){|input|
+      options[:parsed_stream] = $stdout
+    }
+
+    opts.on("-o", "--print-output", "Print the result puzzles."){|output|
+      options[:result_stream] = $stdout
+    }
+
+    opts.on("-s", "--print-steps", "Print each resolution step.",
+            "It will not print steps resolved by trial and error."){|steps|
+      options[:steps_stream] = $stdout
+    }
+
+    opts.on("-p", "--print-puzzle-steps",
+            "Print entire puzzle for each resolution step.",
+            "It will not print steps resolved by trial and error."){|steps|
+      options[:puzzle_stream] = $stdout
+    }
+
+    opts.separator ""
+    opts.separator "Utility:"
+
+    opts.on_tail("-h", "--help", "Show this message.") {
+      $stderr.puts opts
+      return nil
+    }
+  }
+
+  begin
+    option_parser.parse!(argv)
+  rescue OptionParser::InvalidOption => e
+    $stderr.puts option_parser.help
+    return nil
+  end
+
+  options
+end
+
+# Scans the input string and resolves the sudoku puzzles it manages to parse.
+#
+# @param input [String] the string to be parsed
+# @param options [Hash] the options parsed from ARGV, along with output streams for diagnostic purposes.
+# @return [true,false] whether all the puzzles was completely resolved or not.
+def scan_and_resolve!(input, options)
+  success = true
+  begin
+    CombinatorialPuzzleSolver::Sudoku.scan(input, options[:dimension]){|sudoku|
+      begin
+        success &= sudoku.resolve!(!options[:resolution], options[:clues], options)
+
+      rescue CombinatorialPuzzleSolver::Inconsistency => error
+        options[:stderr].puts "Puzzle inconsistent, no solution possible."
+        success = false
+      end
+    }
+  rescue => error
+    options[:stderr].puts error
+    success = false
+  end
+  success
+end
+
+
+
+options = parse_options(ARGV)
+exit 1 if options.nil?
+
+if ARGV.empty? then
+  exit scan_and_resolve!($stdin.read, options) ? 0 : 1
+else
+  success = true
+  ARGV.each{|filename|
+    begin
+      success &= scan_and_resolve!(File.read(filename), options)
+    rescue IOError => error
+      $stderr.puts "Failed reading #{filename}, #{error}."
+    end
+  }
+  exit success ? 0 : 1
+end
+

data/lib/combinatorial_puzzle_solver.rb

@@ -0,0 +1,12 @@
+require "combinatorial_puzzle_solver/version"
+require "combinatorial_puzzle_solver/puzzle"
+require "combinatorial_puzzle_solver/inconsistency"
+require "combinatorial_puzzle_solver/identifier"
+require "combinatorial_puzzle_solver/constraint"
+require "combinatorial_puzzle_solver/solution_space"
+require "combinatorial_puzzle_solver/possibilities"
+require "combinatorial_puzzle_solver/sudoku"
+
+# A resolver of combinatorial number-placement puzzles, like Sudoku.
+module CombinatorialPuzzleSolver
+end

data/lib/combinatorial_puzzle_solver/constraint.rb

@@ -0,0 +1,54 @@
+
+module CombinatorialPuzzleSolver
+
+  # A collection of identifiers that all should have unique values, like a row or a
+  # column in a Sudoku puzzle.
+  class Constraint < Array
+
+    def initialize(identifiers)
+      super(identifiers)
+      fail unless identifiers.is_a?(Array)
+      identifiers.each{|id| fail unless id.is_a?(Identifier)}
+
+      each{|identifier| identifier.constraints << self }
+    end
+
+    # Iterates all possible values that can be set within this constraint, and
+    # when a value can only be placed within that specific identifier.
+    #
+    # @param solution_space [SolutionSpace] the mapping between the puzzle's
+    #                                       identifiers and the values they can have.
+    # @param resolvable [Hash<Identifier,Object>] an optional Hash to store all
+    #                                             identifiers and values that becomes
+    #                                             resolvable.
+    # @return [Hash<Identifier,Object>] the identifiers that can be resolved, mapped
+    #                                   to the only value they can have.
+    def resolvable_identifiers(solution_space, resolvable=Hash.new)
+      possible_values(solution_space).each{|value, identifiers|
+        if identifiers.size == 1 then
+          resolved_identifier = identifiers.first
+          unless solution_space[resolved_identifier].resolved? then
+            resolvable[resolved_identifier] = value
+          end
+        end
+      }
+      resolvable
+    end
+
+    # @param solution_space [SolutionSpace] the mapping between the puzzle's
+    #                                       identifiers and the values they can have.
+    # @return [Hash<Object,Set<Identifier>>] a map between each possible value within
+    #                                        this constraint and the set of
+    #                                        identifiers that can have them.
+    def possible_values(solution_space)
+      values = Hash.new{|value,ids| value[ids] = Set.new }
+
+      each{|identifier|
+        solution_space[identifier].each{|value|
+          values[value] << identifier
+        }
+      }
+      values
+    end
+  end
+end

data/lib/combinatorial_puzzle_solver/identifier.rb

@@ -0,0 +1,55 @@
+
+module CombinatorialPuzzleSolver
+
+  # Designates the smallest unit that should be mapped to a number, e.g. a cell
+  # in a Sudoku puzzle.
+  class Identifier
+    # @return [Object, nil] the value that this identifier is assigned to, or nil.
+    attr_reader :value
+
+    # @return [Array<Constraint>] the constraints that affect this identifier
+    attr_reader :constraints
+
+    # @return [Puzzle] the puzzle that this identifier belongs to.
+    attr_reader :puzzle
+
+    # Creates an Identifier
+    # @param puzzle [Puzzle] the puzzle this identifier belongs to.
+    def initialize(puzzle)
+      @puzzle = puzzle;
+      @value = nil
+      @constraints = []
+    end
+
+    # Sets the value for this identifier
+    # @param value [Object] the value to set.
+    def set!(value)
+      @value = value
+    end
+
+    # @return [Array<Identifier>] all other identifiers that are covered by this
+    #                             identifier's constraints.
+    def dependent_identifiers
+      @constraints.flatten.uniq - [self]
+    end
+
+    # @return [true,false] true if this identifier has a value, false otherwise.
+    def has_value?
+      !@value.nil?
+    end
+
+    # @return [String] a string representation of this identifier, which is defined
+    #                  by  {Puzzle#identifier_to_s}.
+    # @see Puzzle#identifier_to_s
+    def to_s
+      @puzzle.identifier_to_s(self)
+    end
+
+    # @return [String] a string representation of this identifier, which is defined
+    #                  by  {Puzzle#inspect_identifier}.
+    # @see Puzzle#identifier_to_s
+    def inspect
+      @puzzle.inspect_identifier(self)
+    end
+  end
+end

data/lib/combinatorial_puzzle_solver/inconsistency.rb

@@ -0,0 +1,9 @@
+
+module CombinatorialPuzzleSolver
+
+  # The current state of the solution space has become inconsistent and unresolvable.
+  class Inconsistency < RuntimeError
+  end
+
+end
+

data/lib/combinatorial_puzzle_solver/possibilities.rb

@@ -0,0 +1,89 @@
+
+module CombinatorialPuzzleSolver
+
+  # A collection of the possible values an identifier can have. It is reduced by
+  # invoking {#cannot_be!} and {#must_be!} until it only has one possible value, and
+  # thus becomes {#resolved?}.
+  class Possibilities < Array
+
+    # Creates a set of possibilities for a specific identifier, which initially would
+    # be all possible symbols of the puzzle.
+    # @param solution_space [SolutionSpace] the solution space that this set belongs
+    #                                       to.
+    # @param identifier [Identifier] the identifier associated with this set of
+    #                                possible values.
+    def initialize(solution_space, identifier)
+      @solution_space = solution_space
+      @identifier = identifier
+
+      super(identifier.puzzle.symbols) unless identifier.has_value?
+    end
+
+    # Reduce the possible values by stating that the identifier can only have a
+    # certain value.
+    #
+    # @param value [Object] the only possible value the identifier can have.
+    # @param resolvable [Hash<Identifier,Object>] an optional Hash to store all
+    #                                             identifiers and values that becomes
+    #                                             resolvable.
+    # @return [Hash<Identifier,Object>] a Hash of identifiers that becomes
+    #                                   resolvable because of this action.
+    # @raise [Inconsistency] if the solution space becomes inconsistent without any
+    #                        possible solution.
+    def must_be!(value, resolvable=Hash.new)
+      raise Inconsistency if @identifier.has_value? && @identifier.value != value
+      raise Inconsistency unless include?(value)
+
+      clear
+      push(value)
+
+      dependent_identifiers_cannot_be!(value, resolvable)
+    end
+
+    # Notifies dependent identifiers that they can't have a certain value.
+    #
+    # @param value [Object] a value that the dependent identifiers cannot have.
+    # @param resolvable [Hash<Identifier,Object>] an optional Hash to store all
+    #                                             identifiers and values that becomes
+    #                                             resolvable.
+    # @return [Hash<Identifier,Object>] the hash of identifiers that becomes
+    #                                   resolvable because of this action.
+    # @raise [Inconsistency] if the solution space becomes inconsistent without any
+    #                        possible solution.
+    def dependent_identifiers_cannot_be!(value, resolvable=Hash.new)
+      @identifier.dependent_identifiers.each{|dependency|
+        @solution_space[dependency].cannot_be!(value, resolvable)
+      }
+      resolvable
+    end
+
+    # Reduce the possible values by stating that the identifier cannot have a certain
+    # value.
+    #
+    # @param value [Object] a value that the identifier cannot have.
+    # @param resolvable [Hash<Identifier,Object>] an optional Hash to store all
+    #                                             identifiers and values that becomes
+    #                                             resolvable.
+    # @return [Hash<Identifier,Object>] the hash of identifiers that becomes
+    #                                   resolvable because of this action.
+    # @raise [Inconsistency] if the solution space becomes inconsistent without any
+    #                        possible solution.
+    def cannot_be!(value, resolvable=Hash.new)
+      raise Inconsistency if @identifier.value == value
+
+      if delete(value) then
+        raise Inconsistency if empty?
+        resolvable[@identifier] = first if resolved?
+      end
+      resolvable
+    end
+
+    # @return [true,false] true if the identifier can only have one possible value,
+    #                      false otherwise.
+    def resolved?
+       size == 1
+    end
+  end
+
+end
+

data/lib/combinatorial_puzzle_solver/puzzle.rb

@@ -0,0 +1,124 @@
+require 'set'
+
+module CombinatorialPuzzleSolver
+
+  # Base class for a combinatorial number-placement puzzle
+  class Puzzle
+
+    # @return [Array<Identifier>] the identifiers of this puzzle.
+    attr_reader :identifiers
+
+    # @return [Array<Constraint>] the constraints of this puzzle.
+    attr_reader :constraints
+
+    # @return [Array] an array that contains all the possible values each
+    #                 identifier can have.
+    attr_reader :symbols
+
+    # Creates a new puzzle.
+    #
+    # @param identifier_count [Fixnum] The number of identifiers in this puzzle
+    # @param symbols [Array] The possible values each identifier can have.
+    # @yieldparam identifiers [Array<Identifier>] the identifiers of this puzzle.
+    # @yieldreturn [Array<Constraint>] The initialized constraints
+    #
+    def initialize(identifier_count, symbols, &constraint_block)
+
+      @symbols = symbols.uniq
+      @identifiers = Array.new(identifier_count) { Identifier.new(self) }
+
+      fail "No block for initiating constraints given" unless block_given?
+      @constraints = yield @identifiers
+
+      fail "The constraint block returned 0 constraints" if @constraints.empty?
+      unless @constraints.all?{|constraint| constraint.is_a?(Constraint)} then
+        fail "The constraint block may only contain Constraint"
+      end
+    end
+
+    # @return [SolutionSpace,nil] the resolved solution space for this puzzle, or nil
+    #                             if the puzzle doesn't have any solution.
+    def resolved_solution_space
+      begin
+        solution_space = SolutionSpace.new(self)
+        solution_space.resolve!(solution_space.resolved_identifiers)
+        return solution_space.resolve_by_trial_and_error!
+      rescue Inconsistency
+        nil
+      end
+    end
+
+    # @return [String] identifiers and constraints as a string representation.
+    # @see Identifier#inspect
+    # @see Constraint#inspect
+    def inspect
+      (@identifiers + @constraints).collect{|obj| obj.inspect }.join("\n")
+    end
+
+    # @return [String] a string representation of an identifier, in the context of
+    #                  this puzzle.
+    def identifier_to_s(identifier)
+      "[#{identifiers.index(identifier)}]"
+    end
+
+    # @return [String] a string representation of an identifier (including value), in
+    #                  the context of this puzzle.
+    def inspect_identifier(identifier)
+      if identifier.has_value? then
+        identifier_to_s(identifier) << "=#{identifier.value.to_s}"
+      else
+        identifier_to_s(identifier)
+      end
+    end
+
+    # Sets all identifiers to the value they are resolved to.
+    # @param solution_space [SolutionSpace]
+    def set_resolved_identifiers!(solution_space)
+      solution_space.resolved_identifiers.each{|identifier, value|
+        identifier.set!(value)
+      }
+    end
+
+    # Resolves a puzzle while writing diagnostic output to given streams.
+    #
+    # @param trial_and_error [Boolean] whether it should resort to trial and error if
+    #                                  a complete solution cannot be resolved.
+    # @param steps [Fixnum] how many steps it will perform before aborting (or 0).
+    # @param output [Hash] a collection of output streams for diagnostic purposes.
+    # @return [true,false] whether the puzzle was completely resolved or not.
+    # @raise [Inconsistency] if the solution space becomes inconsistent without any
+    #                         possible solution.
+    def resolve!(trial_and_error=true, steps=0, output={})
+
+      # print the parsed puzzle
+      output[:parsed_stream].puts to_s << "\n\n" if output[:parsed_stream]
+
+      step_count = 0
+
+      solution = SolutionSpace.new(self)
+      solution.resolve!(solution.resolved_identifiers){|x, identifier, value|
+
+        # print the resolved step
+        identifier.set!(value)
+        output[:steps_stream].puts identifier.inspect if output[:steps_stream]
+
+        # print the entire board
+        output[:puzzle_stream].puts to_s << "\n\n" if output[:puzzle_stream]
+
+        step_count += 1
+        step_count != steps
+      }
+
+      # brute force with trial and error unless we only want the resolution steps
+      brute_forced = solution.resolve_by_trial_and_error! if trial_and_error
+      solution = brute_forced unless brute_forced.nil?
+
+      # print the result
+      set_resolved_identifiers!(solution)
+      output[:result_stream].puts to_s << "\n\n" if output[:result_stream]
+
+      solution.resolved?
+    end
+
+  end
+end