xirr 0.7.1 → 1.0.0

data/lib/xirr/bisection.rb

@@ -1,18 +1,20 @@
 # frozen_string_literal: true
 
 module Xirr
-  # Methods that will be included in Cashflow to calculate XIRR
+  # Bisection solver: repeatedly halves a bracket that straddles the root. It
+  # always converges on a bracketed flow but only linearly, so it is slower than
+  # {RtSafe}, which is the default. Kept for `xirr(method: :bisection)`.
   class Bisection
     include Base
 
     # Calculates yearly Internal Rate of Return
-    # @return [BigDecimal]
+    # @return [Float]
     # @param midpoint [Float]
     # An initial guess rate will override the {Cashflow#irr_guess}
     def xirr(midpoint, options)
       # Initial values
-      left  = [BigDecimal(-0.99999999, Xirr.config.precision), cf.irr_guess].min
-      right = [BigDecimal(9.99999999, Xirr.config.precision), cf.irr_guess + 1].max
+      left  = [-0.99999999, cf.irr_guess].min
+      right = [9.99999999, cf.irr_guess + 1].max
       @original_right = right
       midpoint ||= cf.irr_guess
 
@@ -23,16 +25,16 @@ module Xirr
 
     private
 
-    # @param midpoint [BigDecimal]
+    # @param midpoint [Float]
     # @return [Boolean]
     # Checks if result is the right limit.
     def right_limit_reached?(midpoint)
       (@original_right - midpoint).abs < Xirr.config.eps
     end
 
-    # @param left [BigDecimal]
-    # @param midpoint [BigDecimal]
-    # @param right [BigDecimal]
+    # @param left [Float]
+    # @param midpoint [Float]
+    # @param right [Float]
     # @return [Array]
     # Calculates the Bisections
     def bisection(left, midpoint, right)
@@ -57,11 +59,13 @@ module Xirr
 
     def get_answer(midpoint, options, runs)
       if runs >= options[:iteration_limit]
-        if options[:raise_exception]
-          raise ArgumentError, "Did not converge after #{runs} tries."
-        end
+        raise ArgumentError, "Did not converge after #{runs} tries." if options[:raise_exception]
+
+        nil
       else
-        midpoint.round Xirr.config.precision
+        answer = midpoint.round(Xirr.config.precision)
+        # A midpoint parked at the -100% floor means no root was bracketed.
+        answer <= -1 ? nil : answer
       end
     end
 

data/lib/xirr/bonds.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Fixed income: pricing a bond, solving for its yield, and the standard risk
+  # metrics (Macaulay and modified duration, convexity).
+  #
+  # A bond pays a coupon of +coupon_rate+ a year, split across +freq+ payments
+  # (semiannual by default), and returns its +face+ value at maturity, +years+
+  # from now. Rates are quoted per year; +ytm+ is the yield to maturity.
+  # Settlement is assumed to fall on a coupon date, so prices are clean and the
+  # number of coupon periods is whole.
+  #
+  # The risk metrics don't depend on the face value (it cancels out), so they
+  # omit it and lead with +coupon_rate+, unlike {price} and {ytm}.
+  module Bonds
+    module_function
+
+    # Price of a bond: the present value of its coupons and face value discounted
+    # at the yield +ytm+. Prices at par when the coupon rate equals the yield.
+    # @return [Float]
+    def price(face, coupon_rate, ytm, years, freq = 2, precision: Xirr.config.precision)
+      n = periods(years, freq)
+      value = RtSafe.present_value(bond_flows(face, coupon_rate, n, freq), ytm.to_f / freq)
+      round_value(value, precision)
+    end
+
+    # Yield to maturity: the annual yield that discounts a bond's coupons and
+    # face value back to +price+. The inverse of {price}; reuses the {RtSafe}
+    # solver.
+    # @return [Float]
+    def ytm(face, coupon_rate, price, years, freq = 2, guess: 0.05, precision: Xirr.config.precision)
+      n = periods(years, freq)
+      flows = [[0.0, -price * 1.0]] + bond_flows(face, coupon_rate, n, freq)
+      periodic = RtSafe.find(flows, guess: guess)
+      raise ArgumentError, 'ytm did not converge' if periodic.nil?
+
+      round_value(periodic * freq, precision)
+    end
+
+    # Macaulay duration — the present-value-weighted average time, in years,
+    # until a bond's cash flows are received.
+    # @return [Float]
+    def duration(coupon_rate, ytm, years, freq = 2, precision: Xirr.config.precision)
+      with_metric(coupon_rate, years, freq, precision) do |flows|
+        macaulay(flows, ytm.to_f / freq, freq)
+      end
+    end
+
+    # Modified duration — Macaulay duration divided by +1 + ytm/freq+. Estimates
+    # the percentage price change for a small change in yield.
+    # @return [Float]
+    def modified_duration(coupon_rate, ytm, years, freq = 2, precision: Xirr.config.precision)
+      with_metric(coupon_rate, years, freq, precision) do |flows|
+        macaulay(flows, ytm.to_f / freq, freq) / (1 + ytm.to_f / freq)
+      end
+    end
+
+    # Convexity, in years² — the second-order sensitivity of a bond's price to
+    # yield. Pairs with modified duration to refine a price-change estimate.
+    # @return [Float]
+    def convexity(coupon_rate, ytm, years, freq = 2, precision: Xirr.config.precision)
+      with_metric(coupon_rate, years, freq, precision) do |flows|
+        convexity_value(flows, ytm.to_f / freq, freq)
+      end
+    end
+
+    # --- helpers ------------------------------------------------------------
+
+    def round_value(value, precision)
+      value.round(precision) + 0.0
+    end
+
+    # Validate periods, build unit-face flows, apply +block+, and round.
+    def with_metric(coupon_rate, years, freq, precision)
+      flows = bond_flows(1, coupon_rate, periods(years, freq), freq)
+      round_value(yield(flows), precision)
+    end
+
+    # Whole, positive coupon-period count.
+    def periods(years, freq)
+      n = years * freq
+      t = n.to_i
+      raise ArgumentError, 'years * freq must be a positive whole number' unless freq > 0 && n == t && t.positive?
+
+      t
+    end
+
+    # Coupon + redemption flows on +face+ as [[period, amount]], k = 1..n; the
+    # face value is added onto the final coupon.
+    def bond_flows(face, coupon_rate, n, freq)
+      coupon = face * coupon_rate / freq
+      (1..n).map do |k|
+        amount = k == n ? coupon + face : coupon
+        [k * 1.0, amount * 1.0]
+      end
+    end
+
+    def weighted_pv(flows, rate)
+      flows.map { |k, cf| [k, cf / (1 + rate)**k] }
+    end
+
+    # Macaulay duration in years: PV-weighted average period, divided by freq.
+    def macaulay(flows, rate, freq)
+      weighted = weighted_pv(flows, rate)
+      price = weighted.sum { |_k, pv| pv }
+      weighted.sum { |k, pv| k * pv } / price / freq
+    end
+
+    # Convexity in years²: the k·(k+1)-weighted PV sum, annualized by freq².
+    def convexity_value(flows, rate, freq)
+      weighted = weighted_pv(flows, rate)
+      price = weighted.sum { |_k, pv| pv }
+      num = weighted.sum { |k, pv| k * (k + 1) * pv }
+      num / price / (1 + rate)**2 / freq**2
+    end
+
+    private_class_method :round_value, :with_metric, :periods, :bond_flows,
+                         :weighted_pv, :macaulay, :convexity_value
+  end
+end

data/lib/xirr/brent.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Brent's method: a derivative-free root finder combining inverse quadratic
+  # interpolation, the secant method, and bisection. It reuses {RtSafe}'s
+  # bracketing, so it is as robust as the default solver but never evaluates the
+  # NPV derivative — each iteration is cheaper, though it needs more of them.
+  #
+  # In practice it roughly ties {RtSafe}; it is offered for very large cashflows,
+  # where the cheaper per-iteration cost can win. Select it with
+  # `xirr(method: :brent)`. Unlike the Newton-based solvers it ignores the initial
+  # guess — it works from the bracket.
+  class Brent
+    include Base
+
+    # @param guess [Float, nil] ignored; Brent brackets the root itself
+    # @param options [Hash] reads +:iteration_limit+
+    # @return [Float, nil]
+    def xirr(_guess, options)
+      limit = (options && options[:iteration_limit]) || Xirr.config.iteration_limit
+      Brent.find(flows, iteration_limit: limit)
+    end
+
+    # Pure solver over normalized +[time, amount]+ flows.
+    # @param flows [Array<Array(Float, Float)>]
+    # @return [Float, nil]
+    def self.find(flows, tolerance: Xirr.config.eps, iteration_limit: Xirr.config.iteration_limit, precision: Xirr.config.precision)
+      rate = zbrent(flows, tolerance.to_f, iteration_limit)
+      return nil if rate.nil? || rate.nan? || rate.infinite?
+
+      rounded = rate.round(precision)
+      rounded <= -1.0 ? nil : rounded
+    rescue FloatDomainError, Math::DomainError
+      nil
+    end
+
+    # Bracket a sign change (reusing RtSafe), then iterate Brent's method within
+    # it. Returns the rate, or nil if it can't bracket or converge.
+    def self.zbrent(flows, tol, iteration_limit)
+      low = RtSafe.safe_low(flows)
+      f_low = RtSafe.present_value(flows, low)
+      bounds = RtSafe.bracket(flows, low, f_low, 1.0)
+      return nil if bounds.nil?
+
+      a, b = bounds
+      fa = f_low # a == low
+      fb = RtSafe.present_value(flows, b)
+      c = a
+      fc = fa
+      d = e = b - a
+
+      iteration_limit.times do
+        # Keep c as the contrapoint — opposite sign to b, so [b, c] brackets.
+        if (fb.positive? && fc.positive?) || (fb.negative? && fc.negative?)
+          c = a
+          fc = fa
+          d = e = b - a
+        end
+        # Ensure b is the better estimate.
+        if fc.abs < fb.abs
+          a = b
+          b = c
+          c = a
+          fa = fb
+          fb = fc
+          fc = fa
+        end
+
+        tol1 = 2.0 * Float::EPSILON * b.abs + 0.5 * tol
+        xm = 0.5 * (c - b)
+        return b if xm.abs <= tol1 || fb.zero?
+
+        if e.abs >= tol1 && fa.abs > fb.abs
+          s = fb / fa
+          if a == c
+            # Secant step.
+            p = 2.0 * xm * s
+            q = 1.0 - s
+          else
+            # Inverse quadratic interpolation.
+            q = fa / fc
+            r = fb / fc
+            p = s * (2.0 * xm * q * (q - r) - (b - a) * (r - 1.0))
+            q = (q - 1.0) * (r - 1.0) * (s - 1.0)
+          end
+          q = -q if p.positive?
+          p = p.abs
+          min1 = 3.0 * xm * q - (tol1 * q).abs
+          min2 = (e * q).abs
+          if 2.0 * p < (min1 < min2 ? min1 : min2)
+            e = d
+            d = p / q # accept interpolation
+          else
+            d = e = xm # fall back to bisection
+          end
+        else
+          d = e = xm # bounds decreasing too slowly; bisect
+        end
+
+        a = b
+        fa = fb
+        b += d.abs > tol1 ? d : (xm.positive? ? tol1 : -tol1)
+        fb = RtSafe.present_value(flows, b)
+      end
+      nil
+    end
+  end
+end

data/lib/xirr/cashflow.rb

@@ -45,40 +45,109 @@ module Xirr
       @max_date ||= map(&:date).max
     end
 
-    # Calculates a simple IRR guess based on period of investment and multiples.
+    # A rough starting rate for the solver: the cash-on-cash multiple annualized
+    # over the investment horizon, +multiple^(1 / years) - 1+.
+    #
+    # It falls back to 0.0 whenever that estimate is undefined or unusable — an
+    # invalid or empty cashflow, a horizon of zero, a non-positive multiple, or a
+    # rate at or below -100% (which the solver can't start from). The default
+    # +rtsafe+ solver does not depend on this being accurate; it only needs a
+    # finite rate above -1.
     # @return [Float]
     def irr_guess
-      return @irr_guess = 0.0 if periods_of_investment.zero?
-      return @irr_guess = 0.0 if multiple <= 0
-    
-      @irr_guess = valid? ? ((multiple**(1.0 / periods_of_investment)) - 1).round(3) : 0.0
-      @irr_guess.infinite? ? 0.0 : @irr_guess
+      return @irr_guess = 0.0 unless valid?
+      return @irr_guess = 0.0 if periods_of_investment.zero? || multiple <= 0
+
+      guess = ((multiple**(1.0 / periods_of_investment)) - 1).round(3)
+      @irr_guess = (guess.nan? || guess.infinite? || guess <= -1) ? 0.0 : guess
     end
 
     # @param guess [Float]
     # @param method [Symbol]
-    # @return [Float]
+    # @return [Float] the rate, or +Xirr.config.replace_for_nil+ when it can't converge
     def xirr(guess: nil, method: nil, ** options)
       method, options = process_options(method, options)
       if invalid?
         raise ArgumentError, invalid_message if options[:raise_exception]
-        BigDecimal(0, Xirr.config.precision)
-      else
-        xirr = choose_(method).send :xirr, guess, options
-        xirr = choose_(other_calculation_method(method)).send(:xirr, guess, options) if (xirr.nil? || xirr.nan?) && fallback
-        xirr || Xirr.config.replace_for_nil
+        return Xirr.config.replace_for_nil
       end
+
+      result = choose_(method).send(:xirr, guess, options)
+      # rtsafe already combines a Newton step with a bisection safeguard, so it is
+      # the fallback for the fragile solvers; when it is itself the primary there
+      # is nothing better to try, and a failure means the flow has no rate.
+      if unconverged?(result) && fallback && method != :rtsafe && method != :rtsafe_c
+        result = choose_(:rtsafe).send(:xirr, guess, options)
+      end
+      if unconverged?(result)
+        raise ArgumentError, 'XIRR did not converge' if options[:raise_exception]
+        return Xirr.config.replace_for_nil
+      end
+      result
+    ensure
+      # A per-call +period:+ must not leak into later #xnpv / #mirr calls.
+      @temporary_period = nil
+    end
+
+    # Same as {#xirr}, but raises +ArgumentError+ when the cashflow is invalid or
+    # the rate can't be found, instead of returning +Xirr.config.replace_for_nil+.
+    # @return [Float]
+    def xirr!(guess: nil, method: nil, ** options)
+      xirr(guess: guess, method: method, **options.merge(raise_exception: true))
+    end
+
+    # Net present value of the dated flows discounted at +rate+ on the same
+    # Actual/period basis {#xirr} uses. Roughly zero when +rate+ is the XIRR.
+    # @param rate [Float]
+    # @return [Float]
+    def xnpv(rate)
+      inject(0.0) { |sum, t| sum + t.amount / (1.0 + rate) ** ((t.date - min_date) / period) }
+    end
+
+    # Modified IRR of the dated flows. Positive flows are assumed reinvested at
+    # +reinvest_rate+, negative flows financed at +finance_rate+. Unlike XIRR it
+    # has a closed form and a single answer.
+    # @param finance_rate [Float]
+    # @param reinvest_rate [Float]
+    # @return [Float]
+    def mirr(finance_rate, reinvest_rate)
+      raise ArgumentError, invalid_message if invalid?
+      years = periods_of_investment
+      raise ArgumentError, 'Flows span no time' if years.zero?
+
+      future_of_inflows = 0.0
+      present_of_outflows = 0.0
+      each do |t|
+        if t.amount > 0
+          future_of_inflows += t.amount * (1.0 + reinvest_rate) ** ((max_date - t.date) / period)
+        elsif t.amount < 0
+          present_of_outflows += t.amount / (1.0 + finance_rate) ** ((t.date - min_date) / period)
+        end
+      end
+
+      ((future_of_inflows / -present_of_outflows) ** (1.0 / years) - 1).round(Xirr.config.precision)
     end
 
     def process_options(method, options)
       @temporary_period         = options[:period]
-      options[:raise_exception] ||= @options[:raise_exception] || Xirr.config.raise_exception
-      options[:iteration_limit] ||= @options[:iteration_limit] || Xirr.config.iteration_limit
+      options[:raise_exception] = resolve_option(options, :raise_exception)
+      options[:iteration_limit] = resolve_option(options, :iteration_limit)
       return switch_fallback(method), options
     end
 
-    # If method is defined it will turn off fallback
-    # it return either the provided method or the system default
+    # Resolve an option in precedence order: this call, then the cashflow's own
+    # options, then the global config. Reads +key?+ so an explicit +false+ or +0+
+    # is honored rather than overwritten.
+    # @return [Object]
+    def resolve_option(options, key)
+      return options[key] if options.key?(key)
+      return @options[key] if @options.key?(key)
+
+      Xirr.config.public_send(key)
+    end
+
+    # Providing a method turns off fallback; otherwise use the configured default
+    # with fallback on. Returns the method to run.
     # @param method [Symbol]
     # @return [Symbol]
     def switch_fallback(method)
@@ -91,15 +160,14 @@ module Xirr
       end
     end
 
-    def other_calculation_method(method)
-      method == :newton_method ? :bisection : :newton_method
-    end
+    private :process_options, :resolve_option, :switch_fallback
 
+    # A copy of the cashflow with same-date transactions merged into one.
+    # @return [Cashflow]
     def compact_cf
-      # self
       compact = Hash.new 0
       each { |flow| compact[flow.date] += flow.amount }
-      Cashflow.new flow: compact.map { |key, value| Transaction.new(value, date: key) }, options: options, period: period
+      Cashflow.new(flow: compact.map { |date, amount| Transaction.new(amount, date: date) }, period: period, **options)
     end
 
     # First investment date
@@ -122,6 +190,9 @@ module Xirr
     def <<(arg)
       super arg
       sort! { |x, y| x.date <=> y.date }
+      # Adding a transaction can change the date range and leading sign, so drop
+      # the values memoized from the old contents.
+      @min_date = @max_date = @first_transaction_direction = nil
       self
     end
 
@@ -132,22 +203,37 @@ module Xirr
     # @return [Class]
     def choose_(method)
       case method
+      when :rtsafe
+        RtSafe.new compact_cf
+      when :brent
+        Brent.new compact_cf
+      when :rtsafe_c
+        unless Xirr::NATIVE
+          raise ArgumentError, 'the native :rtsafe_c extension is not compiled; ' \
+                               'reinstall the gem with a C toolchain or run `rake compile`'
+        end
+        RtSafeC.new compact_cf
       when :bisection
         Bisection.new compact_cf
       when :newton_method
         NewtonMethod.new compact_cf
       else
-        raise ArgumentError, "There is no method called #{method} "
+        raise ArgumentError, "unknown method #{method.inspect}; use :rtsafe, :rtsafe_c, :brent, :bisection, or :newton_method"
       end
     end
 
+    # A solver result that means "no rate found": nil, or a NaN.
+    # @return [Boolean]
+    def unconverged?(value)
+      value.nil? || (value.respond_to?(:nan?) && value.nan?)
+    end
+
     # @api private
     # Sorts the {Cashflow} by date ascending
     #   and finds the signal of the first transaction.
     # This implies the first transaction is a disbursement
     # @return [Integer]
     def first_transaction_direction
-      # self.sort! { |x, y| x.date <=> y.date }
       @first_transaction_direction ||= first.amount / first.amount.abs
     end
 

data/lib/xirr/config.rb

@@ -1,22 +1,25 @@
+# frozen_string_literal: true
+
 module Xirr
   include ActiveSupport::Configurable
 
-  # Sets as constants all the entries in the Hash Default values
+  # Default configuration. Each entry becomes both a config setting
+  # (+Xirr.config.eps+) and a frozen constant of the same name upcased
+  # (+Xirr::EPS+); the constant keeps the original default even after the setting
+  # is reconfigured.
   default_values = {
     eps:             '1.0e-6'.to_f,
     period:          365.0,
     iteration_limit: 50,
     precision:       6,
-    default_method:  :newton_method,
+    default_method:  :rtsafe,
     fallback:        true,
     replace_for_nil: 0.0,
-    compact: true,
     raise_exception: false
   }
 
-  # Iterates though default values and sets in config
   default_values.each do |key, value|
-    self.config.send("#{key.to_sym}=", value)
+    config.public_send("#{key}=", value)
     const_set key.to_s.upcase.to_sym, value
   end
 end

data/lib/xirr/depreciation.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Writing an asset down from its +cost+ to its +salvage+ value over its +life+.
+  # {sln} spreads the loss evenly; {syd}, {ddb}, and {db} are accelerated methods
+  # that depreciate more early on and return the amount for a single +period+
+  # (counting from 1).
+  module Depreciation
+    module_function
+
+    # Straight-line depreciation: the equal amount the asset is written down by
+    # each period.
+    # @return [Float]
+    def sln(cost, salvage, life)
+      raise ArgumentError, 'life must be non-zero' if life.zero?
+
+      (cost - salvage) / life * 1.0
+    end
+
+    # Sum-of-years'-digits depreciation for a single +period+ — an accelerated
+    # method charging more in the early periods.
+    # @return [Float]
+    def syd(cost, salvage, life, period)
+      raise ArgumentError, 'undefined' if life <= 0 || period < 1 || period > life
+
+      (cost - salvage) * (life - period + 1) * 2.0 / (life * (life + 1))
+    end
+
+    # Double-declining-balance depreciation for a single +period+: each period
+    # takes +factor/life+ of the remaining book value (never below +salvage+).
+    # +factor+ defaults to 2 (the usual double-declining rate).
+    # @return [Float]
+    def ddb(cost, salvage, life, period, factor = 2)
+      n = period.to_i
+      unless life.positive? && factor.positive? && period == n && n >= 1 && n <= life
+        raise ArgumentError, 'undefined'
+      end
+
+      declining_balance(cost, salvage, factor.to_f / life, n)
+    end
+
+    # Fixed-declining-balance depreciation for a single +period+. Like {ddb}, but
+    # the rate is derived from +cost+, +salvage+, and +life+ (rounded to three
+    # places, as spreadsheets do). +month+ is how many months the asset was in
+    # service during its first year (default 12); a shorter first year spills the
+    # remainder into an extra final period.
+    # @return [Float]
+    def db(cost, salvage, life, period, month = 12)
+      n = period.to_i
+      unless cost.positive? && salvage >= 0 && life.positive? && month >= 1 && month <= 12 &&
+             period == n && n >= 1 && n <= life + 1
+        raise ArgumentError, 'undefined'
+      end
+
+      fixed_declining(cost, salvage, life, n, month)
+    end
+
+    # --- helpers ------------------------------------------------------------
+
+    # Walk periods 1..period carrying accumulated depreciation; return the amount
+    # for the final period. Depreciation stops at the salvage floor.
+    def declining_balance(cost, salvage, rate, period)
+      accumulated = 0.0
+      dep = 0.0
+      (1..period).each do
+        book = cost - accumulated
+        dep = [[book * rate, book - salvage].min, 0.0].max
+        accumulated += dep
+      end
+      dep
+    end
+
+    def fixed_declining(cost, salvage, life, period, month)
+      rate = (1 - (salvage.to_f / cost)**(1.0 / life)).round(3)
+      accumulated = 0.0
+      dep = 0.0
+      (1..period).each do |p|
+        dep = db_period(cost, accumulated, rate, life, month, p)
+        accumulated += dep
+      end
+      dep
+    end
+
+    def db_period(cost, accumulated, rate, life, month, period)
+      return cost * rate * month / 12.0 if period == 1
+
+      if period <= life
+        (cost - accumulated) * rate
+      else
+        # The partial last period when the first year was shorter than 12 months.
+        (cost - accumulated) * rate * (12 - month) / 12.0
+      end
+    end
+
+    private_class_method :declining_balance, :fixed_declining, :db_period
+  end
+end