xirr 0.7.1 → 1.0.0

data/lib/xirr/newton_method.rb

@@ -1,61 +1,35 @@
 # frozen_string_literal: true
-require 'bigdecimal/newton'
 
 module Xirr
-  # Class to calculate IRR using Newton Method
+  # Plain Newton-Raphson: step from the guess by -xnpv/xnpv' until the step is
+  # smaller than the tolerance. Fast when it converges, but with no bracketing it
+  # can walk off to a non-root or below -100%; {RtSafe} is the safeguarded default
+  # that avoids that. Kept for `xirr(method: :newton_method)`.
   class NewtonMethod
     include Base
-    include Newton
 
-
-    # Base class for working with Newton's Method.
-    # @api private
-    class Function
-      values = {
-          eps: Xirr.config.eps,
-          one:  '1.0',
-          two:  '2.0',
-          ten:  '10.0',
-          zero: '0.0'
-      }
-
-      # define default values
-      values.each do |key, value|
-        define_method key do
-          BigDecimal(value, Xirr.config.precision)
-        end
+    # @param guess [Float, nil] initial rate
+    # @param options [Hash] reads +:iteration_limit+
+    # @return [Float, nil] the rate rounded to +Xirr.config.precision+, or nil
+    def xirr(guess, options)
+      limit = (options && options[:iteration_limit]) || Xirr.config.iteration_limit
+      rate = (guess || cf.irr_guess).to_f
+
+      limit.times do
+        derivative = xnpv_derivative(rate)
+        return nil if derivative.zero?
+
+        step = xnpv(rate).to_f / derivative
+        rate -= step
+        # Below -100% the discount base (1 + rate) turns negative and the next
+        # xnpv raises it to a fractional power, producing a Complex. Bail first.
+        return nil if rate.nan? || rate.infinite? || rate <= -1
+        break if step.abs < Xirr.config.eps
       end
 
-      # @param transactions [Cashflow]
-      # @param function [Symbol]
-      # Initializes the Function with the Cashflow it will use as data source and the function to reduce it.
-      def initialize(transactions, function)
-        @transactions = transactions
-        @function = function
-      end
-
-      # Necessary for #nlsolve
-      # @param x [BigDecimal]
-      def values(x)
-        value = @transactions.send(@function, BigDecimal(x[0].to_s, Xirr.config.precision))
-        [BigDecimal(value.to_s, Xirr.config.precision)]
-      end
-    end
-
-    # Calculates XIRR using Newton method
-    # @return [BigDecimal]
-    # @param guess [Float]
-    def xirr(guess, _options)
-      func = Function.new(self, :xnpv)
-      rate = [guess || cf.irr_guess]
-      begin
-        nlsolve(func, rate)
-        (rate[0] <= -1 || rate[0].nan?) ? nil : rate[0].round(Xirr.config.precision)
-
-          # rate[0].round(Xirr.config.precision)
-      rescue
-        nil
-      end
+      rate.nan? ? nil : rate.round(Xirr.config.precision)
+    rescue FloatDomainError, Math::DomainError, RangeError
+      nil
     end
   end
 end

data/lib/xirr/periodic.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Periodic (dateless) cash-flow functions. Where {Cashflow} works with dated
+  # flows, these take a plain list of amounts landing at equally spaced periods
+  # 0, 1, 2, …, for when the exact dates don't matter. The rate they return is
+  # per period.
+  module_function
+
+  # Internal rate of return of +amounts+ at periods 0, 1, 2, …
+  #
+  #   Xirr.irr([-1000, 1100])         # => 0.1
+  #   Xirr.irr([-1000, 500, 500, 300]) # => 0.156579
+  #
+  # @param amounts [Array<Numeric>]
+  # @param guess [Float] initial rate for the solver
+  # @return [Float] the rate per period
+  # @raise [ArgumentError] when there aren't at least one inflow and one outflow
+  def irr(amounts, guess: 0.1)
+    flows = validated_flows(amounts)
+    rate = RtSafe.find(flows, guess: guess)
+    raise ArgumentError, 'IRR did not converge' if rate.nil?
+    rate
+  end
+
+  # Net present value of +amounts+ at periods 0, 1, 2, … discounted at +rate+.
+  # The first amount sits at period 0 and is left undiscounted, so
+  # +Xirr.npv(Xirr.irr(a), a)+ comes out to roughly zero. This differs from a
+  # spreadsheet +NPV+, which places the first amount at period 1.
+  #
+  #   Xirr.npv(0.1, [-1000, 1100])      # => 0.0
+  #   Xirr.npv(0.1, [-1000, 600, 600])  # => 41.322314
+  #
+  # @param rate [Numeric]
+  # @param amounts [Array<Numeric>]
+  # @return [Float]
+  def npv(rate, amounts)
+    amounts.each_with_index.inject(0.0) do |sum, (amount, i)|
+      sum + amount.to_f / (1.0 + rate) ** i
+    end.round(Xirr.config.precision)
+  end
+
+  # Modified internal rate of return of periodic +amounts+. Positive flows are
+  # assumed reinvested at +reinvest_rate+, negative flows financed at
+  # +finance_rate+.
+  #
+  #   Xirr.mirr([-120_000, 39_000, 30_000, 21_000, 37_000, 46_000], 0.10, 0.12)
+  #   # => 0.126094
+  #
+  # @param amounts [Array<Numeric>]
+  # @param finance_rate [Numeric]
+  # @param reinvest_rate [Numeric]
+  # @return [Float]
+  def mirr(amounts, finance_rate, reinvest_rate)
+    values = validated_amounts(amounts)
+    periods = values.length - 1
+
+    future_of_inflows = values.each_with_index.inject(0.0) do |acc, (value, i)|
+      value > 0 ? acc + value * (1.0 + reinvest_rate) ** (periods - i) : acc
+    end
+    present_of_outflows = values.each_with_index.inject(0.0) do |acc, (value, i)|
+      value < 0 ? acc + value / (1.0 + finance_rate) ** i : acc
+    end
+
+    ((future_of_inflows / -present_of_outflows) ** (1.0 / periods) - 1).round(Xirr.config.precision)
+  end
+
+  # @api private
+  def validated_amounts(amounts)
+    values = amounts.map(&:to_f)
+    raise ArgumentError, 'Need at least two amounts' if values.length < 2
+    unless values.any?(&:positive?) && values.any?(&:negative?)
+      raise ArgumentError, 'Need at least one positive and one negative amount'
+    end
+    values
+  end
+
+  # @api private
+  def validated_flows(amounts)
+    validated_amounts(amounts).each_with_index.map { |amount, i| [i.to_f, amount] }
+  end
+
+  private_class_method :validated_amounts, :validated_flows
+end

data/lib/xirr/rates.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Converting between the ways an interest rate can be quoted. A nominal rate
+  # paired with a compounding frequency, the effective annual rate it actually
+  # earns, and a continuously-compounded rate all describe the same return in
+  # different terms; these move between them.
+  module Rates
+    module_function
+
+    # Effective annual rate earned by a +nominal+ rate compounded +m+ times a
+    # year: +(1 + nominal/m)^m − 1+.
+    # @return [Float]
+    def effective_annual_rate(nominal, m)
+      raise ArgumentError, 'm must be positive' if m <= 0
+
+      (1 + nominal / m)**m - 1
+    end
+
+    # Nominal rate that, compounded +m+ times a year, produces the +effective+
+    # annual rate. The inverse of {effective_annual_rate}.
+    # @return [Float]
+    def nominal_rate(effective, m)
+      raise ArgumentError, 'm must be positive' if m <= 0
+      raise ArgumentError, 'effective must be above -100%' if 1 + effective <= 0
+
+      m * ((1 + effective)**(1.0 / m) - 1)
+    end
+
+    # Per-period rate equivalent to a continuously-compounded annual +rate+, for
+    # +periods+ periods a year: +e^(rate/periods) − 1+.
+    # @return [Float]
+    def continuous_to_periodic(rate, periods)
+      raise ArgumentError, 'periods must be positive' if periods <= 0
+
+      Math.exp(rate / periods) - 1
+    end
+  end
+end

data/lib/xirr/returns.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Performance and risk metrics: {volatility}, {cagr}, {payback_period},
+  # {discounted_payback_period}, {profitability_index}, and {twr}.
+  #
+  # The cash-flow functions follow the same convention as {Xirr.npv}: the initial
+  # outlay sits at index 0 (undiscounted) and later flows fall at periods 1, 2, ….
+  module Returns
+    module_function
+
+    # Annualised volatility of a price series — the sample standard deviation of
+    # its period-over-period returns, scaled up by +√periods_per_year+. Needs at
+    # least three positive prices, in time order.
+    # @param returns [:simple, :log] how to measure each return: +(b-a)/a+ or +ln(b/a)+
+    # @return [Float]
+    def volatility(prices, periods_per_year: 252, returns: :simple, precision: Xirr.config.precision)
+      rets = period_returns(prices, returns)
+      raise ArgumentError, 'need at least three prices' if rets.length < 2
+
+      round_value(annualise(rets, periods_per_year), precision)
+    end
+
+    # Compound annual growth rate — the constant yearly rate that grows
+    # +begin_value+ into +end_value+ over +years+.
+    # @return [Float]
+    def cagr(begin_value, end_value, years, precision: Xirr.config.precision)
+      if begin_value <= 0 || years <= 0 || end_value.to_f / begin_value < 0
+        raise ArgumentError, 'undefined'
+      end
+
+      round_value((end_value.to_f / begin_value)**(1.0 / years) - 1, precision)
+    end
+
+    # Payback period — how many periods of cash flow it takes to recover the
+    # initial outlay, interpolating within the recovering period. The first
+    # amount is the outlay (negative), the rest are inflows.
+    # @return [Float]
+    def payback_period(cash_flows, precision: Xirr.config.precision)
+      recovery(cash_flows, precision)
+    end
+
+    # Like {payback_period}, but recovers the outlay from cash flows discounted
+    # at +rate+, so it accounts for the time value of money.
+    # @return [Float]
+    def discounted_payback_period(cash_flows, rate, precision: Xirr.config.precision)
+      recovery(discount_flows(cash_flows, rate), precision)
+    end
+
+    # Profitability index — the present value of future inflows per unit of
+    # initial investment, discounted at +rate+. Above 1 means the project adds
+    # value. Equivalent to +1 + NPV / initial investment+.
+    # @return [Float]
+    def profitability_index(cash_flows, rate, precision: Xirr.config.precision)
+      raise ArgumentError, 'need at least one flow' if cash_flows.empty?
+      raise ArgumentError, 'the first flow must be an outlay (negative)' if cash_flows.first >= 0
+
+      npv = Xirr.npv(rate, cash_flows)
+      round_value(1 + npv / -cash_flows.first, precision)
+    end
+
+    # Time-weighted return — period returns linked geometrically,
+    # +∏(1 + rᵢ) − 1+. Immune to the timing of cash flows. Pass
+    # +periods_per_year+ to annualise.
+    # @return [Float]
+    def twr(period_returns, periods_per_year: nil, precision: Xirr.config.precision)
+      raise ArgumentError, 'need at least one return' if period_returns.empty?
+      raise ArgumentError, 'returns must be numbers' unless period_returns.all? { |r| r.is_a?(Numeric) }
+
+      round_value(time_weighted(period_returns, periods_per_year), precision)
+    end
+
+    # --- helpers ------------------------------------------------------------
+
+    def round_value(value, precision)
+      value.round(precision) + 0.0
+    end
+
+    # Consecutive-pair returns. Raises if a price is non-numeric or non-positive.
+    def period_returns(prices, kind)
+      prices.each_cons(2).map do |a, b|
+        raise ArgumentError, 'prices must be numbers' unless a.is_a?(Numeric) && b.is_a?(Numeric)
+        raise ArgumentError, 'every price must be positive' unless a.positive? && b.positive?
+
+        kind == :log ? Math.log(b.to_f / a) : (b - a).to_f / a
+      end
+    end
+
+    def annualise(returns, periods_per_year)
+      n = returns.length
+      mean = returns.sum / n.to_f
+      sum_of_squares = returns.sum { |r| (r - mean)**2 }
+      Math.sqrt(sum_of_squares / (n - 1)) * Math.sqrt(periods_per_year)
+    end
+
+    def recovery(flows, precision)
+      whole, shortfall, recovering_flow = cumulative_recovery(flows)
+      round_value(whole + shortfall / recovering_flow, precision)
+    end
+
+    # Find the first period where the running cumulative crosses from negative to
+    # non-negative. Raises when it never crosses or there are no flows.
+    def cumulative_recovery(flows)
+      raise ArgumentError, 'need at least one flow' if flows.empty?
+
+      cumulative = 0.0
+      flows.each_with_index do |flow, i|
+        nxt = cumulative + flow
+        return [i - 1, -cumulative, flow] if i.positive? && cumulative.negative? && nxt >= 0
+
+        cumulative = nxt
+      end
+      raise ArgumentError, 'the outlay is never recovered'
+    end
+
+    def discount_flows(flows, rate)
+      flows.each_with_index.map { |flow, i| flow / (1 + rate)**i }
+    end
+
+    def time_weighted(returns, periods_per_year)
+      cumulative = returns.reduce(1.0) { |acc, r| acc * (1 + r) } - 1
+      return cumulative if periods_per_year.nil?
+
+      (1 + cumulative)**(periods_per_year.to_f / returns.length) - 1
+    end
+
+    private_class_method :round_value, :period_returns, :annualise, :recovery,
+                         :cumulative_recovery, :discount_flows, :time_weighted
+  end
+end

data/lib/xirr/rtsafe.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Safeguarded Newton-Raphson root finder — the classic +rtsafe+.
+  #
+  # It brackets a sign change of the net present value first, then each iteration
+  # takes a Newton step when that step lands inside the bracket and is shrinking
+  # the interval fast enough, and a bisection step otherwise. This keeps Newton's
+  # speed on well-behaved flows while retaining bisection's guaranteed
+  # convergence, in a single pass rather than running Newton to exhaustion and
+  # then bisecting separately.
+  #
+  # The maintained bracket always encloses a sign change, so the result is a
+  # genuine root rather than a stalled non-root, and a long-dated flow whose raw
+  # Newton step would overflow takes a bisection step instead.
+  class RtSafe
+    include Base
+
+    # Stop expanding the upper bound once it passes this — the flow has no root
+    # in a sane rate range.
+    BRACKET_CEILING = 1.0e7
+
+    # Solves the compacted {Cashflow} the instance was built with.
+    # @param guess [Float, nil] initial rate; used when it lands inside the bracket
+    # @param options [Hash] reads +:iteration_limit+
+    # @return [Float, nil] the rate rounded to +Xirr.config.precision+, or nil when it can't converge
+    def xirr(guess, options)
+      limit = (options && options[:iteration_limit]) || Xirr.config.iteration_limit
+      start = guess || cf.irr_guess
+      RtSafe.find(flows, guess: start.to_f, iteration_limit: limit)
+    end
+
+    # Pure solver over normalized +[time, amount]+ flows (time in years/periods).
+    # Shared by the dated {Cashflow} path and the periodic {Xirr} module helpers.
+    # @param flows [Array<Array(Float, Float)>]
+    # @return [Float, nil]
+    def self.find(flows, guess: 0.1, tolerance: Xirr.config.eps, iteration_limit: Xirr.config.iteration_limit, precision: Xirr.config.precision)
+      rate = rtsafe(flows, guess.to_f, tolerance.to_f, iteration_limit)
+      return nil if rate.nil? || rate.nan? || rate.infinite?
+
+      # Round before the floor check: a rate just above -1 can round down to it.
+      rounded = rate.round(precision)
+      rounded <= -1.0 ? nil : rounded
+    rescue FloatDomainError, Math::DomainError
+      nil
+    end
+
+    # Net present value of +flows+ at +rate+: Σ amount / (1 + rate)^t
+    def self.present_value(flows, rate)
+      flows.inject(0.0) { |sum, (t, amount)| sum + amount / (1.0 + rate) ** t }
+    end
+
+    # Derivative of the NPV with respect to rate: Σ -t · amount / (1 + rate)^(t+1)
+    def self.present_value_derivative(flows, rate)
+      flows.inject(0.0) { |sum, (t, amount)| sum + (-t * amount / (1.0 + rate) ** (t + 1)) }
+    end
+
+    # Bracket a sign change, then run the safeguarded iteration from +guess+
+    # (when it falls inside the bracket) or the midpoint.
+    def self.rtsafe(flows, guess, tol, iteration_limit)
+      low = safe_low(flows)
+      f_low = present_value(flows, low)
+      bounds = bracket(flows, low, f_low, 1.0)
+      return nil if bounds.nil?
+
+      a, b = bounds
+      # a == low, so the NPV at a is f_low. Orient so it is negative at xlo and
+      # positive at xhi — the invariant the step selection relies on.
+      xlo, xhi = f_low < 0.0 ? [a, b] : [b, a]
+      x = (guess > a && guess < b) ? guess : (a + b) / 2.0
+      f = present_value(flows, x)
+      df = present_value_derivative(flows, x)
+      search(flows, x, xlo, xhi, f, df, (b - a).abs, tol, iteration_limit)
+    end
+
+    # Iterate to the root, taking a Newton or bisection step each time. Looped
+    # (not recursed) so a large +iteration_limit+ can't overflow the stack.
+    # @return [Float, nil] the root, or nil if it doesn't converge within +iters+
+    def self.search(flows, x, xlo, xhi, f, df, dxold, tol, iters)
+      iters.times do
+        nxt, dx = move(x, xlo, xhi, f, df, dxold)
+        return nxt if dx.abs < tol
+
+        f = present_value(flows, nxt)
+        df = present_value_derivative(flows, nxt)
+        f < 0.0 ? xlo = nxt : xhi = nxt
+        x = nxt
+        dxold = dx
+      end
+      nil
+    end
+
+    # A Newton step when it's usable, a bisection step otherwise.
+    # @return [Array(Float, Float)] +[next_x, step]+
+    def self.move(x, xlo, xhi, f, df, dxold)
+      if newton_usable?(x, xlo, xhi, f, df, dxold)
+        dx = f / df
+        [x - dx, dx]
+      else
+        dx = (xhi - xlo) / 2.0
+        [xlo + dx, dx]
+      end
+    end
+
+    # Prefer Newton when the derivative isn't flat, the step lands inside the
+    # bracket, and it shrinks the interval by at least half. Comparing the Newton
+    # point against the bracket — rather than the classic product form — avoids an
+    # overflow in the steep zone near the bracket's floor. +df != 0+ short-circuits
+    # before +x - f / df+.
+    def self.newton_usable?(x, xlo, xhi, f, df, dxold)
+      df != 0.0 && inside?(x - f / df, xlo, xhi) && (2.0 * f).abs <= (dxold * df).abs
+    end
+
+    def self.inside?(point, xlo, xhi)
+      point >= [xlo, xhi].min && point <= [xlo, xhi].max
+    end
+
+    # The bracket's floor. As +rate+ nears -1, +(1 + rate)^t+ underflows to zero
+    # (then divides by zero) for large +t+, so raise the floor just enough that the
+    # longest-dated flow's discount factor stays finite. For short-dated flows this
+    # is the familiar -0.999999; for a 30-year monthly schedule it sits higher.
+    def self.safe_low(flows)
+      max_t = flows.map { |t, _amount| t }.max
+      max_t = 1.0 if max_t.nil? || max_t < 1.0
+      [1.0e-290 ** (1.0 / max_t), 1.0e-6].max - 1.0
+    end
+
+    # Expand the upper bound until the NPV changes sign, giving a bracket.
+    def self.bracket(flows, low, f_low, high)
+      return nil if high > BRACKET_CEILING
+
+      if straddles_zero?(f_low, present_value(flows, high))
+        [low, high]
+      else
+        bracket(flows, low, f_low, high * 2 + 1)
+      end
+    end
+
+    # Whether +a+ and +b+ sit on opposite sides of zero. Comparing signs rather
+    # than the product +a * b+ avoids overflow when the NPV is astronomically large
+    # near the bracket's floor for long-dated flows.
+    def self.straddles_zero?(a, b)
+      (a <= 0 && b >= 0) || (a >= 0 && b <= 0)
+    end
+  end
+end

data/lib/xirr/rtsafe_c.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Xirr
+  # True when the native rtsafe extension compiled and loaded.
+  begin
+    require 'xirr/xirr_native'
+    NATIVE = true
+  rescue LoadError
+    NATIVE = false
+  end
+
+  # C-backed rtsafe. Same algorithm and results as {RtSafe}, run in a native
+  # extension. Only usable when {NATIVE} is true (the extension was compiled);
+  # otherwise the gem runs the pure-Ruby {RtSafe} instead.
+  class RtSafeC
+    include Base
+
+    # @param guess [Float, nil]
+    # @param options [Hash] reads +:iteration_limit+
+    # @return [Float, nil]
+    def xirr(guess, options)
+      limit = (options && options[:iteration_limit]) || Xirr.config.iteration_limit
+      start = (guess || cf.irr_guess).to_f
+      rate = Xirr::Native.rtsafe(flows, start, Xirr.config.eps.to_f, limit)
+      return nil if rate.nil?
+
+      # Round before the floor check: a rate just above -1 can round down to it.
+      rounded = rate.round(Xirr.config.precision)
+      rounded <= -1.0 ? nil : rounded
+    end
+  end
+end

data/lib/xirr/transaction.rb

@@ -6,17 +6,12 @@ module Xirr
     attr_reader :amount, :date
 
     # @example
-    #   Transaction.new -1000, date: Date.now
+    #   Transaction.new(-1000, date: Date.new(2013, 1, 1))
     # @param amount [Numeric]
-    # @param opts [Hash]
-    # @note Don't forget to add date: [Date] in the opts hash.
+    # @param opts [Hash] must include +:date+, the date the amount falls on
     def initialize(amount, opts = {})
       self.amount = amount
-
-      # Set optional attributes..
-      opts.each do |key, value|
-        send("#{key}=", value)
-      end
+      opts.each { |key, value| send("#{key}=", value) }
     end
 
     # Sets the date
@@ -30,7 +25,7 @@ module Xirr
     # @param value [Numeric]
     # @return [Float]
     def amount=(value)
-      @amount = value.to_f || 0.0
+      @amount = value.to_f
     end
 
     # @return [String]