finrb 0.1.11 → 1.0.0

data/lib/finrb/amortization.rb

@@ -2,23 +2,22 @@
 
 require_relative 'cashflows'
 require_relative 'decimal'
+require_relative 'precision'
 require_relative 'transaction'
+require_relative 'validation'
 
 module Finrb
   # the Amortization class provides an interface for working with loan amortizations.
-  # @note There are _two_ ways to create an amortization.  The first
-  #   example uses the amortize method for the Numeric class.  The second
-  #   calls Amortization.new directly.
   # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR
   #   rate = Rate.new(0.0425, :apr, :duration => (30 * 12))
-  #   amortization = 250000.amortize(rate)
+  #   amortization = Finrb::Amortization.new(250000, rate)
   # @example Borrow $250,000 under a 30 year, adjustable rate loan, with an APR starting at 4.25%, and increasing by 1% every five years
   #   values = %w{ 0.0425 0.0525 0.0625 0.0725 0.0825 0.0925 }
   #   rates = values.collect { |value| Rate.new( value, :apr, :duration = (5 * 12) ) }
   #   arm = Amortization.new(250000, *rates)
   # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR, but pay $150 extra each month
   #   rate = Rate.new(0.0425, :apr, :duration => (5 * 12))
-  #   extra_payments = 250000.amortize(rate){ |period| period.payment - 150 }
+  #   extra_payments = Finrb::Amortization.new(250000, rate){ |period| period.payment - 150 }
   # @api public
   class Amortization
     # @return [Flt::DecNum] the balance of the loan at the end of the amortization period (usually zero)
@@ -46,11 +45,19 @@ module Finrb
     # @see https://en.wikipedia.org/wiki/Amortization_calculator
     # @api public
     def self.payment(principal, rate, periods)
+      principal = Validation.decimal(principal, name: 'principal')
+      raise(ArgumentError, 'principal must be positive.') unless principal.positive?
+
+      rate = Validation.decimal(rate, name: 'rate')
+      raise(ArgumentError, 'periodic rate must be greater than -1.') if rate <= -1
+
+      periods = Validation.positive_integer(periods, name: 'periods')
+
       if rate.zero?
         # simplified formula to avoid division-by-zero when interest rate is zero
-        -(principal / periods).round(2)
+        -Precision.money(principal / periods)
       else
-        -(principal * (rate + (rate / (((rate + 1)**periods) - 1)))).round(2)
+        -Precision.money(principal * (rate + (rate / (((rate + 1)**periods) - 1))))
       end
     end
 
@@ -61,7 +68,12 @@ module Finrb
     # @param [Proc] block
     # @api public
     def initialize(principal, *rates, &block)
-      @principal = Flt::DecNum.new(principal.to_s)
+      @principal = Validation.decimal(principal, name: 'principal')
+      raise(ArgumentError, 'principal must be positive.') unless @principal.positive?
+      raise(ArgumentError, 'at least one rate is required.') if rates.empty?
+      raise(ArgumentError, 'rates must be Finrb::Rate instances.') unless rates.all?(Rate)
+      raise(ArgumentError, 'every rate must have a duration.') if rates.any? { |rate| rate.duration.nil? }
+
       @rates     = rates
       @block     = block
 
@@ -83,7 +95,7 @@ module Finrb
     # @return [Array] the amount of any additional payments in each period
     # @example
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
-    #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
+    #   amt = Finrb::Amortization.new(300000, rate){ |payment| payment.amount-100}
     #   amt.additional_payments #=> [Flt::DecNum('-100.00'), Flt::DecNum('-100.00'), ... ]
     # @api public
     def additional_payments
@@ -103,13 +115,14 @@ module Finrb
 
       pmt = Payment.new(amount, period: @period)
       pmt.modify(&@block) if @block
+      raise(ArgumentError, 'payment modification must produce a negative amount.') unless pmt.amount.negative?
 
       rate.duration.to_i.times do
         # Do this first in case the balance is zero already.
         break if @balance.zero?
 
         # Compute and record interest on the outstanding balance.
-        int = (@balance * rate.monthly).round(2)
+        int = Precision.money(@balance * rate.monthly)
         interest = Interest.new(int, period: @period)
         @balance += interest.amount
         @transactions << interest.dup
@@ -148,11 +161,11 @@ module Finrb
     # @return [Integer] the time required to pay off the loan, in months
     # @example In most cases, the duration is equal to the total duration of all rates
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
-    #   amt = 300000.amortize(rate)
+    #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.duration #=> 360
     # @example Extra payments may reduce the duration
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
-    #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
+    #   amt = Finrb::Amortization.new(300000, rate){ |payment| payment.amount-100}
     #   amt.duration #=> 319
     # @api public
     def duration
@@ -167,11 +180,11 @@ module Finrb
     # @return [Array] the amount of interest charged in each period
     # @example find the total cost of interest for a loan
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
-    #   amt = 300000.amortize(rate)
+    #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.interest.sum #=> Flt::DecNum('200163.94')
     # @example find the total interest charges in the first six months
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
-    #   amt = 300000.amortize(rate)
+    #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.interest[0,6].sum #=> Flt::DecNum('5603.74')
     # @api public
     def interest
@@ -181,7 +194,7 @@ module Finrb
     # @return [Array] the amount of the payment in each period
     # @example find the total payments for a loan
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
-    #   amt = 300000.amortize(rate)
+    #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.payments.sum #=> Flt::DecNum('-500163.94')
     # @api public
     def payments
@@ -189,11 +202,3 @@ module Finrb
     end
   end
 end
-
-class Numeric
-  # @see Amortization#new
-  # @api public
-  def amortize(...)
-    Finrb::Amortization.new(self, ...)
-  end
-end

data/lib/finrb/cashflows.rb

@@ -2,83 +2,83 @@
 
 require_relative 'config'
 require_relative 'decimal'
+require_relative 'errors'
+require_relative 'numerical/brent'
+require_relative 'numerical/rate_search'
 require_relative 'rates'
+require_relative 'validation'
 
-require 'bigdecimal'
-require 'bigdecimal/newton'
-require 'business_time'
+require 'date'
 
 module Finrb
   # Provides methods for working with cash flows (collections of transactions)
   # @api public
   module Cashflow
-    include Newton
+    class << self
+      def irr(cashflows, guess = nil)
+        sequence(cashflows).irr(guess)
+      end
 
-    # Base class for working with Newton's Method.
-    # @api private
-    class Function
-      values = { eps: Finrb.config.eps, one: '1.0', two: '2.0', ten: '10.0', zero: '0.0' }
+      def npv(cashflows, rate)
+        sequence(cashflows).npv(rate)
+      end
 
-      values.each do |key, value|
-        define_method key do
-          BigDecimal(value)
-        end
+      def xirr(transactions, guess = nil)
+        sequence(transactions).xirr(guess)
       end
 
-      def initialize(transactions, function)
-        @transactions = transactions
-        @function = function
+      def xnpv(transactions, rate)
+        sequence(transactions).xnpv(rate)
       end
 
-      def values(x)
-        value = @transactions.public_send(@function, Flt::DecNum.new(x.first.to_s))
-        begin
-          [BigDecimal(value.to_s)]
-        rescue ArgumentError
-          [0]
-        end
+      private
+
+      def sequence(cashflows)
+        raise(ArgumentError, 'cashflows must be an enumerable collection') unless cashflows.respond_to?(:to_a)
+
+        cashflows.to_a.extend(Finrb::Cashflow)
       end
     end
 
-    # calculate the internal rate of return for a sequence of cash flows
-    # @return [Flt::DecNum] the internal rate of return
-    # @param [Numeric] guess Initial guess rate, Defaults to 1.0
+    # Calculate the per-period internal rate of return for an ordered sequence
+    # of equally spaced cashflows.
+    #
+    # For cashflows with multiple sign-changing roots, the guess determines
+    # which nearby root is selected. Rates must be greater than -1.
+    # @return [Flt::DecNum] the per-period internal rate of return
+    # @param [Numeric, nil] guess initial rate used for root selection; defaults
+    #   to +Finrb.config.guess+
+    # @raise [InvalidCashflowError] if the sequence lacks both cashflow signs
+    # @raise [ArgumentError] if the guess is not numeric
+    # @raise [DomainError] if the rate domain or function evaluation is invalid
+    # @raise [ConvergenceError] if no root can be bracketed or solved
     # @example
-    #   [-4000,1200,1410,1875,1050].irr #=> 0.143
+    #   Finrb::Cashflow.irr([-4000,1200,1410,1875,1050]) #=> 0.143
     # @see https://en.wikipedia.org/wiki/Internal_rate_of_return
     # @api public
     def irr(guess = nil)
-      # Make sure we have a valid sequence of cash flows.
-      positives, negatives = partition { |i| i >= 0 }
-      raise(ArgumentError, 'Calculation does not converge.') if positives.empty? || negatives.empty?
-
-      func = Function.new(self, :npv)
-      rate = [valid(guess)]
-      nlsolve(func, rate)
-      rate.first
-    end
-
-    def method_missing(name, *args, &)
-      return sum if name.to_s == 'sum'
+      validate_numeric_cashflows!
 
-      super
-    end
+      # Make sure we have a valid sequence of cash flows.
+      raise(InvalidCashflowError, 'Cashflow needs at least one positive and one negative value.') if none?(&:positive?) || none?(&:negative?)
 
-    def respond_to_missing?(name, include_private = false)
-      name.to_s == 'sum' || super
+      solve(:npv, valid(guess))
     end
 
     # calculate the net present value of a sequence of cash flows
     # @return [Flt::DecNum] the net present value
     # @param [Numeric] rate the discount rate to be applied
     # @example
-    #   [-100.0, 60, 60, 60].npv(0.1) #=> 49.211
+    #   Finrb::Cashflow.npv([-100.0, 60, 60, 60], 0.1) #=> 49.211
     # @see https://en.wikipedia.org/wiki/Net_present_value
     # @api public
     def npv(rate)
-      cashflows = map { |entry| Flt::DecNum.new(entry.to_s) }
+      validate_numeric_cashflows!
+      cashflows = map { |entry| Validation.decimal(entry, name: 'cashflow amount') }
+
+      rate = Validation.decimal(rate, name: 'rate')
+      raise(DomainError, 'Rate must be greater than -1.') if rate <= -1
 
-      rate = Flt::DecNum.new(rate.to_s)
       total = Flt::DecNum.new(0.to_s)
       cashflows.each_with_index do |cashflow, index|
         total += cashflow / ((rate + 1)**index)
@@ -87,25 +87,36 @@ module Finrb
       total
     end
 
-    # calculate the internal rate of return for a sequence of cash flows with dates
-    # @param[Numeric] Initial guess rate, Deafults to 1.0
-    # @return [Rate] the internal rate of return
+    # Calculate the effective annual internal rate of return for an ordered
+    # sequence of dated transactions.
+    #
+    # Under the default configuration, date offsets are actual calendar days
+    # from the first transaction and a 365-day year is used. Transactions
+    # should be supplied chronologically and their dates must respond to
+    # +to_date+. For multiple roots, the guess determines which nearby root is
+    # selected. Rates must be greater than -1.
+    # @param [Numeric, nil] guess initial rate used for root selection; defaults
+    #   to +Finrb.config.guess+
+    # @return [Rate] the effective annual internal rate of return
+    # @raise [InvalidCashflowError] if the sequence lacks both cashflow signs
+    # @raise [ArgumentError] if the guess is not numeric
+    # @raise [DomainError] if the rate domain or function evaluation is invalid
+    # @raise [ConvergenceError] if no root can be bracketed or solved
     # @example
     #   @transactions = []
     #   @transactions << Transaction.new(-1000, :date => Time.new(1985,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
-    #   @transactions.xirr(0.6) #=> Rate("0.024851", :apr, :compounds => :annually)
+    #   Finrb::Cashflow.xirr(@transactions, 0.6) #=> Rate("0.024851", :effective, :compounds => :annually)
     # @api public
     def xirr(guess = nil)
+      validate_dated_cashflows!
+
       # Make sure we have a valid sequence of cash flows.
-      positives, negatives = partition { |t| t.amount >= 0 }
-      raise(ArgumentError, 'Calculation does not converge. Cashflow needs to have a least one positive and one negative value.') if positives.empty? || negatives.empty?
+      raise(InvalidCashflowError, 'Cashflow needs at least one positive and one negative value.') if none? { |transaction| transaction.amount.positive? } || none? { |transaction| transaction.amount.negative? }
 
-      func = Function.new(self, :xnpv)
-      rate = [valid(guess)]
-      nlsolve(func, rate)
-      Rate.new(rate.first, :apr, compounds: Finrb.config.periodic_compound ? :continuously : :annually)
+      rate = solve(:xnpv, valid(guess))
+      Rate.new(rate, :effective, compounds: Finrb.config.periodic_compound ? :continuously : :annually)
     end
 
     # calculate the net present value of a sequence of cash flows
@@ -115,10 +126,12 @@ module Finrb
     #   @transactions << Transaction.new(-1000, :date => Time.new(1985,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
-    #   @transactions.xnpv(0.6).round(2) #=> -937.41
+    #   Finrb::Cashflow.xnpv(@transactions, 0.6).round(2) #=> -937.41
     # @api public
     def xnpv(rate)
-      rate = Flt::DecNum.new(rate.to_s)
+      validate_dated_cashflows!
+      rate = Validation.decimal(rate, name: 'rate')
+      raise(DomainError, 'Rate must be greater than -1.') if rate <= -1
 
       sum do |t|
         t.amount / ((rate + 1)**(date_diff(start, t.date) / days_in_period))
@@ -127,19 +140,37 @@ module Finrb
 
     private
 
+    def validate_numeric_cashflows!
+      raise(InvalidCashflowError, 'Cashflow cannot be empty.') if empty?
+
+      each { |amount| Validation.decimal(amount, name: 'cashflow amount') }
+    rescue ArgumentError => e
+      raise(InvalidCashflowError, e.message, e.backtrace)
+    end
+
+    def validate_dated_cashflows!
+      raise(InvalidCashflowError, 'Dated cashflow cannot be empty.') if empty?
+      raise(InvalidCashflowError, 'Dated cashflows require Finrb::Transaction instances with dates.') unless all? { |transaction| transaction.is_a?(Transaction) && transaction.date.respond_to?(:to_date) }
+      raise(InvalidCashflowError, 'Dated cashflows must be in chronological order.') unless each_cons(2).all? { |left, right| left.date.to_date <= right.date.to_date }
+    end
+
     def date_diff(from, to)
       if Finrb.config.business_days
-        from.to_date.business_days_until(to)
+        business_days_between(from.to_date, to.to_date)
       else
-        to - from
+        to.to_date - from.to_date
       end
     end
 
+    def business_days_between(from, to)
+      (from...to).count { |date| (1..5).cover?(date.wday) }
+    end
+
     def days_in_period
       if Finrb.config.periodic_compound && Finrb.config.business_days
-        start.to_date.business_days_until(stop).to_f
+        business_days_between(start.to_date, stop).to_f
       else
-        Flt::DecNum.new(365.days.to_s)
+        Flt::DecNum.new(365)
       end
     end
 
@@ -147,6 +178,14 @@ module Finrb
       @start ||= first.date
     end
 
+    def solve(function, guess)
+      rate_function = ->(rate) { public_send(function, rate) }
+      bounds = Numerical::RateSearch.new.bracket(rate_function, guess:)
+      return bounds.first if bounds.first == bounds.last
+
+      Numerical::Brent.new(tolerance: Finrb.config.eps).solve(rate_function, lower: bounds.first, upper: bounds.last)
+    end
+
     def stop
       @stop ||= last.date.to_date
     end
@@ -160,11 +199,7 @@ module Finrb
         raise(ArgumentError, 'Invalid Guess. Use a [Numeric] value.') unless guess.is_a?(Numeric)
 
         guess
-      end.to_f
+      end.then { |value| Flt::DecNum.new(value.to_s) }
     end
   end
 end
-
-class Array
-  include Finrb::Cashflow
-end

data/lib/finrb/config.rb

@@ -1,14 +1,63 @@
 # frozen_string_literal: true
 
+require_relative 'validation'
+
 module Finrb
-  Config = Struct.new(:eps, :guess, :business_days, :periodic_compound)
-  private_constant :Config
+  Configuration = Data.define(:eps, :guess, :business_days, :periodic_compound)
+  ConfigurationBuilder = Struct.new(:eps, :guess, :business_days, :periodic_compound)
+  DEFAULT_CONFIGURATION = Configuration.new(eps: Flt::DecNum.new('1.0e-16'), guess: Flt::DecNum.new('1.0'), business_days: false, periodic_compound: false)
+  CONFIG_OVERRIDE_KEY = :finrb_configuration_override
+  private_constant :Configuration, :ConfigurationBuilder, :DEFAULT_CONFIGURATION, :CONFIG_OVERRIDE_KEY
 
   def self.config
-    @config ||= Config.new(eps: '1.0e-16', guess: 1.0, business_days: false, periodic_compound: false)
+    Thread.current[CONFIG_OVERRIDE_KEY] || (@config ||= DEFAULT_CONFIGURATION)
   end
 
+  # Atomically replace the process-wide defaults. Configure the application at
+  # startup; use +with_config+ for temporary or concurrent overrides.
   def self.configure
-    yield(config)
+    raise(ArgumentError, 'configuration requires a block.') unless block_given?
+
+    builder = ConfigurationBuilder.new(**config.to_h)
+    yield(builder)
+    @config = build_configuration(builder.to_h)
+  end
+
+  # Apply a validated configuration only for the current execution context and
+  # restore the previous configuration even when the block raises.
+  def self.with_config(**overrides)
+    raise(ArgumentError, 'configuration override requires a block.') unless block_given?
+
+    unknown = overrides.keys - config.to_h.keys
+    raise(ArgumentError, "unknown configuration options: #{unknown.join(', ')}") unless unknown.empty?
+
+    previous = Thread.current[CONFIG_OVERRIDE_KEY]
+    Thread.current[CONFIG_OVERRIDE_KEY] = build_configuration(config.to_h.merge(overrides))
+    begin
+      yield
+    ensure
+      Thread.current[CONFIG_OVERRIDE_KEY] = previous
+    end
+  end
+
+  def self.build_configuration(values)
+    eps = configuration_decimal(values.fetch(:eps), name: 'eps')
+    raise(ArgumentError, 'eps must be positive.') unless eps.positive?
+
+    guess = configuration_decimal(values.fetch(:guess), name: 'guess')
+    raise(ArgumentError, 'guess must be greater than -1.') if guess <= -1
+
+    business_days = values.fetch(:business_days)
+    periodic_compound = values.fetch(:periodic_compound)
+    booleans = [business_days, periodic_compound].all? { |value| value.equal?(true) || value.equal?(false) }
+    raise(ArgumentError, 'business_days and periodic_compound must be boolean.') unless booleans
+
+    Configuration.new(eps:, guess:, business_days:, periodic_compound:)
+  end
+
+  def self.configuration_decimal(value, name:)
+    value = Flt::DecNum.new(value) if value.is_a?(String)
+    Validation.decimal(value, name:)
   end
+  private_class_method :build_configuration, :configuration_decimal
 end

data/lib/finrb/core_ext/array.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Legacy fluent cashflow API, loaded only through +finrb/core_ext+.
+class Array
+  include Finrb::Cashflow
+end

data/lib/finrb/core_ext/numeric.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Legacy numeric convenience API, loaded only through +finrb/core_ext+.
+class Numeric
+  def to_dec
+    instance_of?(Flt::DecNum) ? self : Flt::DecNum(to_s)
+  end
+
+  def amortize(...)
+    Finrb::Amortization.new(self, ...)
+  end
+end

data/lib/finrb/core_ext.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'finrb'
+require 'finrb/core_ext/array'
+require 'finrb/core_ext/numeric'
+
+module Finrb
+  # Namespace marker for the explicitly loaded legacy core extensions.
+  module CoreExt
+  end
+end

data/lib/finrb/decimal.rb

@@ -10,13 +10,3 @@ end
 Flt::DecNum.context.define_conversion_to(BigDecimal) do |x|
   BigDecimal(x.to_s)
 end
-
-class Numeric
-  def to_dec
-    if instance_of?(Flt::DecNum)
-      self
-    else
-      Flt::DecNum(to_s)
-    end
-  end
-end

data/lib/finrb/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Finrb
+  class Error < StandardError; end
+  class ConvergenceError < Error; end
+  class DomainError < Error; end
+  class InvalidCashflowError < Error; end
+end

data/lib/finrb/numerical/brent.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'flt'
+require_relative '../errors'
+
+module Finrb
+  module Numerical
+    # Brent-Dekker root solver for a continuous function on a sign-changing
+    # interval. The interpolation steps are safeguarded by bisection.
+    #
+    # Algorithm: R. P. Brent, Algorithms for Minimization Without Derivatives,
+    # Chapter 4 (1973). See also the GNU GSL root-finding documentation:
+    # https://www.gnu.org/software/gsl/doc/html/roots.html
+    class Brent
+      DEFAULT_MAX_ITERATIONS = 256
+      private_constant :DEFAULT_MAX_ITERATIONS
+
+      def initialize(tolerance:, relative_tolerance: tolerance, max_iterations: DEFAULT_MAX_ITERATIONS)
+        @absolute_tolerance = decimal(tolerance)
+        @relative_tolerance = decimal(relative_tolerance)
+        @max_iterations = Integer(max_iterations)
+
+        raise(ArgumentError, 'Tolerance must be positive.') unless @absolute_tolerance.positive? && @relative_tolerance.positive?
+        raise(ArgumentError, 'Maximum iterations must be positive.') unless @max_iterations.positive?
+      end
+
+      def solve(function, lower:, upper:)
+        left = decimal(lower)
+        right = decimal(upper)
+        raise(ArgumentError, 'Lower bound must be less than upper bound.') if left >= right
+
+        left_value = evaluate(function, left)
+        right_value = evaluate(function, right)
+
+        return left if left_value.zero?
+        return right if right_value.zero?
+        raise(ConvergenceError, 'Root is not bracketed.') unless opposite_signs?(left_value, right_value)
+
+        left, right, left_value, right_value = best_approximation_last(left, right, left_value, right_value)
+
+        previous = left
+        previous_value = left_value
+        penultimate = previous
+        bisected = true
+
+        @max_iterations.times do
+          tolerance = @absolute_tolerance + (@relative_tolerance * right.abs)
+          return right if right_value.zero? || (right - left).abs <= tolerance
+
+          candidate =
+            if distinct_values?(left_value, right_value, previous_value)
+              inverse_quadratic(left, right, previous, left_value, right_value, previous_value)
+            else
+              right - (right_value * (right - left) / (right_value - left_value))
+            end
+
+          bound = ((left * 3) + right) / 4
+          outside_safe_interval = candidate <= [bound, right].min || candidate >= [bound, right].max
+          insufficient_progress =
+            (candidate - right).abs >= if bisected
+                                         ((right - previous).abs / 2)
+                                       else
+                                         ((previous - penultimate).abs / 2)
+                                       end
+          bracket_too_small =
+            if bisected
+              (right - previous).abs < tolerance
+            else
+              (previous - penultimate).abs < tolerance
+            end
+
+          if outside_safe_interval || insufficient_progress || bracket_too_small
+            candidate = (left + right) / 2
+            bisected = true
+          else
+            bisected = false
+          end
+
+          candidate_value = evaluate(function, candidate)
+          penultimate = previous
+          previous = right
+          previous_value = right_value
+
+          if opposite_signs?(left_value, candidate_value)
+            right = candidate
+            right_value = candidate_value
+          else
+            left = candidate
+            left_value = candidate_value
+          end
+
+          left, right, left_value, right_value = best_approximation_last(left, right, left_value, right_value)
+        end
+
+        raise(ConvergenceError, "Calculation did not converge after #{@max_iterations} iterations.")
+      end
+
+      private
+
+      def inverse_quadratic(left, right, previous, left_value, right_value, previous_value)
+        left_term = (left * right_value * previous_value) / ((left_value - right_value) * (left_value - previous_value))
+        right_term = (right * left_value * previous_value) / ((right_value - left_value) * (right_value - previous_value))
+        previous_term = (previous * left_value * right_value) / ((previous_value - left_value) * (previous_value - right_value))
+        left_term + right_term + previous_term
+      end
+
+      def best_approximation_last(left, right, left_value, right_value)
+        return [right, left, right_value, left_value] if left_value.abs < right_value.abs
+
+        [left, right, left_value, right_value]
+      end
+
+      def distinct_values?(*values)
+        values.uniq.length == values.length
+      end
+
+      def evaluate(function, value)
+        result = decimal(function.call(value))
+        raise(DomainError, "Solver function returned a non-finite value at #{value}.") unless result.finite?
+
+        result
+      rescue Flt::Num::Exception, FloatDomainError, Math::DomainError, ZeroDivisionError => e
+        raise(DomainError, "Solver function is undefined at #{value}: #{e.message}", e.backtrace)
+      end
+
+      def decimal(value)
+        Flt::DecNum.new(value.to_s)
+      end
+
+      def opposite_signs?(left, right)
+        left.negative? != right.negative?
+      end
+    end
+  end
+end