finrb 0.1.12 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 312d19ce29f9c0fc5cb7efca39d9cd6ef9ceedec77e9432f817c1b639a4a7c47
-  data.tar.gz: 46901c63d6c174af45186020bdcc0727ec7cc5e2cf138b38fec43ba1bbb5e90c
+  metadata.gz: e783eb0696497a848cc5506b4bd0d75e4327b383a8a4c998fd34ed86c3092a8c
+  data.tar.gz: ca82637abc1703af93554215a2704469af63a3e4d95c4659da9ab86df289bdf2
 SHA512:
-  metadata.gz: 59c3c4c172cfd860f28afbaa07d294c7bef5d3f7a71020ddbb05ef4cefc0acac7cebc385f88efb5e0d9d7a12fedd45437c54c6fdd2234acfe1e5f5b7f9701ed9
-  data.tar.gz: 3889d3561dc138d16f9696dc7850a3c5f55803c4f1ff17d98be962d82778e365df9ebd5d4c84cc2ec49e9e562e44d947553a7839e194c1dd7225d23e72b702dd
+  metadata.gz: a1b6da22366494309440b3095f6ea046512c27bf1aed43586701788f87c4fd25e67a246e35172419077cdf2c2a074c5bc9f2ae23ec110a2c3d4a65d690bdf0c0
+  data.tar.gz: 2d3fa7f43260c6d00767e899a37ca977e86a4b146cb500dd6f1fa9ffaeabcc1dbed38fa2a7f1e38168e0a86c4f69e960131e96d9d2e8f3dedffe24f2c3064cd8

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # finrb changelog
 
+## 1.0.0
+
+This release intentionally breaks parts of the 0.1 public API.
+
+### Financial correctness
+
+- Normalize XNPV date calculations and distinguish nominal APR from effective APY.
+- Replace deprecated BigDecimal Newton solving with a decimal Brent–Dekker solver and explicit convergence/domain errors.
+- Validate public financial inputs and centralize amortization rounding policy.
+- Fix FIFO/LIFO ending inventory when a sale is satisfied before every layer is traversed.
+
+### Public API
+
+- Replace `Finrb::Utils` with `Finrb::TVM`, `Accounting`, `Ratios`, `Returns`, and `Yields`.
+- Expose IRR, NPV, XIRR, and XNPV through `Finrb::Cashflow`.
+- Stop modifying `Array` and `Numeric` by default; legacy fluent methods require `finrb/core_ext`.
+- Publish immutable configuration snapshots with thread-scoped temporary overrides.
+
+### Dependencies and assurance
+
+- Remove ActiveSupport and `business_time` production dependencies.
+- Add deterministic generated-root tests, SciPy/QuantLib reference verification, line and branch coverage, and packaged RBS signatures.
+- Support Ruby 3.3, 3.4, and 4.0.
+
 ## 0.1.12
 
 - bump gem versions

data/NOTICE.md

@@ -0,0 +1,20 @@
+# finrb notices and attribution
+
+finrb is licensed under the GNU Lesser General Public License version 3.0 or
+later. The complete GPLv3 and LGPLv3 texts are distributed as `COPYING` and
+`COPYING.LESSER`.
+
+finrb is derived from the Ruby
+[finance](https://github.com/Edward-Intelligence/finance) gem. Financial
+calculation utilities were also ported from R's
+[FinCal](https://github.com/felixfan/FinCal) package. Their contributors are
+acknowledged in the README and repository history.
+
+The bracketed scalar root solver implements the Brent–Dekker algorithm using
+the method described by Richard P. Brent in *Algorithms for Minimization
+Without Derivatives* (1973). The implementation is local Ruby code and is not
+copied from SciPy or QuantLib.
+
+SciPy and QuantLib are optional, independently maintained reference
+implementations used by the maintainer verification scripts. They are not
+runtime dependencies and their code is not distributed in the finrb gem.

data/README.md

@@ -4,154 +4,242 @@
 [![CodeQL](https://github.com/ncs1/finrb/actions/workflows/codeql.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/codeql.yml)
 [![RuboCop](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml/badge.svg)](https://github.com/ncs1/finrb/actions/workflows/rubocop.yml)
 
-<!-- TOC depthfrom:2 -->
+Precision-first financial mathematics for Ruby.
 
-- [Overview](#overview)
-  - [Features](#features)
-  - [Configuration](#configuration)
-  - [API and examples](#api-and-examples)
-- [Resources](#resources)
-- [Acknowledgements](#acknowledgements)
-- [License](#license)
+finrb provides decimal calculations for cashflows, interest rates, loan
+amortization, time value of money, investment returns, financial ratios, and
+basic accounting. Public APIs live under explicit `Finrb` namespaces, and
+loading the gem does not modify Ruby's core classes.
 
-<!-- /TOC -->
+finrb is a fork of the Ruby [finance](https://github.com/Edward-Intelligence/finance)
+gem and includes calculations ported from R's
+[FinCal](https://github.com/felixfan/FinCal) package.
 
-Ruby gem for financial calculations/modeling.
+## Installation
 
-finrb forked from the ruby [finance](https://github.com/Edward-Intelligence/finance) gem.
+Add finrb to your bundle:
 
-## Overview
+```shell
+bundle add finrb
+```
 
-### Features
+Or install it directly:
 
-Currently implemented features include:
+```shell
+gem install finrb
+```
 
-- Uses the [flt](https://github.com/jgoizueta/flt) gem to ensure precision decimal arithmetic in all calculations.
-- Fixed-rate mortgage amortization (30/360).
-- Interest rates
-- Various cash flow computations, such as NPV and IRR.
-- Adjustable rate mortgage amortization.
-- Payment modifications (i.e., how does paying an additional $75 per month affect the amortization?)
-- Utils class provides basic financial calculation utilities (ported from R's [FinCal](https://github.com/felixfan/FinCal) library):
+finrb requires Ruby 3.3 or newer.
 
-  - Basic Earnings Per Share
+## Quick start
 
-  - Bond-equivalent yield (BEY), 2 x the semiannual discount rate
+```ruby
+require 'finrb'
 
-  - Calculate the net increase in common shares from the potential exercise of stock options or warrants
+cashflows = [-4000, 1200, 1410, 1875, 1050]
 
-  - Calculate weighted average shares - weighted average number of common shares
+Finrb::Cashflow.irr(cashflows).round(6)
+# => Flt::DecNum('0.142993')
 
-  - Cash ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+Finrb::Cashflow.npv(cashflows, 0.10).round(2)
+# => Flt::DecNum('382.08')
+```
 
-  - Computing Coefficient of variation
+Inputs are validated and calculations return `Flt::DecNum` values unless an
+API explicitly returns another financial object, such as `Finrb::Rate`.
 
-  - Computing HPR, the holding period return
+## Financial domains
 
-  - Computing IRR, the internal rate of return
+| Namespace | Purpose |
+| --- | --- |
+| `Finrb::Cashflow` | NPV, XNPV, IRR, and XIRR |
+| `Finrb::Rate` | Nominal APR, effective APY, and compounding conversions |
+| `Finrb::Amortization` | Fixed and adjustable-rate loan amortization |
+| `Finrb::TVM` | Present value, future value, payments, periods, and perpetuities |
+| `Finrb::Returns` | Holding-period, time-weighted, portfolio, and risk-adjusted returns |
+| `Finrb::Yields` | Money-market, bond-equivalent, effective, and continuous yield conversions |
+| `Finrb::Ratios` | Liquidity, leverage, profitability, and per-share ratios |
+| `Finrb::Accounting` | Inventory costing and depreciation |
 
-  - Computing NPV, the PV of the cash flows less the initial (time = 0) outlay
+The detailed [API and examples guide](docs/api.md) lists each calculation and
+its parameters. Packaged RBS declarations are available under `sig/`.
 
-  - Computing Roy's safety-first ratio
+## Cashflows
 
-  - Computing Sampling error
+Periodic IRR is a per-period rate. XIRR evaluates irregularly dated
+`Finrb::Transaction` objects and returns an effective annual `Finrb::Rate`.
 
-  - Computing Sharpe Ratio
+```ruby
+require 'date'
 
-  - Computing TWRR, the time-weighted rate of return
+transactions = [
+  Finrb::Transaction.new(-10_000, date: Date.new(2020, 1, 1)),
+  Finrb::Transaction.new(12_500, date: Date.new(2022, 1, 1))
+]
 
-  - Computing bank discount yield (BDY) for a T-bill
+rate = Finrb::Cashflow.xirr(transactions, 0.10)
+rate.apy.round(6)
+# => Flt::DecNum('0.117863')
+```
 
-  - Computing money market yield (MMY) for a T-bill
+Cashflows must contain at least one positive and one negative amount. Dated
+cashflows must be chronological and every transaction must have a date. For
+ordinary discrete discounting, rates and guesses must be greater than `-1`.
 
-  - Computing the future value of an uneven cash flow series
+IRR and XIRR can have more than one economically valid root. The optional
+guess controls which nearby sign-changing root finrb selects:
 
-  - Computing the present value of an uneven cash flow series
+```ruby
+cashflows = [-100, 230, -132] # roots at 10% and 20%
 
-  - Computing the rate of return for each period
+Finrb::Cashflow.irr(cashflows, 0.05).round(2) # => 0.10
+Finrb::Cashflow.irr(cashflows, 0.25).round(2) # => 0.20
+```
 
-  - Convert a given continuous compounded rate to a norminal rate
+## Rates and amortization
 
-  - Convert a given norminal rate to a continuous compounded rate
+APR is a nominal annual rate; APY is an effective annual rate. They are not
+aliases:
 
-  - Convert holding period return to the effective annual rate
+```ruby
+rate = Finrb::Rate.new(0.12, :apr)
 
-  - Convert stated annual rate to the effective annual rate (with continuous compounding)
+rate.monthly # => Flt::DecNum('0.01')
+rate.apy.round(6) # => Flt::DecNum('0.126825')
+```
 
-  - Cost of goods sold and ending inventory under three methods (FIFO,LIFO,Weighted average)
+Create a fixed-rate loan by giving the rate a duration in months:
 
-  - Current ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+```ruby
+rate = Finrb::Rate.new(0.0425, :apr, duration: 30 * 12)
+loan = Finrb::Amortization.new(250_000, rate)
 
-  - Debt ratio - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+loan.payment      # => Flt::DecNum('-1229.85')
+loan.interest.sum # => Flt::DecNum('192745.98')
+loan.balance      # => Flt::DecNum('0.00')
+```
 
-  - Depreciation Expense Recognition - Straight-line depreciation (SL) allocates an equal amount of depreciation each year over the asset's useful life
+Pass several duration-bearing rates for an adjustable-rate schedule. A block
+can modify each scheduled payment, for example to add a $150 principal payment:
 
-  - Depreciation Expense Recognition - double-declining balance (DDB), the most common declining balance method, which applies two times the straight-line rate to the declining balance.
+```ruby
+faster = Finrb::Amortization.new(250_000, rate) do |period|
+  period.payment - 150
+end
+```
 
-  - Diluted Earnings Per Share
+Payments and interest follow the sign convention used throughout finrb:
+money received is positive and money paid is negative.
 
-  - Equivalent/proportional Interest Rates
+## Configuration
 
-  - Estimate future value (fv) (of a single sum)
+Configure process-wide defaults during application startup:
 
-  - Estimate future value of an annuity
+```ruby
+Finrb.configure do |config|
+  config.eps = '1e-12'
+  config.guess = 0.10
+  config.business_days = false
+  config.periodic_compound = false
+end
+```
 
-  - Estimate period payment
+Configuration is validated and published as one immutable snapshot.
+`Finrb.config` is read-only. Use `Finrb.with_config` for a temporary override
+that is restored afterward and does not leak into another thread:
 
-  - Estimate present value (pv) (of a single sum) (of an annuity)
+```ruby
+Finrb.with_config(guess: 0.25) do
+  Finrb::Cashflow.irr(cashflows)
+end
+```
 
-  - Estimate present value of a perpetuity
+The `business_days` compatibility option excludes weekends only. It is not a
+holiday calendar or a market business-day convention.
 
-  - Estimate the number of periods
+## Precision, rounding, and failures
 
-  - Financial leverage - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+General calculations retain the active `Flt::DecNum` context and are not
+rounded for display. Callers choose presentation precision with `round` or a
+formatter. `Finrb.config.eps` controls root-solver convergence; it does not set
+decimal arithmetic precision.
 
-  - Geometric mean return
+Amortization is deliberately different because payments and interest are
+monetary postings. They are rounded to cents using half-up rounding, and any
+remaining cent-level balance is allocated to the final payment. These policies
+are exposed through `Finrb::Precision`.
 
-  - Gross profit margin - Evaluate a company's financial performance
+finrb reports invalid financial or numerical states explicitly:
 
-  - Harmonic mean, average price
+- `Finrb::InvalidCashflowError` for malformed cashflow sequences
+- `Finrb::DomainError` for values outside a calculation's legal domain
+- `Finrb::ConvergenceError` when a root cannot be bracketed or solved
+- `ArgumentError` for invalid public inputs and options
 
-  - Long-term debt-to-equity - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+## Migrating from the legacy API
 
-  - Net profit margin - Evaluate a company's financial performance
+The current API contains intentional breaking changes:
 
-  - Quick ratio - Liquidity ratios measure the firm's ability to satisfy its short-term obligations as they come due.
+- `Finrb::Utils` was removed. Use `Finrb::TVM`, `Returns`, `Yields`, `Ratios`,
+  or `Accounting` according to the calculation's domain.
+- Loading `finrb` no longer adds methods to `Array` or `Numeric`.
+- `Finrb.config` is immutable; use `Finrb.configure` or `Finrb.with_config`.
+- APR is nominal and APY is effective, so conversions now follow their stated
+  financial semantics.
 
-  - Rate of return for a perpetuity
+Applications migrating gradually can explicitly load the legacy fluent core
+extensions:
 
-  - Total debt-to-equity - Solvency ratios measure the firm's ability to satisfy its long-term obligations.
+```ruby
+require 'finrb/core_ext'
 
-  - Weighted mean as a portfolio return
+[-4000, 1200, 1410, 1875, 1050].irr
+250_000.amortize(rate)
+```
 
-### Configuration
+New code should use `Finrb::Cashflow.irr(cashflows)` and
+`Finrb::Amortization.new(principal, rate)`.
 
-In `config/initializers/finrb.rb` Finrb allows to set tolerance (eps) and default guess for IRR and XIRR calculations, such as:
+## Development and verification
 
-```ruby
-Finrb.configure do |config|
-  config.eps = '1.0e-12'
-  config.guess = 0.5
-  config.business_days = false # only relevant when using Transaction object, skips weekends
-  config.periodic_compound = false # only relevant when using Transaction object
-end
+Install the bundle and run the self-contained quality checks:
+
+```shell
+bundle install
+bundle exec rake quality
+bundle exec rubocop
 ```
 
-### API and examples
+The quality task runs the RSpec suite with line and branch coverage, generated
+IRR/XIRR properties, committed SciPy/QuantLib reference fixtures, and RBS
+validation.
+
+Maintainers with the optional Python environment can run the larger seeded
+solver verification campaign:
+
+```shell
+python3 -m pip install --requirement script/requirements-solver-verification.txt
+bundle exec rake solver:verify
+```
 
-See [api.md](docs/api.md)
+The Python packages are verification references, not gem dependencies. See
+[the fixture documentation](spec/fixtures/README.md) for reproducibility,
+Docker, batching, and tolerance details.
 
-## Resources
+## Project links
 
-- [RubyGems Page](https://rubygems.org/gems/finrb)
-- [Source Code](https://github.com/ncs1/finrb)
-- [Bug Tracker](https://github.com/ncs1/finrb/issues)
+- [RubyGems](https://rubygems.org/gems/finrb)
+- [Source](https://github.com/ncs1/finrb)
+- [Issue tracker](https://github.com/ncs1/finrb/issues)
 
 ## Acknowledgements
 
-- Martin Bjeldbak Madsen (@martinbjeldbak), Bill Kranec (@wkranec) - original [finance](https://github.com/Edward-Intelligence/finance) gem maintainers.
-- Yanhui Fan (@felixfan) - maintainer of [FinCal](https://github.com/felixfan/FinCal) library.
+- Martin Bjeldbak Madsen, Bill Kranec, and the contributors to the original
+  [finance](https://github.com/Edward-Intelligence/finance) gem
+- Yanhui Fan and the contributors to R's
+  [FinCal](https://github.com/felixfan/FinCal) package
 
 ## License
 
-See [COPYING](./COPYING) and [COPYING.LESSER](./COPYING.LESSER)
+finrb is available under the GNU Lesser General Public License v3.0 or later.
+See [COPYING](COPYING) and [COPYING.LESSER](COPYING.LESSER).

data/lib/finrb/accounting.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative 'decimal'
+require_relative 'errors'
+
+module Finrb
+  # Inventory costing and depreciation calculations.
+  module Accounting
+    def self.wrap_array(object)
+      if object.nil?
+        []
+      elsif object.respond_to?(:to_ary)
+        object.to_ary || [object]
+      else
+        [object]
+      end
+    end
+    private_class_method :wrap_array
+
+    # Cost of goods sold and ending inventory under three methods (FIFO,LIFO,Weighted average)
+    #
+    # @param uinv units of beginning inventory
+    # @param pinv price of beginning inventory
+    # @param units nx1 vector of inventory units. inventory purchased ordered by time (from first to last)
+    # @param price nx1 vector of inventory price. same order as units
+    # @param sinv units of sold inventory
+    # @param method inventory methods: FIFO (first in first out, permitted under both US and IFRS), LIFO (late in first out, US only), WAC (weighted average cost,US and IFRS)
+    # @example
+    #   Finrb::Accounting.cogs(uinv=2,pinv=2,units=[3,5],price=[3,5],sinv=7,method="FIFO")
+    #
+    # @example
+    #   Finrb::Accounting.cogs(uinv=2,pinv=2,units=[3,5],price=[3,5],sinv=7,method="LIFO")
+    #
+    # @example
+    #   Finrb::Accounting.cogs(uinv=2,pinv=2,units=[3,5],price=[3,5],sinv=7,method="WAC")
+    def self.cogs(uinv:, pinv:, units:, price:, sinv:, method: 'FIFO')
+      uinv = Flt::DecNum(uinv.to_s)
+      pinv = Flt::DecNum(pinv.to_s)
+      units = wrap_array(units).map { |value| Flt::DecNum(value.to_s) }
+      price = wrap_array(price).map { |value| Flt::DecNum(value.to_s) }
+      sinv = Flt::DecNum(sinv.to_s)
+      method = method.to_s
+
+      n = units.size
+      m = price.size
+      cost_of_goods = 0
+      ending_inventory = 0
+      if m == n
+        case method
+        when 'FIFO'
+          if sinv <= uinv
+            cost_of_goods = sinv * pinv
+            ending_inventory = (uinv - sinv) * pinv
+            (0...n).each do |i|
+              ending_inventory += (units[i] * price[i])
+            end
+          else
+            cost_of_goods = uinv * pinv
+            sinv -= uinv
+            (0...n).each do |i|
+              if sinv <= units[i]
+                cost_of_goods += (sinv * price[i])
+                ending_inventory = (units[i] - sinv) * price[i]
+                if i < n
+                  temp = i + 1
+                  (temp...n).each do |j|
+                    ending_inventory += (units[j] * price[j])
+                  end
+                end
+                sinv = 0
+                break
+              else
+                cost_of_goods += (units[i] * price[i])
+                sinv -= units[i]
+              end
+            end
+            raise(Error, "Inventory is not enough to sell\n") if sinv.positive?
+          end
+        when 'WAC'
+          ending_inventory = uinv * pinv
+          tu = uinv
+          (0...n).each do |i|
+            ending_inventory += (units[i] * price[i])
+            tu += units[i]
+          end
+          if tu >= sinv
+            cost_of_goods = ending_inventory / tu * sinv
+            ending_inventory = ending_inventory / tu * (tu - sinv)
+          else
+            raise(Error, "Inventory is not enough to sell\n")
+          end
+
+        when 'LIFO'
+          (n - 1).downto(0).each do |i|
+            if sinv <= units[i]
+              cost_of_goods += (sinv * price[i])
+              ending_inventory = (units[i] - sinv) * price[i]
+              if i > 1
+                temp = i - 1
+                temp.downto(0).each do |j|
+                  ending_inventory += (units[j] * price[j])
+                end
+              end
+              ending_inventory += (uinv * pinv)
+              sinv = 0
+              break
+            else
+              cost_of_goods += (units[i] * price[i])
+              sinv -= units[i]
+            end
+          end
+          if sinv.positive?
+            if sinv <= uinv
+              cost_of_goods += (sinv * pinv)
+              ending_inventory += ((uinv - sinv) * pinv)
+            else
+              raise(Error, "Inventory is not enough to sell\n")
+            end
+          end
+        end
+
+      else
+        raise(Error, "length of units and price are not the same\n")
+      end
+
+      {
+        cost_of_goods:,
+        ending_inventory:
+      }
+    end
+
+    # Depreciation Expense Recognition -- double-declining balance (DDB), the most common declining balance method, which applies two times the straight-line rate to the declining balance.
+    #
+    # @param cost cost of long-lived assets
+    # @param rv   residual value of the long-lived assets at the end of its useful life. DDB does not explicitly use the asset's residual value in the calculations, but depreciation ends once the estimated residual value has been reached. If the asset is expected to have no residual value, the DB method will never fully depreciate it, so the DB method is typically changed to straight-line at some point in the asset's life.
+    # @param t    length of the useful life
+    # @example
+    #   Finrb::Accounting.ddb(cost=1200,rv=200,t=5)
+    def self.ddb(cost:, rv:, t:)
+      cost = Flt::DecNum(cost.to_s)
+      rv = Flt::DecNum(rv.to_s)
+      t = Flt::DecNum(t.to_s)
+
+      raise(Error, 't should be larger than 1') if t < 2
+
+      ddb = [Flt::DecNum(0)] * t
+      ddb[0] = cost * 2 / t
+      if cost - ddb.first <= rv
+        ddb[0] = cost - rv
+      else
+        cost -= ddb.first
+        (1...t).each do |i|
+          ddb[i] = cost * 2 / t
+          if cost - ddb[i] <= rv
+            ddb[i] = cost - rv
+            break
+          else
+            cost -= ddb[i]
+          end
+        end
+      end
+      { t: (0...t).to_a, ddb: }
+    end
+
+    # Depreciation Expense Recognition -- Straight-line depreciation (SL) allocates an equal amount of depreciation each year over the asset's useful life
+    #
+    # @param cost cost of long-lived assets
+    # @param rv   residual value of the long-lived assets at the end of its useful life
+    # @param t    length of the useful life
+    # @example
+    #   Finrb::Accounting.slde(cost=1200,rv=200,t=5)
+    def self.slde(cost:, rv:, t:)
+      cost = Flt::DecNum(cost.to_s)
+      rv = Flt::DecNum(rv.to_s)
+      t = Flt::DecNum(t.to_s)
+
+      ((cost - rv) / t)
+    end
+  end
+end