> ## Documentation Index > Fetch the complete documentation index at: https://docs.truemath.ai/llms.txt > Use this file to discover all available pages before exploring further. # Finance > Time-value-of-money and amortization functions, uniform and single-payment series, interest-rate conversion, and cash-flow analysis — with their unit rules. These functions cover the time value of money, amortization, and cash-flow analysis. ## Conventions Across all of them: * Cash **inflows are positive** and **outflows are negative**. * Interest rates are entered and returned as **decimals** (`0.08`, not `8%`). * `periods_per_year` and `compounds_per_year` default to `12`; a value less than 1 returns a `Parameter out of range` error. The [cash flow analysis](#cash-flow-analysis) functions take neither — their rate is [per period](#periodic-rates). * `beginning_of_period` is `false` for end-of-period (the default) or `true` for 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`, and `payment` may each be a [currency value](/math/types/unit-numbers) (`375000 USD`) or a plain [scalar](/math/types/scalar-numbers) (`375000`). Within a single call they must all be the **same kind**. A value of `0` is the exception: it is accepted for any of these arguments regardless of the others. * **Periods** — `periods` may be a [time value](/math/units) (`30 yr`) or a scalar. A time value is converted to a number of periods by converting it to years and multiplying by `periods_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. If `present_value`, `future_value`, and `payment` are currency values, the result is a [time value](/math/units) in **years** (the period count divided by `periods_per_year`). If they are scalars, the result is a bare scalar count of periods. See [`periods`](#number-of-periods-periods). ## Time value of money The five core functions each solve for one variable given the others. Each accepts the optional tail `periods_per_year; compounds_per_year; beginning_of_period`. `periods` of `0` returns a result of `0`. ### Present value \[pv] ``` pv(future_value; payment; interest_rate; periods) pv(future_value; payment; interest_rate; periods; periods_per_year; compounds_per_year; beginning_of_period) ``` *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units).* ``` pv(0; -2000; 0.05; 60) => 105981.4126 pv(0; -2000; 0.05; 60; 4; 4; false) => 84069.1836 ``` ### Future value \[fv] ``` fv(present_value; payment; interest_rate; periods) fv(present_value; payment; interest_rate; periods; periods_per_year; compounds_per_year; beginning_of_period) ``` *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units).* ``` fv(50000; 500; 0.1; 240) => -746088.0997 fv(50000; 500; 0.1; 20; 1; 1; false) => -365012.4972 ``` ### Payment \[pmt] ``` pmt(present_value; future_value; interest_rate; periods) pmt(present_value; future_value; interest_rate; periods; periods_per_year; compounds_per_year; beginning_of_period) ``` *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units).* ``` pmt(300000; 0; 0.07; 360) => -1995.9075 pmt(300000; 0; 0.07; 30; 1; 1; false) => -24175.9211 ``` ### Interest rate \[rate] ``` rate(present_value; future_value; payment; periods) rate(present_value; future_value; payment; periods; periods_per_year; compounds_per_year; beginning_of_period) ``` Returns the interest rate as a decimal. *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units).* ``` rate(300000; 100000; -4000; 360) => 0.158088 rate(-150000; 100000; -4000; 30; 1; 1; 0) => -0.047224 ``` ### Number of periods \[periods] ``` periods(present_value; future_value; payment; interest_rate) periods(present_value; future_value; payment; interest_rate; periods_per_year; compounds_per_year; beginning_of_period) ``` *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units).* The return type mirrors the present value, future value, and payment arguments. With **scalar** values, `periods()` returns a bare scalar count. With **currency** values, it returns a [time value](/math/units) in **years** — the period count divided by `periods_per_year` — because the result carries the period unit rather than a dimensionless count. ``` periods(300000; 0; -4000; 0.06) => 94.2355 periods(300000 USD; 0; -4000 USD; 0.06) => 7.853 yr ``` These are equivalent results: with `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`](/math/functions/units#unit-value). At the default of 12 periods per year, one period is a month, so convert to `"mo"`: ``` unitvalue(periods(300000 USD; 0; -4000 USD; 0.06); "mo") => 94.2355 ``` This `"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](#value-and-period-units) as the functions above, and the `begin` 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] ``` endbal(end; present_value; future_value; payment; interest_rate; periods) endbal(...; periods_per_year; compounds_per_year; beginning_of_period) endbal(...; beginning_of_period; positive_result) ``` The balance remaining at the end of period `end`. *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units); see [Amortization](#amortization) for the period and `positive_result` rules.* ### Principal paid \[prnpaid] ``` prnpaid(begin; end; present_value; future_value; payment; interest_rate; periods) prnpaid(...; periods_per_year; compounds_per_year; beginning_of_period) prnpaid(...; beginning_of_period; positive_result) ``` The total **principal** paid from period `begin` to period `end`, inclusive. *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units); see [Amortization](#amortization) for the period and `positive_result` rules.* ### Interest paid \[intpaid] ``` intpaid(begin; end; present_value; future_value; payment; interest_rate; periods) intpaid(...; periods_per_year; compounds_per_year; beginning_of_period) intpaid(...; beginning_of_period; positive_result) ``` The total **interest** paid from period `begin` to period `end`, inclusive. *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units); see [Amortization](#amortization) for the period and `positive_result` rules.* ### Amortization table \[amortization] ``` amortization(begin; end; present_value; future_value; payment; interest_rate; periods) amortization(...; periods_per_year; compounds_per_year; beginning_of_period) amortization(...; beginning_of_period; positive_result) ``` A [table](/math/types/tables) of amortization results for each period from `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`](/math/functions/tables#column-column-columns): `columns(schedule; 2; 3)` returns a two-column table ready to show as a [bar chart](/authoring/charts). A single column is taken the same way — `column(schedule; 4)` is the end-balance curve. *Follows the shared [conventions](#conventions) and [value and period units](#value-and-period-units); see [Amortization](#amortization) for the period and `positive_result` rules.* ## Uniform and single payment series These take an `interest_rate` **per compounding period** and a number of `periods`. `uspv()` calculates the present value of a series of $1 payments while `usfv()` calculates the future value of a series of $1 payments. `sppv()` calculates the present value of $1 while `spfv()` calculates the future 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%`. ``` uspv(interest_rate; periods) # uniform series present value usfv(interest_rate; periods) # uniform series future value sppv(interest_rate; periods) # single payment present value spfv(interest_rate; periods) # single payment future value ``` ``` uspv(0.06 / 12; 360) => 166.7916 usfv(0.06 / 12; 360) => 1004.515 sppv(0.06 / 12; 360) => 0.166 spfv(0.06 / 12; 360) => 6.0226 ``` ## Interest rate conversion ``` effrate(nominal_rate; compounds_per_year) nomrate(effective_rate; compounds_per_year) ``` `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. ``` effrate(0.06; 12) => 0.0617 effrate(0.06; 0) => 0.0618 nomrate(0.06; 12) => 0.0584 nomrate(0.06; 0) => 0.0583 ``` ## Cash flow analysis These functions evaluate an **uneven** series of cash flows held in a [table](/math/types/tables) — a project's outlay and the returns that follow it, a lease, an investment with irregular contributions. Where the [time value of money](#time-value-of-money) functions assume one level `payment` 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](#conventions). Each cell is a [scalar](/math/types/scalar-numbers) or a [currency value](/math/types/unit-numbers); any other unit returns an incompatible-type error. Currency amounts must share a single currency — TrueMath supports `USD` today, 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 `4` is four periods at that amount. Each cell must be a non-negative whole number, or an incompatible-type error is returned. A frequency of `0` drops the row, contributing no periods. With no second column, every row is one period. Further columns are ignored. The notations overlap — `[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: ``` npv([280; 1492.56; 380.11; 125.25; 100; 56.78; 21.34]; 0.05) => 2297.1354 npv([[280; 1]; [1492.56; 2]; [380.11; 2]; [125.25; 3]; [100; 1]; [56.78; 1]; [21.34; 6]]; 0.05) => 4151.0712 ``` The first call is seven periods, one per row. The second holds the same seven amounts but repeats them, spanning sixteen. **The first row is the flow at period 0.** It is the flow at the start, before any period has elapsed: it is not discounted, and it does not count as a period. The rows after it are periods 1, 2, 3, and so on — so a six-row table spans period 0 through period 5, and the series runs for five periods. Where the first row carries a frequency greater than 1, its first occurrence is period 0 and the rest fall in the periods after it: `[[-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: ``` npv([[-20000; 1]; [500; 4]; [1000; 4]; [2000; 4]; [3000; 4]]; 0.02) => 928.4409 npv([[-20000; 1]; [500; 4]; [1000; 4]; [2000; 4]; [3000; 4]; [0; 4]]; 0.02) => 928.4409 nfv([[-20000; 1]; [500; 4]; [1000; 4]; [2000; 4]; [3000; 4]]; 0.02) => 1274.5504 nfv([[-20000; 1]; [500; 4]; [1000; 4]; [2000; 4]; [3000; 4]; [0; 4]]; 0.02) => 1379.6144 ``` ### 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`. ``` npv([[-20000; 1]; [500; 4]; [1000; 4]; [2000; 4]; [3000; 4]]; 0.08 / 4) => 928.4409 ``` `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] ``` npv(table; interest_rate) ``` The value of the whole series at period 0: every later flow discounted back at `interest_rate`, plus the period-0 flow at face value. *Follows [Reading the cash flow table](#reading-the-cash-flow-table) and [Periodic rates](#periodic-rates).* ``` npv([-80000; 5000; 4500; 5500; 4000; 115000]; 0.105) => 4774.6328 npv([[-50000; 1]; [5000; 3]; [10000; 4]; [0; 1]; [15000; 3]]; 0.09) => 6728.6266 ``` ### Net future value \[nfv] ``` nfv(table; interest_rate) ``` The value of the whole series at its **last period** — the net present value compounded forward over the periods the series runs for. *Follows [Reading the cash flow table](#reading-the-cash-flow-table) and [Periodic rates](#periodic-rates).* ``` nfv([-80000; 5000; 4500; 5500; 4000; 115000]; 0.105) => 7865.9533 nfv([[-50000; 1]; [5000; 3]; [10000; 4]; [0; 1]; [15000; 3]]; 0.09) => 17362.7257 ``` ### Net uniform series \[nus] ``` nus(table; interest_rate) nus(table; interest_rate; beginning_of_period) ``` The **level** flow with the same net present value as the uneven series — what the series is worth per period, and the figure to compare two series of different shapes. It repeats for the number of periods after period 0, at the end of each period by default; `beginning_of_period` of `true` places it at the start of each period instead. *Follows [Reading the cash flow table](#reading-the-cash-flow-table), [Periodic rates](#periodic-rates), and the `beginning_of_period` [convention](#conventions).* ``` nus([-80000; 5000; 4500; 5500; 4000; 115000]; 0.105) => 1275.6649 nus([280; 1492.56; 380.11; 125.25; 100; 56.78; 21.34]; 0.05) => 452.5758 nus([280; 1492.56; 380.11; 125.25; 100; 56.78; 21.34]; 0.05; true) => 431.0246 ``` ### Internal rate of return \[irr] ``` irr(table) ``` The rate **per period** at which the series' net present value is zero. A meaningful result requires the cash flows to change sign at least once; with no sign change, an out-of-range error is returned. When they change sign more than once, more than one rate can satisfy NPV = 0 and `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`](#modified-internal-rate-of-return-mirr), which has a single solution by construction. *Follows [Reading the cash flow table](#reading-the-cash-flow-table) and [Periodic rates](#periodic-rates).* ``` irr([-80000; 5000; 4500; 5500; 4000; 115000]) => 0.1193 irr([[-20000; 1]; [500; 4]; [1000; 4]; [2000; 4]; [3000; 4]]) => 0.0243 ``` The second series is quarterly, so its result is 2.43% per quarter — 9.72% nominal annual. ### Modified internal rate of return \[mirr] ``` mirr(table; interest_rate; risk_rate) ``` An internal rate of return with a separate rate for each side of the series: outflows discounted at the finance rate `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](#reading-the-cash-flow-table) and [Periodic rates](#periodic-rates).* ``` mirr([-80000; 5000; 4500; 5500; 4000; 115000]; 0.105; 0.1054) => 0.1179 mirr([[-50000; 1]; [5000; 3]; [10000; 4]; [0; 1]; [15000; 3]]; 0.09; 0.1054) => 0.1095 ``` ### Payback period \[payback] ``` payback(table) ``` The number of periods from period 0 until the **cumulative, undiscounted** flows return to zero — how long an outlay takes to recover. No rate is passed; discounting plays no part. The result is fractional: within the period where the running total crosses zero it is interpolated linearly, so `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](#reading-the-cash-flow-table).* ``` payback([-80000; 5000; 4500; 5500; 4000; 115000]) => 4.53 payback([[-50000; 1]; [5000; 3]; [10000; 4]; [0; 1]; [15000; 3]]) => 6.5 payback([-280; 1492.56; 380.11; 125.25; 100; 56.78; 21.34]) => 0.1876 ``` ### Profitability index \[profindex] ``` profindex(table; interest_rate) ``` The present value of the inflows divided by the present value of the outflows, both discounted at `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](#reading-the-cash-flow-table) and [Periodic rates](#periodic-rates).* ``` profindex([-80000; 5000; 4500; 5500; 4000; 115000]; 0.105) => 1.06 profindex([[-50000; 1]; [5000; 3]; [10000; 4]; [0; 1]; [15000; 3]]; 0.09) => 1.13 ```