fast_xirr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 164d5fa4cee3f5843f73e98ebb07c1b07b35c3bd76b2cb203729e4de0bbf117b
+  data.tar.gz: 8e39e9dd7b740f4bc5a50161f13b4022eccac626faf02e4d05148393ff1d67c5
+SHA512:
+  metadata.gz: 1afc7e0a0c46fffb68036501eda4a431d935924b4e0c4cc32befaeb67ec5520acaf3221c87ff90ef2523936b13df061e914b68469d537ef1524b2ab63b0d30fc
+  data.tar.gz: 22f0d3670038bdabeacb097d17f52227dd6a79f8d5cf01ada768fde793ee3605f3c99bcd93fad3eec4688c4fd52dda1b46e4038d9509be5f24b6ab38e7d9237e

data/README.md

@@ -0,0 +1,134 @@
+# FastXirr
+
+FastXirr is a high-performance Ruby gem for calculating the Extended Internal Rate of Return (XIRR). It leverages C under the hood for rapid calculations, making it suitable for performance-critical applications.
+
+## Features
+
+- Fast XIRR calculations using efficient algorithms
+- Implemented in C for high performance
+- Easy to use Ruby interface
+- Includes both Brent's method and Bisection method for robust root-finding
+
+## Installation
+
+### From RubyGems
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fast_xirr', git: 'https://github.com/fintual-oss/fast-xirr.git'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+## Usage
+
+### Calculate XIRR
+
+To calculate the XIRR for a series of cash flows, use the calculate method:
+
+```ruby
+require 'fast_xirr'
+require 'date'
+
+cashflows = [
+  [1000, Date.new(1985, 1, 1)],
+  [-600, Date.new(1990, 1, 1)],
+  [-6000, Date.new(1995, 1, 1)]
+]
+
+result = FastXirr.calculate(cashflows: cashflows)
+puts "XIRR: #{result}"
+# => XIRR: 0.22568401743016633
+```
+
+If it is not possible to find a solution, the method will return `nan`.
+
+```ruby
+require 'fast_xirr'
+require 'date'
+
+result = FastXirr.calculate(cashflows: [[1000, Date.new(1985, 1, 1)]])
+
+puts "XIRR: #{result}"
+# => XIRR: NaN
+
+result.nan?
+# => true
+```
+
+Tolerance can be set to a custom value (default is 1e-10), as well as the maximum number of iterations (default is 100000000000000).
+
+
+```ruby
+require 'fast_xirr'
+require 'date'
+
+cashflows = [
+  [1000, Date.new(1985, 1, 1)],
+  [-600, Date.new(1990, 1, 1)],
+  [-6000, Date.new(1995, 1, 1)]
+]
+
+result = FastXirr.calculate(cashflows: cashflows, tol: 1e-2, max_iter: 100)
+puts "XIRR: #{result}"
+# => XIRR: 0.22305878076614422
+
+result = FastXirr.calculate(cashflows: cashflows, tol: 1e-8, max_iter: 2)
+puts "XIRR: #{result}"
+# => XIRR: NaN
+```
+
+## Build and test
+
+### Building the Gem
+
+To build the gem from the source code, follow these steps:
+
+1. **Clone the Repository**:
+
+    ```bash
+    git clone https://github.com/fintual-oss/fast-xirr.git
+    cd fast_xirr
+    ```
+
+2. **Build the Gem**:
+
+    ```bash
+    gem build fast_xirr.gemspec
+    ```
+
+    This will create a `.gem` file in the directory, such as `fast_xirr-0.1.0.gem`.
+
+3. **Install the Gem Locally**:
+
+    ```bash
+    gem install ./fast_xirr-0.1.0.gem
+    ```
+
+### Testing the Gem
+
+To run the tests, follow these steps:
+
+1. **Install Development Dependencies**:
+
+    ```bash
+    bundle install
+    ```
+
+2. **Run the Tests**:
+
+    ```bash
+    rake test
+    ```
+
+    This will run the test suite using RSpec.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/fintual-oss/fast-xirr. This project is intended to be a safe, welcoming space for collaboration.
+

data/ext/fast_xirr/bisection.c

@@ -0,0 +1,100 @@
+#include <ruby.h>
+#include <time.h>
+#include <math.h>
+#include "bisection.h"
+#include "common.h"
+
+/**
+ * Bisection Method for finding the root of a function within a given interval.
+ * This method iteratively narrows the interval where the root is located by halving the interval.
+ *
+ * @param cashflows Array of CashFlow structures containing amount and date.
+ * @param count Number of elements in the cashflows array.
+ * @param tol Tolerance for convergence.
+ * @param max_iter Maximum number of iterations.
+ * @param low Lower bound of the initial interval.
+ * @param high Upper bound of the initial interval.
+ *
+ * @return The estimated root (XIRR) or NAN if it fails to converge.
+ */
+double bisection_method(CashFlow *cashflows, long count, double tol, long max_iter, double low, double high) {
+    double mid, f_low, f_mid, f_high;
+
+    // Calculate the NPV at the boundaries of the interval
+    f_low = npv(low, cashflows, count, cashflows[0].date);
+    f_high = npv(high, cashflows, count, cashflows[0].date);
+
+    // Ensure the root is bracketed
+    if (f_low * f_high > 0) {
+        return NAN; // Root is not bracketed
+    }
+
+    // Iteratively apply the bisection method
+    for (long iter = 0; iter < max_iter; iter++) {
+        mid = (low + high) / 2.0;
+        f_mid = npv(mid, cashflows, count, cashflows[0].date);
+
+        // Check for convergence
+        if (fabs(f_mid) < tol || fabs(high - low) < tol) {
+            return mid;
+        }
+
+        // Narrow the interval
+        if (f_low * f_mid < 0) {
+            high = mid;
+            f_high = f_mid;
+        } else {
+            low = mid;
+            f_low = f_mid;
+        }
+    }
+
+    // If we reach here, it means we failed to converge
+    return NAN;
+}
+
+/**
+ * Ruby wrapper to calculate XIRR using the Bisection method.
+ *
+ * @param self Ruby object (self).
+ * @param rb_cashflows Ruby array of cash flows.
+ * @param rb_tol Ruby float for tolerance.
+ * @param rb_max_iter Ruby integer for maximum iterations.
+ *
+ * @return Ruby float with the calculated XIRR.
+ */
+VALUE calculate_xirr_with_bisection(VALUE self, VALUE rb_cashflows, VALUE rb_tol, VALUE rb_max_iter) {
+    // Get the number of cash flows
+    long count = RARRAY_LEN(rb_cashflows);
+    CashFlow cashflows[count];
+
+    // Convert Ruby cash flows array to C array
+    for (long i = 0; i < count; i++) {
+        VALUE rb_cashflow = rb_ary_entry(rb_cashflows, i);
+        cashflows[i].amount = NUM2DBL(rb_ary_entry(rb_cashflow, 0));
+        cashflows[i].date = (time_t)NUM2LONG(rb_ary_entry(rb_cashflow, 1));
+    }
+
+    // Convert tolerance and max iterations to C types
+    double tol = NUM2DBL(rb_tol);
+    long max_iter = NUM2LONG(rb_max_iter);
+
+    // Initial standard bracketing interval
+    double low = -0.999999, high = 100.0;
+
+    // Try Bisection method with the standard interval
+    double result = bisection_method(cashflows, count, tol, max_iter, low, high);
+    if (!isnan(result)) {
+        return rb_float_new(result);
+    }
+
+    // If the standard interval fails, try to find a better bracketing interval
+    low = -0.9999999; high = 1000.0;
+    if (find_bracketing_interval(cashflows, count, &low, &high)) {
+        result = bisection_method(cashflows, count, tol, max_iter, low, high);
+        return rb_float_new(result);
+    }
+
+    // If no interval is found, return NAN
+    return rb_float_new(NAN);
+}

data/ext/fast_xirr/bisection.h

@@ -0,0 +1,8 @@
+#ifndef BISECTION_H
+#define BISECTION_H
+
+#include <ruby.h>
+
+VALUE calculate_xirr_with_bisection(VALUE self, VALUE rb_cashflows, VALUE rb_tol, VALUE rb_max_iter);
+
+#endif

data/ext/fast_xirr/brent.c

@@ -0,0 +1,152 @@
+#include <ruby.h>
+#include <time.h>
+#include <math.h>
+#include "brent.h"
+#include "common.h"
+
+/**
+ * Brent's Method for finding the root of a function within a given interval.
+ * This method combines root bracketing, bisection, secant, and inverse quadratic interpolation.
+ *
+ * @param cashflows Array of CashFlow structures containing amount and date.
+ * @param count Number of elements in the cashflows array.
+ * @param tol Tolerance for convergence.
+ * @param max_iter Maximum number of iterations.
+ * @param low Lower bound of the initial interval.
+ * @param high Upper bound of the initial interval.
+ *
+ * @return The estimated root (XIRR) or NAN if it fails to converge.
+ */
+double brent_method(CashFlow *cashflows, long count, double tol, long max_iter, double low, double high) {
+    // Calculate the NPV at the boundaries of the interval
+    double fa = npv(low, cashflows, count, cashflows[0].date);
+    double fb = npv(high, cashflows, count, cashflows[0].date);
+
+    // Ensure the root is bracketed
+    if (fa * fb > 0) {
+        return NAN; // Root is not bracketed
+    }
+
+    double c = low, fc = fa, s, d = 0.0, e = 0.0;
+
+    // Iteratively apply Brent's method
+    for (long iter = 0; iter < max_iter; iter++) {
+        if (fb * fc > 0) {
+            // Adjust c to ensure that f(b) and f(c) have opposite signs
+            c = low;
+            fc = fa;
+            d = e = high - low;
+        }
+        if (fabs(fc) < fabs(fb)) {
+            // Swap low and high to make f(b) smaller in magnitude
+            low = high;
+            high = c;
+            c = low;
+            fa = fb;
+            fb = fc;
+            fc = fa;
+        }
+
+        // Tolerance calculation for convergence check
+        double tol1 = 2 * tol * fabs(high) + 0.5 * tol;
+        double m = 0.5 * (c - high);
+        
+        // Check for convergence
+        if (fabs(m) <= tol1 || fb == 0.0) {
+            return high;
+        }
+
+        // Use inverse quadratic interpolation if conditions are met
+        if (fabs(e) >= tol1 && fabs(fa) > fabs(fb)) {
+            double p, q, r;
+            s = fb / fa;
+            if (low == c) {
+                // Use the secant method
+                p = 2 * m * s;
+                q = 1 - s;
+            } else {
+                // Use inverse quadratic interpolation
+                q = fa / fc;
+                r = fb / fc;
+                p = s * (2 * m * q * (q - r) - (high - low) * (r - 1));
+                q = (q - 1) * (r - 1) * (s - 1);
+            }
+            if (p > 0) q = -q;
+            p = fabs(p);
+            if (2 * p < fmin(3 * m * q - fabs(tol1 * q), fabs(e * q))) {
+                // Accept interpolation
+                e = d;
+                d = p / q;
+            } else {
+                // Use bisection
+                d = m;
+                e = m;
+            }
+        } else {
+            // Use bisection
+            d = m;
+            e = m;
+        }
+        
+        // Update bounds
+        low = high;
+        fa = fb;
+        
+        // Update the new high value
+        if (fabs(d) > tol1) {
+            high += d;
+        } else {
+            high += copysign(tol1, m);
+        }
+        fb = npv(high, cashflows, count, cashflows[0].date);
+    }
+    
+    return NAN; // Failed to converge
+}
+
+/**
+ * Ruby wrapping to calculate XIRR using Brent's method.
+ *
+ * @param self Ruby object (self).
+ * @param rb_cashflows Ruby array of cash flows.
+ * @param rb_tol Ruby float for tolerance.
+ * @param rb_max_iter Ruby integer for maximum iterations.
+ *
+ * @return Ruby float with the calculated XIRR.
+ */
+VALUE calculate_xirr_with_brent(VALUE self, VALUE rb_cashflows, VALUE rb_tol, VALUE rb_max_iter) {
+    // Get the number of cash flows
+    long count = RARRAY_LEN(rb_cashflows);
+    CashFlow cashflows[count];
+
+    // Convert Ruby cash flows array to C array
+    for (long i = 0; i < count; i++) {
+        VALUE rb_cashflow = rb_ary_entry(rb_cashflows, i);
+        cashflows[i].amount = NUM2DBL(rb_ary_entry(rb_cashflow, 0));
+        cashflows[i].date = (time_t)NUM2LONG(rb_ary_entry(rb_cashflow, 1));
+    }
+
+    // Convert tolerance and max iterations to C types
+    double tol = NUM2DBL(rb_tol);
+    long max_iter = NUM2LONG(rb_max_iter);
+
+    double result;
+
+    // Try Brent's method with a standard bracketing interval
+    double low = -0.9999, high = 10.0;
+    result = brent_method(cashflows, count, tol, max_iter, low, high);
+    if (!isnan(result)) {
+        return rb_float_new(result);
+    }
+
+    // If the standard interval fails, try to find a better bracketing interval
+    low = -0.9999999; high = 10.0;
+    if (find_bracketing_interval(cashflows, count, &low, &high)) {
+        result = brent_method(cashflows, count, tol, max_iter, low, high);
+        return rb_float_new(result);
+    }
+
+    // If no interval is found, return NAN
+    return rb_float_new(NAN);
+}
+

data/ext/fast_xirr/brent.h

@@ -0,0 +1,9 @@
+#ifndef BRENT_H  
+#define BRENT_H
+
+#include <ruby.h>
+
+VALUE calculate_xirr_with_brent(VALUE self, VALUE rb_cashflows, VALUE rb_tol, VALUE rb_max_iter);
+
+#endif
+

data/ext/fast_xirr/common.c

@@ -0,0 +1,85 @@
+#include "common.h"
+#include <math.h>
+
+/**
+ * Calculate the Net Present Value (NPV) for a given rate.
+ *
+ * @param rate The discount rate.
+ * @param cashflows Array of CashFlow structures containing amount and date.
+ * @param count Number of elements in the cashflows array.
+ * @param min_date The earliest date in the cashflows array.
+ *
+ * @return The calculated NPV.
+ */
+double npv(double rate, CashFlow *cashflows, long count, time_t min_date) {
+    double npv_value = 0.0;
+
+    for (long i = 0; i < count; i++) {
+        // Calculate the number of days from the minimum date to the cash flow date
+        double days = difftime(cashflows[i].date, min_date) / (60 * 60 * 24);
+        
+        // Calculate the discount factor and add the discounted amount to the NPV
+        npv_value += cashflows[i].amount / pow(1 + rate, days / 365.0);
+    }
+
+    return npv_value;
+}
+
+
+
+/**
+ * Find a bracketing interval for the root using the NPV function.
+ *
+ * @param cashflows Array of CashFlow structures containing amount and date.
+ * @param count Number of elements in the cashflows array.
+ * @param low Pointer to store the lower bound of the bracketing interval.
+ * @param high Pointer to store the upper bound of the bracketing interval.
+ *
+ * @return 1 if a bracketing interval is found, 0 otherwise.
+ */
+int find_bracketing_interval(CashFlow *cashflows, long count, double *low, double *high) {
+    double min_rate = -0.99999999, max_rate = 10.0;
+    double step = 0.0001;
+    time_t min_date = cashflows[0].date;
+
+    // Find the earliest date in the cashflows array
+    for (long i = 1; i < count; i++) {
+        if (cashflows[i].date < min_date) {
+            min_date = cashflows[i].date;
+        }
+    }
+
+    // Calculate NPV at the minimum rate
+    double npv_min_rate = npv(min_rate, cashflows, count, min_date);
+
+    // Search for a bracketing interval within the initial range
+    for (double rate = min_rate + step; rate <= max_rate; rate += step) {
+        double npv_rate = npv(rate, cashflows, count, min_date);
+
+        // Check if the function values at consecutive rates have opposite signs
+        if (npv_min_rate * npv_rate <= 0) {
+            *low = rate - step;
+            *high = rate;
+            return 1;
+        }
+        npv_min_rate = npv_rate;
+    }
+
+    // Extend the search range if no interval is found within the initial range
+    step = 10.0;
+    for (double rate = max_rate + step; rate <= 10000.0; rate += step) {
+        double npv_rate = npv(rate, cashflows, count, min_date);
+
+        // Check if the function values at consecutive rates have opposite signs
+        if (npv_min_rate * npv_rate < 0) {
+            *low = rate - step;
+            *high = rate;
+            return 1;
+        }
+        npv_min_rate = npv_rate;
+    }
+
+    // If no bracketing interval is found, return 0
+    return 0;
+}
+

data/ext/fast_xirr/common.h

@@ -0,0 +1,15 @@
+#ifndef COMMON_H
+#define COMMON_H
+
+#include <time.h>
+
+typedef struct {
+    double amount;
+    time_t date;
+} CashFlow;
+
+double npv(double rate, CashFlow *cashflows, long count, time_t min_date);
+
+int find_bracketing_interval(CashFlow *cashflows, long count, double *low, double *high);
+
+#endif

data/ext/fast_xirr/extconf.rb

@@ -0,0 +1,6 @@
+require 'mkmf'
+
+$srcs = ['xirr.c', 'brent.c', 'bisection.c', 'common.c']
+
+create_makefile('fast_xirr/fast_xirr')
+

data/ext/fast_xirr/xirr.c

@@ -0,0 +1,12 @@
+#include <ruby.h>
+#include "brent.h" 
+#include "bisection.h"
+
+/**
+ * Initialize the FastXirr module and define its methods.
+ */
+void Init_fast_xirr(void) {
+    VALUE XirrModule = rb_define_module("FastXirr");
+    rb_define_singleton_method(XirrModule, "_calculate_with_bisection", calculate_xirr_with_bisection, 3);
+    rb_define_singleton_method(XirrModule, "_calculate_with_brent", calculate_xirr_with_brent, 3);
+}

data/lib/fast_xirr/version.rb

@@ -0,0 +1,4 @@
+module FastXirr
+  VERSION = "0.1.0"
+end
+

data/lib/fast_xirr.rb

@@ -0,0 +1,19 @@
+require 'fast_xirr/fast_xirr'
+
+module FastXirr
+  def self.calculate(cashflows:, tol: 1e-7, max_iter: 1e10)
+    cashflows_with_timestamps = cashflows.map do |amount, date|
+      [amount, date.to_time.to_i]
+    end
+    result = _calculate_with_brent(cashflows_with_timestamps, tol, max_iter)
+    
+    if result.nan?
+      result = _calculate_with_bisection(cashflows_with_timestamps, tol, max_iter)
+      puts "Brent failed, trying bisection" unless result.nan?
+    end
+
+    return result
+  end
+end
+
+

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: fast_xirr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matias Martini
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-06-28 00:00:00.000000000 Z
+dependencies: []
+description: A gem to calculate the XIRR using a C extension for performance.
+email:
+- martini@fintual.com
+executables: []
+extensions:
+- ext/fast_xirr/extconf.rb
+extra_rdoc_files: []
+files:
+- README.md
+- ext/fast_xirr/bisection.c
+- ext/fast_xirr/bisection.h
+- ext/fast_xirr/brent.c
+- ext/fast_xirr/brent.h
+- ext/fast_xirr/common.c
+- ext/fast_xirr/common.h
+- ext/fast_xirr/extconf.rb
+- ext/fast_xirr/xirr.c
+- lib/fast_xirr.rb
+- lib/fast_xirr/version.rb
+homepage: https://github.com/fintual-oss/fast-xirr
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fintual-oss/fast-xirr
+  source_code_uri: https://github.com/fintual-oss/fast-xirr
+  changelog_uri: https://github.com/fintual-oss/fast-xirr/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: XIRR calculation in Ruby with C extension
+test_files: []