annealing 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5435b7e34667fdfd63782d895080435f7f2dffb685b2a918bba83bf6781f432
-  data.tar.gz: 82bfb71e31afed6d53e0649b35c373fc5ea27bcc19e6b72ae8522983df1d4734
+  metadata.gz: f42d7b6ef54f628c761f716ab2dffe55f227b1c3bac9c4e962c971bddc835961
+  data.tar.gz: 6a4a6673ce1e9893d6da3d8e4ff37781f98dd6108ab33819e6d1a1bb7d9cbf6b
 SHA512:
-  metadata.gz: 54dd58f3c4c2007aa0c6cd0ca264dc9a53ddb9680a354ea2808ff3c7a8ebcae5fc032aefb70f9cdbb6fe023cd23d0dff014254c99a577e2119172597cefd5202
-  data.tar.gz: 21c78d1a11bc7ddf2e9b02e916f3bb94986944ad37ceb08cddf5a70178b82477be414e8478d1d51f26220a147f8442f5594667152bce496b7b98897204ec221f
+  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: ['3.0']
+        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: ['3.0', '3.1', '3.2']
+        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: 3.0
+  TargetRubyVersion: 3.4
   NewCops: enable
   DefaultFormatter: progress
   DisplayCopNames: true

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.0", ">= 13.0.6"
-gem "rubocop", "~> 1.48.0"
-gem "rubocop-minitest", "~> 0.29.0"
-gem "rubocop-performance", "~> 1.16.0"
-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,51 +1,83 @@
 PATH
   remote: .
   specs:
-    annealing (0.4.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.6.0)
-    irb (1.6.3)
-      reline (>= 0.3.0)
-    json (2.6.3)
-    minitest (5.18.0)
-    parallel (1.22.1)
-    parser (3.2.1.1)
+    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)
+      racc
+    pp (0.6.4)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.7.0)
-    reline (0.3.2)
+    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.48.0)
+    rubocop (1.88.2)
       json (~> 2.3)
-      parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      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 (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.26.0, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.27.0)
-      parser (>= 3.2.1.0)
-    rubocop-minitest (0.29.0)
-      rubocop (>= 1.39, < 2.0)
-    rubocop-performance (1.16.0)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
-    rubocop-rake (0.6.0)
-      rubocop (~> 1.0)
-    ruby-prof (1.6.1)
+      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)
-    unicode-display_width (2.4.2)
+    tsort (0.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
 
 PLATFORMS
   ruby
@@ -53,13 +85,13 @@ PLATFORMS
 DEPENDENCIES
   annealing!
   debug (>= 1.0.0)
-  minitest (~> 5.0)
-  rake (~> 13.0.0, >= 13.0.6)
-  rubocop (~> 1.48.0)
-  rubocop-minitest (~> 0.29.0)
-  rubocop-performance (~> 1.16.0)
-  rubocop-rake (~> 0.6.0)
-  ruby-prof (~> 1.6, >= 1.6.1)
+  minitest (~> 5.22)
+  rake (~> 13.0, >= 13.0.6)
+  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.4.4
+   2.7.2

data/README.md

@@ -213,6 +213,10 @@ Annealing.configuration.termination_condition = lambda do |_state, energy, tempe
 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(">= 3.0.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.6", ">= 1.6.1"
   spec.metadata["rubygems_mfa_required"] = "true"
 end

data/bin/run

@@ -44,14 +44,20 @@ 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).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).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.rb

@@ -5,12 +5,14 @@ module Annealing
   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,
+                  :return_best,
                   :state_change,
                   :temperature,
                   :termination_condition
@@ -20,6 +22,7 @@ module Annealing
       @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
@@ -39,6 +42,8 @@ module Annealing
                   "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?
@@ -56,6 +61,7 @@ module Annealing
         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

data/lib/annealing/metal.rb

@@ -27,14 +27,20 @@ module Annealing
       end
     end
 
+    def lower_energy?(cooled_metal)
+      cooled_metal.energy < energy
+    end
+
     private
 
     # 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)
-      return true if cooled_metal.energy < energy
+      lower_energy?(cooled_metal) || prefer_despite_higher_energy?(cooled_metal)
+    end
 
+    def prefer_despite_higher_energy?(cooled_metal)
       energy_delta = energy - cooled_metal.energy
       (Math::E**(energy_delta / cooled_metal.temperature)) > rand
     end

data/lib/annealing/simulator.rb

@@ -9,18 +9,24 @@ module Annealing
       @configuration = Annealing.configuration.merge(config_hash)
     end
 
+    # rubocop:disable Metrics/MethodLength
     def run(initial_state, config_hash = {})
       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?(current, runtime_config)
           steps += 1
           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
-        current
+        final_or_best(current, best, runtime_config)
       end
     end
+    # rubocop:enable Metrics/MethodLength
 
     private
 
@@ -48,5 +54,14 @@ module Annealing
                                         metal.energy,
                                         metal.temperature)
     end
+
+    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.4.0"
+  VERSION = "0.4.1"
 end

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.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Luis Ezcurdia
 - Chris Bloom
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-09 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.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.6.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.6.1
+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
@@ -61,6 +41,7 @@ files:
 - lib/annealing/metal.rb
 - lib/annealing/simulator.rb
 - lib/annealing/version.rb
+- mise.toml
 homepage: https://github.com/3zcurdia/annealing
 licenses:
 - MIT
@@ -69,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
@@ -77,15 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Simulated Annealing
 test_files: []