winston 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b136df3119babb39b3950a0cc96b393d3344453e
-  data.tar.gz: c10c1db2ceda4d4a553b209e7fceb433375eeabd
+SHA256:
+  metadata.gz: accbe29e2a4b319fb17079fed3b14a6c6516222f546323195f6f6d0c65fc6edc
+  data.tar.gz: 151ea768f38489232668bb53e64bde84ec76d9569a84c7c286b04b554f566054
 SHA512:
-  metadata.gz: d47e3a5f91c608f5c5ad49a649bc9aabf9fd29a243ce0efffa89610a2ba1ad37c68ea026cefbf0b42a1fd0574887af20a50820bd357a0c85f5bd8fe5670ea0a9
-  data.tar.gz: f4a9e5f2c31ef671a50618eb0236d15f59861cf39c2659c980dc34e2e7123f4a84eff5c7c4602220ef0da16ca82eb4541050ffbdeadde0b623601e147b848469
+  metadata.gz: aa0872cce4702b580118d1a4741f9c3be0f835ad3dfb484e1087e76c7456bb0e9af854a58056fca30ec83d9c4bd851a9fe79f6ba7f09a3560bdb9c7054c8b40e
+  data.tar.gz: da8ff827c889a0e431d1b45a863b9718b4e7e71d7c96db5f69698df499ffb622de63c2da5322e678cc60618caae5a776a67653ef48c0dd30f8a3dfaed1d4272e

data/.gitignore

@@ -24,7 +24,6 @@ build/
 /.bundle/
 /lib/bundler/man/
 
-Gemfile.lock
 .ruby-version
 .ruby-gemset
 

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.3.6

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.0

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+Winston
+===============
+
+http://github.com/dmnelson/winston
+
+CHANGELOG
+---------
+
+### 0.1.0
+* Added MAC (Maintaining Arc Consistency) solver with GAC for AllDifferent.
+* Added min-conflicts solver.
+* Added heuristics (MRV/LCV) and forward checking support.
+* Added DSL for defining CSPs, named domains, and named constraints.
+* Added benchmark suite and solver selection via `CSP#solve`.
+* Updated gemspec metadata and Ruby version requirement.
+
+### 0.0.2
+* Added NotInList constraint.
+* Added Sudoku example spec.
+* Added 'allow_nil' option for constraints, so not all variables are necessarily required.
+* Changed AllDifferent constraint to be restricted to given variables when not global

data/Gemfile.lock

@@ -0,0 +1,36 @@
+PATH
+  remote: .
+  specs:
+    winston (0.0.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.6.2)
+    rake (13.2.1)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  bundler (>= 2.4.22)
+  rake (>= 13.1)
+  rspec (>= 3.13)
+  winston!
+
+BUNDLED WITH
+   2.5.22

data/README.md

@@ -1,10 +1,12 @@
 # Winston
 
 [Constraint Satisfaction Problem](http://en.wikipedia.org/wiki/Constraint_satisfaction_problem) (CSP) implementation for Ruby. 
-It provides a useful way to solve problems like resource allocation or planning though a set of constraints.
+It provides a useful way to solve problems like resource allocation or planning through a set of constraints.
 
 The most common example of usage for CSPs is probably the game [Sudoku](http://en.wikipedia.org/wiki/Sudoku).
 
+[![Gem Version](https://badge.fury.io/rb/winston.svg)](http://badge.fury.io/rb/winston) [![Build Status](https://travis-ci.org/dmnelson/winston.svg)](https://travis-ci.org/dmnelson/winston) [![Code Climate](https://codeclimate.com/github/dmnelson/winston/badges/gpa.svg)](https://codeclimate.com/github/dmnelson/winston)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,7 +24,7 @@ Or install it yourself as:
 ## Usage
 
 The problem consists of three sets of information: Domain, Variables and Constraints. It will try to determine a value
-from the given domain for each variable that will attend all the constraints. 
+from the given domain for each variable that will satisfy all the constraints.
 
 ```ruby
 require 'winston'
@@ -42,6 +44,167 @@ csp.solve
 = { a: 6, b: 4, c: 3 }
 ```
 
+### Solvers and heuristics
+
+The default solver is backtracking, and you can configure it with heuristics to speed up search on harder problems.
+
+```ruby
+solver = Winston::Solvers::Backtrack.new(
+  csp,
+  variable_strategy: :mrv,
+  value_strategy: :lcv,
+  forward_checking: true
+)
+
+csp.solve(solver)
+```
+
+You can also pass your own strategies as lambdas:
+
+```ruby
+custom_var = ->(vars, assignments, csp) { vars.first }
+custom_val = ->(values, var, assignments, csp) { values.reverse }
+
+solver = Winston::Solvers::Backtrack.new(
+  csp,
+  variable_strategy: custom_var,
+  value_strategy: custom_val
+)
+```
+
+Built-in heuristic helpers are also available:
+
+```ruby
+solver = Winston::Solvers::Backtrack.new(
+  csp,
+  variable_strategy: Winston::Heuristics.mrv,
+  value_strategy: Winston::Heuristics.lcv,
+  forward_checking: Winston::Heuristics.forward_checking
+)
+```
+
+You can also use a local-search solver (min-conflicts), which is often fast on large problems:
+
+```ruby
+solver = Winston::Solvers::MinConflicts.new(csp, max_steps: 10_000)
+csp.solve(solver)
+```
+
+Min-conflicts is not complete, so it may return `false` even if a solution exists.
+
+For stronger pruning, you can use MAC (Maintaining Arc Consistency), which enforces arc consistency during search:
+
+```ruby
+solver = Winston::Solvers::MAC.new(csp, variable_strategy: :mrv, value_strategy: :lcv)
+csp.solve(solver)
+```
+
+MAC is complete and usually faster than plain backtracking on constrained problems, but can be slower on very small ones.
+
+#### Solver selection guide
+
+- Use `:backtrack` for small problems or when you want deterministic depth-first search.
+- Use `:mac` for tighter constraints or when backtracking explores too many dead ends.
+- Use `:min_conflicts` for large problems where you want speed and can tolerate incompleteness.
+
+### DSL
+
+You can build problems using a small DSL:
+
+```ruby
+csp = Winston.define do
+  domain :digits, (1..9).to_a
+
+  var :a, domain: :digits
+  var :b, domain: :digits
+  var :c, domain: :digits
+
+  constraint(:a, :c) { |a, c| a == c * 2 }
+  constraint(:a, :b) { |a, b| a > b }
+  constraint(:b, :c) { |b, c| b > c }
+  constraint(:b) { |b| b.even? }
+end
+
+csp.solve
+```
+
+You can select a solver by name from any CSP instance:
+
+```ruby
+csp.solve(:backtrack, variable_strategy: :mrv)
+csp.solve(:mac, value_strategy: :lcv)
+csp.solve(:min_conflicts, max_steps: 10_000)
+```
+
+Named solvers:
+- `:backtrack`
+- `:mac`
+- `:min_conflicts`
+
+#### DSL Reference
+
+`Winston.define { ... }` builds and returns a `Winston::CSP`.
+
+DSL methods:
+- `domain :name, values` registers a named domain.
+- `var :name, domain: <values or :name>, value: <preset>, &block` adds a variable.
+- `constraint(*vars, allow_nil: false) { |*values, assignments| ... }` adds a custom constraint.
+- `use_constraint :name, *vars, allow_nil: false, **options` adds a named constraint.
+
+Notes:
+- Domains are static. Use constraints for dynamic behavior.
+- `value:` presets a variable and is validated before search starts.
+- `allow_nil: true` lets a constraint run even if some variables are unset.
+
+#### Named Domains
+
+Named domains reduce repetition and keep variable declarations clean:
+
+```ruby
+Winston.define do
+  domain :digits, (1..9).to_a
+  var :a, domain: :digits
+  var :b, domain: :digits
+end
+```
+
+#### Named Constraints
+
+Built-in named constraints:
+- `:all_different`
+- `:not_in_list`
+
+```ruby
+Winston.define do
+  var :a, domain: [1, 2]
+  var :b, domain: [1, 2]
+  use_constraint :all_different, :a, :b
+end
+```
+
+Register custom constraints:
+
+```ruby
+Winston.register_constraint(:all_twos) do |variables, allow_nil, **_options|
+  Class.new(Winston::Constraint) do
+    def validate(assignments)
+      values = values_at(assignments)
+      values.all? { |v| v == 2 }
+    end
+  end.new(variables: variables, allow_nil: allow_nil)
+end
+```
+
+Use them in the DSL:
+
+```ruby
+Winston.define do
+  var :a, domain: [1, 2]
+  var :b, domain: [1, 2]
+  use_constraint :all_twos, :a, :b
+end
+```
+
 ### Variables and Domain
 
 It's possible to preset values for variables, and in that case the problem would not try to determine values for
@@ -51,7 +214,8 @@ it, but it will take those values into account for validating the constraints.
 csp.add_variable "my_var", value: "predefined value"
 ```
 
-And it's also possible to set the domain as `Proc` so it'd be evaluated on-demand.
+And it's also possible to set the domain as `Proc` so it'd be evaluated on-demand. Domains are static and do not
+receive partial assignments; use constraints for dynamic behavior.
 
 ```ruby
 csp.add_variable("other_var") { |var_name, csp| [:a, :b, :c ] } 
@@ -61,8 +225,8 @@ csp.add_variable("other_var", domain: proc { |var_name, csp| [:a, :b, :c ] })
 
 ### Constraints
 
-Constraints can be set for specific variables and would be evaluated only when all those variables are set and one
-of them has changed; Or globals, in which case, they'd evaluated for every assignment.
+Constraints can be set for specific variables and are evaluated based on the active solver strategy. Global
+constraints are evaluated for every assignment; some solvers (like MAC) also use constraints to prune domains.
 
 ```ruby
 csp.add_constraint(:a) { |a| a > 0 } # positive value
@@ -78,11 +242,11 @@ end
 # hash with all current assignments
 
 csp.add_constraint do |assignments|
-  assignmets.values.uniq.size == assignments.keys.size # checks if every value is unique
+  assignments.values.uniq.size == assignments.keys.size # checks if every value is unique
 end
 ```
 
-Constraint can be also set as their own objects, that's great for reusability.
+Constraints can also be set as their own objects, which is great for reusability.
 
 ```ruby
 csp.add_constraint constraint: MyConstraint.new(...)
@@ -90,7 +254,7 @@ csp.add_constraint constraint: MyConstraint.new(...)
 csp.add_constraint constraint: Winston::Constraints::AllDifferent.new # built-in constraint, checks if all values are different from each other
 ```
 
-### Problems without solution
+### Problems without a solution
 
 ```ruby
 require 'winston'
@@ -108,18 +272,30 @@ csp.solve
 ```
 
 **IMPORTANT NOTE: Depending on the number of variables and the size of the domain it can take a long time to test all different possibilities.
-In that case it'll be recomendable to use of ways to reduce the number of iterations, for example, removing an item from a shared domain
-when it is tested ( A `queue` type of structure, that would `pop` the value on the `each` block).**
+In that case it's recommended to use heuristics or stronger solvers like MAC to reduce the number of iterations.**
 
 ### More examples
 
-Check the folder `specs/examples` for more usage examples.
+Check the folder `spec/examples` for more usage examples.
+The `spec/examples/map_coloring_spec.rb` example is a good starting point for small graph problems, and it demonstrates
+using the MAC solver via `csp.solve(:mac, ...)`.
+
+### Benchmarks
+
+Run benchmarks with:
+
+```ruby
+rake bench
+```
+
+The benchmarks live in `bench/run.rb` and compare backtracking, MAC, and min-conflicts on a few sample problems.
+Benchmarks are run with a fixed timeout and number of runs to make results comparable.
 
 ## TODOs / Nice-to-haves
 
-- Create a DSL for setting up the problem
-- Currently only algorithm to solve the CSP is Backtracking, implement other like Local search, Constraint propagation, ...
-- Implement heuristics to improve search time (least constraining value, minimum remaining values,...)
+- Add more named constraints (sum, all_equal, in_range, ...)
+- Add additional inference techniques (backjumping, nogood recording, ...)
+- Add more solver examples and benchmarks
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,12 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+task :default do
+  RSpec::Core::RakeTask.new(:spec)
+  Rake::Task["spec"].execute
+end
+
+desc "Run benchmarks"
+task :bench do
+  ruby "bench/run.rb"
+end

data/bench/run.rb

@@ -0,0 +1,310 @@
+require "benchmark"
+require "timeout"
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "winston"
+
+TIMEOUT_SECONDS = 10
+RUNS = 5
+
+def timed(label)
+  seconds = nil
+  status = :ok
+
+  begin
+    Timeout.timeout(TIMEOUT_SECONDS) do
+      samples = []
+      RUNS.times do
+        samples << Benchmark.realtime { yield }
+      end
+      seconds = samples
+    end
+  rescue Timeout::Error
+    status = :timeout
+  end
+
+  if status == :ok
+    avg = seconds.sum / seconds.size
+    min = seconds.min
+    max = seconds.max
+    puts format("%-28s %0.4fs (avg, %0.4f-%0.4f)", label, avg, min, max)
+  else
+    puts format("%-28s %s", label, "timeout (#{TIMEOUT_SECONDS}s)")
+  end
+end
+
+def map_coloring_csp
+  Winston.define do
+    domain :colors, %i[red green blue]
+
+    var :western_australia, domain: :colors
+    var :northern_territory, domain: :colors
+    var :south_australia, domain: :colors
+    var :queensland, domain: :colors
+    var :new_south_wales, domain: :colors
+    var :victoria, domain: :colors
+    var :tasmania, domain: :colors
+
+    constraint(:western_australia, :northern_territory) { |wa, nt| wa != nt }
+    constraint(:western_australia, :south_australia) { |wa, sa| wa != sa }
+    constraint(:northern_territory, :south_australia) { |nt, sa| nt != sa }
+    constraint(:northern_territory, :queensland) { |nt, q| nt != q }
+    constraint(:south_australia, :queensland) { |sa, q| sa != q }
+    constraint(:south_australia, :new_south_wales) { |sa, nsw| sa != nsw }
+    constraint(:south_australia, :victoria) { |sa, v| sa != v }
+    constraint(:queensland, :new_south_wales) { |q, nsw| q != nsw }
+    constraint(:new_south_wales, :victoria) { |nsw, v| nsw != v }
+  end
+end
+
+def dense_graph_coloring_csp(nodes: 18, colors: %i[red green blue], edge_probability: 0.6, seed: 42)
+  # Dense constraint graph to compare propagation vs backtracking.
+  random = Random.new(seed)
+  csp = Winston::CSP.new
+  nodes.times do |i|
+    csp.add_variable(:"v#{i}", domain: colors)
+  end
+
+  edges = []
+  (0...nodes).to_a.combination(2).each do |i, j|
+    next unless random.rand < edge_probability
+    edges << [i, j]
+  end
+
+  edges.each do |i, j|
+    csp.add_constraint(:"v#{i}", :"v#{j}") { |a, b| a != b }
+  end
+
+  csp
+end
+
+def n_queens_csp(n)
+  # AllDifferent-heavy problem to showcase GAC propagation.
+  csp = Winston::CSP.new
+  rows = (0...n).to_a
+  rows.each { |row| csp.add_variable(:"row_#{row}", domain: rows) }
+  csp.add_constraint constraint: Winston::Constraints::AllDifferent.new(variables: rows.map { |r| :"row_#{r}" })
+
+  rows.combination(2).each do |i, j|
+    csp.add_constraint(:"row_#{i}", :"row_#{j}") do |ci, cj|
+      (ci - cj).abs != (i - j)
+    end
+  end
+  csp
+end
+
+def random_binary_csp(vars: 50, domain: (1..5).to_a, edge_probability: 0.15, allowed_ratio: 0.5, seed: 42)
+  # Random binary CSP near phase transition.
+  random = Random.new(seed)
+  csp = Winston::CSP.new
+  vars.times { |i| csp.add_variable(:"x#{i}", domain: domain) }
+
+  allowed_pairs = {}
+  domain.each do |a|
+    domain.each do |b|
+      allowed_pairs[[a, b]] = random.rand < allowed_ratio
+    end
+  end
+
+  (0...vars).to_a.combination(2).each do |i, j|
+    next unless random.rand < edge_probability
+    csp.add_constraint(:"x#{i}", :"x#{j}") do |x, y|
+      allowed_pairs[[x, y]]
+    end
+  end
+
+  csp
+end
+
+def hard_binary_csp
+  # Larger binary CSP to test search vs propagation overhead.
+  random_binary_csp(vars: 80, domain: (1..6).to_a, edge_probability: 0.35, allowed_ratio: 0.35, seed: 1337)
+end
+
+def sudoku_csp
+  # Medium puzzle for balanced comparison.
+  puzzle = [
+    [8, 0, 0, 1, 0, 4, 0, 9, 0],
+    [9, 6, 0, 0, 2, 7, 1, 0, 8],
+    [3, 4, 1, 6, 0, 0, 7, 5, 0],
+    [5, 0, 3, 4, 0, 8, 0, 7, 1],
+    [4, 7, 0, 0, 1, 3, 6, 0, 9],
+    [6, 1, 8, 9, 0, 2, 0, 3, 0],
+    [0, 0, 0, 2, 3, 5, 0, 1, 4],
+    [0, 0, 4, 7, 0, 6, 8, 0, 3],
+    [0, 0, 9, 8, 4, 1, 5, 0, 7]
+  ]
+
+  csp = Winston::CSP.new
+  digits = (1..9).to_a
+  (0...9).each do |r|
+    (0...9).each do |c|
+      value = puzzle[r][c]
+      name = :"r#{r}c#{c}"
+      if value == 0
+        csp.add_variable(name, domain: digits)
+      else
+        csp.add_variable(name, value: value)
+      end
+    end
+  end
+
+  rows = (0...9).map { |r| (0...9).map { |c| :"r#{r}c#{c}" } }
+  cols = (0...9).map { |c| (0...9).map { |r| :"r#{r}c#{c}" } }
+  boxes = []
+  [0, 3, 6].each do |br|
+    [0, 3, 6].each do |bc|
+      box = []
+      (0...3).each do |r|
+        (0...3).each do |c|
+          box << :"r#{br + r}c#{bc + c}"
+        end
+      end
+      boxes << box
+    end
+  end
+
+  (rows + cols + boxes).each do |group|
+    group.combination(2).each do |a, b|
+      csp.add_constraint(a, b) { |x, y| x != y }
+    end
+  end
+
+  csp
+end
+
+def sudoku_hard_csp
+  # Harder puzzle with more branching.
+  puzzle = [
+    [0, 0, 0, 2, 6, 0, 7, 0, 1],
+    [6, 8, 0, 0, 7, 0, 0, 9, 0],
+    [1, 9, 0, 0, 0, 4, 5, 0, 0],
+    [8, 2, 0, 1, 0, 0, 0, 4, 0],
+    [0, 0, 4, 6, 0, 2, 9, 0, 0],
+    [0, 5, 0, 0, 0, 3, 0, 2, 8],
+    [0, 0, 9, 3, 0, 0, 0, 7, 4],
+    [0, 4, 0, 0, 5, 0, 0, 3, 6],
+    [7, 0, 3, 0, 1, 8, 0, 0, 0]
+  ]
+
+  csp = Winston::CSP.new
+  digits = (1..9).to_a
+  (0...9).each do |r|
+    (0...9).each do |c|
+      value = puzzle[r][c]
+      name = :"r#{r}c#{c}"
+      if value == 0
+        csp.add_variable(name, domain: digits)
+      else
+        csp.add_variable(name, value: value)
+      end
+    end
+  end
+
+  rows = (0...9).map { |r| (0...9).map { |c| :"r#{r}c#{c}" } }
+  cols = (0...9).map { |c| (0...9).map { |r| :"r#{r}c#{c}" } }
+  boxes = []
+  [0, 3, 6].each do |br|
+    [0, 3, 6].each do |bc|
+      box = []
+      (0...3).each do |r|
+        (0...3).each do |c|
+          box << :"r#{br + r}c#{bc + c}"
+        end
+      end
+      boxes << box
+    end
+  end
+
+  (rows + cols + boxes).each do |group|
+    group.combination(2).each do |a, b|
+      csp.add_constraint(a, b) { |x, y| x != y }
+    end
+  end
+
+  csp
+end
+
+def sudoku_very_hard_csp
+  # Very hard puzzle to stress propagation.
+  puzzle = [
+    [0, 0, 0, 0, 0, 0, 0, 0, 1],
+    [0, 0, 0, 0, 2, 0, 0, 0, 0],
+    [0, 0, 1, 0, 0, 9, 0, 0, 0],
+    [0, 0, 0, 5, 0, 0, 0, 4, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 6, 0, 0, 0, 1, 0, 0, 0],
+    [0, 0, 0, 9, 0, 0, 8, 0, 0],
+    [0, 0, 0, 0, 7, 0, 0, 0, 0],
+    [7, 0, 0, 0, 0, 0, 0, 0, 0]
+  ]
+
+  csp = Winston::CSP.new
+  digits = (1..9).to_a
+  (0...9).each do |r|
+    (0...9).each do |c|
+      value = puzzle[r][c]
+      name = :"r#{r}c#{c}"
+      if value == 0
+        csp.add_variable(name, domain: digits)
+      else
+        csp.add_variable(name, value: value)
+      end
+    end
+  end
+
+  rows = (0...9).map { |r| (0...9).map { |c| :"r#{r}c#{c}" } }
+  cols = (0...9).map { |c| (0...9).map { |r| :"r#{r}c#{c}" } }
+  boxes = []
+  [0, 3, 6].each do |br|
+    [0, 3, 6].each do |bc|
+      box = []
+      (0...3).each do |r|
+        (0...3).each do |c|
+          box << :"r#{br + r}c#{bc + c}"
+        end
+      end
+      boxes << box
+    end
+  end
+
+  (rows + cols + boxes).each do |group|
+    group.combination(2).each do |a, b|
+      csp.add_constraint(a, b) { |x, y| x != y }
+    end
+  end
+
+  csp
+end
+
+def run_case(name, csp)
+  puts "\n#{name}"
+  timed("Backtrack") { csp.solve(:backtrack) }
+  timed("MAC (default)") { csp.solve(:mac) }
+  timed("MAC (mrv)") { csp.solve(:mac, variable_strategy: :mrv) }
+  timed("Min-Conflicts") do
+    csp.solve(:min_conflicts, max_steps: 10_000, random: Random.new(1))
+  end
+end
+
+run_case("Map coloring (Australia)", map_coloring_csp)
+run_case(
+  "Dense graph coloring (18)",
+  dense_graph_coloring_csp(nodes: 18, edge_probability: 0.7, seed: 42)
+)
+run_case(
+  "Dense graph coloring (30)",
+  dense_graph_coloring_csp(nodes: 30, edge_probability: 0.8, seed: 42)
+)
+run_case(
+  "Random binary CSP (50)",
+  random_binary_csp(vars: 50, edge_probability: 0.15, allowed_ratio: 0.5, seed: 42)
+)
+run_case(
+  "Hard binary CSP (80)",
+  hard_binary_csp
+)
+run_case("N-Queens (8)", n_queens_csp(8))
+run_case("Sudoku (medium)", sudoku_csp)
+run_case("Sudoku (hard)", sudoku_hard_csp)
+run_case("Sudoku (very hard)", sudoku_very_hard_csp)