finrb 1.0.1 → 1.2.0

data/lib/finrb/amortization.rb

@@ -18,20 +18,67 @@ module Finrb
   # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR, but pay $150 extra each month
   #   rate = Rate.new(0.0425, :apr, :duration => (5 * 12))
   #   extra_payments = Finrb::Amortization.new(250000, rate){ |period| period.payment - 150 }
-  # @api public
   class Amortization
+    # Immutable breakdown of one amortization period. Payments retain finrb's
+    # cashflow sign convention and are negative; the other monetary fields are
+    # non-negative.
+    class Entry
+      ATTRIBUTES = %i[period opening_balance payment interest principal additional_payment balloon_payment interest_only closing_balance].freeze
+      MONETARY_ATTRIBUTES = ATTRIBUTES - %i[period interest_only]
+      private_constant :ATTRIBUTES, :MONETARY_ATTRIBUTES
+
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(period:, opening_balance:, payment:, interest:, principal:, additional_payment:, balloon_payment:, interest_only:, closing_balance:)
+        raise(ArgumentError, 'period must be a non-negative integer.') unless period.is_a?(Integer) && !period.negative?
+        raise(ArgumentError, 'interest_only must be true or false.') unless [true, false].include?(interest_only)
+
+        @period = period
+        @interest_only = interest_only
+        MONETARY_ATTRIBUTES.each do |name|
+          value = binding.local_variable_get(name)
+          instance_variable_set("@#{name}", Validation.decimal(value, name: name.to_s.tr('_', ' ')))
+        end
+        freeze
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && ATTRIBUTES.all? { |name| public_send(name) == other.public_send(name) }
+      end
+      alias eql? ==
+
+      def hash
+        attributes = ATTRIBUTES.map { |name| public_send(name) }
+        attributes.hash
+      end
+
+      def to_h
+        ATTRIBUTES.to_h { |name| [name, public_send(name)] }
+      end
+
+      alias interest_only? interest_only
+    end
+
     # @return [Flt::DecNum] the balance of the loan at the end of the amortization period (usually zero)
-    # @api public
     attr_reader :balance
+    # @return [Flt::DecNum] contractual principal settled as a balloon in the final period
+    attr_reader :balloon
+    # @return [Flt::DecNum] principal balance including any financed origination fee
+    attr_reader :amount_financed
+    # @return [Flt::DecNum] cash made available to the borrower after an unfinanced fee
+    attr_reader :net_proceeds
+    # @return [Flt::DecNum] fee charged when the loan is originated
+    attr_reader :origination_fee
+    # @return [Integer] number of leading periods that pay interest but no scheduled principal
+    attr_reader :interest_only_periods
     # @return [Flt::DecNum] the required monthly payment.  For loans with more than one rate, returns nil
-    # @api public
     attr_reader :payment
     # @return [Flt::DecNum] the principal amount of the loan
-    # @api public
     attr_reader :principal
     # @return [Array] the interest rates used for calculating the amortization
-    # @api public
     attr_reader :rates
+    # @return [Array<Entry>] immutable period-by-period loan breakdown
+    attr_reader :schedule
 
     # @return [Flt::DecNum] the periodic payment due on a loan
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
@@ -43,21 +90,22 @@ module Finrb
     #   rate.duration #=> 360
     #   Amortization.payment(200000, rate.monthly, rate.duration) #=> Flt::DecNum('-926.23')
     # @see https://en.wikipedia.org/wiki/Amortization_calculator
-    # @api public
-    def self.payment(principal, rate, periods)
-      principal = Validation.decimal(principal, name: 'principal')
-      raise(ArgumentError, 'principal must be positive.') unless principal.positive?
+    def self.payment(principal, rate, periods, balloon: 0)
+      principal = Validation.positive_decimal(principal, name: 'principal', message: 'principal must be positive.')
 
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(ArgumentError, 'periodic rate must be greater than -1.') if rate <= -1
+      balloon = Validation.decimal(balloon, name: 'balloon')
+      raise(ArgumentError, 'balloon must be non-negative and no greater than principal.') unless balloon.between?(0, principal)
 
-      periods = Validation.positive_integer(periods, name: 'periods')
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'periodic rate')
+
+      periods = Validation.positive_integer(periods, name: 'period count')
 
       if rate.zero?
         # simplified formula to avoid division-by-zero when interest rate is zero
-        -Precision.money(principal / periods)
+        -Precision.money((principal - balloon) / periods)
       else
-        -Precision.money(principal * (rate + (rate / (((rate + 1)**periods) - 1))))
+        growth = (rate + 1)**periods
+        -Precision.money(((principal * growth) - balloon) * rate / (growth - 1))
       end
     end
 
@@ -66,10 +114,19 @@ module Finrb
     # @param [Flt::DecNum] principal the initial amount of the loan or investment
     # @param [Rate] rates the applicable interest rates
     # @param [Proc] block
-    # @api public
-    def initialize(principal, *rates, &block)
-      @principal = Validation.decimal(principal, name: 'principal')
-      raise(ArgumentError, 'principal must be positive.') unless @principal.positive?
+    def initialize(principal, *rates, balloon: 0, interest_only_periods: 0, origination_fee: 0, finance_origination_fee: false, &block)
+      @principal = Validation.positive_decimal(principal, name: 'principal', message: 'principal must be positive.')
+
+      @origination_fee = Validation.non_negative_decimal(origination_fee, name: 'origination fee')
+      raise(ArgumentError, 'finance_origination_fee must be true or false.') unless [true, false].include?(finance_origination_fee)
+      raise(ArgumentError, 'an unfinanced origination_fee must be less than principal.') if !finance_origination_fee && @origination_fee >= @principal
+
+      @finance_origination_fee = finance_origination_fee
+      @amount_financed = @principal + (finance_origination_fee ? @origination_fee : 0)
+      @net_proceeds = @principal - (finance_origination_fee ? 0 : @origination_fee)
+
+      @balloon = Validation.decimal(balloon, name: 'balloon')
+      raise(ArgumentError, 'balloon must be non-negative and less than amount financed.') if @balloon.negative? || @balloon >= @amount_financed
       raise(ArgumentError, 'at least one rate is required.') if rates.empty?
       raise(ArgumentError, 'rates must be Finrb::Rate instances.') unless rates.all?(Rate)
       raise(ArgumentError, 'every rate must have a duration.') if rates.any? { |rate| rate.duration.nil? }
@@ -79,7 +136,11 @@ module Finrb
 
       # compute the total duration from all of the rates.
       @periods = rates.sum(&:duration)
-      @period  = 0
+      valid_interest_only = interest_only_periods.is_a?(Integer) && interest_only_periods.between?(0, @periods - 1)
+      raise(ArgumentError, 'interest_only_periods must be a non-negative integer shorter than the loan term.') unless valid_interest_only
+
+      @interest_only_periods = interest_only_periods
+      @period = 0
 
       compute
     end
@@ -87,17 +148,18 @@ module Finrb
     # compare two Amortization instances
     # @return [Numeric] -1, 0, or +1
     # @param [Amortization] other
-    # @api public
     def ==(other)
-      (principal == other.principal) && (rates == other.rates) && (payments == other.payments)
+      (principal == other.principal) && (origination_fee == other.origination_fee) && (finance_origination_fee? == other.finance_origination_fee?) && (balloon == other.balloon) && (interest_only_periods == other.interest_only_periods) && (rates == other.rates) && (payments == other.payments)
     end
 
+    attr_reader :finance_origination_fee
+    alias finance_origination_fee? finance_origination_fee
+
     # @return [Array] the amount of any additional payments in each period
     # @example
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate){ |payment| payment.amount-100}
     #   amt.additional_payments #=> [Flt::DecNum('-100.00'), Flt::DecNum('-100.00'), ... ]
-    # @api public
     def additional_payments
       @transactions.filter_map { |trans| trans.difference if trans.payment? }
     end
@@ -105,32 +167,29 @@ module Finrb
     # amortize the balance of loan with the given interest rate
     # @return none
     # @param [Rate] rate the interest rate to use in the amortization
-    # @api private
     def amortize(rate)
-      # For the purposes of calculating a payment, the relevant time
-      # period is the remaining number of periods in the loan, not
-      # necessarily the duration of the rate itself.
-      periods = @periods - @period
-      amount = Amortization.payment(@balance, rate.monthly, periods)
-
-      pmt = Payment.new(amount, period: @period)
-      pmt.modify(&@block) if @block
-      raise(ArgumentError, 'payment modification must produce a negative amount.') unless pmt.amount.negative?
+      regular_payment = nil
 
       rate.duration.to_i.times do
         # Do this first in case the balance is zero already.
         break if @balance.zero?
 
+        interest_only = @period < @interest_only_periods
+        regular_payment ||= build_regular_payment(rate) unless interest_only
+
         # Compute and record interest on the outstanding balance.
         int = Precision.money(@balance * rate.monthly)
         interest = Interest.new(int, period: @period)
         @balance += interest.amount
         @transactions << interest.dup
 
-        # Record payment.  Don't pay more than the outstanding balance.
-        pmt.amount = -@balance if pmt.amount.abs > @balance
-        @transactions << pmt.dup
-        @balance += pmt.amount
+        payment = interest_only ? build_interest_only_payment(int) : regular_payment
+        payment.period = @period
+        payment.amount = -@balance if payment.amount.abs > @balance
+        @additional_by_period << [-payment.difference, Flt::DecNum(0)].max
+        @interest_only_by_period << interest_only
+        @transactions << payment.dup
+        @balance += payment.amount
 
         @period += 1
       end
@@ -138,26 +197,35 @@ module Finrb
 
     # compute the amortization of the principal
     # @return none
-    # @api private
     def compute
-      @balance = @principal
+      @balance = @amount_financed
       @transactions = []
+      @additional_by_period = []
+      @interest_only_by_period = []
 
       @rates.each do |rate|
         amortize(rate)
       end
 
-      # Add any remaining balance due to rounding error to the last payment.
+      # Add the residual balloon and any rounding remainder to the last payment.
+      @balloon_by_period = Array.new(@additional_by_period.length, Flt::DecNum(0))
       if @balance.nonzero?
+        @balloon_by_period[-1] = [@balloon, @balance].min
         @transactions.reverse.find(&:payment?).amount -= @balance
         @balance = 0
       end
 
-      @payment = (payments.first if @rates.length == 1)
+      @payment = (payments.first if @rates.length == 1 && @interest_only_periods.zero?)
 
       @transactions.freeze
+      @additional_by_period.freeze
+      @balloon_by_period.freeze
+      @interest_only_by_period.freeze
+      @schedule = build_schedule.freeze
     end
 
+    private :amortize, :compute
+
     # @return [Integer] the time required to pay off the loan, in months
     # @example In most cases, the duration is equal to the total duration of all rates
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
@@ -167,12 +235,10 @@ module Finrb
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate){ |payment| payment.amount-100}
     #   amt.duration #=> 319
-    # @api public
     def duration
       payments.length
     end
 
-    # @api public
     def inspect
       "Amortization.new(#{@principal})"
     end
@@ -186,7 +252,6 @@ module Finrb
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.interest[0,6].sum #=> Flt::DecNum('5603.74')
-    # @api public
     def interest
       @transactions.filter_map { |trans| trans.amount if trans.interest? }
     end
@@ -196,9 +261,45 @@ module Finrb
     #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
     #   amt = Finrb::Amortization.new(300000, rate)
     #   amt.payments.sum #=> Flt::DecNum('-500163.94')
-    # @api public
     def payments
       @transactions.filter_map { |trans| trans.amount if trans.payment? }
     end
+
+    private
+
+    def build_schedule
+      opening_balance = @amount_financed
+      @transactions.each_slice(2).with_index.map do |(interest, payment), index|
+        principal = -(payment.amount + interest.amount)
+        closing_balance = opening_balance - principal
+        entry = Entry.new(period: payment.period, opening_balance:, payment: payment.amount, interest: interest.amount, principal:, additional_payment: @additional_by_period.fetch(index), balloon_payment: @balloon_by_period.fetch(index), interest_only: @interest_only_by_period.fetch(index), closing_balance:)
+        opening_balance = closing_balance
+        entry
+      end
+    end
+
+    def build_regular_payment(rate)
+      periods = @periods - @period
+      amount = Amortization.payment(@balance, rate.monthly, periods, balloon: @balloon)
+      Payment.new(amount, period: @period).tap do |payment|
+        payment.modify(&@block) if @block
+        validate_payment!(payment)
+      end
+    end
+
+    def build_interest_only_payment(interest)
+      Payment.new(-interest, period: @period).tap do |payment|
+        payment.modify(&@block) if @block
+        validate_payment!(payment, allow_zero: true)
+      end
+    end
+
+    def validate_payment!(payment, allow_zero: false)
+      valid = payment.amount.negative? || (allow_zero && payment.amount.zero?)
+      return if valid
+
+      requirement = allow_zero ? 'must not produce a positive amount' : 'must produce a negative amount'
+      raise(ArgumentError, "payment modification #{requirement}.")
+    end
   end
 end

data/lib/finrb/cashflows.rb

@@ -12,7 +12,6 @@ require 'date'
 
 module Finrb
   # Provides methods for working with cash flows (collections of transactions)
-  # @api public
   module Cashflow
     class << self
       def irr(cashflows, guess = nil)
@@ -23,6 +22,10 @@ module Finrb
         sequence(cashflows).npv(rate)
       end
 
+      def mirr(cashflows, finance_rate:, reinvestment_rate:)
+        sequence(cashflows).mirr(finance_rate:, reinvestment_rate:)
+      end
+
       def xirr(transactions, guess = nil)
         sequence(transactions).xirr(guess)
       end
@@ -55,7 +58,6 @@ module Finrb
     # @example
     #   Finrb::Cashflow.irr([-4000,1200,1410,1875,1050]) #=> 0.143
     # @see https://en.wikipedia.org/wiki/Internal_rate_of_return
-    # @api public
     def irr(guess = nil)
       validate_numeric_cashflows!
 
@@ -71,13 +73,11 @@ module Finrb
     # @example
     #   Finrb::Cashflow.npv([-100.0, 60, 60, 60], 0.1) #=> 49.211
     # @see https://en.wikipedia.org/wiki/Net_present_value
-    # @api public
     def npv(rate)
       validate_numeric_cashflows!
       cashflows = map { |entry| Validation.decimal(entry, name: 'cashflow amount') }
 
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(DomainError, 'Rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'rate', error: DomainError)
 
       total = Flt::DecNum.new(0.to_s)
       cashflows.each_with_index do |cashflow, index|
@@ -87,6 +87,32 @@ module Finrb
       total
     end
 
+    # Calculate the modified internal rate of return for equally spaced
+    # cashflows using separate financing and reinvestment assumptions.
+    # @return [Flt::DecNum] modified per-period internal rate of return
+    def mirr(finance_rate:, reinvestment_rate:)
+      validate_numeric_cashflows!
+      raise(InvalidCashflowError, 'MIRR requires at least two cashflows.') if size < 2
+
+      cashflows = map { |entry| Validation.decimal(entry, name: 'cashflow amount') }
+      raise(InvalidCashflowError, 'Cashflow needs at least one positive and one negative value.') if cashflows.none?(&:positive?) || cashflows.none?(&:negative?)
+
+      finance_rate = Validation.decimal_greater_than(finance_rate, minimum: -1, name: 'finance rate', error: DomainError)
+      reinvestment_rate = Validation.decimal_greater_than(reinvestment_rate, minimum: -1, name: 'reinvestment rate', error: DomainError)
+
+      last_period = cashflows.size - 1
+      future_positive =
+        cashflows.each_with_index.sum do |amount, index|
+          amount.positive? ? amount * ((reinvestment_rate + 1)**(last_period - index)) : Flt::DecNum(0)
+        end
+      present_negative =
+        cashflows.each_with_index.sum do |amount, index|
+          amount.negative? ? amount / ((finance_rate + 1)**index) : Flt::DecNum(0)
+        end
+
+      ((future_positive / -present_negative)**(Flt::DecNum(1) / last_period)) - 1
+    end
+
     # Calculate the effective annual internal rate of return for an ordered
     # sequence of dated transactions.
     #
@@ -108,7 +134,6 @@ module Finrb
     #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
     #   Finrb::Cashflow.xirr(@transactions, 0.6) #=> Rate("0.024851", :effective, :compounds => :annually)
-    # @api public
     def xirr(guess = nil)
       validate_dated_cashflows!
 
@@ -127,11 +152,9 @@ module Finrb
     #   @transactions << Transaction.new(  600, :date => Time.new(1990,01,01))
     #   @transactions << Transaction.new(  600, :date => Time.new(1995,01,01))
     #   Finrb::Cashflow.xnpv(@transactions, 0.6).round(2) #=> -937.41
-    # @api public
     def xnpv(rate)
       validate_dated_cashflows!
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(DomainError, 'Rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'rate', error: DomainError)
 
       sum do |t|
         t.amount / ((rate + 1)**(date_diff(start, t.date) / days_in_period))

data/lib/finrb/config.rb

@@ -41,16 +41,16 @@ module Finrb
   end
 
   def self.build_configuration(values)
-    eps = configuration_decimal(values.fetch(:eps), name: 'eps')
-    raise(ArgumentError, 'eps must be positive.') unless eps.positive?
+    eps = configuration_decimal(values.fetch(:eps), name: 'solver tolerance')
+    raise(ArgumentError, 'solver tolerance must be positive.') unless eps.positive?
 
-    guess = configuration_decimal(values.fetch(:guess), name: 'guess')
-    raise(ArgumentError, 'guess must be greater than -1.') if guess <= -1
+    guess = configuration_decimal(values.fetch(:guess), name: 'rate guess')
+    raise(ArgumentError, 'rate guess must be greater than -1.') if guess <= -1
 
     business_days = values.fetch(:business_days)
     periodic_compound = values.fetch(:periodic_compound)
     booleans = [business_days, periodic_compound].all? { |value| value.equal?(true) || value.equal?(false) }
-    raise(ArgumentError, 'business_days and periodic_compound must be boolean.') unless booleans
+    raise(ArgumentError, 'business days and periodic compounding settings must be boolean.') unless booleans
 
     Configuration.new(eps:, guess:, business_days:, periodic_compound:)
   end

data/lib/finrb/rates.rb

@@ -6,7 +6,6 @@ require_relative 'validation'
 module Finrb
   # the Rate class provides an interface for working with interest rates.
   # {render:Rate#new}
-  # @api public
   class Rate
     include Comparable
 
@@ -18,10 +17,7 @@ module Finrb
       infinite = value.infinite? if value.respond_to?(:infinite?)
       return Flt::DecNum.infinity if [true, 1].include?(infinite)
 
-      periods = Validation.decimal(value, name: 'compounding periods')
-      raise(ArgumentError, 'compounding periods must be positive.') unless periods.positive?
-
-      periods
+      Validation.positive_decimal(value, name: 'compounding periods', message: 'compounding periods must be positive.')
     end
     private_class_method :compounding_periods
 
@@ -31,7 +27,6 @@ module Finrb
     # @param [Numeric] periods the number of compounding periods per year
     # @example
     #   Rate.to_effective(0.05, 4) #=> Flt::DecNum('0.05095')
-    # @api public
     def self.to_effective(rate, periods)
       rate = Validation.decimal(rate, name: 'rate')
       periods = compounding_periods(periods)
@@ -50,10 +45,8 @@ module Finrb
     # @example
     #   Rate.to_nominal(0.06, 365) #=> Flt::DecNum('0.05827')
     # @see https://www.miniwebtool.com/nominal-interest-rate-calculator/
-    # @api public
     def self.to_nominal(rate, periods)
-      rate = Validation.decimal(rate, name: 'rate')
-      raise(ArgumentError, 'effective rate must be greater than -1.') if rate <= -1
+      rate = Validation.decimal_greater_than(rate, minimum: -1, name: 'effective rate')
 
       periods = compounding_periods(periods)
 
@@ -75,7 +68,6 @@ module Finrb
     #   Rate.new(0.035, :apr) #=> Rate(0.035, :apr)
     # @see https://en.wikipedia.org/wiki/Effective_interest_rate
     # @see https://en.wikipedia.org/wiki/Nominal_interest_rate
-    # @api public
     def initialize(rate, type, opts = {})
       raise(ArgumentError, 'options must be a Hash.') unless opts.is_a?(Hash)
       raise(ArgumentError, 'options may only contain compounds and duration.') unless (opts.keys - %i[compounds duration]).empty?
@@ -97,13 +89,10 @@ module Finrb
     end
 
     # @return [Integer] the duration for which the rate is valid, in months
-    # @api public
     attr_reader :duration
     # @return [Flt::DecNum] the effective interest rate
-    # @api public
     attr_reader :effective
     # @return [Flt::DecNum] the nominal interest rate
-    # @api public
     attr_reader :nominal
 
     # compare two Rates, using the effective rate
@@ -113,21 +102,18 @@ module Finrb
     #   r1 = Rate.new(0.15, :nominal) #=> Rate.new(0.160755, :apr)
     #   r2 = Rate.new(0.155, :nominal, :compounds => :semiannually) #=> Rate.new(0.161006, :apr)
     #   r1 <=> r2 #=> -1
-    # @api public
     def <=>(other)
       @effective <=> other.effective
     end
 
     # Return the nominal annual percentage rate for the configured compounding frequency.
     # @return [Flt::DecNum] the nominal annual percentage rate
-    # @api public
     def apr
       nominal
     end
 
     # Return the effective annual percentage yield.
     # @return [Flt::DecNum] the effective annual percentage yield
-    # @api public
     def apy
       effective
     end
@@ -136,7 +122,6 @@ module Finrb
     # @return none
     # @param [Symbol, Numeric] input the compounding frequency
     # @raise [ArgumentError] if input is not an accepted keyword or Numeric
-    # @api private
     def compounds=(input)
       @periods =
         case input
@@ -152,13 +137,12 @@ module Finrb
     end
 
     def duration=(value)
-      @duration = Validation.positive_integer(value, name: 'duration')
+      @duration = Validation.positive_integer(value, name: 'duration in months')
     end
 
     # set the effective interest rate
     # @return none
     # @param [Flt::DecNum] rate the effective interest rate
-    # @api private
     def effective=(rate)
       raise(ArgumentError, 'effective rate must be greater than -1.') if rate <= -1
 
@@ -176,7 +160,6 @@ module Finrb
     #   rate.apr.round(6) #=> Flt::DecNum('0.15')
     #   rate.apy.round(6) #=> Flt::DecNum('0.160755')
     #   rate.monthly.round(6) #=> Flt::DecNum('0.0125')
-    # @api public
     def monthly
       @monthly ||= Precision.rate(Rate.to_nominal(effective, 12) / 12)
     end
@@ -184,7 +167,6 @@ module Finrb
     # set the nominal interest rate
     # @return none
     # @param [Flt::DecNum] rate the nominal interest rate
-    # @api private
     def nominal=(rate)
       raise(ArgumentError, 'nominal rate must keep every compounded period greater than -100%.') if !@periods.infinite? && rate <= -@periods