annealing 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53e5900add60de36b8e3bb441be9bce450f6dcb3cbd67552913684745e90a0c1
-  data.tar.gz: 00347f761988a73951ed950317c1fc6ebf6d1add2d2ab1889bf8cbe6eebabe36
+  metadata.gz: 8b20378dea6d3ebcee0d0adca58d721576605d17c34c91a1828f887733c5fc5e
+  data.tar.gz: 62935118c575c16e8e0efaaf58224845fc8e975f230ac58b81da41cf66a9c08c
 SHA512:
-  metadata.gz: ef3653ce209af0a76189157cdecbbac58613aa86845b0e8476a22407fc17b9edb75e879f1676497eb7f1d8b4f86549719f67825f7c48db134603ed784d2d5ef1
-  data.tar.gz: 022accd062db4cc155e50606d22ea7e51db7603a61ef9b40512625110d528975de275b1abbb5ea6604fa98162122ef8b5e143f474593536af4291089e4d3f229
+  metadata.gz: 4916ea9c5c854ce9891b9264d7dfe117f56da58fb906735f2afb015f2a0acf08757702991d988ed82096910225cca25794b78e135635d03b41dcf51496543a72
+  data.tar.gz: f3c74cb98d4b45512fd78bf6e18dfc751550ba33f6ccfa4ab80720d01dcdf4a1a0ec7215387033523792a503876e4abd6bc7b017330539a8367bed3da3a23741

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: ['2.6']
+    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: ['2.6', '2.7', '3.0', '3.1']
+
+    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: 2.6
+  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,42 @@
 # 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-02-18 23:32:32 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: 9
+# Configuration parameters: IgnoredMethods, CountRepeatedAttributes, Max.
+Metrics/AbcSize:
+  Exclude:
+    - 'test/annealing/configuration/configurator_test.rb'
+    - 'test/annealing/metal_test.rb'
+    - 'test/annealing/simulator_test.rb'
+    - 'test/annealing_test.rb'
 
-# Offense count: 1
-# Configuration parameters: CountComments, ExcludedMethods.
+# Offense count: 3
+# Configuration parameters: CountComments, Max, CountAsOne.
+Metrics/ClassLength:
+  Exclude:
+    - 'test/annealing/configuration/configurator_test.rb'
+    - 'test/annealing/metal_test.rb'
+    - 'test/annealing/simulator_test.rb'
 
+# Offense count: 13
+# 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/metal_test.rb'
+    - 'test/annealing/simulator_test.rb'
+    - 'test/annealing_test.rb'
 
-# Offense count: 2
-Style/Documentation:
+# Offense count: 8
+# Configuration parameters: Max.
+Minitest/MultipleAssertions:
   Exclude:
-    - 'test/**/*'
+    - 'test/annealing/configuration/configurator_test.rb'
+    - 'test/annealing/configuration_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", ">= 13.0.6"
+gem "rubocop", "~> 1.23"
+gem "rubocop-minitest", "~> 0.17.0"
+gem "rubocop-performance", "~> 1.12"
+gem "rubocop-rake", "~> 0.6.0"

data/Gemfile.lock

@@ -1,21 +1,63 @@
 PATH
   remote: .
   specs:
-    annealing (0.1.0)
+    annealing (0.2.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.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.1)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    regexp_parser (2.2.0)
+    reline (0.3.1)
+      io-console (~> 0.5)
+    rexml (3.2.5)
+    rubocop (1.23.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.12.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)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   annealing!
+  debug (>= 1.0.0)
   minitest (~> 5.0)
-  rake (~> 12.0)
+  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)
 
 BUNDLED WITH
    2.1.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,219 @@ 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
+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)]
+```
+
+## 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 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.
 
 ```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)]
+Annealing.configuration.cool_down = lambda do |_energy, temperature, cooling_rate, steps|
+  # Reduce temperature exponentially
+  temperature - (cooling_rate * (steps**2))
+end
 ```
 
-You can also configure the default parameters
+### `cooling_rate` and `temperature`
+
+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.temperature  = 10_000.0
-  c.cooling_rate = 0.003
+Annealing.configure do |config|
+  config.cooling_rate = 0.001
+  config.temperature = 25_000
 end
 ```
 
-### Custom total energy calculator
+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.
 
-You can set a lambda function to customize the total energy in a collection by setting in the default parameters
+### `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
-Annealing.configure do |c|
-  c.total_energy_calculator = lambda do |enumerable|
-    enumerable.each_cons(2).sum { |a, b| a.distance(b) }
+# 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
+### `logger`
+
+The default logger is a standard Ruby Logger that writes to stdout. You can specify a different `logger` if you wish.
 
 ```ruby
-calc = lambda do |enumerable|
-  enumerable.each_cons(2).sum { |a, b| a.distance(b) }
+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.
+
+```ruby
+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. 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.
+
+```ruby
+Annealing.configuration.termination_condition = lambda do |_state, energy, temperature|
+  # Stop early if we encounter any 0-energy state
+  energy == 0 || temperature <= 0.0
+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(">= 2.6.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.4", ">= 1.4.3"
+  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,58 @@
+#!/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
+
+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)
+
+puts "\nInitial itinerary:"
+locations.each_cons(2).each_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).each_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/configurator.rb

@@ -0,0 +1,41 @@
+# 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

data/lib/annealing/configuration.rb

@@ -3,17 +3,28 @@
 module Annealing
   # It enables the gem configuration
   class Configuration
-    attr_accessor :temperature, :cooling_rate, :total_energy_calculator, :logger
+    attr_accessor :cool_down,
+                  :cooling_rate,
+                  :energy_calculator,
+                  :logger,
+                  :state_change,
+                  :temperature,
+                  :termination_condition
 
     def initialize
-      @temperature  = 10_000.0
+      @cool_down = lambda do |_energy, temperature, cooling_rate, _steps|
+        # Reduce the temperature linearly by default
+        temperature - cooling_rate
+      end
       @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
+      @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
-      @logger = Logger.new(STDOUT)
     end
   end
 end

data/lib/annealing/metal.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Annealing
+  # It manages the total energy of a given collection
+  class Metal
+    include Configuration::Configurator
+    attr_reader :state, :temperature
+
+    def initialize(current_state, current_temperature, **config)
+      init_configuration(config)
+      @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)
+    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)
+        cooled_metal
+      else
+        @temperature = new_temperature
+        self
+      end
+    end
+
+    def to_s
+      format("%<temperature>.4f:%<energy>.4f:%<value>s",
+             temperature: temperature,
+             energy: energy,
+             value: state)
+    end
+
+    private
+
+    def energy_calculator
+      current_config_for(:energy_calculator)
+    end
+
+    def state_change
+      current_config_for(:state_change)
+    end
+
+    def better_than?(cooled_metal)
+      energy_delta = energy - cooled_metal.energy
+      energy_delta.positive? ||
+        (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)
+    end
+  end
+end

data/lib/annealing/simulator.rb

@@ -3,36 +3,68 @@
 module Annealing
   # It runs simulated annealing
   class Simulator
-    attr_reader :temperature, :cooling_rate
+    include Configuration::Configurator
 
-    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)
+      init_configuration(config)
     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_configuration_overrides(config_hash) do
+        validate_configuration!
+        current = Metal.new(initial_state, temperature,
+                            **configuration_overrides)
+        Annealing.logger.debug("Original: #{current}")
+        steps = 0
+        until termination_condition_met?(termination_condition, current)
+          steps += 1
+          current = reduce_temperature(cool_down, current, steps)
+        end
+        Annealing.logger.debug("Optimized: #{current}")
+        current
       end
-      Annealing.logger.debug("Optimized: #{best}")
-      best
     end
 
     private
 
     def cool_down
-      (temperature..0).step(cooling_rate).each { |temp| yield temp }
+      current_config_for(:cool_down)
     end
 
-    def normalize_cooling_rate
-      @cooling_rate = -1.0 * cooling_rate if cooling_rate.positive?
+    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)
+      metal.cool!(new_temperature)
+    end
+
+    def termination_condition_met?(termination_condition, metal)
+      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)
     end
   end
 end

data/lib/annealing/version.rb

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

data/lib/annealing.rb

@@ -1,16 +1,18 @@
 # frozen_string_literal: true
 
-require 'logger'
-require 'annealing/version'
-require 'annealing/configuration'
-require 'annealing/pool'
-require 'annealing/simulator'
+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
   # Default error class
   class Error < StandardError; end
+
   class << self
     attr_writer :configuration
   end
@@ -23,11 +25,8 @@ module Annealing
     yield(configuration)
   end
 
-  def self.simulate(collection)
-    return [] if collection.empty?
-
-    simulator = Simulator.new
-    simulator.run(collection).collection
+  def self.simulate(initial_state, config_hash = {})
+    Simulator.new.run(initial_state, config_hash).state
   end
 
   def self.logger

metadata

@@ -1,26 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: annealing
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.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: 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
 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,12 @@ files:
 - Rakefile
 - annealing.gemspec
 - bin/console
+- bin/run
 - bin/setup
 - lib/annealing.rb
 - lib/annealing/configuration.rb
-- lib/annealing/pool.rb
+- lib/annealing/configuration/configurator.rb
+- lib/annealing/metal.rb
 - lib/annealing/simulator.rb
 - lib/annealing/version.rb
 homepage: https://github.com/3zcurdia/annealing
@@ -41,6 +66,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 +76,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.3
+rubygems_version: 3.3.7
 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