Conventions
Across all of them:- Cash inflows are positive and outflows are negative.
- Interest rates are entered and returned as decimals (
0.08, not8%). periods_per_yearandcompounds_per_yeardefault to12; a value less than 1 returns aParameter out of rangeerror. The cash flow analysis functions take neither — their rate is per period.beginning_of_periodisfalsefor end-of-period (the default) ortruefor beginning-of-period.
Value and period units
The time-value-of-money and amortization functions accept units on their value and period arguments, with these rules:- Values —
present_value,future_value, andpaymentmay each be a currency value (375000 USD) or a plain scalar (375000). Within a single call they must all be the same kind. A value of0is the exception: it is accepted for any of these arguments regardless of the others. - Periods —
periodsmay be a time value (30 yr) or a scalar. A time value is converted to a number of periods by converting it to years and multiplying byperiods_per_year. A scalar is used as the number of periods unchanged. - Solving for periods — when
periods()solves for the number of periods, its return type mirrors the value arguments. Ifpresent_value,future_value, andpaymentare currency values, the result is a time value in years (the period count divided byperiods_per_year). If they are scalars, the result is a bare scalar count of periods. Seeperiods.
Time value of money
The five core functions each solve for one variable given the others. Each accepts the optional tailperiods_per_year; compounds_per_year; beginning_of_period. periods of 0 returns a result of 0.
Present value [pv]
Future value [fv]
Payment [pmt]
Interest rate [rate]
Number of periods [periods]
periods() returns a bare scalar count. With currency values, it returns a time value in years — the period count divided by periods_per_year — because the result carries the period unit rather than a dimensionless count.
periods_per_year at its default of 12, the first call returns the count in periods (months) and the second returns it in years (94.2355 periods / 12 periods per year = 7.853 yr).
To recover a scalar count from a currency-valued call, convert the result to the unit that matches one period and strip it with unitvalue. At the default of 12 periods per year, one period is a month, so convert to "mo":
"mo" form is exact only because periods_per_year is 12. For any other cadence, recover the count by converting to years and multiplying by periods_per_year — unitvalue(periods(...); "yr") * periods_per_year — which holds regardless of how many periods fall in a year.
Recovering the count matters when a downstream calculation multiplies it by a currency amount: a yr-typed count raises input.incompatible_units (“Cannot multiply Currency and Time”), while the recovered scalar count multiplies cleanly.
Amortization
These analyze a loan or investment over its schedule. They follow the same value and period unit rules as the functions above, and thebegin and end arguments follow the same rule as periods — a time value is converted to periods, a scalar is used unchanged. In addition, a fractional begin or end is reduced to its integer part (1.5 → 1, 11.3 → 11).
Each function also accepts a final positive_result argument: set it to true to always report the result as a positive number. periods of 0 returns 0 (or, for amortization, an empty table).
End balance [endbal]
end.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Principal paid [prnpaid]
begin to period end, inclusive.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Interest paid [intpaid]
begin to period end, inclusive.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Amortization table [amortization]
begin to end, inclusive. Each row is one period; its four columns are, in order, the payment, the principal paid, the interest paid, and the end balance.
To chart how a payment splits between principal and interest across the schedule, slice those two columns with columns: columns(schedule; 2; 3) returns a two-column table ready to show as a bar chart. A single column is taken the same way — column(schedule; 4) is the end-balance curve.
Follows the shared conventions and value and period units; see Amortization for the period and positive_result rules.
Uniform and single payment series
These take aninterest_rate per compounding period and a number of periods. uspv() calculates the present value of a series of 1 payments. sppv() calculates the present value of 1.
Because the rate is per period, divide an annual rate by the number of compounding periods per year — for a 6% annual rate compounding monthly, pass 0.06 / 12. The rate is a decimal, so you can also write it as rate / 100 or rate%.
Interest rate conversion
effrate converts a nominal rate to an effective annual rate; nomrate does the reverse. A compounds_per_year of 0 denotes continuous compounding; a negative value returns a Parameter out of range error. Both take and return decimals.
Cash flow analysis
These functions evaluate an uneven series of cash flows held in a table — a project’s outlay and the returns that follow it, a lease, an investment with irregular contributions. Where the time value of money functions assume one levelpayment repeated every period, these read the flows period by period from the table. They share a table shape and a period model, described below.
Reading the cash flow table
The table has one or two columns:- Column one — amounts. One cash flow per row, inflows positive and outflows negative. Each cell is a scalar or a currency value; any other unit returns an incompatible-type error. Currency amounts must share a single currency — TrueMath supports
USDtoday, and amounts in different currencies are not converted. - Column two — frequencies (optional). How many consecutive periods the amount on that row repeats: a frequency of
4is four periods at that amount. Each cell must be a non-negative whole number, or an incompatible-type error is returned. A frequency of0drops the row, contributing no periods. With no second column, every row is one period. Further columns are ignored.
[500; 500; 500] and [[500; 3]] are the same three periods either way — so the second column is how you compress a long schedule: fifteen years of monthly flows at four distinct amounts is four rows rather than 180. Repeat counts lengthen the series, and the result follows:
[[-5000; 3]; ...] is an outflow of 5,000 at periods 0, 1, and 2.
Two consequences worth planning for. An initial investment belongs on the first row, where it is taken at face value; a series whose first flow arrives one period out needs an explicit 0 on the first row to place it correctly. And trailing rows extend the series — rows with an amount of 0 add periods without adding value, which leaves npv, irr, payback, and profindex untouched but moves nfv, nus, and mirr, all three of which depend on how many periods the series runs for:
Periodic rates
interest_rate is the rate for one period of the table. These functions take no periods_per_year or compounds_per_year argument and make no assumption about how long a period is, so convert an annual rate yourself: for quarterly flows at an 8% nominal annual rate, pass 0.08 / 4.
irr and mirr return a rate on the same basis — per period. Multiply by the number of periods in a year to read it as a nominal annual rate. An interest_rate of -1 or lower returns an out-of-range error.
Net present value [npv]
interest_rate, plus the period-0 flow at face value.
Follows Reading the cash flow table and Periodic rates.
Net future value [nfv]
Net uniform series [nus]
beginning_of_period of true places it at the start of each period instead.
Follows Reading the cash flow table, Periodic rates, and the beginning_of_period convention.
Internal rate of return [irr]
irr returns one of them. The same series always returns the same rate, but treat which root that is as unspecified: for a series that reverses sign more than once, prefer mirr, which has a single solution by construction.
Follows Reading the cash flow table and Periodic rates.
Modified internal rate of return [mirr]
interest_rate, inflows compounded forward at the reinvestment rate risk_rate. Returns a rate per period. A series with no outflow returns an infinity error rather than a rate.
Follows Reading the cash flow table and Periodic rates.
Payback period [payback]
4.53 puts the recovery a little past halfway through period 5. A series that opens with an inflow is measured the same way, reporting when the total falls back to zero.
When the flows never return to zero, payback returns 0 — a 0 result means no payback, not immediate payback.
Follows Reading the cash flow table.
Profitability index [profindex]
interest_rate — above 1 when the series returns more than it costs. A series with no outflow returns an infinity error rather than a number.
Follows Reading the cash flow table and Periodic rates.