xirr 0.7.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1281b23c8069cbd5bf16cecf50ae129ea2d4bab31c4c5e89906d970f6e15b7d
-  data.tar.gz: 2431eed14a1de0deb4694621eb8136b10b53c6ce44d888682101e9ca04e46aca
+  metadata.gz: 3aca532866fb5a06872ab2ea0e49a812d4ad4e2a638df03e456e7ea2c742efd7
+  data.tar.gz: 7cf7a6cd4334bc92a5949cdad6d291a0001fa4a2986c86b413106612dca08dd6
 SHA512:
-  metadata.gz: f6e38c8051ab43168cfafb1442fc897a96e9e25c62b55eb95320cc8f22fca57421ac360626ade4764115c17a4c7aa0fca84568f8d03238d78bc5bb3a123039cf
-  data.tar.gz: 4b450e70ef5d58150e0b9cf416f9246e67b8fa015449f6697042dafe49b49e9114065bc6f711dafa41c5e2bcbff7882ee87d2a77ae55046c89c55aa7d81f6b90
+  metadata.gz: 1f9c988579766fc11c056506f760c12e88996cedcfee582c0497822155a50a943e6674de0e3bca7a90c2afbb7a9e5e61569d75e5cad4b2b809e7a03b527c00c9
+  data.tar.gz: 16a1104a0f0961beabcd2fcb2ae0f4043f4ef2f6682e044e2d8cc2077d64c257b6d0c9ba7cf2903c61ac08d62243b950ca47990131699839cb9ec634b8c14fc9

data/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.1', '3.2', '3.3']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rake

data/CHANGE_LOG.md

@@ -1,8 +1,37 @@
-## Unreleased
-* Fix removal of `RubyInLine`
-* Allow activesupport 7. Fixes #30
-* Breaking: Require activesupport >= 6.1
-* Breaking: Require ruby >= 3.1
+## Version 1.0.0
+* New default solver: a safeguarded Newton (`rtsafe`) that brackets the root and
+  falls back to a bisection step per iteration. It converges on flows the old
+  Newton/bisection pair failed on — long maturities, low rates, and returns near
+  -100% — without overflowing.
+* `Cashflow#xirr` no longer silently returns `0.0` for a flow that does have a
+  rate; the more robust solver now finds it. `Cashflow#xirr!` raises on an
+  invalid flow or genuine non-convergence instead of returning
+  `config.replace_for_nil`.
+* Added `Cashflow#xnpv(rate)` and `Cashflow#mirr(finance_rate, reinvest_rate)`.
+* Added periodic (dateless) helpers `Xirr.irr`, `Xirr.npv`, `Xirr.mirr` for
+  amounts at equally spaced periods.
+* Added the wider finance toolkit ported from the finance-elixir library:
+  `Xirr::TVM` (`fv`, `pv`, `pmt`, `ipmt`, `ppmt`, `nper`, `rate`,
+  `amortization_schedule`), `Xirr::Rates` (`effective_annual_rate`,
+  `nominal_rate`, `continuous_to_periodic`), `Xirr::Bonds` (`price`, `ytm`,
+  `duration`, `modified_duration`, `convexity`), `Xirr::Depreciation` (`sln`,
+  `syd`, `ddb`, `db`), and `Xirr::Returns` (`volatility`, `cagr`,
+  `payback_period`, `discounted_payback_period`, `profitability_index`, `twr`).
+* Added an optional native (C) build of the rtsafe solver, selectable with
+  `xirr(method: :rtsafe_c)`. It is best-effort: without a compiler the gem falls
+  back to pure Ruby, and `Xirr::NATIVE` reports whether it loaded. Added a
+  `benchmark/solvers.rb` comparing the solvers.
+* Added a `:brent` solver (`xirr(method: :brent)`): derivative-free Brent's
+  method over rtsafe's bracketing — as robust as rtsafe, and cheaper per
+  iteration, which can help on very large cashflows.
+* The `:bisection` and `:newton_method` methods are still available via
+  `xirr(method:)`. `:newton_method` was reimplemented in plain Ruby, dropping the
+  deprecated `bigdecimal/newton` standard library.
+* Dropped the `bigdecimal` dependency entirely — results are `Float`, rounded to
+  `config.precision`. (The solvers already computed in `Float`.)
+* Removed the defunct Travis and Coveralls setup; added GitHub Actions CI.
+* Allow activesupport 7 (Fixes #30). Breaking: require activesupport >= 6.1 and
+  ruby >= 3.1.
 
 ## Version 0.7.0
 * Removed `RubyInLine`

data/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+- `rake` / `rake test_units` — run the full test suite (Minitest, `test/*.rb`).
+- `ruby -Ilib -Itest test/test_cashflow.rb` — run one test file.
+- `ruby -Ilib -Itest test/test_cashflow.rb -n "/pattern/"` — filter by test name.
+- `rake compile` — build the optional native extension into `lib/xirr/` (needs a C compiler).
+- `ruby -Ilib benchmark/solvers.rb` — benchmark the solvers.
+
+Requires Ruby `>= 3.1` and `activesupport >= 6.1, < 8`. There is no system Ruby on
+the dev box used here; see the project memory for the asdf build recipe and the
+`PATH` / `LD_LIBRARY_PATH` needed to run the suite.
+
+## Architecture
+
+The gem computes XIRR (the IRR of an irregularly-dated cashflow, like Excel's
+XIRR) and carries a wider finance toolkit. Everything works in `Float` — there is
+no `BigDecimal` dependency. Functions return plain numbers and raise
+`ArgumentError` on inputs with no answer (no Elixir-style ok/error tuples).
+
+### Cashflow and the solvers
+
+- **`Xirr::Transaction`** (`transaction.rb`) — one dated amount (`Float`, `Date`).
+- **`Xirr::Cashflow`** (`cashflow.rb`) — an `Array` subclass; the orchestrator and
+  public entry point (`#xirr`, `#xirr!`, `#xnpv`, `#mirr`). It validates the flow,
+  resolves options, compacts same-date transactions (`#compact_cf`), picks a
+  solver, and delegates. It does no root-finding itself.
+- **Solvers** all `include Xirr::Base` (`base.rb`), which supplies `xnpv`,
+  `xnpv_derivative`, and the memoized `[years_from_start, amount]` `flows`:
+  - **`RtSafe`** (`rtsafe.rb`) — safeguarded Newton (the classic *rtsafe*): bracket
+    a sign change, then take a Newton step when it stays inside the bracket and a
+    bisection step otherwise. **This is the default** (`config.default_method`).
+  - **`RtSafeC`** (`rtsafe_c.rb` + `ext/xirr/xirr_native.c`) — the same algorithm
+    in C. Optional: loaded only if compiled (`Xirr::NATIVE`); `method: :rtsafe_c`.
+    **`rtsafe.rb` and `xirr_native.c` are meant to stay algorithmically identical —
+    change them together and re-check parity.**
+  - **`Brent`** (`brent.rb`) — derivative-free Brent's method over rtsafe's
+    bracketing (`method: :brent`); as robust as rtsafe, cheaper per iteration but
+    needs more of them, so it roughly ties rtsafe except on very large flows.
+  - **`Bisection`, `NewtonMethod`** — legacy solvers kept for `method:` and the
+    benchmark. rtsafe dominates both (faster and more robust).
+
+### Control flow of `Cashflow#xirr`
+
+1. `process_options` resolves `raise_exception` / `iteration_limit` / `period` in
+   precedence order (call → cashflow → config) via `resolve_option`, and
+   `switch_fallback` picks the method (an explicit `method:` turns fallback off).
+2. Invalid flow (no sign change) → `config.replace_for_nil`, or raises if asked.
+3. `compact_cf` merges same-date transactions; the chosen solver runs on it.
+4. On non-convergence, if fallback is on and the method wasn't already rtsafe, it
+   retries with `:rtsafe` (rtsafe is the safety net; nothing beats it, so it does
+   not fall back to the weaker solvers).
+
+### Key conventions
+
+- **Sign is relative to the first transaction** (`first_transaction_direction`):
+  `inflow`/`outflows` and validity are defined by each amount's sign times that
+  direction, not by absolute positive/negative.
+- **rtsafe does not depend on `irr_guess`** — it brackets independently and only
+  uses a guess when it falls inside the bracket. `irr_guess` is a public
+  convenience and the starting point for the fragile legacy Newton.
+- **Precision & convergence** come from config: `eps` (tolerance on the *rate
+  step/interval*, not on NPV), `precision` (rounding), `iteration_limit`, `period`
+  (days/year).
+
+### The other finance modules
+
+Module functions (not on `Cashflow`), each in its own file: `Xirr::TVM`
+(`fv`/`pv`/`pmt`/`ipmt`/`ppmt`/`nper`/`rate`/`amortization_schedule`),
+`Xirr::Rates`, `Xirr::Bonds`, `Xirr::Depreciation`, `Xirr::Returns`, plus periodic
+`Xirr.irr`/`npv`/`mirr` (`periodic.rb`). `TVM.rate` and `Bonds.ytm` reuse
+`RtSafe.find`. These were ported from the `finance-elixir` library; its tests are
+the source of the expected values in `test/`.
+
+### Configuration
+
+`config.rb` uses `ActiveSupport::Configurable`. Each default is both
+`Xirr.config.<key>` and a frozen constant `Xirr::<KEY>` (the constant keeps the
+original default after reconfiguration). Configure with `Xirr.configure { |c| ... }`.

data/README.md

@@ -1,17 +1,17 @@
-[![Build Status](https://travis-ci.org/tubedude/xirr.svg)](https://travis-ci.org/tubedude/xirr)[![Coverage Status](https://coveralls.io/repos/tubedude/xirr/badge.svg?branch=master)](https://coveralls.io/r/tubedude/xirr?branch=master)[![Code Climate](https://codeclimate.com/github/tubedude/xirr/badges/gpa.svg)](https://codeclimate.com/github/tubedude/xirr)
-
-## NOTE
-
-This gem is not very well maintained. You can check out a new and properlly maintained library for fast XIRR calculation:
-https://github.com/fintual-oss/fast-xirr
+# Xirr
 
-I haven't tried it yet, but I liked two things:
-- All calculations are underlying C ( = Fast )
-- Bad results return NaN ( = you can decide how to deal with it )
+[![CI](https://github.com/tubedude/xirr/actions/workflows/ci.yml/badge.svg)](https://github.com/tubedude/xirr/actions/workflows/ci.yml)
 
-# Xirr
+Calculates the XIRR of a cashflow — the internal rate of return for
+transactions that land on arbitrary dates, the way a spreadsheet's `XIRR` does.
 
-This is a gem to calculate XIRR on Bisection Method or Newton Method.
+The default solver is a safeguarded Newton method (`rtsafe`): it brackets the
+root first, then takes a Newton step when that step stays inside the bracket and
+a bisection step otherwise. That converges on flows the plain Newton or bisection
+methods struggle with — long maturities, low rates, and returns near -100% — and
+reports non-convergence instead of returning a wrong number. The `:bisection` and
+`:newton_method` solvers remain available, and there is an optional native (C)
+build of `rtsafe`. See [Choosing a solver](#choosing-a-solver).
 
 ## Installation
 
@@ -37,7 +37,7 @@ cf << Xirr::Transaction.new(-1000,  date: '2014-01-01'.to_date)
 cf << Xirr::Transaction.new(-2000,  date: '2014-03-01'.to_date)
 cf << Xirr::Transaction.new( 4500, date: '2015-12-01'.to_date)
 cf.xirr
-# 0.25159694345042327 # [BigDecimal]
+# 0.251405 # Float, rounded to config.precision
 
 flow = []
 flow << Xirr::Transaction.new(-1000,  date: '2014-01-01'.to_date)
@@ -46,17 +46,132 @@ flow << Xirr::Transaction.new( 4500, date: '2015-12-01'.to_date)
 
 cf = Xirr::Cashflow.new(flow: flow)
 cf.xirr
-```    
+```
+
+`xirr` returns `config.replace_for_nil` (0.0 by default) when it can't find a
+rate. Use `xirr!` when you would rather have an exception:
+
+```rb
+cf.xirr!                 # raises ArgumentError on an invalid or unsolvable flow
+cf.xirr(method: :bisection)
+```
+
+### Related figures
+
+```rb
+cf.xnpv(0.1)             # net present value of the dated flows at a given rate
+cf.mirr(0.10, 0.12)      # modified IRR: finance rate, then reinvestment rate
+```
+
+### Periodic (dateless) flows
+
+When the flows fall at equally spaced periods and the exact dates don't matter,
+work with a plain list of amounts. The rate is per period.
+
+```rb
+Xirr.irr([-1000, 1100])              # => 0.1
+Xirr.npv(0.1, [-1000, 600, 600])     # => 41.322314
+Xirr.mirr([-120_000, 39_000, 30_000, 21_000, 37_000, 46_000], 0.10, 0.12)
+# => 0.126094
+```
+
+### More finance functions
+
+Beyond cash-flow analysis, the gem carries the usual finance toolkit, grouped
+into modules. Every function returns a plain number and raises `ArgumentError`
+on inputs that have no answer.
+
+```rb
+# Time value of money — Xirr::TVM
+Xirr::TVM.fv(0.05, 10, -100, -1000)          # => 2886.68 (future value)
+Xirr::TVM.pmt(0.10, 10, 1000)                # => -162.75 (level payment)
+Xirr::TVM.nper(0.05, -100, 1000)             # => 14.21   (number of periods)
+Xirr::TVM.amortization_schedule(0.10 / 12, 12, 1000)
+# => [{period: 1, payment: -87.92, interest: -8.33, principal: -79.59, balance: 920.41}, ...]
+
+# Rate conversions — Xirr::Rates
+Xirr::Rates.effective_annual_rate(0.10, 12)  # => 0.104713
+
+# Fixed income — Xirr::Bonds
+Xirr::Bonds.price(1000, 0.08, 0.10, 10)      # => 875.377897
+Xirr::Bonds.ytm(1000, 0.08, 875.377897, 10)  # => 0.1
+Xirr::Bonds.duration(0.06, 0.06, 3, 1)       # => 2.833393
+
+# Depreciation — Xirr::Depreciation
+Xirr::Depreciation.sln(10_000, 1_000, 5)     # => 1800.0
+Xirr::Depreciation.ddb(10_000, 1_000, 5, 1)  # => 4000.0
+
+# Performance & risk — Xirr::Returns
+Xirr::Returns.cagr(1000, 2000, 10)           # => 0.071773
+Xirr::Returns.twr([0.10, -0.05, 0.08])       # => 0.1286
+Xirr::Returns.volatility([100, 102, 101, 103, 105]) # => 0.234528
+```
+
+## Choosing a solver
+
+Four solvers are available; pick one per call with `method:`, or set a default
+globally with `config.default_method`. They all return the same rate — they
+differ in speed and robustness.
+
+```rb
+cf.xirr(method: :rtsafe)         # default: safeguarded Newton, pure Ruby
+cf.xirr(method: :rtsafe_c)       # same algorithm, native C extension (optional)
+cf.xirr(method: :brent)          # derivative-free; can win on very large flows
+cf.xirr(method: :newton_method)  # plain Newton — fast, but guess-sensitive
+cf.xirr(method: :bisection)      # robust on a bracketed flow, but slowest
+
+Xirr.configure { |c| c.default_method = :rtsafe_c }
+```
+
+`:rtsafe` is the default because among the pure-Ruby solvers it is both the
+fastest and the one that converges reliably — it combines a Newton step with a
+bisection safeguard, so `:newton_method` and `:bisection` exist mainly for
+comparison. `:rtsafe_c` is faster still but needs the native extension.
+
+`:brent` shares rtsafe's bracketing, so it is just as robust, but is
+derivative-free: cheaper per iteration at the cost of more of them. It roughly
+ties rtsafe on ordinary flows and can pull ahead on very large cashflows, where
+skipping the derivative pass matters.
+
+### The optional native extension
+
+The gem ships a C build of `rtsafe`. It is optional: if a compiler isn't
+available at install time the gem falls back to the pure-Ruby solver, and nothing
+about the public API changes. Check whether it loaded with `Xirr::NATIVE`;
+selecting `:rtsafe_c` without it raises `ArgumentError`. Build it during
+development with `rake compile`.
+
+## Benchmark
+
+Time per `xirr` call, averaged over many runs (Ruby 3.3.1). All four solvers
+return the same rate; lower is faster. Reproduce with
+`ruby -Ilib benchmark/solvers.rb`.
+
+| Cashflow | `rtsafe_c` | `rtsafe` | `newton_method` | `bisection` |
+| --- | ---: | ---: | ---: | ---: |
+| moderate (3 flows)         | 0.04 ms | 0.06 ms | 0.10 ms | 0.40 ms |
+| high rate (~22)            | 0.05 ms | 0.08 ms | 0.10 ms | 0.66 ms |
+| long horizon (56 yr)       | 0.03 ms | 0.06 ms | 0.07 ms | 0.29 ms |
+| near -100%                 | 0.06 ms | 0.11 ms | 0.12 ms | 0.29 ms |
+| large (361 monthly flows)  | 2.59 ms | 4.05 ms | 8.10 ms | 40.4 ms |
+
+`rtsafe` beats plain Newton and is several times faster than bisection, which
+converges only linearly. The native `rtsafe_c` is roughly 1.5–2× faster again.
 
 ## Configuration
 
-    # intializer/xirr.rb
+    # initializer/xirr.rb
 
     Xirr.configure do |config|
-      config.eps = '1.0e-12'
-      config.days_in_year = 365.25
+      config.eps    = 1.0e-12  # convergence tolerance on the rate (the step/interval size)
+      config.period = 365.25   # days per year used to discount
     end
 
+Other settings: `precision` (decimal places, default 6), `iteration_limit`
+(default 50), `default_method` (default `:rtsafe`), `fallback` (default true),
+`replace_for_nil` (returned when no rate is found, default 0.0), and
+`raise_exception` (default false).
+
 
 ## Documentation
 
@@ -64,17 +179,8 @@ http://rubydoc.info/github/tubedude/xirr/master/frames
 
 ## Supported versions
 
-    Ruby:
-     - 2.2.1
-     - 2.3
-     - 2.4
-     - 2.7
-
-    ActiveSupport:
-     - 4.2
-     - 5
-     - 6
-     - 7
+    Ruby: >= 3.1
+    ActiveSupport: >= 6.1, < 8
 
 ## Thanks
 

data/Rakefile

@@ -2,6 +2,7 @@ require "bundler/gem_tasks"
 
 require 'rake'
 require 'rake/testtask'
+require 'fileutils'
 
 task :default => [:test_units]
 
@@ -10,3 +11,12 @@ Rake::TestTask.new("test_units") do |t|
   t.verbose = false
   t.warning = false
 end
+
+desc 'Build the optional native rtsafe extension into lib/xirr'
+task :compile do
+  Dir.chdir('ext/xirr') { ruby 'extconf.rb'; sh 'make' }
+  built = Dir['ext/xirr/xirr_native.{so,bundle}'].first
+  raise 'native build produced no library (compiler missing?)' unless built
+  FileUtils.cp built, 'lib/xirr/'
+  puts "compiled #{File.basename(built)} -> lib/xirr/"
+end

data/benchmark/solvers.rb

@@ -0,0 +1,59 @@
+# Benchmarks the solvers (rtsafe_c when the native extension is built, rtsafe,
+# newton_method, bisection) across a range of cashflows: moderate, high-rate,
+# long-horizon, near -100%, and a large flow.
+#
+#   ruby -Ilib benchmark/solvers.rb
+#
+# Reports average time per full `xirr` call and the value each solver returns
+# (so speed can be read alongside whether the solver actually converged).
+
+require 'active_support/all'
+require 'xirr'
+include Xirr
+
+def cf(pairs)
+  c = Cashflow.new
+  pairs.each { |amount, date| c << Transaction.new(amount, date: date.to_date) }
+  c
+end
+
+# --- test cashflows -------------------------------------------------------
+
+monthly = [[-100_000, Date.new(1990, 1, 1)]]
+360.times { |m| monthly << [650, Date.new(1990, 1, 1) >> (m + 1)] }
+
+FLOWS = {
+  'moderate (3 flows, ~0.23)'   => cf([[1000, '1985-01-01'], [-600, '1990-01-01'], [-6000, '1995-01-01']]),
+  'high rate (~22)'             => cf([[1_000_000, '2020-01-01'], [-2_200_000, '2020-05-01'], [-800_000, '2020-06-01']]),
+  'long horizon (56 yr)'        => cf([[-1000, '1957-01-01'], [390_000, '2013-01-01']]),
+  'near -100%'                  => cf([[-10_000, '2014-04-15'], [305.6, '2014-05-15'], [500, '2014-10-19']]),
+  'large (361 monthly flows)'   => cf(monthly),
+}
+
+METHODS = %i[rtsafe brent newton_method bisection]
+METHODS.unshift(:rtsafe_c) if Xirr::NATIVE
+
+# --- timing ---------------------------------------------------------------
+
+def time_call(cashflow, method, iterations)
+  # Warm up memoized dates / guess.
+  cashflow.xirr(method: method)
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  iterations.times { cashflow.xirr(method: method) }
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+  (elapsed / iterations) * 1_000.0 # ms per call
+end
+
+puts format('%-28s %-15s %12s  %s', 'cashflow', 'solver', 'ms/call', 'result')
+puts '-' * 78
+
+FLOWS.each do |name, cashflow|
+  iterations = cashflow.size > 50 ? 200 : 5_000
+  METHODS.each_with_index do |method, i|
+    ms     = time_call(cashflow, method, iterations)
+    result = cashflow.xirr(method: method)
+    label  = i.zero? ? name : ''
+    puts format('%-28s %-15s %12.4f  %s', label, method, ms, result)
+  end
+  puts
+end

data/ext/xirr/extconf.rb

@@ -0,0 +1,23 @@
+require 'mkmf'
+
+# The native rtsafe solver is optional. If it can't be built — no working C
+# compiler, or create_makefile fails — write a do-nothing Makefile so
+# `gem install` still succeeds; at runtime the require is rescued and the gem
+# falls back to the pure-Ruby solver.
+def skip_native(reason)
+  warn "xirr: skipping native extension (#{reason}); using pure Ruby."
+  File.write('Makefile', "all:\n\t@true\ninstall:\n\t@true\nclean:\n\t@true\n")
+  true
+end
+
+# try_compile actually exercises the toolchain, which create_makefile does not.
+if !try_compile('int main(void){return 0;}')
+  skip_native('no working C compiler')
+else
+  begin
+    $CFLAGS << ' -O3'
+    create_makefile('xirr/xirr_native')
+  rescue StandardError => e
+    skip_native(e.message)
+  end
+end

data/ext/xirr/xirr_native.c

@@ -0,0 +1,125 @@
+#include <ruby.h>
+#include <math.h>
+
+/*
+ * Native implementation of the safeguarded-Newton (rtsafe) solver. This mirrors
+ * lib/xirr/rtsafe.rb line for line so the two produce the same result; keep them
+ * in sync. Flows arrive as an array of [time, amount] pairs (time in years).
+ */
+
+#define BRACKET_CEILING 1.0e7
+
+static double present_value(long n, const double *t, const double *amt, double rate) {
+    double sum = 0.0;
+    long i;
+    for (i = 0; i < n; i++) sum += amt[i] / pow(1.0 + rate, t[i]);
+    return sum;
+}
+
+static double present_value_derivative(long n, const double *t, const double *amt, double rate) {
+    double sum = 0.0;
+    long i;
+    for (i = 0; i < n; i++) sum += -t[i] * amt[i] / pow(1.0 + rate, t[i] + 1.0);
+    return sum;
+}
+
+/* Raise the floor just enough that the longest-dated discount factor stays finite. */
+static double safe_low(long n, const double *t) {
+    double max_t = 1.0, v;
+    long i;
+    for (i = 0; i < n; i++) if (t[i] > max_t) max_t = t[i];
+    v = pow(1.0e-290, 1.0 / max_t);
+    if (v < 1.0e-6) v = 1.0e-6;
+    return v - 1.0;
+}
+
+static int straddles_zero(double a, double b) {
+    return (a <= 0 && b >= 0) || (a >= 0 && b <= 0);
+}
+
+static int inside(double point, double xlo, double xhi) {
+    double lo = xlo < xhi ? xlo : xhi;
+    double hi = xlo < xhi ? xhi : xlo;
+    return point >= lo && point <= hi;
+}
+
+/* Returns the rate, or NAN when it can't converge. */
+static double rtsafe(long n, const double *t, const double *amt,
+                     double guess, double tol, long max_iter) {
+    double low = safe_low(n, t);
+    double f_low = present_value(n, t, amt, low);
+    double high = 1.0, a, b, xlo, xhi, x, f, df, dxold;
+    long i;
+
+    /* Expand the upper bound until the NPV changes sign. */
+    while (!straddles_zero(f_low, present_value(n, t, amt, high))) {
+        high = high * 2 + 1;
+        if (high > BRACKET_CEILING) return NAN;
+    }
+    a = low;
+    b = high;
+
+    /* a == low, so the NPV at a is f_low. Orient so it is negative at xlo and
+       positive at xhi. */
+    if (f_low < 0.0) { xlo = a; xhi = b; }
+    else             { xlo = b; xhi = a; }
+
+    x = (guess > a && guess < b) ? guess : (a + b) / 2.0;
+    f = present_value(n, t, amt, x);
+    df = present_value_derivative(n, t, amt, x);
+    dxold = fabs(b - a);
+
+    for (i = 0; i < max_iter; i++) {
+        double next, dx, f_next, df_next;
+        int newton_usable = 0;
+
+        if (df != 0.0 && inside(x - f / df, xlo, xhi) && fabs(2.0 * f) <= fabs(dxold * df))
+            newton_usable = 1;
+
+        if (newton_usable) { dx = f / df;            next = x - dx; }
+        else               { dx = (xhi - xlo) / 2.0; next = xlo + dx; }
+
+        if (fabs(dx) < tol) return next;
+
+        f_next = present_value(n, t, amt, next);
+        df_next = present_value_derivative(n, t, amt, next);
+        if (f_next < 0.0) xlo = next; else xhi = next;
+
+        x = next; f = f_next; df = df_next; dxold = dx;
+    }
+    return NAN; /* did not converge within the iteration limit */
+}
+
+/* Xirr::Native.rtsafe(flows, guess, tolerance, max_iterations) -> Float | nil */
+static VALUE rb_rtsafe(VALUE self, VALUE flows, VALUE guess, VALUE tol, VALUE max_iter) {
+    long n, i;
+    double *t, *amt, rate;
+    /* ALLOCV buffers are freed by the GC even if a conversion below raises, so a
+       bad element can't leak them. */
+    VALUE t_buf, amt_buf;
+
+    Check_Type(flows, T_ARRAY);
+    n = RARRAY_LEN(flows);
+    t = ALLOCV_N(double, t_buf, n);
+    amt = ALLOCV_N(double, amt_buf, n);
+
+    for (i = 0; i < n; i++) {
+        VALUE pair = rb_ary_entry(flows, i);
+        Check_Type(pair, T_ARRAY);
+        t[i] = NUM2DBL(rb_ary_entry(pair, 0));
+        amt[i] = NUM2DBL(rb_ary_entry(pair, 1));
+    }
+
+    rate = rtsafe(n, t, amt, NUM2DBL(guess), NUM2DBL(tol), NUM2LONG(max_iter));
+    ALLOCV_END(t_buf);
+    ALLOCV_END(amt_buf);
+
+    if (isnan(rate) || isinf(rate) || rate <= -1.0) return Qnil;
+    return DBL2NUM(rate);
+}
+
+void Init_xirr_native(void) {
+    VALUE mXirr = rb_define_module("Xirr");
+    VALUE mNative = rb_define_module_under(mXirr, "Native");
+    rb_define_singleton_method(mNative, "rtsafe", rb_rtsafe, 4);
+}

data/lib/xirr/base.rb

@@ -1,32 +1,47 @@
 # frozen_string_literal: true
 
 module Xirr
-  #  Base module for XIRR calculation Methods
+  # Shared numerics for the solver classes: the net present value of a cashflow,
+  # its derivative, and the discounting timeline. Each solver includes this and
+  # is constructed with the {Cashflow} it works on.
   module Base
-    extend ActiveSupport::Concern
     attr_reader :cf
 
-    # @param cf [Cashflow]
-    # Must provide the calling Cashflow in order to calculate
+    # @param cf [Cashflow] the cashflow to solve
     def initialize(cf)
       @cf = cf
     end
 
-    # Calculates days until last transaction
-    # @return [Rational]
+    # Periods (years, with the default period) from the first transaction to +date+.
     # @param date [Date]
+    # @return [Float]
     def periods_from_start(date)
       (date - cf.min_date) / cf.period
     end
 
-    # Net Present Value function that will be used to reduce the cashflow
-    # @param rate [BigDecimal]
-    # @return [BigDecimal]
+    # Net present value of the cashflow at +rate+: Σ amount / (1 + rate)^t.
+    # @param rate [Float]
+    # @return [Float]
     def xnpv(rate)
-      cf.inject(0) do |sum, t|
-        # sum + (xnpv_c rate, t.amount, periods_from_start(t.date))
-        sum + t.amount / (1+rate.to_f) ** periods_from_start(t.date)
-      end
+      r = rate.to_f
+      flows.inject(0.0) { |sum, (t, amount)| sum + amount / (1 + r)**t }
+    end
+
+    # Derivative of {#xnpv} with respect to rate: Σ -t · amount / (1 + rate)^(t+1).
+    # @param rate [Float]
+    # @return [Float]
+    def xnpv_derivative(rate)
+      r = rate.to_f
+      flows.inject(0.0) { |sum, (t, amount)| sum + (-t * amount / (1 + r)**(t + 1)) }
+    end
+
+    private
+
+    # The cashflow as [years_from_start, amount] pairs, built once per solve so
+    # the date arithmetic isn't repeated on every NPV evaluation.
+    # @return [Array<Array(Float, Float)>]
+    def flows
+      @flows ||= cf.map { |t| [periods_from_start(t.date).to_f, t.amount.to_f] }
     end
   end
 end