We recently announced Refinance, a software library for doing annuity calculations. At the time, its documentation was minimal‚Äîer, *streamlined*. So I’ll give a brief introduction here. I’ll explain the kind of problems Refinance helps you solve, and show an example of use.

## Annuities

Refinance does calculations related to *annuities*. An annuity is a finite series of regular payments. An installment loan for a car, or a fixed-rate home mortgage, are familiar examples.

The library helps you answer questions like these:

- Say you have a car loan and are paying a fixed amount each month to pay it off. If you got a reduced interest rate, exactly how much lower would your monthly payments be?
- If you get a reduced interest rate but continue to pay the same monthly payments, exactly how much shorter will the loan duration be?
- Say you want to borrow money to buy a car. If your bank will lend you money at an X% annual interest rate, and you’re willing to make monthly payments as high as $Y, how expensive of a car can you buy?
- Say you’re making monthly payments of $X to pay off a $Y loan. What interest rate are you being charged?
- Say your loan has an interest rate of X% per month. What is its effective
*annual*interest rate?

Annuities have four defining properties (at least for our purposes), and the first four questions above provide examples of each: The first question is asking for the annuity’s *periodic payment amount*. The second is asking for the *number of remaining payments*. The third is asking for the *principal*. The fourth is asking for the *interest rate*. In general, if you know three of those properties, Refinance can calculate the fourth.

The fifth question is about converting an interest rate. Perhaps you think this is trivial: if you’re paying 1% per month, then it’s equivalent to paying 12% per year, right? Wrong. It’s more like 12.68%. You need to account for the effects of compound interest.

## Using Refinance

Consider Example 2 from Stan Brown’s *Loan or Investment Formulas*:

You are buying a $250,000 house, with 10% down, on a 30-year mortgage at a fixed rate of 7.8%. What is the monthly payment?

We want to calculate the monthly payment, so we’ll use the method Refinance::Annuities.payment. It requires three arguments: the interest rate (per month, since we’re calculating the monthly payment), the total number of monthly payments, and the principal. These are easy to determine from the example:

- The interest rate is 7.8%, but there are two things to note here. First, 7.8% is a nominal annual rate, and we want the monthly interest rate. So we divide 7.8% by 12 (because there are 12 months in a year) and get 0.65%. Second, the method wants the argument in decimal form, not percent form, so 0.65% becomes
*0.0065*. - The loan lasts 30 years, and we want the number of payment periods‚Äîthat is, the number of months. 30 years is
*360 months*. - The house’s purchase price is $250,000, and we’re making a 10% down payment, so the loan’s principal will be 90% of $250,000, or
*$225,000*.

Now we can call the method:

```
Refinance::Annuities.payment 0.0065, 360.0, 225000.0
```

(You can name the arguments “interest rate”, “periods”, and “principal”. For this and related methods, the arguments go in alphabetical order.)

The return value is 1619.7086268909618. So the monthly payment is about $1,619.71.