xirr 0.7.1 → 1.0.0

data/lib/xirr/tvm.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Xirr
+  # Time-value-of-money scalars: {fv}, {pv}, {pmt}, {ipmt}, {ppmt}, {nper}, and
+  # {rate}, plus an {amortization_schedule}. Each solves the standard annuity
+  # equation for one unknown:
+  #
+  #   pv·(1+r)^n + pmt·(1 + r·type)·((1+r)^n − 1)/r + fv = 0
+  #
+  # +type+ is 0 for payments at the end of each period (an ordinary annuity) or 1
+  # for the beginning (an annuity due). The sign convention follows spreadsheets:
+  # money you receive is positive, money you pay out is negative.
+  module TVM
+    module_function
+
+    # Future value: what an investment grows to after +nper+ periods, starting
+    # from present value +pv+ with a fixed +pmt+ each period, compounding at
+    # +rate+.
+    # @return [Float]
+    def fv(rate, nper, pmt, pv = 0.0, type = 0)
+      validate_type!(type)
+      if rate.zero?
+        -(pv + pmt * nper) * 1.0
+      else
+        -(pv * (1 + rate)**nper + pmt * annuity(rate, nper, type)) * 1.0
+      end
+    end
+
+    # Present value: what a stream of +pmt+ per period for +nper+ periods plus a
+    # lump sum +fv+ at the end is worth today, discounted at +rate+.
+    # @return [Float]
+    def pv(rate, nper, pmt, fv = 0.0, type = 0)
+      validate_type!(type)
+      if rate.zero?
+        -(fv + pmt * nper) * 1.0
+      else
+        -(fv + pmt * annuity(rate, nper, type)) / (1 + rate)**nper * 1.0
+      end
+    end
+
+    # Level payment per period that pays off +pv+ (and reaches +fv+) over +nper+
+    # periods at +rate+.
+    # @return [Float]
+    def pmt(rate, nper, pv, fv = 0.0, type = 0)
+      validate_type!(type)
+      raise ArgumentError, 'nper must be non-zero' if nper.zero?
+      return -(pv + fv) / nper * 1.0 if rate.zero?
+
+      -(pv * (1 + rate)**nper + fv) / annuity(rate, nper, type) * 1.0
+    end
+
+    # Interest portion of the payment in period +per+ (counting from 1). Pairs
+    # with {ppmt}: the two add up to {pmt} for every period.
+    # @return [Float]
+    def ipmt(rate, per, nper, pv, fv = 0.0, type = 0)
+      validate_type!(type)
+      split_payment(rate, per, nper, pv, fv, type).first
+    end
+
+    # Principal portion of the payment in period +per+ (counting from 1). The
+    # companion of {ipmt}.
+    # @return [Float]
+    def ppmt(rate, per, nper, pv, fv = 0.0, type = 0)
+      validate_type!(type)
+      split_payment(rate, per, nper, pv, fv, type).last
+    end
+
+    # Number of periods it takes for payments of +pmt+ to pay off +pv+ (reaching
+    # +fv+) at +rate+.
+    # @return [Float]
+    def nper(rate, pmt, pv, fv = 0.0, type = 0)
+      validate_type!(type)
+      raise ArgumentError, 'undefined' if rate.zero? && pmt.zero?
+      return -(pv + fv) / pmt * 1.0 if rate.zero?
+      raise ArgumentError, 'undefined' if 1 + rate <= 0
+
+      k = pmt * (1 + rate * type) / rate
+      denom = pv + k
+      raise ArgumentError, 'undefined' if denom.zero? || (k - fv) / denom <= 0
+
+      Math.log((k - fv) / denom) / Math.log(1 + rate)
+    end
+
+    # Interest rate per period of an annuity of +nper+ payments of +pmt+, present
+    # value +pv+, and future value +fv+. There is no closed form, so this reuses
+    # the {RtSafe} solver.
+    # @return [Float]
+    def rate(nper, pmt, pv, fv = 0.0, type = 0, guess: 0.1)
+      validate_type!(type)
+      n = nper.to_i
+      raise ArgumentError, 'nper must be a positive whole number' unless nper == n && n.positive?
+
+      result = RtSafe.find(tvm_flows(n, pmt, pv, fv, type), guess: guess)
+      raise ArgumentError, 'rate did not converge' if result.nil?
+
+      result
+    end
+
+    # Full amortization schedule for a loan of +pv+ repaid with a level payment
+    # over +nper+ periods at +rate+. Returns an array of row hashes with
+    # +:period+, +:payment+, +:interest+, +:principal+, and +:balance+; the
+    # balance runs from +pv+ down to exactly 0. Monetary columns are rounded to
+    # +precision+ (default 2, i.e. cents).
+    # @return [Array<Hash>]
+    def amortization_schedule(rate, nper, pv, precision: 2)
+      n = nper.to_i
+      raise ArgumentError, 'nper must be a positive whole number' unless nper == n && n >= 1
+
+      build_schedule(rate.to_f, n, pv.to_f, precision)
+    end
+
+    # --- helpers ------------------------------------------------------------
+
+    def validate_type!(type)
+      raise ArgumentError, 'type must be 0 (ordinary) or 1 (due)' unless type == 0 || type == 1
+    end
+
+    # (1 + r·type) · ((1+r)^n − 1) / r — the factor that multiplies pmt.
+    def annuity(rate, nper, type)
+      (1 + rate * type) * ((1 + rate)**nper - 1) / rate
+    end
+
+    # Split period +per+'s level payment into [interest, principal].
+    def split_payment(rate, per, nper, pv, fv, type)
+      n = per.to_i
+      unless per == n && n >= 1 && n <= nper
+        raise ArgumentError, 'per must be a whole number within 1..nper'
+      end
+
+      payment = pmt(rate, nper, pv, fv, type)
+      balance = fv(rate, n - 1, payment, pv, type)
+      interest = annuity_due_adjust(balance * rate, rate, n, type)
+      # + 0.0 collapses a floating-point negative zero to 0.0.
+      [interest + 0.0, payment - interest + 0.0]
+    end
+
+    # For an annuity due (type 1) the first period carries no interest and later
+    # periods discount one step; an ordinary annuity (type 0) is left as-is.
+    def annuity_due_adjust(interest, rate, per, type)
+      return interest if type == 0
+      return 0.0 if per == 1
+
+      interest / (1 + rate)
+    end
+
+    # A TVM problem as a cash-flow series so {rate} can reuse the solver: +pv+ at
+    # period 0, +pmt+ each period, +fv+ at the last period.
+    def tvm_flows(nper, pmt, pv, fv, type)
+      periods = type == 1 ? (0...nper) : (1..nper)
+      acc = Hash.new(0.0)
+      periods.each { |i| acc[i * 1.0] += pmt * 1.0 }
+      acc[0.0] += pv * 1.0
+      acc[nper * 1.0] += fv * 1.0
+      acc.to_a
+    end
+
+    # Build the schedule in integer minor units (10^precision), so money is exact
+    # and the balance ends at exactly zero, then convert back to floats.
+    def build_schedule(rate, nper, pv, precision)
+      scale = 10**precision
+      payment = pmt(rate, nper, pv)
+      rows = integer_schedule(rate, nper, (pv * scale).round, (payment * scale).round)
+      rows.map do |period, pay, interest, principal, balance|
+        {
+          period:    period,
+          payment:   pay / scale.to_f,
+          interest:  interest / scale.to_f,
+          principal: principal / scale.to_f,
+          balance:   balance / scale.to_f
+        }
+      end
+    end
+
+    # Running balance in integer minor units; the final row pays off whatever
+    # remains, so the balance ends at exactly 0.
+    def integer_schedule(rate, nper, opening, payment)
+      balance = opening
+      (1..nper).map do |period|
+        interest = (-balance * rate).round
+        scheduled = period == nper ? -balance : payment - interest
+        # Keep the balance retiring toward zero: never grow it and never overpay.
+        principal = [[scheduled, -balance].max, 0].min
+        balance += principal
+        [period, interest + principal, interest, principal, balance]
+      end
+    end
+
+    private_class_method :validate_type!, :annuity, :split_payment, :annuity_due_adjust,
+                         :tvm_flows, :build_schedule, :integer_schedule
+  end
+end

data/lib/xirr/version.rb

@@ -1,4 +1,4 @@
 module Xirr
   # Version of the Gem
-  VERSION = '0.7.1'
+  VERSION = '1.0.0'
 end

data/lib/xirr.rb

@@ -1,11 +1,18 @@
 require 'xirr/version'
-require 'bigdecimal'
 require 'active_support/configurable'
-require 'active_support/concern'
 require 'xirr/config'
 require 'xirr/base'
+require 'xirr/rtsafe'
+require 'xirr/rtsafe_c'
+require 'xirr/brent'
 require 'xirr/bisection'
 require 'xirr/newton_method'
+require 'xirr/periodic'
+require 'xirr/tvm'
+require 'xirr/rates'
+require 'xirr/bonds'
+require 'xirr/depreciation'
+require 'xirr/returns'
 
 # @abstract adds a {Xirr::Cashflow} and {Xirr::Transaction} classes to calculate IRR of irregular transactions.
 # Calculates Xirr

data/test/test_bonds.rb

@@ -0,0 +1,34 @@
+require_relative 'test_helper'
+
+describe 'Xirr::Bonds' do
+  it 'price — at par when coupon equals yield' do
+    assert_equal 100.0, Xirr::Bonds.price(100, 0.05, 0.05, 10)
+  end
+
+  it 'price — at a discount when yield exceeds coupon' do
+    assert_in_delta 875.377897, Xirr::Bonds.price(1000, 0.08, 0.10, 10), 1e-6
+  end
+
+  it 'ytm is the inverse of price' do
+    assert_in_delta 0.1, Xirr::Bonds.ytm(1000, 0.08, 875.377897, 10), 1e-6
+  end
+
+  it 'duration — Macaulay' do
+    assert_equal 10.0, Xirr::Bonds.duration(0.0, 0.05, 10, 1)
+    assert_in_delta 2.833393, Xirr::Bonds.duration(0.06, 0.06, 3, 1), 1e-6
+  end
+
+  it 'modified_duration' do
+    assert_in_delta 9.52381, Xirr::Bonds.modified_duration(0.0, 0.05, 10, 1), 1e-5
+    assert_in_delta 2.673012, Xirr::Bonds.modified_duration(0.06, 0.06, 3, 1), 1e-6
+  end
+
+  it 'convexity' do
+    assert_in_delta 99.773243, Xirr::Bonds.convexity(0.0, 0.05, 10, 1), 1e-6
+    assert_in_delta 9.891032, Xirr::Bonds.convexity(0.06, 0.06, 3, 1), 1e-6
+  end
+
+  it 'rejects a degenerate period count' do
+    assert_raises(ArgumentError) { Xirr::Bonds.price(100, 0.05, 0.05, 0) }
+  end
+end

data/test/test_brent.rb

@@ -0,0 +1,48 @@
+require_relative 'test_helper'
+
+describe 'Xirr::Brent solver' do
+  def cf(*pairs)
+    c = Cashflow.new
+    pairs.each { |amount, date| c << Transaction.new(amount, date: date.to_date) }
+    c
+  end
+
+  it 'matches known XIRR values' do
+    ok = cf([1000, '1985-01-01'], [-600, '1990-01-01'], [-6000, '1995-01-01'])
+    assert_equal '0.225683'.to_f, ok.xirr(method: :brent)
+
+    long = Cashflow.new(flow: [
+      Transaction.new(-1000, date: Date.new(1957, 1, 1)),
+      Transaction.new(390_000, date: Date.new(2013, 1, 1))
+    ])
+    assert_equal '0.112339'.to_f, long.xirr(method: :brent)
+  end
+
+  it 'handles high rates and near -100% returns' do
+    high = cf([1_000_000, '2020-01-01'], [-2_200_000, '2020-05-01'], [-800_000, '2020-06-01'])
+    assert_in_delta 21.66094, high.xirr(method: :brent).to_f, 1e-4
+
+    near1 = cf([-10_000, '2014-04-15'], [305.6, '2014-05-15'], [500, '2014-10-19'])
+    assert_in_delta(-0.996815, near1.xirr(method: :brent).to_f, 1e-5)
+  end
+
+  it 'agrees with rtsafe across random cashflows' do
+    rng = Random.new(0xB6E17)
+    base = Date.new(2000, 1, 1)
+    checked = 0
+    100.times do
+      c = Cashflow.new
+      c << Transaction.new(-(1_000 + rng.rand(9_000)), date: base)
+      n = 1 + rng.rand(8)
+      (1..n).each { |i| c << Transaction.new(rng.rand(3_000) - 700, date: base + i * (30 + rng.rand(300))) }
+      c << Transaction.new(500 + rng.rand(6_000), date: base + (n + 1) * 400)
+      next unless c.valid?
+
+      # Different algorithms can land on opposite sides of the last rounded digit,
+      # so agree to within a rounding step rather than bit-for-bit.
+      assert_in_delta c.xirr(method: :rtsafe).to_f, c.xirr(method: :brent).to_f, 1e-5
+      checked += 1
+    end
+    assert checked > 50, "only #{checked} cases checked"
+  end
+end

data/test/test_cashflow.rb

@@ -130,11 +130,11 @@ describe 'Cashflows' do
     end
 
     it 'is invalid' do
-      assert true, !@cf.valid?
+      refute @cf.valid?
     end
 
     it 'returns 0 instead of exception ' do
-      assert_equal BigDecimal(0, 6), @cf.xirr
+      assert_equal 0.0, @cf.xirr
     end
 
     it 'with a wrong method is invalid' do
@@ -145,8 +145,8 @@ describe 'Cashflows' do
       assert_raises(ArgumentError) { @cf.xirr raise_exception: true }
     end
 
-    it 'raises error when xirr is called' do
-      assert true, !@cf.irr_guess
+    it 'has a zero irr_guess' do
+      assert_equal 0.0, @cf.irr_guess
     end
   end
 
@@ -158,15 +158,15 @@ describe 'Cashflows' do
     end
 
     it 'is invalid' do
-      assert true, !@cf.valid?
+      refute @cf.valid?
     end
 
     it 'raises error when #xirr is called' do
       assert_raises(ArgumentError) { @cf.xirr raise_exception: true }
     end
 
-    it 'is invalid when #irr_guess is called' do
-      assert true, !@cf.irr_guess
+    it 'has a zero irr_guess' do
+      assert_equal 0.0, @cf.irr_guess
     end
   end
 
@@ -184,7 +184,8 @@ describe 'Cashflows' do
     end
 
     it 'has an Internal Rate of Return on Newton Method' do
-      assert true, @cf.xirr(method: :newton_method).nan?
+      # The pure-Ruby Newton now finds this root instead of failing on it.
+      assert_equal '-0.034592'.to_f, @cf.xirr(method: :newton_method)
     end
 
     it 'has an educated guess' do
@@ -210,7 +211,7 @@ describe 'Cashflows' do
     end
   end
 
-  describe 'reapeated cashflow' do
+  describe 'repeated cashflow' do
     before(:all) do
       @cf = Cashflow.new
       @cf << Transaction.new(1000.0, date: '2011-12-07'.to_date)
@@ -218,10 +219,10 @@ describe 'Cashflows' do
       @cf << Transaction.new(-2000.0, date: '2013-05-21'.to_date)
       @cf << Transaction.new(-4000.0, date: '2013-05-21'.to_date)
     end
-    #
-    # it 'has a compact cashflow' do
-    #   assert_equal 2, @cf.compact_cf.count
-    # end
+
+    it 'has a compact cashflow' do
+      assert_equal 2, @cf.compact_cf.count
+    end
 
     it 'sums all transactions' do
       assert_equal -3000.0, @cf.compact_cf.map(&:amount).inject(&:+)
@@ -267,9 +268,10 @@ describe 'Cashflows' do
       @cf << Transaction.new(-144413.24, date: '2013-05-21'.to_date)
     end
 
-    it 'is a long and bad investment and newton generates an error' do
-      skip 'Test is weirdly taking too long'
-      assert_equal '-1.0'.to_f, @cf.xirr #(method: :newton_method)
+    it 'returns replace_for_nil for a net-positive flow with no rate' do
+      # The old solver hung or raised here; rtsafe finds no sign change and
+      # returns cleanly.
+      assert_equal Xirr::REPLACE_FOR_NIL, @cf.xirr
     end
   end
 
@@ -324,8 +326,10 @@ describe 'Cashflows' do
       @cf << Transaction.new(8509.93, date: '2021-06-21'.to_date)
     end
 
-    it 'gives nil value for xirr' do
-      assert_equal 0.0, @cf.xirr
+    it 'finds the rate the old solver missed' do
+      # The previous default solver returned config.replace_for_nil (0.0) here.
+      # rtsafe converges on this flow at the default precision.
+      assert_in_delta(-0.831717, @cf.xirr.to_f, 1e-6)
     end
 
     it 'gives correct value with configuration' do
@@ -350,7 +354,8 @@ describe 'Cashflows' do
       @cf = Cashflow.new
       @cf << Transaction.new(1000, date: '2000-01-01'.to_date)
       @cf << Transaction.new(-1200, date: '2001-01-01'.to_date)
-      assert_equal '0.2'.to_f, @cf.irr_guess
+      # 2000 is a leap year, so the horizon is 366/365 years, not exactly 1.
+      assert_equal 0.199, @cf.irr_guess
     end
     
     it 'Zero Periods of Investment' do
@@ -377,7 +382,8 @@ describe 'Cashflows' do
       @cf << Transaction.new(1000, date: '2000-01-01'.to_date)
       @cf << Transaction.new(-100, date: '2010-01-01'.to_date)
       @cf << Transaction.new(-100, date: '2020-01-01'.to_date)
-      assert_equal '0.072'.to_f, @cf.irr_guess
+      # 200 returned on 1000 over 20 years annualizes to a negative rate.
+      assert_equal(-0.077, @cf.irr_guess)
     end
     
     it 'Very Small Periods of Investment' do
@@ -393,7 +399,8 @@ describe 'Cashflows' do
       @cf << Transaction.new(-500, date: '2001-01-01'.to_date)
       @cf << Transaction.new(-300, date: '2002-01-01'.to_date)
       @cf << Transaction.new(-200, date: '2003-01-01'.to_date)
-      assert_equal '0.195'.to_f, @cf.irr_guess
+      # Inflows and outflows net to zero, so the cash-on-cash guess is 0.
+      assert_equal 0.0, @cf.irr_guess
     end
     
     it 'Only Negative Cash Flows' do
@@ -408,7 +415,38 @@ describe 'Cashflows' do
       @cf << Transaction.new(500, date: '2000-01-01'.to_date)
       @cf << Transaction.new(-100, date: '2005-01-01'.to_date)
       @cf << Transaction.new(-400, date: '2010-01-01'.to_date)
-      assert_equal '0.033'.to_f, @cf.irr_guess
+      # Inflows and outflows net to zero, so the cash-on-cash guess is 0.
+      assert_equal 0.0, @cf.irr_guess
+    end
+  end
+
+  describe 'option and state handling' do
+    it 'lets a per-call raise_exception: false override a cashflow-level true' do
+      cf = Cashflow.new(flow: [
+        Transaction.new(-600, date: '1990-01-01'.to_date),
+        Transaction.new(-600, date: '1995-01-01'.to_date)
+      ], raise_exception: true)
+      assert_raises(ArgumentError) { cf.xirr }
+      assert_equal Xirr::REPLACE_FOR_NIL, cf.xirr(raise_exception: false)
+    end
+
+    it 'does not let a per-call period leak into later xnpv/mirr' do
+      cf = Cashflow.new(flow: [
+        Transaction.new(-1000, date: '2000-01-01'.to_date),
+        Transaction.new(1200, date: '2001-01-01'.to_date)
+      ])
+      before = cf.xnpv(0.1)
+      cf.xirr(period: 100)
+      assert_equal before, cf.xnpv(0.1)
     end
-  end 
+
+    it 'refreshes memoized dates when a transaction is pushed' do
+      cf = Cashflow.new
+      cf << Transaction.new(1000, date: '2000-01-01'.to_date)
+      cf << Transaction.new(-500, date: '2005-01-01'.to_date)
+      cf.min_date # memoize
+      cf << Transaction.new(-500, date: '1990-01-01'.to_date)
+      assert_equal Date.new(1990, 1, 1), cf.min_date
+    end
+  end
 end

data/test/test_depreciation.rb

@@ -0,0 +1,26 @@
+require_relative 'test_helper'
+
+describe 'Xirr::Depreciation' do
+  it 'sln — straight line' do
+    assert_equal 1800.0, Xirr::Depreciation.sln(10_000, 1_000, 5)
+  end
+
+  it 'syd — sum of years digits' do
+    assert_equal 3000.0, Xirr::Depreciation.syd(10_000, 1_000, 5, 1)
+    assert_equal 600.0, Xirr::Depreciation.syd(10_000, 1_000, 5, 5)
+  end
+
+  it 'ddb — double declining balance' do
+    assert_equal 4000.0, Xirr::Depreciation.ddb(10_000, 1_000, 5, 1)
+    assert_equal 2400.0, Xirr::Depreciation.ddb(10_000, 1_000, 5, 2)
+  end
+
+  it 'db — fixed declining balance' do
+    assert_in_delta 3690.0, Xirr::Depreciation.db(10_000, 1_000, 5, 1), 1e-2
+    assert_in_delta 2328.39, Xirr::Depreciation.db(10_000, 1_000, 5, 2), 1e-2
+  end
+
+  it 'rejects a period outside the asset life' do
+    assert_raises(ArgumentError) { Xirr::Depreciation.syd(10_000, 1_000, 5, 6) }
+  end
+end

data/test/test_helper.rb

@@ -1,8 +1,5 @@
 $LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
 
-require 'coveralls'
-# Coveralls.wear!
-
 require 'minitest/autorun'
 require 'minitest/spec'
 
@@ -10,9 +7,18 @@ require 'active_support/all'
 
 require 'xirr/config.rb'
 require 'xirr/base.rb'
+require 'xirr/rtsafe.rb'
+require 'xirr/rtsafe_c.rb'
+require 'xirr/brent.rb'
 require 'xirr/bisection.rb'
 require 'xirr/newton_method.rb'
 require 'xirr/cashflow.rb'
 require 'xirr/transaction.rb'
+require 'xirr/periodic.rb'
+require 'xirr/tvm.rb'
+require 'xirr/rates.rb'
+require 'xirr/bonds.rb'
+require 'xirr/depreciation.rb'
+require 'xirr/returns.rb'
 include Xirr
 

data/test/test_periodic.rb

@@ -0,0 +1,45 @@
+require_relative 'test_helper'
+
+describe 'Periodic (dateless) functions' do
+  describe 'Xirr.irr' do
+    it 'solves a simple two-period flow' do
+      assert_in_delta 0.1, Xirr.irr([-1000, 1100]), 1e-6
+    end
+
+    it 'solves a multi-period flow' do
+      assert_in_delta 0.156579, Xirr.irr([-1000, 500, 500, 300]), 1e-6
+    end
+
+    it 'agrees with npv at the root' do
+      rate = Xirr.irr([-1000, 500, 500, 300])
+      # The rate is rounded to config.precision, so npv lands near — not exactly — zero.
+      assert_in_delta 0.0, Xirr.npv(rate, [-1000, 500, 500, 300]), 1e-3
+    end
+
+    it 'raises without both a positive and a negative amount' do
+      assert_raises(ArgumentError) { Xirr.irr([-1000, -500]) }
+      assert_raises(ArgumentError) { Xirr.irr([1000, 500]) }
+    end
+  end
+
+  describe 'Xirr.npv' do
+    it 'leaves the first amount at period 0' do
+      assert_equal 0.0, Xirr.npv(0.1, [-1000, 1100])
+    end
+
+    it 'discounts later amounts' do
+      assert_in_delta 41.322314, Xirr.npv(0.1, [-1000, 600, 600]), 1e-6
+    end
+  end
+
+  describe 'Xirr.mirr' do
+    it 'matches the closed form' do
+      amounts = [-120_000, 39_000, 30_000, 21_000, 37_000, 46_000]
+      assert_in_delta 0.126094, Xirr.mirr(amounts, 0.10, 0.12), 1e-6
+    end
+
+    it 'raises without both a positive and a negative amount' do
+      assert_raises(ArgumentError) { Xirr.mirr([-1, -2], 0.1, 0.1) }
+    end
+  end
+end

data/test/test_rates.rb

@@ -0,0 +1,20 @@
+require_relative 'test_helper'
+
+describe 'Xirr::Rates' do
+  it 'effective_annual_rate' do
+    assert_in_delta 0.104713, Xirr::Rates.effective_annual_rate(0.10, 12), 1e-6
+  end
+
+  it 'nominal_rate is the inverse of effective_annual_rate' do
+    ear = Xirr::Rates.effective_annual_rate(0.10, 12)
+    assert_in_delta 0.1, Xirr::Rates.nominal_rate(ear, 12), 1e-10
+  end
+
+  it 'continuous_to_periodic' do
+    assert_in_delta 0.105171, Xirr::Rates.continuous_to_periodic(0.10, 1), 1e-6
+  end
+
+  it 'rejects a non-positive compounding frequency' do
+    assert_raises(ArgumentError) { Xirr::Rates.effective_annual_rate(0.10, 0) }
+  end
+end

data/test/test_returns.rb

@@ -0,0 +1,35 @@
+require_relative 'test_helper'
+
+describe 'Xirr::Returns' do
+  it 'volatility — annualised' do
+    assert_in_delta 0.234528, Xirr::Returns.volatility([100, 102, 101, 103, 105]), 1e-6
+  end
+
+  it 'cagr — compound annual growth rate' do
+    assert_in_delta 0.071773, Xirr::Returns.cagr(1000, 2000, 10), 1e-6
+  end
+
+  it 'payback_period' do
+    assert_equal 2.5, Xirr::Returns.payback_period([-1000, 400, 400, 400])
+  end
+
+  it 'discounted_payback_period' do
+    assert_in_delta 1.916667, Xirr::Returns.discounted_payback_period([-1000, 600, 600, 600], 0.1), 1e-6
+  end
+
+  it 'profitability_index' do
+    assert_in_delta 1.041322, Xirr::Returns.profitability_index([-1000, 600, 600], 0.1), 1e-6
+  end
+
+  it 'twr — cumulative' do
+    assert_in_delta 0.1286, Xirr::Returns.twr([0.10, -0.05, 0.08]), 1e-6
+  end
+
+  it 'twr — annualised' do
+    assert_in_delta 0.082432, Xirr::Returns.twr([0.02, 0.02], periods_per_year: 4), 1e-6
+  end
+
+  it 'raises when the outlay is never recovered' do
+    assert_raises(ArgumentError) { Xirr::Returns.payback_period([-1000, 100, 100]) }
+  end
+end