Module amortization

Expand description

Amortization schedules with the same solution / series / table pattern as payment TVM.

§What you get

Layer	API	Purpose
Scalar (Excel)	`ipmt`, `ppmt`, `cumipmt`, `cumprinc`	Single numbers, spreadsheet parity
Solution	`amortization_solution`	Inputs + payment + formulas
Series	`AmortizationSolution::series`	Period-by-period principal / interest
Table	`AmortizationSeries::print_table`	Pretty terminal / copy-paste output

§Error handling (v0.1+)

Public construction and Excel-style scalars return FinanceResult. Invalid rates, zero periods, and out-of-range period indices are errors, not panics. AmortizationSolution::series is infallible once a solution was constructed successfully.

Period numbers are 1-based, matching Excel / Google Sheets. Sign conventions match payment. Timing uses PaymentTiming (or bool via From).

§Example: solution → series → table

use finance_solution::*;

// $10,000 at 8% APR, monthly, 12 months
let rate = 0.08 / 12.0;
let periods = 12;
let principal = 10_000.0;

let solution = amortization_solution(rate, periods, principal, 0.0, false).unwrap();
assert!(solution.payment() < 0.0); // positive principal → negative payment

let series = solution.series();
assert_eq!(series.len(), periods as usize);

// Pretty table (running totals + remaining amounts).
series.print_table(true, true);

assert_approx_equal!(solution.ipmt(1).unwrap(), series[0].interest());
assert_approx_equal!(solution.ppmt(1).unwrap(), series[0].principal());

print_table(true, true) prints a schedule like this (truncated for width in some terminals; values match a 12-month $10k loan at 8% APR monthly):

period    payment  principal  interest     balance  principal_to_date  interest_to_date  payments_to_date  principal_remaining  interest_remaining  payments_remaining
------  ---------  ---------  --------  ----------  -----------------  ----------------  ----------------  -------------------  ------------------  ------------------
     1  -869.8843  -803.2176  -66.6667  9_196.7824          -803.2176          -66.6667         -869.8843          -9_196.7824           -371.9448         -9_568.7272
     2  -869.8843  -808.5724  -61.3119  8_388.2100        -1_611.7900         -127.9785       -1_739.7686          -8_388.2100           -310.6329         -8_698.8429
     3  -869.8843  -813.9629  -55.9214  7_574.2471        -2_425.7529         -183.8999       -2_609.6529          -7_574.2471           -254.7115         -7_828.9586
   ...
    12  -869.8843  -864.1235   -5.7608     -0.0000       -10_000.0000         -438.6115      -10_438.6115               0.0000             -0.0000              0.0000

Period 1: payment ≈ −869.88 splits into interest ≈ −66.67 and principal ≈ −803.22; balance after payment ≈ 9,196.78. Period 12 pays the loan down to ≈ 0.

Structs§

AmortizationPeriod: One period of an amortization schedule.
AmortizationSeries: Period-by-period amortization rows. Derefs to [AmortizationPeriod].
AmortizationSolution: Full amortization setup: inputs, level payment, formulas, and access to a period series.

Functions§

amortization_solution: Build an amortization solution (payment + schedule access).
cumipmt: Cumulative interest paid between two periods inclusive (Excel CUMIPMT).
cumprinc: Cumulative principal paid between two periods inclusive (Excel CUMPRINC).
ipmt: Interest portion of the payment for a single period (Excel IPMT).
ppmt: Principal portion of the payment for a single period (Excel PPMT).