> ## 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. * `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 Each takes a `table` of cash flows (inflows positive, outflows negative). For `npv`, `nfv`, `nus`, `mirr`, and `profindex`, the rate is annual by default — divide it by the number of compounding periods per year to use a periodic rate. ``` npv(table; interest_rate) # net present value nfv(table; interest_rate) # net future value nus(table; interest_rate) # net uniform series irr(table) # internal rate of return mirr(table; interest_rate; risk_rate) # modified internal rate of return payback(table) # period when the initial investment is recovered profindex(table; interest_rate) # profitability index ``` `irr` finds the rate at which the cash flows' net present value is zero. A meaningful result requires the cash flows to change sign at least once; when they change sign more than once, more than one rate can satisfy NPV = 0. `mirr` takes a finance `interest_rate` and a reinvestment `risk_rate`.