annealing 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b20378dea6d3ebcee0d0adca58d721576605d17c34c91a1828f887733c5fc5e
-  data.tar.gz: 62935118c575c16e8e0efaaf58224845fc8e975f230ac58b81da41cf66a9c08c
+  metadata.gz: f42d7b6ef54f628c761f716ab2dffe55f227b1c3bac9c4e962c971bddc835961
+  data.tar.gz: 6a4a6673ce1e9893d6da3d8e4ff37781f98dd6108ab33819e6d1a1bb7d9cbf6b
 SHA512:
-  metadata.gz: 4916ea9c5c854ce9891b9264d7dfe117f56da58fb906735f2afb015f2a0acf08757702991d988ed82096910225cca25794b78e135635d03b41dcf51496543a72
-  data.tar.gz: f3c74cb98d4b45512fd78bf6e18dfc751550ba33f6ccfa4ab80720d01dcdf4a1a0ec7215387033523792a503876e4abd6bc7b017330539a8367bed3da3a23741
+  metadata.gz: 03b9fbc0ef5c027ba6f9d33a9eee1ae120c134f4d436916f076b1829ca170343b778da279096e01eda72d377c7370baf170e88315951c70e23fe39cd86315579
+  data.tar.gz: 3402a3824fdc915abccda29fc57ce0ab320547b44fd74a7df5b70c3171e1a08fe88b55d81582419813fb13b71e182f0dae51d4967e309a3017517abe210ffa8b

data/.github/workflows/ruby.yml

@@ -18,9 +18,9 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.6']
+        ruby-version: ['4.0']
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -32,10 +32,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.6', '2.7', '3.0', '3.1']
+        ruby-version: ['3.4', '4.0']
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.rubocop.yml

@@ -1,12 +1,12 @@
 inherit_from: .rubocop_todo.yml
 
-require:
+plugins:
   - rubocop-performance
   - rubocop-minitest
   - rubocop-rake
 
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.4
   NewCops: enable
   DefaultFormatter: progress
   DisplayCopNames: true

data/.rubocop_todo.yml

@@ -1,42 +1,54 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config --auto-gen-only-exclude`
-# on 2022-02-18 23:32:32 UTC using RuboCop version 1.23.0.
+# on 2022-12-12 19:04:19 UTC using RuboCop version 1.23.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 9
+# Offense count: 7
 # Configuration parameters: IgnoredMethods, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
-    - 'test/annealing/configuration/configurator_test.rb'
+    - 'lib/annealing/configuration.rb'
+    - 'test/annealing/configuration_test.rb'
     - 'test/annealing/metal_test.rb'
     - 'test/annealing/simulator_test.rb'
     - 'test/annealing_test.rb'
 
-# Offense count: 3
+# Offense count: 2
 # Configuration parameters: CountComments, Max, CountAsOne.
 Metrics/ClassLength:
   Exclude:
-    - 'test/annealing/configuration/configurator_test.rb'
-    - 'test/annealing/metal_test.rb'
+    - 'test/annealing/configuration_test.rb'
     - 'test/annealing/simulator_test.rb'
 
-# Offense count: 13
+# Offense count: 1
+# Configuration parameters: IgnoredMethods, Max.
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'lib/annealing/configuration.rb'
+
+# Offense count: 11
 # Configuration parameters: CountComments, Max, CountAsOne, ExcludedMethods, IgnoredMethods.
 Metrics/MethodLength:
   Exclude:
     - 'lib/annealing/configuration.rb'
-    - 'lib/annealing/simulator.rb'
-    - 'test/annealing/configuration/configurator_test.rb'
+    - 'test/annealing/configuration_test.rb'
     - 'test/annealing/metal_test.rb'
     - 'test/annealing/simulator_test.rb'
     - 'test/annealing_test.rb'
 
-# Offense count: 8
+# Offense count: 1
+# Configuration parameters: IgnoredMethods, Max.
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/annealing/configuration.rb'
+
+# Offense count: 5
 # Configuration parameters: Max.
 Minitest/MultipleAssertions:
   Exclude:
-    - 'test/annealing/configuration/configurator_test.rb'
+    - 'test/annealing/configuration/terminators_test.rb'
     - 'test/annealing/configuration_test.rb'
+    - 'test/annealing/simulator_test.rb'

data/AGENTS.md

@@ -0,0 +1,53 @@
+# AGENTS.md
+
+Reference for AI agents (and humans) working in this repo. A Ruby gem implementing
+simulated annealing. See `README.md` for the public API and configuration precedence
+(global < instance < just-in-time).
+
+## Commands
+
+- Setup: `bin/setup` (runs `bundle install`).
+- Full default check (order matters): `bundle exec rake` — runs `test`, then `end_to_end_test`, then `rubocop`.
+- Run tests only: `bundle exec rake test`.
+- Run a single test file: `bundle exec ruby -Ilib:test test/path/to_test.rb` (or `rake test TEST=...`).
+- Lint only: `bundle exec rubocop` (or `bundle exec rake rubocop`).
+- Interactive console: `bin/console`. Runnable demo: `bin/run`.
+
+## Gotchas
+
+- `rake`'s default task includes `bin/run` via the `end_to_end_test` task. It runs a
+  real (slow, non-deterministic due to `rand`) annealing simulation; skip it with
+  `rake test rubocop` when you only want fast feedback.
+- Tests use Minitest. `test/test_helper.rb` requires `ruby-prof` and `debug` — both are
+  dev deps in the `Gemfile`; ensure they're installed (`bundle install`) before running tests.
+- `Annealing.configuration` is a global singleton. Tests reset it in
+  `Minitest::Test#teardown` by setting `Annealing.configuration = nil`. When writing
+  tests that touch global config, favor scoped instance/JIT config or rely on teardown.
+- `Metal#cool!` is non-idempotent and depends on `rand`; never assume deterministic
+  output from a single run.
+- `Simulator#run` raises `ConfigurationError` ( subclass of `Annealing::Error`) on
+  invalid config; validation happens lazily at run time, not at `Simulator.new`.
+
+## Style / rubocop
+
+- Inherited from `.rubocop.yml` + `.rubocop_todo.yml`. `TargetRubyVersion: 3.4`,
+  `Layout/LineLength: Max 120`, double-quoted strings, NewCops enabled with rubocop-
+  performance/-minitest/-rake plugins loaded.
+- CI lint job runs `bundle exec rubocop --parallel` on Ruby 4.0; test matrix is 3.4/4.0
+  (see `.github/workflows/ruby.yml`). Keep code compatible with 3.4.
+
+## Architecture
+
+- Entry: `Annealing.simulate` (lib/annealing.rb) — thin wrapper over
+  `Annealing::Simulator.new(...).run(...).state`.
+- `Simulator` (lib/annealing/simulator.rb) drives the loop, merging configs at runtime
+  and calling `Metal#cool!` each step until `termination_condition` returns truthy.
+- `Metal` (lib/annealing/metal.rb) holds current `state`, `temperature`, and lazily
+  computed `energy`; `cool!` applies the probabilistic accept/reject step.
+- `Configuration` (lib/annealing/configuration.rb) plus concrete
+  `Configuration::Coolers` and `Configuration::Terminators` provide built-in callables.
+
+## Release
+
+Bump `lib/annealing/version.rb`, then `bundle exec rake release` (tags, pushes, releases
+to rubygems.org; `rubygems_mfa_required` is set in the gemspec).

data/CHANGELOG.md

@@ -1,5 +1,17 @@
-## [Unreleased]
+## [0.4.1] - 2026-07-16
 
+- Add return_best config option. When true, returns the best (lowest energy) state. When false, returns the final state (preserves old behavior).
+- Bump minimum supported Ruby version to 3.4.0 and add Ruby 4.0 support.
+- Refresh development dependencies (rubocop, ruby-prof, and plugins) to versions
+  compatible with Ruby 4.0.
+- Bump RuboCop `TargetRubyVersion` to 3.4 and CI test matrix to 3.4 / 4.0.
+
+## [0.4.0] - 2023-03-09
+
+- Rename method and add comments to clarify use by @chrisbloom7 in #20
+- Config Cleanup: remove logger config by @chrisbloom7 in #21
+- Simply configuration and overrides by @chrisbloom7 in #22
+- Idea: Add library of built-in functions by @chrisbloom7 in #23
 
 ## [0.3.0] - 2022-02-21
 

data/Gemfile

@@ -5,10 +5,13 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in annealing.gemspec
 gemspec
 
-gem "debug", ">= 1.0.0", require: false
-gem "minitest", "~> 5.0"
-gem "rake", "~> 13.0", ">= 13.0.6"
-gem "rubocop", "~> 1.23"
-gem "rubocop-minitest", "~> 0.17.0"
-gem "rubocop-performance", "~> 1.12"
-gem "rubocop-rake", "~> 0.6.0"
+group :development do
+  gem "debug", ">= 1.0.0", require: false
+  gem "minitest", "~> 5.22"
+  gem "rake", "~> 13.0", ">= 13.0.6"
+  gem "rubocop", "~> 1.78"
+  gem "rubocop-minitest", "~> 0.37"
+  gem "rubocop-performance", "~> 1.25"
+  gem "rubocop-rake", "~> 0.7"
+  gem "ruby-prof", "~> 1.7", ">= 1.7.0"
+end

data/Gemfile.lock

@@ -1,49 +1,83 @@
 PATH
   remote: .
   specs:
-    annealing (0.2.0)
+    annealing (0.4.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    ast (2.4.2)
-    debug (1.4.0)
-      irb (>= 1.3.6)
-      reline (>= 0.2.7)
-    io-console (0.5.11)
-    irb (1.4.1)
-      reline (>= 0.3.0)
-    minitest (5.14.4)
-    parallel (1.21.0)
-    parser (3.0.3.2)
+    ast (2.4.3)
+    base64 (0.3.0)
+    debug (1.11.1)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    erb (6.0.4)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.27.0)
+    parallel (2.1.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
-    rainbow (3.0.0)
-    rake (13.0.6)
-    regexp_parser (2.2.0)
-    reline (0.3.1)
+      racc
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    rbs (4.0.3)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (8.0.0)
+      erb
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.6.3)
       io-console (~> 0.5)
-    rexml (3.2.5)
-    rubocop (1.23.0)
-      parallel (~> 1.10)
-      parser (>= 3.0.0.0)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.12.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.14.0)
-      parser (>= 3.0.1.1)
-    rubocop-minitest (0.17.0)
-      rubocop (>= 0.90, < 2.0)
-    rubocop-performance (1.12.0)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
-    rubocop-rake (0.6.0)
-      rubocop (~> 1.0)
-    ruby-prof (1.4.3)
-    ruby-progressbar (1.11.0)
-    unicode-display_width (2.1.0)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-minitest (0.39.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    ruby-prof (1.7.2)
+      base64
+    ruby-progressbar (1.13.0)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   ruby
@@ -51,13 +85,13 @@ PLATFORMS
 DEPENDENCIES
   annealing!
   debug (>= 1.0.0)
-  minitest (~> 5.0)
+  minitest (~> 5.22)
   rake (~> 13.0, >= 13.0.6)
-  rubocop (~> 1.23)
-  rubocop-minitest (~> 0.17.0)
-  rubocop-performance (~> 1.12)
-  rubocop-rake (~> 0.6.0)
-  ruby-prof (~> 1.4, >= 1.4.3)
+  rubocop (~> 1.78)
+  rubocop-minitest (~> 0.37)
+  rubocop-performance (~> 1.25)
+  rubocop-rake (~> 0.7)
+  ruby-prof (~> 1.7, >= 1.7.0)
 
 BUNDLED WITH
-   2.1.4
+   2.7.2

data/README.md

@@ -102,12 +102,26 @@ The annealer supports a number of configuration options. See the [configuration
 
 ### `cool_down`
 
-By default, the simulation will decrease the `temperature` linearly by `cooling_rate` on each step of the annealing process. In some cases you may wish to override this to use a different cooling algorithm. To do so, you can specify a custom `cool_down` function. The function can be any object that responds to `#call` and accepts three arguments: the `energy` calculation of the current object, the current `temperature` of the annealer, the `cooling_rate` for the simulation, and the number of `steps` the annealer has taken so far. It should return the new temperature as a Float.
+By default, the simulation will decrease the `temperature` linearly by `cooling_rate` on each step of the annealing process. In some cases you may wish to override this to use a different cooling algorithm. To do so, you can use one of the other built-in cooling functions or you can specify a custom `cool_down` function. Custom functions can be any object that responds to `#call` and accepts four arguments: the `energy` calculation of the current object, the current `temperature` of the annealer, the `cooling_rate` for the simulation, and the number of `steps` the annealer has taken so far. It should return the new temperature as a Float.
 
 ```ruby
-Annealing.configuration.cool_down = lambda do |_energy, temperature, cooling_rate, steps|
-  # Reduce temperature exponentially
-  temperature - (cooling_rate * (steps**2))
+# Use the built-in linear cool-down function (the default)
+Annealing.configuration.cool_down = Annealing::Configuration::Coolers.linear
+
+# Use the built-in exponential cool-down function
+Annealing.configuration.cool_down = Annealing::Configuration::Coolers.exponential
+
+# Use the built-in geometric cool-down function with a custom ratio (default ratio is 2)
+Annealing.configuration.cool_down = Annealing::Configuration::Coolers.exponential(1.5)
+
+# Use a custom cool down function
+Annealing.configuration.cool_down = lambda do |energy, temperature, cooling_rate, steps|
+  # Reduce temperature exponentially when the temperature is above 500, then linearly
+  if temperature > 500
+    Annealing::Configuration::Coolers.exponential.call(energy, temperature, cooling_rate, steps)
+  else
+    Annealing::Configuration::Coolers.linear.call(energy, temperature, cooling_rate, steps)
+  end
 end
 ```
 
@@ -161,16 +175,6 @@ calculator = PotentialSalesCalculator.new(8)
 Annealing.configuration.energy_calculator = calculator.method(:energy)
 ```
 
-### `logger`
-
-The default logger is a standard Ruby Logger that writes to stdout. You can specify a different `logger` if you wish.
-
-```ruby
-logger = Logger.new('logfile.log')
-logger.level = Logger::DEBUG
-Annealing.configuration.logger = logger
-```
-
 ### `state_change`
 
 As with `energy_calculator`, you must specify a `state_change` function in order to run any simulations; no default function is provided. The function can be any object that responds to `#call` and accepts a single argument: the `state` representing the current state that should be changed. It should return the changed state.
@@ -193,15 +197,26 @@ Annealing.configuration.state_change = instance.method(:state_change)
 
 ### `termination_condition`
 
-By default, a simulation will run until the temperature reaches 0. In some cases, you might want to specify a termination condition that will stop the annealing process as soon as some other condition is met regardless of the current temperature. You can define a custom `termination_condition` function, which can be any object that responds to `#call` and accepts three arguments: the current `state` of the object, the `energy` calculation of the current object, and the current `temperature` of the simulation. It should return a boolean value where `true` indicates the simulation should stop.
+By default, a simulation will run until the temperature reaches 0. In some cases, you might want to specify a termination condition that will stop the annealing process as soon as some other condition is met regardless of the current temperature. To do so, you can use one of the other built-in termination condition functions or you can specify a custom one. Custom `termination_condition` functions can be any object that responds to `#call` and accepts three arguments: the current `state` of the object, the `energy` calculation of the current object, and the current `temperature` of the simulation. It should return a boolean value where `true` indicates the simulation should stop.
 
 ```ruby
+# Use the built-in zero-temperature termination condition function
+Annealing.configuration.termination_condition = Annealing::Configuration::Terminators.temp_is_zero?
+
+# Use the built-in zero-energy termination condition function
+Annealing.configuration.termination_condition = Annealing::Configuration::Terminators.energy_or_temp_is_zero?
+
+# Use a custom termination condition function
 Annealing.configuration.termination_condition = lambda do |_state, energy, temperature|
-  # Stop early if we encounter any 0-energy state
-  energy == 0 || temperature <= 0.0
+  # Stop if the energy is below 500 and the temperature is below 100, or the temperature is already 0
+  temperature <= 0 || (energy <= 500 && temperature <= 500)
 end
 ```
 
+### 'return_best'
+
+If true (the default), will return the best (lowest energy) state seen during the simulation. If false, Simulator#run will return the final state reached when the simulation completes.
+
 ## Configuration precedence
 
 Configuration options can be set globally using `Annealing.configuration` or `Annealing.configure`, on `Annealing::Simulator.new` to be used on all subsequent runs of that instance, and just-in-time on `Annealing.simulate` and `Annealing::Simulator#run`. They are applied in reverse order of precedence.

data/annealing.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.summary       = "Simulated Annealing"
   spec.description   = "Simulated Annealing algoritm implementation."
   spec.homepage      = "https://github.com/3zcurdia/annealing"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.4.0")
 
   # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
 
@@ -29,6 +29,5 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "ruby-prof", "~> 1.4", ">= 1.4.3"
   spec.metadata["rubygems_mfa_required"] = "true"
 end

data/bin/run

@@ -39,20 +39,25 @@ state_change = lambda do |state|
   swapped
 end
 
-Annealing.configuration.logger.level = Logger::DEBUG
 simulator = Annealing::Simulator.new(temperature: 10_000, cooling_rate: 0.01)
 solution = simulator.run(locations,
                          energy_calculator: energy_calculator,
                          state_change: state_change)
 
+initial_energy = energy_calculator.call(locations)
 puts "\nInitial itinerary:"
-locations.each_cons(2).each_with_index do |(location1, location2), index|
+locations.each_cons(2).with_index do |(location1, location2), index|
   puts "Stop ##{index + 1}: #{location1.name} -> #{location2.name} (#{location1.distance(location2)})"
 end
-puts "-------\nEnergy: #{energy_calculator.call(locations)}"
+puts "-------\nEnergy: #{initial_energy}"
 
 puts "\nAnnealed itinerary:"
-solution.state.each_cons(2).each_with_index do |(location1, location2), index|
+solution.state.each_cons(2).with_index do |(location1, location2), index|
   puts "Stop ##{index + 1}: #{location1.name} -> #{location2.name} (#{location1.distance(location2)})"
 end
 puts "-------\nEnergy: #{solution.energy}"
+
+if solution.energy > initial_energy
+  raise "Annealing failed: solution energy #{solution.energy}\
+ ought to be less than or equal to than initial energy #{initial_energy}"
+end

data/lib/annealing/configuration/coolers.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Annealing
+  class Configuration
+    # Built-in cool down functions
+    module Coolers
+      module_function
+
+      # Reduce temperature linearly by the cooling rate
+      def linear
+        lambda { |_energy, temperature, cooling_rate, _steps|
+          temperature - cooling_rate
+        }
+      end
+
+      # Reduce temperature exponentially on each step by the cooling rate
+      def exponential
+        lambda { |_energy, temperature, cooling_rate, steps|
+          temperature - (Math.exp(steps - 1) * cooling_rate)
+        }
+      end
+
+      # Reduce temperature geometrically at a given ratio by the cooling rate
+      def geometric(ratio = 2)
+        unless ratio.positive?
+          raise(Annealing::Configuration::ConfigurationError,
+                "geometric ratio must be positive")
+        end
+
+        lambda { |_energy, temperature, cooling_rate, steps|
+          temperature - (cooling_rate * (ratio**(steps - 1)))
+        }
+      end
+    end
+  end
+end

data/lib/annealing/configuration/terminators.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Annealing
+  class Configuration
+    # Built-in termination condition check functions
+    module Terminators
+      module_function
+
+      # Returns true when the temperature is at or below zero
+      def temp_is_zero?
+        lambda { |_state, _energy, temperature|
+          temperature <= 0
+        }
+      end
+
+      # Returns true if a 0-energy state is detected, or when the temperature
+      # is at or below zero
+      def energy_or_temp_is_zero?
+        lambda { |state, energy, temperature|
+          energy <= 0 || temp_is_zero?.call(state, energy, temperature)
+        }
+      end
+    end
+  end
+end

data/lib/annealing/configuration.rb

@@ -3,28 +3,76 @@
 module Annealing
   # It enables the gem configuration
   class Configuration
+    DEFAULT_COOLING_RATE = 0.0003
+    DEFAULT_INITIAL_TEMPERATURE = 10_000.0
+    DEFAULT_RETURN_BEST = false
+
+    class ConfigurationError < Annealing::Error; end
+
     attr_accessor :cool_down,
                   :cooling_rate,
                   :energy_calculator,
-                  :logger,
+                  :return_best,
                   :state_change,
                   :temperature,
                   :termination_condition
 
-    def initialize
-      @cool_down = lambda do |_energy, temperature, cooling_rate, _steps|
-        # Reduce the temperature linearly by default
-        temperature - cooling_rate
-      end
-      @cooling_rate = 0.0003
-      @energy_calculator = nil
-      @logger = Logger.new($stdout, level: Logger::INFO)
-      @state_change = nil
-      @temperature  = 10_000.0
-      @termination_condition = lambda do |_state, _energy, temperature|
-        # Terminate the simulation as soon as the temperature reaches 0
-        temperature <= 0.0
-      end
+    def initialize(config_hash = {})
+      @cool_down = config_hash.fetch(:cool_down, Coolers.linear)
+      @cooling_rate = config_hash.fetch(:cooling_rate,
+                                        DEFAULT_COOLING_RATE).to_f
+      @energy_calculator = config_hash.fetch(:energy_calculator, nil)
+      @return_best = config_hash.fetch(:return_best, DEFAULT_RETURN_BEST)
+      @state_change = config_hash.fetch(:state_change, nil)
+      @temperature  = config_hash.fetch(:temperature,
+                                        DEFAULT_INITIAL_TEMPERATURE).to_f
+      @termination_condition = config_hash.fetch(:termination_condition,
+                                                 Terminators.temp_is_zero?)
+    end
+
+    # Return new configuration that merges new attributes with current
+    def merge(config_hash)
+      self.class.new(attributes.merge(config_hash))
+    end
+
+    def validate!
+      message = if !callable?(cool_down)
+                  "Missing cool down function"
+                elsif cooling_rate.negative?
+                  "Cooling rate cannot be negative"
+                elsif !callable?(energy_calculator)
+                  "Missing energy calculator function"
+                elsif ![true, false].include?(return_best)
+                  "'Return best' specification must be either true or false"
+                elsif !callable?(state_change)
+                  "Missing state change function"
+                elsif temperature.negative?
+                  "Initial temperature cannot be negative"
+                elsif !callable?(termination_condition)
+                  "Missing termination condition function"
+                end
+      raise(ConfigurationError, message) if message
+    end
+
+    private
+
+    def attributes
+      {
+        cool_down: cool_down,
+        cooling_rate: cooling_rate,
+        energy_calculator: energy_calculator,
+        return_best: return_best,
+        state_change: state_change,
+        temperature: temperature,
+        termination_condition: termination_condition
+      }
+    end
+
+    def callable?(attribute)
+      attribute.respond_to?(:call)
     end
   end
 end
+
+require "annealing/configuration/coolers"
+require "annealing/configuration/terminators"

data/lib/annealing/metal.rb

@@ -3,28 +3,23 @@
 module Annealing
   # It manages the total energy of a given collection
   class Metal
-    include Configuration::Configurator
-    attr_reader :state, :temperature
+    attr_reader :configuration, :state, :temperature
 
-    def initialize(current_state, current_temperature, **config)
-      init_configuration(config)
+    def initialize(current_state, current_temperature, configuration = nil)
+      @configuration = configuration || Annealing.configuration.merge({})
       @state = current_state
       @temperature = current_temperature
-
-      raise(ArgumentError, "Missing energy calculator function") unless energy_calculator.respond_to?(:call)
-
-      raise(ArgumentError, "Missing state change function") unless state_change.respond_to?(:call)
     end
 
     def energy
-      @energy ||= energy_calculator.call(state)
+      @energy ||= configuration.energy_calculator.call(state)
     end
 
     # This method is not idempotent!
     # It relies on random probability to select the next state
     def cool!(new_temperature)
       cooled_metal = cool(new_temperature)
-      if better_than?(cooled_metal)
+      if prefer?(cooled_metal)
         cooled_metal
       else
         @temperature = new_temperature
@@ -32,32 +27,27 @@ module Annealing
       end
     end
 
-    def to_s
-      format("%<temperature>.4f:%<energy>.4f:%<value>s",
-             temperature: temperature,
-             energy: energy,
-             value: state)
+    def lower_energy?(cooled_metal)
+      cooled_metal.energy < energy
     end
 
     private
 
-    def energy_calculator
-      current_config_for(:energy_calculator)
-    end
-
-    def state_change
-      current_config_for(:state_change)
+    # True if cooled_metal.energy is lower than current energy, otherwise let
+    # probability determine if we should accept a higher value over a lower
+    # value
+    def prefer?(cooled_metal)
+      lower_energy?(cooled_metal) || prefer_despite_higher_energy?(cooled_metal)
     end
 
-    def better_than?(cooled_metal)
+    def prefer_despite_higher_energy?(cooled_metal)
       energy_delta = energy - cooled_metal.energy
-      energy_delta.positive? ||
-        (Math::E**(energy_delta / cooled_metal.temperature)) > rand
+      (Math::E**(energy_delta / cooled_metal.temperature)) > rand
     end
 
     def cool(new_temperature)
-      next_state = state_change.call(state)
-      Metal.new(next_state, new_temperature, **configuration_overrides)
+      next_state = configuration.state_change.call(state)
+      Metal.new(next_state, new_temperature, configuration)
     end
   end
 end

data/lib/annealing/simulator.rb

@@ -3,68 +3,65 @@
 module Annealing
   # It runs simulated annealing
   class Simulator
-    include Configuration::Configurator
+    attr_reader :configuration
 
-    def initialize(**config)
-      init_configuration(config)
+    def initialize(config_hash = {})
+      @configuration = Annealing.configuration.merge(config_hash)
     end
 
+    # rubocop:disable Metrics/MethodLength
     def run(initial_state, config_hash = {})
-      with_configuration_overrides(config_hash) do
-        validate_configuration!
-        current = Metal.new(initial_state, temperature,
-                            **configuration_overrides)
-        Annealing.logger.debug("Original: #{current}")
+      with_runtime_config(config_hash) do |runtime_config|
+        initial_temperature = runtime_config.temperature
+        current = Metal.new(initial_state, initial_temperature, runtime_config)
+        best = current
         steps = 0
-        until termination_condition_met?(termination_condition, current)
+        until termination_condition_met?(current, runtime_config)
           steps += 1
-          current = reduce_temperature(cool_down, current, steps)
+          current = reduce_temperature(current, steps, runtime_config)
+          # If the current state has lower energy than the previous best (lowest energy) state
+          # we've seen so far, the current state is the new best state.
+          best = current if best.lower_energy?(current)
         end
-        Annealing.logger.debug("Optimized: #{current}")
-        current
+        final_or_best(current, best, runtime_config)
       end
     end
+    # rubocop:enable Metrics/MethodLength
 
     private
 
-    def cool_down
-      current_config_for(:cool_down)
+    # Wrapper for public methods that may use a custom configuration
+    def with_runtime_config(config_hash)
+      runtime_config = if config_hash.is_a?(Hash) && config_hash.any?
+                         configuration.merge(config_hash)
+                       else
+                         configuration
+                       end
+      runtime_config.validate!
+      yield(runtime_config)
     end
 
-    def cooling_rate
-      current_config_for(:cooling_rate).to_f
-    end
-
-    def logger
-      current_config_for(:logger)
-    end
-
-    def temperature
-      current_config_for(:temperature).to_f
-    end
-
-    def termination_condition
-      current_config_for(:termination_condition)
-    end
-
-    def reduce_temperature(cool_down, metal, steps)
-      new_temperature = cool_down.call(metal.energy, metal.temperature,
-                                       cooling_rate, steps)
+    def reduce_temperature(metal, steps, config)
+      new_temperature = config.cool_down.call(metal.energy,
+                                              metal.temperature,
+                                              config.cooling_rate,
+                                              steps)
       metal.cool!(new_temperature)
     end
 
-    def termination_condition_met?(termination_condition, metal)
-      termination_condition.call(metal.state, metal.energy, metal.temperature)
+    def termination_condition_met?(metal, config)
+      config.termination_condition.call(metal.state,
+                                        metal.energy,
+                                        metal.temperature)
     end
 
-    def validate_configuration!
-      raise(ArgumentError, "Invalid initial temperature") if temperature.negative?
-
-      raise(ArgumentError, "Invalid initial cooling rate") if cooling_rate.negative?
-
-      raise(ArgumentError, "Missing cool down function") unless cool_down.respond_to?(:call)
-
-      raise(ArgumentError, "Missing termination condition function") unless termination_condition.respond_to?(:call)
+    def final_or_best(final, best, config)
+      if config.return_best
+        # preserve the temperature
+        Metal.new(best.state, final.temperature, config)
+      else
+        final
+      end
     end
   end
 end

data/lib/annealing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Annealing
-  VERSION = "0.3.0"
+  VERSION = "0.4.1"
 end

data/lib/annealing.rb

@@ -1,12 +1,5 @@
 # frozen_string_literal: true
 
-require "logger"
-require "annealing/version"
-require "annealing/configuration"
-require "annealing/configuration/configurator"
-require "annealing/metal"
-require "annealing/simulator"
-
 # Simulated Annealing algoritm
 # https://en.wikipedia.org/wiki/Simulated_annealing
 module Annealing
@@ -23,13 +16,15 @@ module Annealing
 
   def self.configure
     yield(configuration)
+    configuration
   end
 
   def self.simulate(initial_state, config_hash = {})
     Simulator.new.run(initial_state, config_hash).state
   end
-
-  def self.logger
-    configuration.logger
-  end
 end
+
+require "annealing/configuration"
+require "annealing/metal"
+require "annealing/simulator"
+require "annealing/version"

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "4.0.5"

metadata

@@ -1,36 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: annealing
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Luis Ezcurdia
 - Chris Bloom
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-02-22 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: ruby-prof
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.4.3
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.4'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.4.3
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
 description: Simulated Annealing algoritm implementation.
 email:
 - ing.ezcurdia@gmail.com
@@ -43,6 +22,7 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -56,10 +36,12 @@ files:
 - bin/setup
 - lib/annealing.rb
 - lib/annealing/configuration.rb
-- lib/annealing/configuration/configurator.rb
+- lib/annealing/configuration/coolers.rb
+- lib/annealing/configuration/terminators.rb
 - lib/annealing/metal.rb
 - lib/annealing/simulator.rb
 - lib/annealing/version.rb
+- mise.toml
 homepage: https://github.com/3zcurdia/annealing
 licenses:
 - MIT
@@ -68,7 +50,6 @@ metadata:
   source_code_uri: https://github.com/3zcurdia/annealing
   changelog_uri: https://github.com/3zcurdia/annealing/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -76,15 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Simulated Annealing
 test_files: []

data/lib/annealing/configuration/configurator.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module Annealing
-  class Configuration
-    # Configuration mixin
-    module Configurator
-      def self.included(base)
-        base.send :include, InstanceMethods
-      end
-
-      # Mixin methods
-      module InstanceMethods
-        def init_configuration(config_hash = {})
-          @instance_configuration = config_hash
-          @temporary_configuration = {}
-        end
-
-        def with_configuration_overrides(local_config_hash = {})
-          @temporary_configuration = local_config_hash
-          yield
-        ensure
-          @temporary_configuration = {}
-        end
-
-        def configuration_overrides
-          instance_configuration.merge(temporary_configuration)
-        end
-
-        private
-
-        attr_accessor :instance_configuration, :temporary_configuration
-
-        def current_config_for(config)
-          temporary_configuration[config] ||
-            instance_configuration[config] ||
-            Annealing.configuration.public_send(config)
-        end
-      end
-    end
-  end
-end