annealing 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53e5900add60de36b8e3bb441be9bce450f6dcb3cbd67552913684745e90a0c1
-  data.tar.gz: 00347f761988a73951ed950317c1fc6ebf6d1add2d2ab1889bf8cbe6eebabe36
+  metadata.gz: c5435b7e34667fdfd63782d895080435f7f2dffb685b2a918bba83bf6781f432
+  data.tar.gz: 82bfb71e31afed6d53e0649b35c373fc5ea27bcc19e6b72ae8522983df1d4734
 SHA512:
-  metadata.gz: ef3653ce209af0a76189157cdecbbac58613aa86845b0e8476a22407fc17b9edb75e879f1676497eb7f1d8b4f86549719f67825f7c48db134603ed784d2d5ef1
-  data.tar.gz: 022accd062db4cc155e50606d22ea7e51db7603a61ef9b40512625110d528975de275b1abbb5ea6604fa98162122ef8b5e143f474593536af4291089e4d3f229
+  metadata.gz: 54dd58f3c4c2007aa0c6cd0ca264dc9a53ddb9680a354ea2808ff3c7a8ebcae5fc032aefb70f9cdbb6fe023cd23d0dff014254c99a577e2119172597cefd5202
+  data.tar.gz: 21c78d1a11bc7ddf2e9b02e916f3bb94986944ad37ceb08cddf5a70178b82477be414e8478d1d51f26220a147f8442f5594667152bce496b7b98897204ec221f

data/.github/workflows/ruby.yml

@@ -0,0 +1,45 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.0']
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run linter
+      run: bundle exec rubocop --parallel
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.0', '3.1', '3.2']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rake test

data/.rubocop.yml

@@ -1,18 +1,25 @@
 inherit_from: .rubocop_todo.yml
 
-Metrics/AbcSize:
-  Max: 25
-Metrics/MethodLength:
-  Max: 15
+require:
+  - rubocop-performance
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  DefaultFormatter: progress
+  DisplayCopNames: true
+  DisplayStyleGuide: true
+  ExtraDetails: true
+
 Layout/LineLength:
   Max: 120
-Lint/RaiseException:
-  Enabled: true
-Lint/StructNewOverride:
-  Enabled: false
-Style/HashEachMethods:
-  Enabled: true
-Style/HashTransformKeys:
+
+Style/StringLiterals:
   Enabled: true
-Style/HashTransformValues:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
   Enabled: true
+  EnforcedStyle: double_quotes

data/.rubocop_todo.yml

@@ -1,20 +1,54 @@
 # This configuration was generated by
-# `rubocop --auto-gen-config`
-# on 2020-06-15 23:46:36 -0500 using RuboCop version 0.81.0.
+# `rubocop --auto-gen-config --auto-gen-only-exclude`
+# 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: 1
-# Configuration parameters: IgnoredMethods.
+# Offense count: 7
+# Configuration parameters: IgnoredMethods, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - '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: 2
+# Configuration parameters: CountComments, Max, CountAsOne.
+Metrics/ClassLength:
+  Exclude:
+    - 'test/annealing/configuration_test.rb'
+    - 'test/annealing/simulator_test.rb'
 
 # Offense count: 1
-# Configuration parameters: CountComments, ExcludedMethods.
+# 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'
+    - 'test/annealing/configuration_test.rb'
+    - 'test/annealing/metal_test.rb'
+    - 'test/annealing/simulator_test.rb'
+    - 'test/annealing_test.rb'
 
-# Offense count: 2
-Style/Documentation:
+# Offense count: 1
+# Configuration parameters: IgnoredMethods, Max.
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'lib/annealing/configuration.rb'
+
+# Offense count: 5
+# Configuration parameters: Max.
+Minitest/MultipleAssertions:
   Exclude:
-    - 'test/**/*'
+    - 'test/annealing/configuration/terminators_test.rb'
+    - 'test/annealing/configuration_test.rb'
+    - 'test/annealing/simulator_test.rb'

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+## [Unreleased]
+
+
+## [0.3.0] - 2022-02-21
+
+- Removed the default state change function; you are now required to define a custom `state_change` function for the simulation (#2)
+- Added support for specifying a custom `termination_condition` function to override the default condition of the temperature reaching 0 (#5)
+- Added support for specifying a custom `cool_down` function to override the default linear cooling function (#9)
+- Normalized configurations options such that they can be specified in a consistent way across many interfaces (#19)
+- `Annealing::Pool` has been replaced with `Annealing::Metal` which has a different interface from the old class
+- `Annealing.simulate`, `Annealing::Simulator.new` and `Annealing::Simulator#run` method signatures have changed to accommodate normalized configuration options
+- `Annealing::Simulator.new` no longer raises `RuntimeError` exceptions if configuration options are invalid. Instead, they will be raised from `Annealing::Simulator#run` as `ArgumentError` exceptions.
+- Negative `cooling_rate` values are no longer valid; `Annealing::Simulator#run` will raise an error if one is specified
+- Comprehensive test suite added
+
+## [0.2.0] - 2020-07-23
+
+- Improve private methods
+- Minor code cleanup
+
+## [0.1.0] - 2020-07-17
+
+- It allows custom configuration
+- It use distance method to calculate energy
+- It allows user to implement their own total energy calculator

data/Gemfile

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in annealing.gemspec
 gemspec
 
-gem 'minitest', '~> 5.0'
-gem 'rake', '~> 12.0'
+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"

data/Gemfile.lock

@@ -1,21 +1,65 @@
 PATH
   remote: .
   specs:
-    annealing (0.1.0)
+    annealing (0.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    minitest (5.14.1)
-    rake (12.3.3)
+    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.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.7.0)
+    reline (0.3.2)
+      io-console (~> 0.5)
+    rexml (3.2.5)
+    rubocop (1.48.0)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      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)
+      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)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (2.4.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   annealing!
+  debug (>= 1.0.0)
   minitest (~> 5.0)
-  rake (~> 12.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)
 
 BUNDLED WITH
-   2.1.4
+   2.4.4

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Luis Ezcurdia
+Copyright (c) 2022 Luis Ezcurdia
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,9 @@
 # Annealing
+
 [![Gem Version](https://badge.fury.io/rb/annealing.svg)](https://badge.fury.io/rb/annealing)
+[![Ruby](https://github.com/3zcurdia/annealing/actions/workflows/ruby.yml/badge.svg)](https://github.com/3zcurdia/annealing/actions/workflows/ruby.yml)
 
-Find the optimal solution in a complex problem through a simulated annealing implementation for enumerable objects. Where the energy of each object can be measured by a distance method between two elements or a lambda function where the total energy is calculated in the objects.
+Find the optimal solution in a complex problem through a simulated annealing implementation for Ruby objects.
 
 ## Installation
 
@@ -13,18 +15,27 @@ gem 'annealing'
 
 And then execute:
 
-    $ bundle install
+```shell
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install annealing
+```shell
+gem install annealing
+```
 
 ## Usage
 
-To use this gem, you must have an object that implements a `distance` method or a lambda function where you calculate the total energy of an enumerable object.
+Simulated annealing algorithms work by comparing multiple permutations of a given object and measuring their relative efficiencies based on any number of competing factors. If you aren't already familiar with the concept of simulated annealing, we recommend watching [The Most Metal Algorithm in Computer Science](https://www.youtube.com/watch?v=I_0GBWCKft8) from [SciShow](https://www.youtube.com/c/SciShow) as it will help you understand some of the concepts and terms used below.
+
+In order to use this algorithm we must first define 3 things:
+
+1. an initial object state to evaluate
+2. a way to measure the energy of that state
+3. and a way to change the state of the object over time
 
-Lets solve the traveling salesman, for that we will need an object with a distance method
-to mesure the distance between two locations.
+Lets use the the traveling salesperson problem as an example. First we will define a Location object with a `distance` method to measure the distance between two locations.
 
 ```ruby
 Location = Struct.new(:x, :y) do
@@ -40,7 +51,7 @@ Location = Struct.new(:x, :y) do
 end
 ```
 
-Now we can create an array of the locations
+Now we can create an array of locations the salesperson will visit. This is our initial state, and the order can be any random starting state.
 
 ```ruby
 locations = [
@@ -49,69 +60,230 @@ locations = [
   Location.new(40, 120),
   Location.new(100, 120),
   Location.new(20, 40)
-]
+].shuffle
+```
+
+Next we need a way to calculate the total energy of traveling to each location in turn, with low energy states preferable to high energy states. Think of it as a representation of the efficiency of the trip; the further away one point is away from the next, the less efficient the trip is.
+
+```ruby
+energy_calculator = lambda do |locations|
+  locations.each_cons(2).sum do |location1, location2|
+    location1.distance(location2)
+  end
+end
 ```
 
-Now we can just pass the locations argumen.
+Finally, we need a way to make small, random changes in the order of locations the salesperson will visit as we probe for an optimal route.
 
 ```ruby
-puts Annealing.simulate(locations)
-[(20,40), (40,120), (100,120), (60,200), (180,200)]
+state_change = lambda do |locations|
+  size = locations.size
+  swapped = locations.dup
+  idx_a = rand(size)
+  idx_b = rand(size)
+  swapped[idx_b], swapped[idx_a] = swapped[idx_a], swapped[idx_b]
+  swapped
+end
 ```
 
-This will run the simulation with the default parameters and it could take a while to finish.
-But if you want to iterate with other parameters you can send the parameters `temperature` and `cooling_rate`.
+Now we can run the simulation. With the default configuration it will consider ~33 million permutations of the route, so this may take several minutes to complete.
 
 ```ruby
-simulator = Annealing::Simulator.new(temperature: 10_000, cooling_rate: 0.5)
-solution = simulator.run(locations)
-solution.energy
-351.901234
-solution.collection
-[(20,40), (40,120), (100,120), (60,200), (180,200)]
+optimal_route = Annealing.simulate(locations,
+                                   energy_calculator: energy_calculator,
+                                   state_change: state_change)
+optimal_route.state
+# => [(20,40), (40,120), (100,120), (60,200), (180,200)]
 ```
 
-You can also configure the default parameters
+## Configuration options
+
+The annealer supports a number of configuration options. See the [configuration precedence](#configuration-precedence) section below for information on the different scopes they can be applied to.
+
+### `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 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.configure do |c|
-  c.temperature  = 10_000.0
-  c.cooling_rate = 0.003
+# 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
 ```
 
-### Custom total energy calculator
+### `cooling_rate` and `temperature`
 
-You can set a lambda function to customize the total energy in a collection by setting in the default parameters
+In the default configuration, the `cooling_rate` represents the amount by which the `temperature` will be reduced at each step, such that `temperature / cooling_rate` equals the maximum number of steps the annealer will go through in its search for the optimal solution. If a custom `cool_down` function is specified then `cooling_rate` will be passed to that function at each step along with the current temperature. The default `cooling_rate` value is `0.0003` and the default `temperature` is `10_000`.
 
 ```ruby
-Annealing.configure do |c|
-  c.total_energy_calculator = lambda do |enumerable|
-    enumerable.each_cons(2).sum { |a, b| a.distance(b) }
+Annealing.configure do |config|
+  config.cooling_rate = 0.001
+  config.temperature = 25_000
+end
+```
+
+Generally speaking, simulations have a higher chance of finding optimal solutions with a high initial temperature and a low cooling rate. A high temperature gives the simulation more time to search through neighboring states for low energy configurations, while a low cooling rate increases the probability that the simulation will select a low-energy configuration when comparing two states. For example, consider two configurations: `temperature(10000) / cooling_rate(1)` and `temperature(100) / cooling_rate(0.01)`. Even though both provide 10,000 steps when using the default cool down function, the latter configuration will allow for smaller temperature readings which is more likely to result in a more optimal final state.
+
+### `energy_calculator`
+
+You must specify a `energy_calculator` function before running 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 being measured. It should return a measurement representing the efficiency of the current state based on all of its competing factors, and where a lower value represents a better configuration than a higher value.
+
+```ruby
+# A custom calculator class that takes into account hypothetical external factors
+class PotentialSalesCalculator
+  def initialize(initial_time_of_day)
+    @initial_time_of_day = initial_time_of_day
+  end
+
+  def energy(locations)
+    arrival_time = @initial_time_of_day
+    first_location_sales = potential_sales(locations.first, arrival_time)
+    locations.each_cons(2).sum do |location1, location2|
+      arrival_time += travel_time(location1, location2, arrival_time)
+      distance = location1.distance(location2)
+      potential_sales(locations.first, arrival_time) / distance
+    end + first_location_sales
+  end
+
+  def potential_sales(location, time_of_day)
+    habits = CustomerHabits.new(location)
+    customers = habits.whos_home_at(time_of_day)
+    SalesTrends.estimate(customers)
+  end
+
+  def travel_time(location1, location2, time_of_day)
+    traffic = TrafficPredictor.new(location1, location2)
+    traffic.travel_time(time_of_day)
   end
 end
+
+calculator = PotentialSalesCalculator.new(8)
+Annealing.configuration.energy_calculator = calculator.method(:energy)
 ```
 
-or in the simulator as a parameter
+### `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.
 
 ```ruby
-calc = lambda do |enumerable|
-  enumerable.each_cons(2).sum { |a, b| a.distance(b) }
+class MyClass
+  def state_change(state)
+    size = state.size
+    swapped = state.dup
+    idx_a = rand(size)
+    idx_b = rand(size)
+    swapped[idx_b], swapped[idx_a] = swapped[idx_a], swapped[idx_b]
+    swapped
+  end
 end
-solution = simulator.run(locations, calc).collection
-[(20,40), (40,120), (100,120), (60,200), (180,200)]
+
+instance = MyClass.new
+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. 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 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
+```
+
+## 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.
+
+### Global configuration
+
+Global configuration options, including the defaults, have the lowest precedence. They will be used in every simulation when no overriding configuration options are present. For instance, we can rewrite the traveling salesperson example like so:
+
+```ruby
+# Set globally using block style
+Annealing.configure do |config|
+  config.energy_calculator = energy_calculator
+end
+
+# Or set individually
+Annealing.configuration.state_change = state_change
+
+# Now we don't need to specify them just in time
+solution = Annealing.simulate(locations)
+```
+
+### Instance configuration
+
+Instance configurations can be set on new instances of `Annealing::Simulator` objects and will apply to all subsequent simulation runs for that instance. Instance configuration options override their global configuration counterparts.
+
+```ruby
+Annealing.configure do |config|
+  config.energy_calculator = energy_calculator
+  config.state_change = state_change
+  config.temperature = 10_000
+end
+
+simulation = Annealing::Simulator.new(temperature: 1_000)
+simulation.run(locations) # Will use an initial temperature value of 1000
+simulation.run(locations.shuffle) # So will this
+```
+
+### Just-in-time configuration
+
+Just-in-time configuration options have the highest precedence and will override both global and instance options. They are only applied to the current simulation run.
+
+```ruby
+Annealing.configure do |config|
+  config.cooling_rate = 0.001
+  config.energy_calculator = energy_calculator
+  config.state_change = state_change
+  config.temperature = 10_000
+end
+
+# Will use an initial temperature of 20,000 and a cooling rate of 0.001
+solution = Annealing.simulate(locations, temperature: 20_000)
+
+# Set an instance cooling rate of 0.002
+simulation = Annealing::Simulator.new(cooling_rate: 0.002)
+
+# Will use an initial temperature of 20,000 and a cooling rate of 0.002
+simulation.run(locations, temperature: 20_000)
+
+# Will use an initial temperature of 10,000 and a cooling rate of 0.003
+simulation.run(locations.shuffle, cooling_rate: 0.003)
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake` to run the test suite. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/3zcurdia/annealing. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/3zcurdia/annealing/blob/master/CODE_OF_CONDUCT.md).
-
+Bug reports and pull requests are welcome on GitHub at [https://github.com/3zcurdia/annealing](https://github.com/3zcurdia/annealing). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/3zcurdia/annealing/blob/master/CODE_OF_CONDUCT.md).
 
 ## Code of Conduct
 

data/Rakefile

@@ -1,12 +1,23 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rake/testtask'
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << 'test'
-  t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb']
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task default: :test
+RuboCop::RakeTask.new(:rubocop)
+
+desc "Execute the end-to-end integration test script"
+task :end_to_end_test do
+  puts
+  puts "Running full end-to-end test with bin/run"
+  puts `bin/run`
+  puts
+end
+
+task default: %i[test end_to_end_test rubocop]

data/annealing.gemspec

@@ -1,31 +1,34 @@
 # frozen_string_literal: true
 
-require_relative 'lib/annealing/version'
+require_relative "lib/annealing/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = 'annealing'
+  spec.name          = "annealing"
   spec.version       = Annealing::VERSION
-  spec.authors       = ['Luis Ezcurdia Razo']
-  spec.email         = ['ing.ezcurdia@gmail.com']
-  spec.license       = 'MIT'
+  spec.authors       = ["Luis Ezcurdia", "Chris Bloom"]
+  spec.email         = ["ing.ezcurdia@gmail.com", "chrisbloom7@gmail.com"]
+  spec.license       = "MIT"
 
-  spec.summary       = 'Simulated Annealing algoritm'
-  spec.description   = 'Simulated Annealing algoritm implementation.'
-  spec.homepage      = 'https://github.com/3zcurdia/annealing'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+  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.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = 'https://github.com/3zcurdia/annealing'
-  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/3zcurdia/annealing"
+  spec.metadata["changelog_uri"] = "https://github.com/3zcurdia/annealing/blob/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = 'exe'
+  spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "ruby-prof", "~> 1.6", ">= 1.6.1"
+  spec.metadata["rubygems_mfa_required"] = "true"
 end

data/bin/console

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'annealing'
+require "bundler/setup"
+require "annealing"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -11,5 +11,5 @@ require 'annealing'
 # require "pry"
 # Pry.start
 
-require 'irb'
+require "irb"
 IRB.start(__FILE__)

data/bin/run

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "annealing"
+
+Location = Struct.new(:name, :x, :y) do
+  def inspect
+    "#{name} (#{x},#{y})"
+  end
+
+  def distance(location)
+    dx = (x - location.x).abs
+    dy = (y - location.y).abs
+    Math.sqrt((dx**2) + (dy**2))
+  end
+end
+
+locations = [
+  Location.new("Blaire Hills", 60, 200),
+  Location.new("Smallville", 180, 200),
+  Location.new("Boggs Harbor", 40, 120),
+  Location.new("Curtisville", 100, 120),
+  Location.new("Allentown", 20, 40)
+].shuffle
+
+energy_calculator = lambda do |state|
+  state.each_cons(2).sum do |location1, location2|
+    location1.distance(location2)
+  end
+end
+
+state_change = lambda do |state|
+  size = state.size
+  swapped = state.dup
+  idx_a = rand(size)
+  idx_b = rand(size)
+  swapped[idx_b], swapped[idx_a] = swapped[idx_a], swapped[idx_b]
+  swapped
+end
+
+simulator = Annealing::Simulator.new(temperature: 10_000, cooling_rate: 0.01)
+solution = simulator.run(locations,
+                         energy_calculator: energy_calculator,
+                         state_change: state_change)
+
+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 "\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}"

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,17 +3,70 @@
 module Annealing
   # It enables the gem configuration
   class Configuration
-    attr_accessor :temperature, :cooling_rate, :total_energy_calculator, :logger
-
-    def initialize
-      @temperature  = 10_000.0
-      @cooling_rate = 0.0003
-      @total_energy_calculator = lambda do |enumerable|
-        enumerable.each_cons(2).sum do |value_a, value_b|
-          value_a.distance(value_b)
-        end
-      end
-      @logger = Logger.new(STDOUT)
+    DEFAULT_COOLING_RATE = 0.0003
+    DEFAULT_INITIAL_TEMPERATURE = 10_000.0
+
+    class ConfigurationError < Annealing::Error; end
+
+    attr_accessor :cool_down,
+                  :cooling_rate,
+                  :energy_calculator,
+                  :state_change,
+                  :temperature,
+                  :termination_condition
+
+    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)
+      @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 !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,
+        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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Annealing
+  # It manages the total energy of a given collection
+  class Metal
+    attr_reader :configuration, :state, :temperature
+
+    def initialize(current_state, current_temperature, configuration = nil)
+      @configuration = configuration || Annealing.configuration.merge({})
+      @state = current_state
+      @temperature = current_temperature
+    end
+
+    def energy
+      @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 prefer?(cooled_metal)
+        cooled_metal
+      else
+        @temperature = new_temperature
+        self
+      end
+    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
+
+      energy_delta = energy - cooled_metal.energy
+      (Math::E**(energy_delta / cooled_metal.temperature)) > rand
+    end
+
+    def cool(new_temperature)
+      next_state = configuration.state_change.call(state)
+      Metal.new(next_state, new_temperature, configuration)
+    end
+  end
+end

data/lib/annealing/simulator.rb

@@ -3,36 +3,50 @@
 module Annealing
   # It runs simulated annealing
   class Simulator
-    attr_reader :temperature, :cooling_rate
+    attr_reader :configuration
 
-    def initialize(temperature: nil, cooling_rate: nil)
-      @temperature = temperature || Annealing.configuration.temperature
-      @cooling_rate = cooling_rate || Annealing.configuration.cooling_rate
-
-      raise 'Invalid initial temperature' if @temperature.negative?
-
-      normalize_cooling_rate
+    def initialize(config_hash = {})
+      @configuration = Annealing.configuration.merge(config_hash)
     end
 
-    def run(collection, calculator = nil)
-      best = current = Pool.new(collection.shuffle, calculator)
-      Annealing.logger.debug(" Original: #{current}")
-      cool_down do |temp|
-        current = current.solution_at(temp)
-        best = current if current.better_than?(best)
+    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)
+        steps = 0
+        until termination_condition_met?(current, runtime_config)
+          steps += 1
+          current = reduce_temperature(current, steps, runtime_config)
+        end
+        current
       end
-      Annealing.logger.debug("Optimized: #{best}")
-      best
     end
 
     private
 
-    def cool_down
-      (temperature..0).step(cooling_rate).each { |temp| yield temp }
+    # 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 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 normalize_cooling_rate
-      @cooling_rate = -1.0 * cooling_rate if cooling_rate.positive?
+    def termination_condition_met?(metal, config)
+      config.termination_condition.call(metal.state,
+                                        metal.energy,
+                                        metal.temperature)
     end
   end
 end

data/lib/annealing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Annealing
-  VERSION = '0.2.0'
+  VERSION = "0.4.0"
 end

data/lib/annealing.rb

@@ -1,16 +1,11 @@
 # frozen_string_literal: true
 
-require 'logger'
-require 'annealing/version'
-require 'annealing/configuration'
-require 'annealing/pool'
-require 'annealing/simulator'
-
 # Simulated Annealing algoritm
 # https://en.wikipedia.org/wiki/Simulated_annealing
 module Annealing
   # Default error class
   class Error < StandardError; end
+
   class << self
     attr_writer :configuration
   end
@@ -21,16 +16,15 @@ module Annealing
 
   def self.configure
     yield(configuration)
+    configuration
   end
 
-  def self.simulate(collection)
-    return [] if collection.empty?
-
-    simulator = Simulator.new
-    simulator.run(collection).collection
-  end
-
-  def self.logger
-    configuration.logger
+  def self.simulate(initial_state, config_hash = {})
+    Simulator.new.run(initial_state, config_hash).state
   end
 end
+
+require "annealing/configuration"
+require "annealing/metal"
+require "annealing/simulator"
+require "annealing/version"

metadata

@@ -1,26 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: annealing
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
-- Luis Ezcurdia Razo
+- Luis Ezcurdia
+- Chris Bloom
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-06-23 00:00:00.000000000 Z
-dependencies: []
+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
 description: Simulated Annealing algoritm implementation.
 email:
 - ing.ezcurdia@gmail.com
+- chrisbloom7@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
-- ".travis.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -29,10 +52,13 @@ files:
 - Rakefile
 - annealing.gemspec
 - bin/console
+- bin/run
 - bin/setup
 - lib/annealing.rb
 - lib/annealing/configuration.rb
-- lib/annealing/pool.rb
+- lib/annealing/configuration/coolers.rb
+- lib/annealing/configuration/terminators.rb
+- lib/annealing/metal.rb
 - lib/annealing/simulator.rb
 - lib/annealing/version.rb
 homepage: https://github.com/3zcurdia/annealing
@@ -41,6 +67,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/3zcurdia/annealing
   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:
@@ -49,15 +77,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.3
+rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
-summary: Simulated Annealing algoritm
+summary: Simulated Annealing
 test_files: []

data/.travis.yml

@@ -1,6 +0,0 @@
----
-language: ruby
-cache: bundler
-rvm:
-  - 2.7.1
-before_install: gem install bundler -v 2.1.4

data/lib/annealing/pool.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Annealing
-  # It manages the total energy of a given collection
-  class Pool
-    attr_reader :collection
-
-    def initialize(collection, energy_calculator = nil)
-      @collection = collection.dup
-      @energy_calculator = energy_calculator || Annealing.configuration.total_energy_calculator
-    end
-
-    def energy
-      @energy ||= energy_calculator.call(collection)
-    end
-
-    def better_than?(pool)
-      energy < pool.energy
-    end
-
-    def solution_at(temperature)
-      move = self.next
-      energy_delta = energy - move.energy
-      if energy_delta.positive? || (Math::E**(energy_delta / temperature)) > rand
-        move
-      else
-        self
-      end
-    end
-
-    def to_s
-      format('%<energy>.4f:%<value>s', energy: energy, value: collection)
-    end
-
-    def next
-      Pool.new(swap_collection, energy_calculator)
-    end
-
-    private
-
-    attr_reader :energy_calculator
-
-    def swap_collection
-      swapped = collection.dup
-      idx_a = rand(size)
-      idx_b = rand(size)
-      swapped[idx_b], swapped[idx_a] = swapped[idx_a], swapped[idx_b]
-      swapped
-    end
-
-    def size
-      collection.size
-    end
-  end
-end