finance_velocity 2.0.3

data/COPYING.LESSER

@@ -0,0 +1,167 @@
+# @title COPYING.LESSER
+# @markup none
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/HISTORY

@@ -0,0 +1,47 @@
+= Version 2.0.0
+23 Jul 2013
+
+* Removed Integer#months, Integer#years, and replaced Numeric#to_d by Numeric#to_s in the interest of Rails compatibility.
+* Converted unit tests from the shoulda framework to minitest.
+* Removed octal numbers in test_cashflow.rb
+* Thanks to @thadd, @bramswenson, and @xpe for their contributions to this release!
+
+= Version 1.1.2
+16 Jun 2012
+
+* Bugfix: Array#irr and Array#xirr check for a valid sequence of cash flows.
+* Bugfix: Integer#months and Integer#years no longer collide with Rails methods.
+
+= Version 1.1.0
+11 Sep 2011
+
+* Added XNPV and XIRR functions, with basic testing.
+* Bugfix: Array#sum no longer collides with the Array#sum defined in Rails.
+* Bugfix: Numeric#amortize now correctly calls Finance::Amortization#new.
+
+= Version 1.0.0 
+20 Jul 2011
+
+* Moved to Ruby 1.9.
+* All classes are now contained within the +Finance+ namespace.  
+* LOTS of additional documentation and examples.
+* Introduced _shoulda_ for unit tests, to make things a little more readable.
+* Bugfix: The +amortize+ Numeric method now accepts a variable number of rates.
+* Some code refactoring and clean-up for a small performance increase.
+
+= Version 0.2.0
+28 Jun 2011
+
+* Added support for adjustable rate mortgages.
+* Added support for additional payments.
+
+= Version 0.1.1
+21 Jun 2011
+
+* Code examples in README now display correctly in the online documentation.
+
+= Version 0.1.0
+21 Jun 2011
+
+* Support for fixed-rate mortgage amortization.
+* NPV, IRR array methods for cash flow analysis.

data/README.md

@@ -0,0 +1,166 @@
+# FINANCE
+
+a library for financial modelling in Ruby.
+
+## INSTALL
+
+    $ sudo gem install finance
+
+## IMPORTANT CHANGES
+
+Contributions by [@thadd](https://github.com/thadd) and
+[@bramswenson](https://github.com/bramswenson) have made the `finance`
+library fully compatible with rails, at the cost of the `#years` and
+`#months` convenience methods on `Integer`, as well as the `#to_d` method for
+converting `Numerics` into `DecNums`.  These methods have been removed, due to
+conflicts with existing rails methods.
+
+Correspondingly, `finance` has been bumped up to version 2.0.
+
+## OVERVIEW
+
+### GETTING STARTED
+
+    >> require 'finance'
+
+*Note:* As of version 1.0.0, the entire library is contained under the
+Finance namespace.  Existing code will not work unless you add:
+
+    >> include Finance
+
+for all of the examples below, we'll assume that you have done this.
+
+### AMORTIZATION
+
+You are interested in borrowing $250,000 under a 30 year, fixed-rate
+loan with a 4.25% APR.
+
+    >> rate = Rate.new(0.0425, :apr, :duration => (30 * 12))
+    >> amortization = Amortization.new(250000, rate)
+
+Find the standard monthly payment:
+
+    >> amortization.payment
+    => DecNum('-1229.91')
+
+Find the total cost of the loan:
+
+    >> amortization.payments.sum
+    => DecNum('-442766.55')
+
+How much will you pay in interest?
+
+    >> amortization.interest.sum
+    => DecNum('192766.55')
+
+How much interest in the first six months?
+
+    >> amortization.interest[0,6].sum
+    => DecNum('5294.62')
+
+If your loan has an adjustable rate, no problem.  You can pass an
+arbitrary number of rates, and they will be used in the amortization.
+For example, we can look at an amortization of $250000, where the APR
+starts at 4.25%, and increases by 1% every five years.
+
+    >> values = %w{ 0.0425 0.0525 0.0625 0.0725 0.0825 0.0925 }
+    >> rates = values.collect { |value| Rate.new( value, :apr, :duration => (5  * 12) }
+    >> arm = Amortization.new(250000, *rates)
+
+Since we are looking at an ARM, there is no longer a single "payment" value.
+
+    >> arm.payment
+    => nil
+
+But we can look at the different payments over time.
+
+    >> arm.payments.uniq
+    => [DecNum('-1229.85'), DecNum('-1360.41'), DecNum('-1475.65'), DecNum('-1571.07'), ... snipped ... ]
+
+The other methods previously discussed can be accessed in the same way:
+
+    >> arm.interest.sum
+    => DecNum('287515.45')
+    >> arm.payments.sum
+    => DecNum('-537515.45')
+
+Last, but not least, you may pass a block when creating an Amortization
+which returns a modified monthly payment.  For example, to increase your
+payment by $150, do:
+
+    >> rate = Rate.new(0.0425, :apr, :duration => (30 * 12))
+    >> extra_payments = 250000.amortize(rate){ |period| period.payment - 150 }
+
+Disregarding the block, we have used the same parameters as the first
+example.  Notice the difference in the results:
+
+    >> amortization.payments.sum
+    => DecNum('-442745.98')
+    >> extra_payments.payments.sum
+    => DecNum('-400566.24')
+    >> amortization.interest.sum
+    => DecNum('192745.98')
+    >> extra_payments.interest.sum
+    => DecNum('150566.24')
+
+You can also increase your payment to a specific amount:
+
+    >> extra_payments_2 = 250000.amortize(rate){ -1500 }
+
+## ABOUT
+
+I started developing `finance` while analyzing mortgages as a personal
+project.  Spreadsheets have convenient formulas for doing this type of
+work, until you want to do something semi-complex (like ARMs or extra
+payments), at which point you need to create your own amortization
+table.  I thought I could create a better interface for this type of
+work in Ruby, and since I couldn't find an existing resource for these
+tools, I am hoping to save other folks some time by releasing what I
+have as a gem.
+
+More broadly, I believe there are many calculations that are necessary
+for the effective management of personal finances, but are difficult
+(or impossible) to do with spreadsheets or other existing open source
+tools.  My hope is that the `finance` library will grow to provide a set
+of open, tested tools to fill this gap.
+
+If you have used `finance` and find it useful, I would enjoy hearing
+about it!
+
+## FEATURES
+
+Currently implemented features include:
+
+* Uses the [flt](http://flt.rubyforge.org/) library 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?)
+
+## RESOURCES
+
+* [RubyGems Page](https://rubygems.org/gems/finance)
+* [Source Code](http://github.com/wkranec/finance)
+* [Bug Tracker](https://github.com/wkranec/finance/issues)
+* [Google Group](http://groups.google.com/group/finance-gem/topics?pli=1)
+
+## COPYRIGHT
+
+This library is released under the terms of the LGPL license.
+
+Copyright (c) 2011, William Kranec.
+All rights reserved.
+
+This program is free software: you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published by the
+Free Software Foundation, either version 3 of the License, or (at your
+option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License along
+with this program.  If not, see <http://www.gnu.org/licenses/>.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/testtask'
+
+task :default => [:test_units]
+
+Rake::TestTask.new("test_units") do |t|
+  t.pattern = 'test/*.rb'
+  t.verbose = true
+  t.warning = true
+end

data/finance.gemspec

@@ -0,0 +1,19 @@
+SPEC = Gem::Specification.new do |s|
+  s.name = "finance_velocity"
+  s.version = "2.0.3"
+  s.author = "Mani Bhushan"
+  s.license = "LGPL-3.0"
+  s.email = "manilnct@gmail.com"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "a library for financial modelling in Ruby."
+  s.description = "The finance library provides a Ruby interface for working with interest rates, mortgage amortization, and cashflows (NPV, IRR, etc.)."
+  s.homepage = "https://rubygems.org/gems/finance"
+
+  s.required_ruby_version = '>=1.9'
+  s.add_runtime_dependency 'flt', '~> 1.3', '>= 1.3.0'
+  s.add_development_dependency 'minitest', '~> 4.7', '>= 4.7.5'
+  s.add_development_dependency 'activesupport', '~> 4.0', '>= 4.0.0'
+  s.files = `git ls-files`.split("\n")
+
+  s.extra_rdoc_files = ['README.md', 'COPYING', 'COPYING.LESSER', 'HISTORY']
+end

data/lib/finance/amortization.rb

@@ -0,0 +1,201 @@
+require_relative 'cashflows'
+require_relative 'decimal'
+require_relative 'transaction'
+
+module Finance
+  # the Amortization class provides an interface for working with loan amortizations.
+  # @note There are _two_ ways to create an amortization.  The first
+  #   example uses the amortize method for the Numeric class.  The second
+  #   calls Amortization.new directly.
+  # @example Borrow $250,000 under a 30 year, fixed-rate loan with a 4.25% APR
+  #   rate = Rate.new(0.0425, :apr, :duration => (30 * 12))
+  #   amortization = 250000.amortize(rate)
+  # @example Borrow $250,000 under a 30 year, adjustable rate loan, with an APR starting at 4.25%, and increasing by 1% every five years
+  #   values = %w{ 0.0425 0.0525 0.0625 0.0725 0.0825 0.0925 }
+  #   rates = values.collect { |value| Rate.new( value, :apr, :duration = (5 * 12) ) }
+  #   arm = Amortization.new(250000, *rates)
+  # @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 = 250000.amortize(rate){ |period| period.payment - 150 }
+  # @api public
+  class Amortization
+    # @return [DecNum] the balance of the loan at the end of the amortization period (usually zero)
+    # @api public
+    attr_reader :balance
+    # @return [DecNum] the required monthly payment.  For loans with more than one rate, returns nil
+    # @api public
+    attr_reader :payment
+    # @return [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
+
+    # compare two Amortization instances
+    # @return [Numeric] -1, 0, or +1
+    # @param [Amortization]
+    # @api public
+    def ==(amortization)
+      self.principal == amortization.principal and self.rates == amortization.rates and self.payments == amortization.payments
+    end
+
+    # @return [Array] the amount of any additional payments in each period
+    # @example
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
+    #   amt.additional_payments #=> [DecNum('-100.00'), DecNum('-100.00'), ... ]
+    # @api public
+    def additional_payments
+      @transactions.find_all(&:payment?).collect{ |p| p.difference }
+    end
+
+    # 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)
+      if @block then pmt.modify(&@block) end
+
+      rate.duration.to_i.times do
+        # Do this first in case the balance is zero already.
+        if @balance.zero? then break end
+
+        # Compute and record interest on the outstanding balance.
+        int = (@balance * rate.monthly).round(2)
+        interest = Interest.new(int, :period => @period)
+        @balance += interest.amount
+        @transactions << interest.dup
+
+        # Record payment.  Don't pay more than the outstanding balance.
+        if pmt.amount.abs > @balance then pmt.amount = -@balance end
+        @transactions << pmt.dup
+        @balance += pmt.amount
+
+        @period += 1
+      end
+    end
+
+    # compute the amortization of the principal
+    # @return none
+    # @api private
+    def compute
+      @balance = @principal
+      @transactions = []
+
+      @rates.each do |rate|
+        amortize(rate)
+      end
+
+      # Add any remaining balance due to rounding error to the last payment.
+      unless @balance.zero?
+        @transactions.find_all(&:payment?)[-1].amount -= @balance
+        @balance = 0
+      end
+
+      if @rates.length == 1
+        @payment = self.payments[0]
+      else
+        @payment = nil
+      end
+
+      @transactions.freeze
+    end
+
+    # @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))
+    #   amt = 300000.amortize(rate)
+    #   amt.duration #=> 360
+    # @example Extra payments may reduce the duration
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   amt = 300000.amortize(rate){ |payment| payment.amount-100}
+    #   amt.duration #=> 319
+    # @api public
+    def duration
+      self.payments.length
+    end
+
+    # create a new Amortization instance
+    # @return [Amortization]
+    # @param [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 = Flt::DecNum.new(principal.to_s)
+      @rates     = rates
+      @block     = block
+
+      # compute the total duration from all of the rates.
+      @periods = (rates.collect { |r| r.duration }).sum
+      @period  = 0
+
+      compute
+    end
+
+    # @api public
+    def inspect
+      "Amortization.new(#{@principal})"
+    end
+
+    # @return [Array] the amount of interest charged in each period
+    # @example find the total cost of interest for a loan
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   amt = 300000.amortize(rate)
+    #   amt.interest.sum #=> DecNum('200163.94')
+    # @example find the total interest charges in the first six months
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   amt = 300000.amortize(rate)
+    #   amt.interest[0,6].sum #=> DecNum('5603.74')
+    # @api public
+    def interest
+      @transactions.find_all(&:interest?).collect{ |p| p.amount }
+    end
+
+    # @return [DecNum] the periodic payment due on a loan
+    # @param [DecNum] principal the initial amount of the loan or investment
+    # @param [Rate] rate the applicable interest rate (per period)
+    # @param [Integer] periods the number of periods needed for repayment
+    # @note in most cases, you will probably want to use rate.monthly when calling this function outside of an Amortization instance.
+    # @example
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   rate.duration #=> 360
+    #   Amortization.payment(200000, rate.monthly, rate.duration) #=> DecNum('-926.23')
+    # @see http://en.wikipedia.org/wiki/Amortization_calculator
+    # @api public
+    def Amortization.payment(principal, rate, periods)
+      if rate.zero?
+        # simplified formula to avoid division-by-zero when interest rate is zero
+        return -(principal / periods).round(2)
+      else
+        return -(principal * (rate + (rate / ((1 + rate) ** periods - 1)))).round(2)
+      end
+    end
+
+    # @return [Array] the amount of the payment in each period
+    # @example find the total payments for a loan
+    #   rate = Rate.new(0.0375, :apr, :duration => (30 * 12))
+    #   amt = 300000.amortize(rate)
+    #   amt.payments.sum #=> DecNum('-500163.94')
+    # @api public
+    def payments
+      @transactions.find_all(&:payment?).collect{ |p| p.amount }
+    end
+  end
+end
+
+class Numeric
+  # @see Amortization#new
+  # @api public
+  def amortize(*rates, &block)
+    Finance::Amortization.new(self, *rates, &block)
+  end
+end