winston 0.0.1 → 0.1.0

data/spec/examples/sudoku_spec.rb

@@ -0,0 +1,120 @@
+require "winston"
+
+describe "Sudoku Example" do
+  let(:csp) { Winston::CSP.new }
+
+  describe "Unique values for every row, column and quadrant" do
+    before do
+      domain = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+      # Adding variables
+      1.upto(9).each do |x|
+        1.upto(9).each do |j|
+          csp.add_variable({ x: x, y: j }, domain: domain)
+        end
+      end
+
+      variables = csp.variables.keys
+
+      # add columns and rows constraints
+      1.upto(9).each do |i|
+        column = variables.select { |name| name[:x] == i }
+        row = variables.select { |name| name[:y] == i }
+
+        csp.add_constraint constraint: Winston::Constraints::AllDifferent.new(variables: row, allow_nil: true)
+        csp.add_constraint constraint: Winston::Constraints::AllDifferent.new(variables: column, allow_nil: true)
+      end
+
+      # blocks
+      variables.each_slice(3).group_by { |i| (i[0][:y] -1)  % 9 }.values.flatten.each_slice(9).each do |vars|
+        csp.add_constraint constraint: Winston::Constraints::AllDifferent.new(variables: vars, allow_nil: true)
+      end
+    end
+
+    it "should return a valid solution" do
+      expect(csp.solve).to eq({
+        {:x=>1, :y=>1}=>1,
+        {:x=>1, :y=>2}=>2,
+        {:x=>1, :y=>3}=>3,
+        {:x=>1, :y=>4}=>4,
+        {:x=>1, :y=>5}=>5,
+        {:x=>1, :y=>6}=>6,
+        {:x=>1, :y=>7}=>7,
+        {:x=>1, :y=>8}=>8,
+        {:x=>1, :y=>9}=>9,
+        {:x=>2, :y=>1}=>4,
+        {:x=>2, :y=>2}=>5,
+        {:x=>2, :y=>3}=>6,
+        {:x=>2, :y=>4}=>7,
+        {:x=>2, :y=>5}=>8,
+        {:x=>2, :y=>6}=>9,
+        {:x=>2, :y=>7}=>1,
+        {:x=>2, :y=>8}=>2,
+        {:x=>2, :y=>9}=>3,
+        {:x=>3, :y=>1}=>7,
+        {:x=>3, :y=>2}=>8,
+        {:x=>3, :y=>3}=>9,
+        {:x=>3, :y=>4}=>1,
+        {:x=>3, :y=>5}=>2,
+        {:x=>3, :y=>6}=>3,
+        {:x=>3, :y=>7}=>4,
+        {:x=>3, :y=>8}=>5,
+        {:x=>3, :y=>9}=>6,
+        {:x=>4, :y=>1}=>2,
+        {:x=>4, :y=>2}=>1,
+        {:x=>4, :y=>3}=>4,
+        {:x=>4, :y=>4}=>3,
+        {:x=>4, :y=>5}=>6,
+        {:x=>4, :y=>6}=>5,
+        {:x=>4, :y=>7}=>8,
+        {:x=>4, :y=>8}=>9,
+        {:x=>4, :y=>9}=>7,
+        {:x=>5, :y=>1}=>3,
+        {:x=>5, :y=>2}=>6,
+        {:x=>5, :y=>3}=>5,
+        {:x=>5, :y=>4}=>8,
+        {:x=>5, :y=>5}=>9,
+        {:x=>5, :y=>6}=>7,
+        {:x=>5, :y=>7}=>2,
+        {:x=>5, :y=>8}=>1,
+        {:x=>5, :y=>9}=>4,
+        {:x=>6, :y=>1}=>8,
+        {:x=>6, :y=>2}=>9,
+        {:x=>6, :y=>3}=>7,
+        {:x=>6, :y=>4}=>2,
+        {:x=>6, :y=>5}=>1,
+        {:x=>6, :y=>6}=>4,
+        {:x=>6, :y=>7}=>3,
+        {:x=>6, :y=>8}=>6,
+        {:x=>6, :y=>9}=>5,
+        {:x=>7, :y=>1}=>5,
+        {:x=>7, :y=>2}=>3,
+        {:x=>7, :y=>3}=>1,
+        {:x=>7, :y=>4}=>6,
+        {:x=>7, :y=>5}=>4,
+        {:x=>7, :y=>6}=>2,
+        {:x=>7, :y=>7}=>9,
+        {:x=>7, :y=>8}=>7,
+        {:x=>7, :y=>9}=>8,
+        {:x=>8, :y=>1}=>6,
+        {:x=>8, :y=>2}=>4,
+        {:x=>8, :y=>3}=>2,
+        {:x=>8, :y=>4}=>9,
+        {:x=>8, :y=>5}=>7,
+        {:x=>8, :y=>6}=>8,
+        {:x=>8, :y=>7}=>5,
+        {:x=>8, :y=>8}=>3,
+        {:x=>8, :y=>9}=>1,
+        {:x=>9, :y=>1}=>9,
+        {:x=>9, :y=>2}=>7,
+        {:x=>9, :y=>3}=>8,
+        {:x=>9, :y=>4}=>5,
+        {:x=>9, :y=>5}=>3,
+        {:x=>9, :y=>6}=>1,
+        {:x=>9, :y=>7}=>6,
+        {:x=>9, :y=>8}=>4,
+        {:x=>9, :y=>9}=>2
+      })
+    end
+  end
+end

data/spec/winston/backtrack_spec.rb

@@ -1,6 +1,6 @@
 require "winston"
 
-describe Winston::Backtrack do
+describe Winston::Solvers::Backtrack do
   let(:csp) { Winston::CSP.new }
   subject { described_class.new(csp) }
 
@@ -44,5 +44,38 @@ describe Winston::Backtrack do
         end
       end
     end
+
+    context "with heuristics" do
+      it "uses MRV to pick the smallest remaining domain first" do
+        csp.add_variable :a, domain: [1, 2, 3]
+        csp.add_variable :b, domain: [1]
+        csp.add_variable :c, domain: [1, 2]
+
+        solver = described_class.new(csp, variable_strategy: :mrv)
+        result = solver.search
+
+        expect(result.keys).to eq([:b, :c, :a])
+      end
+
+      it "uses LCV to prefer values that leave more options" do
+        csp.add_variable :a, domain: [2, 1]
+        csp.add_variable :b, domain: [2, 3]
+        csp.add_constraint(:a, :b) { |a, b| b > a }
+
+        solver = described_class.new(csp, value_strategy: :lcv)
+        result = solver.search
+
+        expect(result[:a]).to eq(1)
+      end
+
+      it "supports forward checking" do
+        csp.add_variable :a, domain: [1]
+        csp.add_variable :b, domain: [1]
+        csp.add_constraint(:a, :b) { |a, b| a != b }
+
+        solver = described_class.new(csp, forward_checking: true)
+        expect(solver.search).to be(false)
+      end
+    end
   end
 end

data/spec/winston/constraint_spec.rb

@@ -4,7 +4,8 @@ describe Winston::Constraint do
 
   let(:variables) { nil }
   let(:predicate) { nil }
-  subject { described_class.new(variables, predicate) }
+  let(:allow_nil) { false }
+  subject { described_class.new(variables: variables, predicate: predicate, allow_nil: allow_nil) }
 
   describe "#elegible_for?" do
     context "global" do
@@ -49,6 +50,50 @@ describe Winston::Constraint do
         expect(subject.elegible_for?(:a, { b: 2 })).to be(false)
       end
     end
+
+    context "allowing nil" do
+      let(:allow_nil) { true }
+
+      context "for specific variable" do
+        let(:variables) { [:a] }
+
+        it "should return true when that variable is changed" do
+          expect(subject.elegible_for?(:a, { a: nil })).to be(true)
+        end
+
+        it "should return false when that variable isn't the one changed" do
+          expect(subject.elegible_for?(:b, { a: 1, b: 2 })).to be(false)
+        end
+
+        it "should return true when that variable is changed but doesn't have a value" do
+          expect(subject.elegible_for?(:a, { b: 2 })).to be(true)
+        end
+      end
+
+      context "for multiple variables" do
+        let(:variables) { [:a, :b] }
+
+        it "should return true when one of those variables is changed" do
+          expect(subject.elegible_for?(:a, { a: 1, b: nil })).to be(true)
+        end
+
+        it "should return false when one of those variables isn't the one changed" do
+          expect(subject.elegible_for?(:c, { a: 1, b: 2 })).to be(false)
+        end
+
+        it "should return true when one of those variables is changed but doesn't have a value for every one of them" do
+          expect(subject.elegible_for?(:b, { b: 2 })).to be(true)
+        end
+
+        it "should return true when one of those variables is changed but doesn't have a value for every one of them" do
+          expect(subject.elegible_for?(:a, { b: 2 })).to be(true)
+        end
+
+        it "should return true when one of those variables is changed but doesn't have a value for any of them" do
+          expect(subject.elegible_for?(:a, {})).to be(true)
+        end
+      end
+    end
   end
 
   describe "#validate" do

data/spec/winston/constraints/all_different_spec.rb

@@ -3,13 +3,6 @@ require "winston"
 describe Winston::Constraints::AllDifferent do
   subject { described_class.new }
 
-  describe "#elegible_for?" do
-    it "should be elegible for everything" do
-      expect(subject.elegible_for?(:a, {})).to be(true)
-      expect(subject.elegible_for?(:b, { a: 1 })).to be(true)
-    end
-  end
-
   describe "#validate" do
     it "should return 'true' when all values are unique" do
       expect(subject.validate(a: 1, b: 2, c: 3, d: 4)).to be(true)
@@ -18,5 +11,17 @@ describe Winston::Constraints::AllDifferent do
     it "should return 'false' when not all values are unique" do
       expect(subject.validate(a: 1, b: 2, c: 2, d: 4)).to be(false)
     end
+
+    context "for specific variables" do
+      subject { described_class.new(variables: [:a, :b, :c]) }
+
+      it "should return 'true' when all values are unique" do
+        expect(subject.validate(a: 1, b: 2, c: 3, d: 3)).to be(true)
+      end
+
+      it "should return 'false' when not all values are unique" do
+        expect(subject.validate(a: 1, b: 2, c: 2, d: 4)).to be(false)
+      end
+    end
   end
 end

data/spec/winston/constraints/not_in_list_spec.rb

@@ -0,0 +1,35 @@
+require "winston"
+
+describe Winston::Constraints::NotInList do
+  subject { described_class.new(list: [ 4, 5, 6 ]) }
+
+  describe "#validate" do
+    it "should return 'true' none of the values are on the list" do
+      expect(subject.validate(a: 1, b: 2, c: 3, d: 3)).to be(true)
+    end
+
+    it "should return 'false' when any of the values are on the list" do
+      expect(subject.validate(a: 1, b: 2, c: 2, d: 4)).to be(false)
+    end
+
+    it "should return 'false' when all the values are on the list" do
+      expect(subject.validate(a: 4, b: 6, c: 5, d: 4)).to be(false)
+    end
+
+    context "for specific variables" do
+      subject { described_class.new(variables: [:a, :b, :c], list: [ 4, 5, 6 ]) }
+
+      it "should return 'true' when none of the values are on the list" do
+        expect(subject.validate(a: 1, b: 2, c: 3, d: 6)).to be(true)
+      end
+
+      it "should return 'false' when any of the values are on the list" do
+        expect(subject.validate(a: 1, b: 2, c: 5, d: 3)).to be(false)
+      end
+
+      it "should return 'false' when all the values are on the list" do
+        expect(subject.validate(a: 4, b: 6, c: 5, d: 3)).to be(false)
+      end
+    end
+  end
+end

data/spec/winston/csp_spec.rb

@@ -28,7 +28,7 @@ describe Winston::CSP do
   describe "#add_constraint" do
     let(:constraint) { double("Constraint") }
     it "should build a constraint for the given block" do
-      expect(Winston::Constraint).to receive(:new).with([:a, :b], an_instance_of(Proc)).once.and_return(constraint)
+      expect(Winston::Constraint).to receive(:new).with(variables: [:a, :b], allow_nil: false, predicate: an_instance_of(Proc)).once.and_return(constraint)
       subject.add_constraint(:a, :b) { true }
       expect(subject.constraints).to include(constraint)
     end
@@ -60,6 +60,25 @@ describe Winston::CSP do
     end
   end
 
+  describe "#domain_for" do
+    before do
+      subject.add_variable :a, value: 1
+      subject.add_variable :b, domain: [1, 2]
+    end
+
+    it "returns domain values for a given variable" do
+      expect(subject.domain_for(:b)).to eq([1, 2])
+    end
+
+    it "returns an empty list when a variable doesn't exist in the problem" do
+      expect(subject.domain_for(:c)).to be_empty
+    end
+
+    it "return an empty list when a variable doesn't have a domain" do
+      expect(subject.domain_for(:a)).to be_empty
+    end
+  end
+
   describe "#solve" do
     let(:solver) { double("Solver") }
     before do
@@ -68,8 +87,32 @@ describe Winston::CSP do
     end
 
     it "should pass a collection of preset variables to the solver" do
-      expect(solver).to receive(:search).with(a: 1)
+      expect(solver).to receive(:search).with({ a: 1 })
       subject.solve(solver)
     end
+
+    it "builds a solver by name with options" do
+      subject.add_constraint(:a, :b) { |a, b| a < b }
+      result = subject.solve(:backtrack, variable_strategy: :mrv)
+
+      expect(result).to eq({ a: 1, b: 2 })
+    end
+
+    it "raises for an unknown solver name" do
+      expect { subject.solve(:unknown) }.to raise_error(ArgumentError, /Unknown solver/)
+    end
+
+    it "returns false when preset assignments violate a constraint" do
+      subject.add_constraint(:a) { |a| a > 2 }
+      expect(solver).to_not receive(:search)
+      expect(subject.solve(solver)).to be(false)
+    end
+
+    it "returns false when a constraint among preset variables is violated" do
+      subject.add_variable :c, value: 2
+      subject.add_constraint(:a, :c) { |a, c| a == c }
+      expect(solver).to_not receive(:search)
+      expect(subject.solve(solver)).to be(false)
+    end
   end
 end

data/spec/winston/dsl_spec.rb

@@ -0,0 +1,71 @@
+require "winston"
+
+describe Winston::DSL do
+  describe ".define" do
+    it "builds a CSP with variables and constraints" do
+      csp = Winston.define do
+        var :a, domain: [1, 2, 3]
+        var :b, domain: [1, 2, 3]
+        constraint(:a, :b) { |a, b| a > b }
+      end
+
+      expect(csp.solve).to eq({ a: 2, b: 1 })
+    end
+
+    it "supports named domains" do
+      csp = Winston.define do
+        domain :digits, [1, 2, 3]
+        var :a, domain: :digits
+        var :b, domain: :digits
+        constraint(:a, :b) { |a, b| a != b }
+      end
+
+      result = csp.solve
+      expect([1, 2, 3]).to include(result[:a])
+      expect([1, 2, 3]).to include(result[:b])
+      expect(result[:a]).to_not eq(result[:b])
+    end
+
+    it "uses named constraints via use_constraint" do
+      csp = Winston.define do
+        var :a, domain: [1, 2]
+        var :b, domain: [1, 2]
+        use_constraint :all_different, :a, :b
+      end
+
+      expect(csp.solve).to eq({ a: 1, b: 2 })
+    end
+
+    it "passes options to named constraints" do
+      csp = Winston.define do
+        var :a, domain: [1, 2, 3]
+        use_constraint :not_in_list, :a, list: [1, 2]
+      end
+
+      expect(csp.solve).to eq({ a: 3 })
+    end
+  end
+
+  describe ".register_constraint" do
+    it "registers and uses a custom constraint by name" do
+      custom = Class.new(Winston::Constraint) do
+        def validate(assignments)
+          values = values_at(assignments)
+          values.all? { |v| v == 2 }
+        end
+      end
+
+      Winston.register_constraint(:all_twos) do |variables, allow_nil, **_options|
+        custom.new(variables: variables, allow_nil: allow_nil)
+      end
+
+      csp = Winston.define do
+        var :a, domain: [1, 2]
+        var :b, domain: [1, 2]
+        use_constraint :all_twos, :a, :b
+      end
+
+      expect(csp.solve).to eq({ a: 2, b: 2 })
+    end
+  end
+end

data/spec/winston/heuristics_spec.rb

@@ -0,0 +1,47 @@
+require "winston"
+
+describe Winston::Heuristics do
+  let(:csp) { Winston::CSP.new }
+
+  describe ".mrv" do
+    it "picks the variable with the fewest remaining values" do
+      csp.add_variable :a, domain: [1, 2, 3]
+      csp.add_variable :b, domain: [1, 2]
+      csp.add_variable :c, domain: [1, 2, 3]
+      csp.add_constraint(:a) { |a| a == 1 }
+
+      vars = csp.variables.each_value.to_a
+      chosen = described_class.mrv.call(vars, {}, csp)
+
+      expect(chosen.name).to eq(:a)
+    end
+  end
+
+  describe ".lcv" do
+    it "orders values to leave more options for other variables" do
+      csp.add_variable :a, domain: [2, 1]
+      csp.add_variable :b, domain: [2, 3]
+      csp.add_constraint(:a, :b) { |a, b| b > a }
+
+      values = csp.domain_for(:a)
+      ordered = described_class.lcv.call(values, csp.variables[:a], {}, csp)
+
+      expect(ordered).to eq([1, 2])
+    end
+  end
+
+  describe ".in_order" do
+    it "returns values as-is" do
+      values = [3, 1, 2]
+      ordered = described_class.in_order.call(values, nil, {}, csp)
+
+      expect(ordered).to eq(values)
+    end
+  end
+
+  describe ".forward_checking" do
+    it "returns true to enable forward checking" do
+      expect(described_class.forward_checking).to be(true)
+    end
+  end
+end

data/spec/winston/mac_spec.rb

@@ -0,0 +1,44 @@
+require "winston"
+
+describe Winston::Solvers::MAC do
+  let(:csp) { Winston::CSP.new }
+
+  def valid_solution?(csp, assignments)
+    csp.constraints.all? { |constraint| constraint.validate(assignments) }
+  end
+
+  it "solves a simple constraint problem" do
+    csp.add_variable :a, domain: [1, 2, 3]
+    csp.add_variable :b, domain: [1, 2, 3]
+    csp.add_variable :c, domain: [1, 2, 3]
+    csp.add_constraint(:a, :b) { |a, b| a > b }
+    csp.add_constraint(:b, :c) { |b, c| b > c }
+
+    solver = described_class.new(csp)
+    result = solver.search
+
+    expect(result).to be_a(Hash)
+    expect(valid_solution?(csp, result)).to be(true)
+  end
+
+  it "respects preset assignments" do
+    csp.add_variable :a, value: 2
+    csp.add_variable :b, domain: [1, 2, 3]
+    csp.add_constraint(:a, :b) { |a, b| a > b }
+
+    solver = described_class.new(csp)
+    result = solver.search
+
+    expect(result[:a]).to eq(2)
+    expect(valid_solution?(csp, result)).to be(true)
+  end
+
+  it "returns false when constraints are impossible" do
+    csp.add_variable :a, domain: [1]
+    csp.add_variable :b, domain: [1]
+    csp.add_constraint(:a, :b) { |a, b| a != b }
+
+    solver = described_class.new(csp)
+    expect(solver.search).to be(false)
+  end
+end

data/spec/winston/min_conflicts_spec.rb

@@ -0,0 +1,44 @@
+require "winston"
+
+describe Winston::Solvers::MinConflicts do
+  let(:csp) { Winston::CSP.new }
+
+  def valid_solution?(csp, assignments)
+    csp.constraints.all? { |constraint| constraint.validate(assignments) }
+  end
+
+  it "finds a valid solution for a simple problem" do
+    csp.add_variable :a, domain: [1, 2, 3]
+    csp.add_variable :b, domain: [1, 2, 3]
+    csp.add_variable :c, domain: [1, 2, 3]
+    csp.add_constraint(:a, :b) { |a, b| a > b }
+    csp.add_constraint(:b, :c) { |b, c| b > c }
+
+    solver = described_class.new(csp, max_steps: 1_000, random: Random.new(1))
+    result = solver.search
+
+    expect(result).to be_a(Hash)
+    expect(valid_solution?(csp, result)).to be(true)
+  end
+
+  it "respects preset assignments" do
+    csp.add_variable :a, value: 2
+    csp.add_variable :b, domain: [1, 2, 3]
+    csp.add_constraint(:a, :b) { |a, b| a > b }
+
+    solver = described_class.new(csp, max_steps: 1_000, random: Random.new(1))
+    result = solver.search
+
+    expect(result[:a]).to eq(2)
+    expect(valid_solution?(csp, result)).to be(true)
+  end
+
+  it "returns false when no solution is found within max_steps" do
+    csp.add_variable :a, domain: [1]
+    csp.add_variable :b, domain: [1]
+    csp.add_constraint(:a, :b) { |a, b| a != b }
+
+    solver = described_class.new(csp, max_steps: 10, random: Random.new(1))
+    expect(solver.search).to be(false)
+  end
+end

data/winston.gemspec

@@ -1,19 +1,20 @@
 Gem::Specification.new do |gem|
   gem.name        = 'winston'
-  gem.version     = '0.0.1'
+  gem.version     = '0.1.0'
   gem.authors     = ['David Michael Nelson']
   gem.homepage    = 'http://github.com/dmnelson/winston'
 
   gem.summary     = 'Constraint Satisfaction Problem (CSP) implementation for Ruby'
-  gem.description = gem.summary
+  gem.description = 'A small, practical CSP library for Ruby with multiple solvers, heuristics, and a DSL.'
   gem.license     = 'MIT'
+  gem.required_ruby_version = ">= 3.0"
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
-  gem.add_development_dependency "bundler", "~> 1.3"
-  gem.add_development_dependency "rake"
-  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency "bundler", "~> 2.4", ">= 2.4.22"
+  gem.add_development_dependency "rake", "~> 13.1"
+  gem.add_development_dependency "rspec", "~> 3.13"
 end