finance_math 0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cbdffc4856090cc7d1e509ba4e9d0489017a7e44
-  data.tar.gz: 577779f78950688be481d7446c4fda4135f4e027
+  metadata.gz: d9b7d65feab360a3535bf1578c17326c237249e6
+  data.tar.gz: 591d90ccad4311cf1fa67a5479b1a3b7995c1ca6
 SHA512:
-  metadata.gz: 6c12c0a09ab26a16c7e8a7ef3bfa2b7964e3a284f1b371607fe7552dfc0fd90230c2b911cff9c3956534fd7ce7993b4012c820ccb03bed40d2617fd73814e26e
-  data.tar.gz: d31f8f44e884db52c0ac328391fdf9eadcc36f33222bdab02352b079441b16186b616c0c277db5abd7027f5b2a5496ac44e2afece6741294ae13930fbd1eb2d6
+  metadata.gz: 9645d21dd559a86f61f55f417f1ae640581b4a96c0a99f0a75966e527612ba74a33824fc1fbc1b12194486da5d4147069367ff3025bb3287323ec32d759e73db
+  data.tar.gz: 3db071b7b84bd12b44fba98cbce71c97ffcca778e707839d0f1b671ea29a8591e88acc6103a7627ae89c9dd7384ff0a6facaa3b4a86105b0912a4d857add5310

data/README.md

@@ -1,11 +1,11 @@
-![Gem Version](https://img.shields.io/badge/finance_math-0.2-blue.svg)
+![Gem Version](https://img.shields.io/badge/finance_math-1.0-blue.svg)
 [![Build Status](https://semaphoreapp.com/api/v1/projects/869d7630-55d3-46e5-9dc2-03d0d1cfecfe/363108/shields_badge.svg)](https://semaphoreapp.com/kolosek/finance_math)
 [![Code Climate](https://codeclimate.com/github/kolosek/finance_math/badges/gpa.svg)](https://codeclimate.com/github/kolosek/finance_math)
 
 
 ## What is FinanceMath?
 
-FinanceMath is a Ruby library for mapping Exel functions. Due to lack such libraries to handle every day need, this library is created.
+FinanceMath is a Ruby library for mapping Loan based Exel functions. It deals with problem of calculating the PMT and APR functions. It implements advanced usage, taking into account bank fees, fee for for each payment and currency protection (if currency other than $ USD). Highly precise with high speed of execution. 
 
 ## Installation
 
@@ -28,29 +28,47 @@ Create an instance, and pass parameters for nominal annual rate, duration (in mo
 Loan.new(10.5, 12, 15000)
 ```
 
+## Advanced Usage
+
+Create an instance, and pass parameters for nominal annual rate, duration (in months), and amount of loan, and additional values such as bank fee, currency protection, and fee for each monthly payment. 
+
+Defaults are bank fee = 5, currency protection = 3, so please update if you need other values.
+
+```ruby
+
+Loan.new(10.5, 12, 15000, 5.1, 2.75, 25)
+```
+
 ## Functions 
 
 This is the list of available functions.
 
-## PMT
+### Loan.pmt
 
 Calculates the periodic payment for an annuity investment based on constant-amount periodic payments and a constant interest rate.
 
 ```ruby
 
-loan = Loan.new(10.5, 12, 15000)
+loan = Loan.new(10, 12, 1000)
 loan.pmt
+# 87.9158872300099
+
 ```
 
-## APR
+### Loan.apr
 
 Calculates the Annual Percentage Rate.
 
 ```ruby
 
-loan = Loan.new(10.5, 12, 15000)
+loan = Loan.new(13, 12, 10000)
+loan.apr
+#29.179538647635006
 
+loan = Loan.new(15, 36, 10000, 5, 3, 10)
 loan.apr
+#23.964418264624054
+
 ```
 
 ## Contributing
@@ -65,12 +83,13 @@ loan.apr
 
 Please cover with tests your pull requests
 
-## License
-
-MIT License. See LICENSE for details.
-
 ## Copyright
 
 Copyright (c) 2014-2015 Nebojsa Zoric, and Kolosek, Inc. (http://kolosek.com)
 
-For any Ruby on Rails related work, please contact directly via form on http://kolosek.com
+###Follow up @nebojsaz and @kolosek
+
+
+## License
+
+MIT License. See LICENSE for details.

data/finance_math.gemspec

@@ -1,16 +1,16 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'finance_math/version'
+require 'version'
 
 Gem::Specification.new do |spec|
   spec.name          = "finance_math"
   spec.version       = FinanceMath::VERSION
   spec.authors       = ["Nebojsa Zoric"]
   spec.email         = ["office@kolosek.com"]
-  spec.summary       = %q{Finance library for Ruby.}
-  spec.description   = %q{Implementation of Loan/Mortgage functions in Ruby language}
-  spec.homepage      = ""
+  spec.summary       = %q{Finance and mortgage library for Ruby.}
+  spec.description   = %q{Implementation of Loan/Mortgage functions in Ruby language. APR function and PMT function. In calculations it includes implementation of bank fee, marketplace fee, fees for each payment to provide the most precise calculation at very high speed. }
+  spec.homepage      = "http://kolosek.com/gems/finance_math"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/finance_math.rb

@@ -1,5 +1,6 @@
-require "finance_math/version"
+require "version"
 
 module FinanceMath
-  autoload :Loan,         'finance_math/loan'
+  autoload :Loan,             'finance_math/loan'
+  autoload :Mortgage,         'finance_math/mortgage'
 end

data/lib/finance_math/loan.rb

@@ -28,9 +28,11 @@ module FinanceMath
 
     # @return [DecNum] P principal
     # @api public
-    attr_reader :principal    
-
+    attr_reader :principal
 
+    # @return [Float] fee
+    # @api public
+    attr_reader :fee
 
     # create a new Loan instance
     # @return [Loan]
@@ -44,8 +46,8 @@ module FinanceMath
     # @see http://en.wikipedia.org/wiki/Nominal_interest_rate
     # @api public
 
-    def initialize(nominal_rate, duration, amount, structure_fee=5, currency_protection=3)
-      @nominal_rate, @amount, @duration, @structure_fee, @currency_protection = nominal_rate.to_f, amount, duration, structure_fee.to_f, currency_protection.to_f
+    def initialize(nominal_rate, duration, amount, structure_fee=5, currency_protection=3, fee=0)
+      @nominal_rate, @amount, @duration, @structure_fee, @currency_protection, @fee = nominal_rate.to_f, amount, duration, structure_fee.to_f, currency_protection.to_f, fee.to_f
       @principal = principal_calculation
       @monthly_rate = @nominal_rate / 100 / 12
     end
@@ -55,35 +57,7 @@ module FinanceMath
     end
 
     def apr
-      pmt_base = pmt
-      n = duration.to_f / 12
-      q = (duration > 12) ? 12 : duration
-      i = pmt_base * n * q / principal - 1
-      #puts "n: #{n} q: #{q} i: #{i} pmt: #{pmt_base}"
-      find(pmt_base, n, q, i)
-    end
-
-    def principal_base(m, n, q, i)
-      m * ( 1 - ( 1 + ( i / q ) ) ** (- n * q) ) * q / i
-    end
-
-    def near(a, b)
-      r = 0.1
-      return ((a - r) < b && (a + r) > b) || ((b - r) < a && (b + r) > a)
-    end
-
-    def find(pmt_base, n, q, i)
-      p = principal_base(pmt_base, n, q, i)
-
-      return i if near(p, principal)
-      
-      if p < principal
-        i -= 0.00001
-      elsif p > principal
-        i += 0.00001
-      end
-      
-      find(pmt_base, n, q, i)
+      @apr ||= calculate_apr
     end
 
     protected
@@ -107,7 +81,36 @@ module FinanceMath
     private
 
       def principal_calculation
-        amount * (1 - currency_protection/100 - structure_fee / 100 )
+        amount * (1 - currency_protection/100 - structure_fee / 100 ) - fee * duration
+      end
+
+      # solves APR
+      # [a (1 + a)^N] / [(1 + a)^N - 1] - P/C = 0
+      # where a = APR/1200, N = duration, P = monthly payment, C = loan_amount
+      # Newton-Raphson finds root (the value for 'a' that makes f(a) = 0)
+      def calculate_apr
+        payment_ratio = pmt / principal_calculation 
+        duration = @duration 
+        f = lambda {|k| (k**(duration + 1) - (k**duration * (payment_ratio + 1)) + payment_ratio)}
+        f_deriv = lambda { |k| ((duration + 1) * k**duration) - (duration * (payment_ratio + 1) * k**(duration - 1))}
+
+        root = newton_raphson(f, f_deriv, monthly_rate + 1)
+        100 * 12 * (root -1).to_f
+      end
+
+      # 'start' is the monthly_rate, Newton Raphson will find the apr root very quickly
+      # k1 = k0 - f(k0)/f'(k0)
+      # k_plus_one = k - f(k)/f_deriv(k)  f_deriv should be an positive number!
+      # We find the k-intercept of the tangent line at point k_plus_one and compare k to k_plus_one.
+      # This is repeated until a sufficiently accurate value is reached, which can be specified with the 'precision' parameter
+      def newton_raphson(f, f_deriv, start, precision = 5)
+        k_plus_one = start
+        k = 0.0
+        while ((k - 1) * 10**precision).to_f.floor !=  ((k_plus_one - 1) * 10**precision).to_f.floor
+          k = k_plus_one
+          k_plus_one = k - f.call(k) / f_deriv.call(k).abs
+        end
+        k_plus_one
       end
   end
 end

data/lib/{finance_math/version.rb → version.rb}

@@ -1,3 +1,3 @@
 module FinanceMath
-  VERSION = "0.2"
+  VERSION = "1.0.0"
 end

data/spec/lib/loan_spec.rb

@@ -37,33 +37,73 @@ describe Loan do
       loan = Loan.new(0, 6, 10000)
       expect(loan.pmt).to eq(1666.6666666666667)
     end
+
+    it "should return correct pmt value" do
+      loan = Loan.new(13, 90, 1000000)
+      expect(loan.pmt).to eq(17449.90775727763)
+    end
   end
 
-  context ".apr" do
+  context ".apr, edge cases" do
 
     it "should return correct apr value" do
-      loan = Loan.new(16, 24, 10000)
-      expect(loan.apr).to eq(0.24699853524196447)
+      loan = Loan.new(16, 24, 9200)
+      expect(loan.apr).to eq(24.699310868498614)
     end
 
     it "should return correct apr value" do
       loan = Loan.new(13, 24, 10000)
-      expect(loan.apr).to eq(0.2159014588291408)
+      expect(loan.apr).to eq(21.589972932434698)
     end
 
     it "should return correct apr value" do
       loan = Loan.new(13, 18, 10000)
-      expect(loan.apr).to eq(0.2418055150965281)
+      expect(loan.apr).to eq(24.1815502466296)
+    end
+
+    it "should return correct apr value" do
+      loan = Loan.new(13, 12, 10000)
+      expect(loan.apr).to eq(29.179538647635006)
+    end
+
+    it "should return correct apr value" do
+      loan = Loan.new(13, 6, 10000)
+      expect(loan.apr).to eq(42.82076503747119)
+    end
+
+    it "should return correct apr value" do
+      loan = Loan.new(13, 36, 10000)
+      expect(loan.apr).to eq(18.93638316167774)
+    end
+
+    it "should return correct apr value" do
+      loan = Loan.new(13, 90, 10000000)
+      expect(loan.apr).to eq(15.690778147507167)
+    end
+
+    it "should return correct apr value" do
+      loan = Loan.new(13, 90, 50000000)
+      expect(loan.apr).to eq(15.690778147507167)
+    end
+
+    it "should return correct apr value" do
+      loan = Loan.new(13, 1, 50000000)
+      expect(loan.apr).to eq(118.47826151517138)
     end
 
-    # it "should return correct apr value" do
-    #   loan = Loan.new(13, 6, 10000)
-    #   expect(loan.apr).to eq(0.2418055150965281)
-    # end
+    it "should return correct apr value" do
+      loan = Loan.new(80, 1, 1000)
+      expect(loan.apr).to eq(191.30434783476406)
+    end
 
-    # it "should return correct apr value" do
-    #   loan = Loan.new(13, 36, 10000)
-    #   expect(loan.apr).to eq(0.2418055150965281)
-    # end
+    it "should return correct apr value" do
+      loan = Loan.new(36, 200, 500)
+      expect(loan.apr).to eq(39.173057290003044)
+    end
+
+    it "should return correct apr value" do
+      loan = Loan.new(15, 36, 10000, 5, 3, 10)
+      expect(loan.apr).to eq(23.964418264624054)
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: finance_math
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: 1.0.0
 platform: ruby
 authors:
 - Nebojsa Zoric
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-03 00:00:00.000000000 Z
+date: 2015-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,7 +52,10 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Implementation of Loan/Mortgage functions in Ruby language
+description: 'Implementation of Loan/Mortgage functions in Ruby language. APR function
+  and PMT function. In calculations it includes implementation of bank fee, marketplace
+  fee, fees for each payment to provide the most precise calculation at very high
+  speed. '
 email:
 - office@kolosek.com
 executables: []
@@ -67,10 +70,10 @@ files:
 - finance_math.gemspec
 - lib/finance_math.rb
 - lib/finance_math/loan.rb
-- lib/finance_math/version.rb
+- lib/version.rb
 - spec/lib/loan_spec.rb
 - spec/spec_helper.rb
-homepage: ''
+homepage: http://kolosek.com/gems/finance_math
 licenses:
 - MIT
 metadata: {}
@@ -93,7 +96,7 @@ rubyforge_project:
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: Finance library for Ruby.
+summary: Finance and mortgage library for Ruby.
 test_files:
 - spec/lib/loan_spec.rb
 - spec/spec_helper.rb