alns 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d806c11f4437a5a793860c605ebd32c5b85f266d66ee86d575735cb73306c25
+  data.tar.gz: 2e36605d0d6827b77681ca4a94f1b279c8e2d94f7857137c793c581fcaef4c8c
+SHA512:
+  metadata.gz: 57fd77798edad151c997b1e60c137a0ceabe031bba9a0d48dbf7f9b3e9f6c370a1d2bbaf8a5f203cb830dc2c3a557f9678a94d961b743d690b868a9a8af7adc2
+  data.tar.gz: 6979b6066219dbc028d4863e416e7892675fd88dfcbc9a9871d0bff2ec4f88a7577d750cce1305566c85651729fc3e41c20394ab970bb43035c296c443beefd5

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019 Niels Wouda and contributors
+Copyright (c) 2025 bibenga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/alns/accept/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ALNS
+  module Accept
+    class Base
+      def accept?(rnd, best, current, candidate)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/alns/accept/hill_climbing.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'alns/accept/base'
+
+module ALNS
+  module Accept
+    class HillClimbing < Base
+      def accept?(_rnd, _best, current, candidate)
+        candidate.objective <= current.objective
+      end
+    end
+  end
+end

data/lib/alns/math.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ALNS
+  def self.weighted_random_index(rnd, weights)
+    raise 'Invalid weights: Array is empty' if weights.empty?
+    return 0 if weights.size == 1
+
+    total_sum = weights.sum
+    adjusted_value = rnd.rand * total_sum
+
+    weights.each_with_index do |weight, index|
+      adjusted_value -= weight
+
+      return index if adjusted_value <= 0
+    end
+
+    # we will only be here when errors accumulate
+    weights.length - 1
+  end
+end

data/lib/alns/outcome.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ALNS
+  module Outcome
+    BEST = 0
+    BETTER = 1
+    ACCEPT = 2
+    REJECT = 3
+
+    def self.to_s(value)
+      case value
+      when BEST   then 'BEST'
+      when BETTER then 'BETTER'
+      when ACCEPT then 'ACCEPT'
+      when REJECT then 'REJECT'
+      else
+        raise ArgumentError, "Invalid outcome: #{value}"
+      end
+    end
+  end
+end

data/lib/alns/random/random.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module ALNS
+  module Random
+    class Random
+      def rand(max = nil)
+        if max.nil?
+          SecureRandom.random_number
+        else
+          SecureRandom.random_number(max)
+        end
+      end
+    end
+  end
+end

data/lib/alns/result.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ALNS
+  Result = Data.define(:best_state, :statistics)
+end

data/lib/alns/select/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ALNS
+  module Select
+    class Base
+      def initialize(num_destroy, num_repair, op_coupling = nil)
+        if num_destroy <= 0 || num_repair <= 0
+          raise ArgumentError, 'Missing destroy or repair operators.'
+        end
+
+        unless op_coupling.nil?
+          rows = op_coupling.length
+          cols = op_coupling[0].length
+
+          if rows != num_destroy || cols != num_repair
+            raise ArgumentError,
+                  "coupling matrix of shape (#{rows}, #{cols}), expected (#{num_destroy}, #{num_repair})"
+          end
+
+          op_coupling.each_with_index do |row, i|
+            if row.length != cols
+              raise ArgumentError,
+                    "the number of columns in a row #{i} does not match the expected #{cols}"
+            end
+
+            coupled = row.any? { |b| b }
+            unless coupled
+              raise ArgumentError,
+                    "destroy operator #{i} has no coupled repair operators"
+            end
+          end
+        end
+
+        @num_destroy = num_destroy
+        @num_repair = num_repair
+        @op_coupling = op_coupling
+      end
+
+      def select(rnd, best, current)
+        raise NotImplementedError
+      end
+
+      def update(candidate, d_idx, r_idx, outcome)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/alns/select/roulette_wheel.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'alns/select/base'
+require 'alns/math'
+
+module ALNS
+  module Select
+    class RouletteWheel < Base
+      def initialize(scores, decay, num_destroy, num_repair, op_coupling = nil)
+        super(num_destroy, num_repair, op_coupling)
+
+        @scores = scores
+        @decay = decay
+
+        @d_weights = Array.new(num_destroy, 1)
+        @r_weights = Array.new(num_repair, 1)
+      end
+
+      def select(rnd, _best, _current)
+        if @op_coupling
+          d_idx = ALNS.weighted_random_index(rnd, @d_weights)
+
+          coupled_r_idcs = []
+          coupled_r_weights = []
+          @op_coupling[d_idx].each_with_index do |coupled, i|
+            if coupled
+              coupled_r_idcs << i
+              coupled_r_weights << @r_weights[i]
+            end
+          end
+
+          r_idx = coupled_r_idcs[ALNS.weighted_random_index(rnd, coupled_r_weights)]
+
+          [d_idx, r_idx]
+        else
+          d_idx = ALNS.weighted_random_index(rnd, @d_weights)
+          r_idx = ALNS.weighted_random_index(rnd, @r_weights)
+          [d_idx, r_idx]
+        end
+      end
+
+      def update(_candidate, d_idx, r_idx, outcome)
+        @d_weights[d_idx] *= @decay
+        @d_weights[d_idx] += (1 - @decay) * @scores[outcome]
+
+        @r_weights[r_idx] *= @decay
+        @r_weights[r_idx] += (1 - @decay) * @scores[outcome]
+      end
+    end
+  end
+end

data/lib/alns/solver.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'alns/outcome'
+require 'alns/statistics'
+require 'alns/result'
+
+module ALNS
+  # Implements the adaptive large neighbourhood search (ALNS) algorithm.
+  class Solver
+    attr_reader :rnd, :destroy_operators, :repair_operators
+
+    def initialize(rnd = nil)
+      @rnd = rnd || Random.new
+      @on_outcome = nil
+      @destroy_operators = []
+      @repair_operators = []
+    end
+
+    def on_outcome(callback = nil, &block)
+      @on_outcome = callback || block
+    end
+
+    def add_destroy_operator(callback = nil, &block)
+      @destroy_operators << (callback || block)
+    end
+
+    def add_repair_operator(callback = nil, &block)
+      @repair_operators << (callback || block)
+    end
+
+    def iterate(initial_solution, select, accept, stop)
+      if @destroy_operators.empty? || @repair_operators.empty?
+        raise ArgumentError, 'Missing destroy or repair operators.'
+      end
+
+      curr = initial_solution
+      best = initial_solution
+
+      stats = Statistics.new(@destroy_operators.length, @repair_operators.length)
+
+      stats.collect_objective(Time.new, initial_solution.objective)
+
+      until stop.done?(@rnd, best, curr)
+        d_idx, r_idx = select.select(@rnd, best, curr)
+
+        destroy_op = @destroy_operators[d_idx]
+        repair_op = @repair_operators[r_idx]
+
+        destroyed = destroy_op.call(curr, @rnd)
+        cand = repair_op.call(destroyed, @rnd)
+
+        best, curr, outcome = eval_cand(accept, best, curr, cand)
+
+        select.update(cand, d_idx, r_idx, outcome)
+
+        stats.collect_objective(Time.new, curr.objective)
+        stats.collect_operators(d_idx, r_idx, outcome)
+      end
+
+      stats.freeze
+
+      Result.new(best, stats)
+    end
+
+    private
+
+    def eval_cand(accept, best, curr, cand)
+      outcome = determine_outcome(accept, best, curr, cand)
+
+      @on_outcome&.call(outcome, cand)
+
+      case outcome
+      when Outcome::BEST
+        [cand, cand, outcome]
+      when Outcome::REJECT
+        [best, curr, outcome, nil]
+      else
+        [best, cand, outcome, nil]
+      end
+    end
+
+    def determine_outcome(accept, best, curr, cand)
+      outcome = Outcome::REJECT
+
+      if accept.accept?(@rnd, best, curr, cand)
+        outcome = Outcome::ACCEPT
+
+        outcome = Outcome::BETTER if cand.objective < curr.objective
+      end
+
+      outcome = Outcome::BEST if cand.objective < best.objective
+
+      outcome
+    end
+  end
+end

data/lib/alns/state.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ALNS
+  class State
+    def objective
+      raise NotImplementedError
+    end
+  end
+end

data/lib/alns/statistics.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ALNS
+  class Statistics
+    attr_reader :runtimes, :objectives, :destroy_operator_counts, :repair_operator_counts
+
+    def initialize(num_destroy, num_repair)
+      @runtimes = []
+      @objectives = []
+      @destroy_operator_counts = Array.new(num_destroy) { [0, 0, 0, 0] }
+      @repair_operator_counts = Array.new(num_repair) { [0, 0, 0, 0] }
+    end
+
+    def collect_objective(time, objective)
+      @runtimes << time
+      @objectives << objective
+    end
+
+    def collect_operators(d_idx, r_idx, outcome)
+      @destroy_operator_counts[d_idx][outcome] += 1
+      @repair_operator_counts[r_idx][outcome] += 1
+    end
+
+    def freeze
+      @runtimes.freeze
+      @objectives.freeze
+      destroy_operator_counts.each(&:freeze)
+      @destroy_operator_counts.freeze
+      repair_operator_counts.each(&:freeze)
+      @repair_operator_counts.freeze
+    end
+  end
+end

data/lib/alns/stop/base.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ALNS
+  module Stop
+    class Base
+      def done?(rnd, best, current)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/alns/stop/max_iterations.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'alns/stop/base'
+
+module ALNS
+  module Stop
+    class MaxIterations < Base
+      def initialize(max_iterations)
+        super()
+        @max_iterations = max_iterations
+        @current_iteration = 0
+      end
+
+      def done?(_rnd, _best, _current)
+        @current_iteration += 1
+        @current_iteration > @max_iterations
+      end
+    end
+  end
+end

data/lib/alns/stop/max_runtime.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'alns/stop/base'
+
+module ALNS
+  module Stop
+    class MaxRuntime < Base
+      def initialize(max_runtime)
+        super()
+        @max_runtime = max_runtime
+        @started = nil
+      end
+
+      def done?(_rnd, _best, _current)
+        if @started.nil?
+          @started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          return false
+        end
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started
+        elapsed > @max_runtime
+      end
+    end
+  end
+end

data/lib/alns.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'alns/solver'

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: alns
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- bibenga
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: ''
+email: bibenga@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/alns.rb
+- lib/alns/accept/base.rb
+- lib/alns/accept/hill_climbing.rb
+- lib/alns/math.rb
+- lib/alns/outcome.rb
+- lib/alns/random/random.rb
+- lib/alns/result.rb
+- lib/alns/select/base.rb
+- lib/alns/select/roulette_wheel.rb
+- lib/alns/solver.rb
+- lib/alns/state.rb
+- lib/alns/statistics.rb
+- lib/alns/stop/base.rb
+- lib/alns/stop/max_iterations.rb
+- lib/alns/stop/max_runtime.rb
+homepage: https://github.com/bibenga/alns-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bibenga/alns-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Adaptive Large Neighbourhood Search
+test_files: []