# Bankroll

Bankroll is a set of financial calculations for mortgages and loans.

The goal of this library is to make time value of money calculations understandable and decomposed into well written functions.

I find most financial math libraries to be somewhat opaque so hopefully this helps when learning how to calculate mortgages and other annuity based investments.

Features:

- Uses safe math with BigDecimal through the Bankroll::Decimal api
- Handles only ordinary annuities (annuities due at the END of the period)
- Implements most excel functions using some inspiration from Exonio gem

## Installation

Add this line to your application's Gemfile:

`gem 'bankroll'`

And then execute:

```
$ bundle install
```

Or install it yourself as:

```
$ gem install bankroll
```

## Usage

```
# What is the monthly payment?
payment = Bankroll.payment(
periods: 360,
interest_rate: 0.01 / 12.0,
present_value: 1_000_000
).round
puts payment #=> Bankroll::Decimal["3_216.40"]
# What was the original loan amount?
original_amount = Bankroll.present_value(
periods: 360, # 30 years
monthly_payment: 3_216.40,
interest_rate: 0.01 / 12.0, # 1% APR
).round
puts original_amount #=> Bankroll::Decimal["1_000_001.49"]
# What does the balance look like after a single mortgage payment?
unpaid_balance = Bankroll.unpaid_balance(
present_value: 1_000_000,
interest_rate: 0.01 / 12.0,
periods: 360,
period: 1,
payment: 3_216.40
).round
puts unpaid_balance #=> Bankroll::Decimal["997_616.94"]
# What was the interest rate?
interest_rate = Bankroll.interest_rate(
present_value: 1_000_000,
periods: 360,
payment: -3_216.40,
).round(3)
puts interest_rate #=> Bankroll::Decimal["0.833e-3"]
# What is the annuity factor of a rate for n periods?
annuity_factor = Bankroll.annuity_factor(
interest_rate: 0.01,
periods: 2
).round(4)
puts annuity_factor #=> Bankroll::Decimal["1.9704"]
# What is the total interest paid on a 500_000 1% mortgage
interest_paid = Bankroll.cumulative_interest(
periods: 360,
interest_rate: 0.01 / 12.0,
payment: 1_608.20,
present_value: 500_000
).round
puts interest_paid #=> Bankroll::Decimal["832.34"]
# What is the total cost of a 500_000 1% loan with interest?
total_amount = Bankroll.future_value(
present_value: 0,
interest_rate: 0.01 / 12.0,
periods: 360,
payment: 1_608.20
).round
puts total_amount #=> Bankroll::Decimal["647_846.10"]
# What is the interest payment on the 17th period of a $165,000 3% mortgage?
interest_payment = Bankroll.interest_payment(
interest_rate: 0.03 / 12.0,
periods: 360,
period: 17,
present_value: 165_000
).round
puts interest_payment #=> Bankroll::Decimal["400.96"]
# How many periods until a -$1000 account with -$100/month reaches $10_000 with
# 12% interest rate?
total_periods = Bankroll.total_periods(
interest_rate: 0.12 / 12.0,
payment: -100,
present_value: -1_000,
future_value: 10_000
)
puts total_periods #=> Bankroll::Decimal["59.67"]
# What is the amortization schedule of a $165_000 3% 30 year mortgage?
amortization_schedule = Bankroll.amortization_schedule(
present_value: 165_000,
interest_rate: 0.03 / 12.0,
periods: 360
)
puts amortization_schedule.payments #=> [
# Bankroll::AmortizationSchedule::Payment.new(
# payment: Bankroll::Decimal["695.65"],
# principal: Bankroll::Decimal["283.15"],
# interest: Bankroll::Decimal["412.50"],
# total_interest: Bankroll::Decimal["412.50"],
# balance: Bankroll::Decimal["164_716.85"]
# )
# ... and 359 more payments
# ]
```

## Development

After checking out the repo, run `bin/setup`

to install dependencies.
Then, run `rake spec`

to run the tests. You can also run `bin/console`

for an
interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`

.
To release a new version, update the version number in `version.rb`

, and then
run `bundle exec rake release`

, which will create a git tag for the version,
push git commits and the created tag, and push the `.gem`

file
to rubygems.org.

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/nolantait/bankroll.

## License

The gem is available as open source under the terms of the MIT License.