Crate finance_solution

Expand description

finance_solution is a collection of financial functions for time-value-of-money, cashflows, amortization, returns, and basic equity metrics.

In addition to being rigorously tested with symmetry tests and Excel-matching tests, the library provides solution structs with formulas and period-by-period series — useful for financial software audit trails and for students of finance.

§Error handling (v0.1+)

Public financial calculations return FinanceResult (Result<T, FinanceError)). Invalid rates, non-finite amounts, and unsolvable inputs are errors, not panics. Compose with ? or match on FinanceError variants.

There is no dual panicking / try_* API for public math: the ordinary name (e.g. [future_value], [payment], amortization_solution) is the fallible function.

§Example

use finance_solution::*;
let (rate, periods, present_value, is_continuous) = (0.034, 10, -1000.0, false);
let fv = future_value_solution(rate, periods, present_value, is_continuous).unwrap();
dbg!(&fv);

which prints to the terminal:

fv = TvmSolution {
   calculated_field: FutureValue,
   continuous_compounding: false,
   rate: 0.034,
   periods: 10,
   fractional_periods: 10.0,
   present_value: -1000.0,
   future_value: 1397.0288910795477,
   formula: "1397.0289 = 1000.0000 * (1.034000 ^ 10)",
   symbolic_formula: "fv = -pv * (1 + r)^n",
}

and if you run this line:

fv.series().print_table();

a pretty-printed table will be displayed in the terminal:

period      rate        value
------  --------  -----------
     0  0.000000  -1_000.0000
     1  0.034000  -1_034.0000
     2  0.034000  -1_069.1560
     3  0.034000  -1_105.5073
     4  0.034000  -1_143.0946
     5  0.034000  -1_181.9598
     6  0.034000  -1_222.1464
     7  0.034000  -1_263.6994
     8  0.034000  -1_306.6652
     9  0.034000  -1_351.0918
    10  0.034000  -1_397.0289

This can be very useful for functions in the cashflow family, such as a payment.

let (rate, periods, present_value, future_value, due) = (0.034, 10, 1000, 0, false);
let pmt = payment_solution(rate, periods, present_value, future_value, due).unwrap();
pmt.print_table();

Which prints to the terminal:

// period  payments_to_date  payments_remaining  principal  principal_to_date  principal_remaining  interest  interest_to_date  interest_remaining
// ------  ----------------  ------------------  ---------  -----------------  -------------------  --------  ----------------  ------------------
//      1         -119.6361         -1_076.7248   -85.6361           -85.6361            -914.3639  -34.0000          -34.0000           -162.3609
//      2         -239.2722           -957.0887   -88.5477          -174.1838            -825.8162  -31.0884          -65.0884           -131.2725
//      3         -358.9083           -837.4526   -91.5583          -265.7421            -734.2579  -28.0778          -93.1661           -103.1947
//      4         -478.5443           -717.8165   -94.6713          -360.4134            -639.5866  -24.9648         -118.1309            -78.2300
//      5         -598.1804           -598.1804   -97.8901          -458.3036            -541.6964  -21.7459         -139.8768            -56.4840
//      6         -717.8165           -478.5443  -101.2184          -559.5220            -440.4780  -18.4177         -158.2945            -38.0663
//      7         -837.4526           -358.9083  -104.6598          -664.1818            -335.8182  -14.9763         -173.2708            -23.0901
//      8         -957.0887           -239.2722  -108.2183          -772.4001            -227.5999  -11.4178         -184.6886            -11.6723
//      9       -1_076.7248           -119.6361  -111.8977          -884.2978            -115.7022   -7.7384         -192.4270             -3.9339
//     10       -1_196.3609             -0.0000  -115.7022          -999.0000              -0.0000   -3.9339         -196.3609              0.0000

Re-exports§

pub use float_cmp;
pub use num_format;

Modules§

amortization: Amortization schedules with the same solution / series / table pattern as payment TVM.
cashflow: The internal module which supports the solution struct for the Cashflow family of functions (e.g., payment).
convert_rate: Rate conversions (APR / EAR / EPR). Historical module path kept for API stability (cannot be named rate at the crate root because [rate] is a TVM function). Rate conversions. Given a rate and number of compound periods per year, what is this rate when converted to APR, Effective annual, and Periodic rates? Also consider the apr ear and epr helper functions.
future_value: Future value calculations. Given an initial investment amount, a number of periods such as periods, and fixed or varying interest rates, what is the value of the investment at the end?
future_value_annuity: Future value annuity calculations. Given a series of constant cashflows, a number of periods such as years, and a fixed interest rate, what is the value of the series at the final payment?
net_present_value: Net Present Value calculations. Given cashflows (including the time-0 investment), periods, and fixed or varying discount rates, what is the net value of the series right now?
nper: Number of periods with payments (NPER). How many periods for an annuity cashflow to grow from a present value to a future value at a periodic rate?
path: Price-path analysis: solution struct, period series, and pretty tables.
payment: Payment calculations. What is the periodic payment needed for an amortized loan and how much of that is interest or principal?
periods: Number of periods calculations. Given a periodic rate, present value, and future value, find the number of periods needed to satisfy the equation.
present_value: Present value calculations. Given a final amount, a number of periods such as years, and fixed or varying interest rates, what is the current value?
present_value_annuity: Present value annuity calculations. Given a series of constant cashflows, a number of periods such as years, and a fixed interest rate, what is the current value of the series right now?
rate: Periodic rate calculations. Given an initial investment amount, a final amount, and a number of periods what does the rate per period need to be?
returns: Educational doubling-time helpers: Rule of 72 / 69 / 70 and exact formulas.
risk: Risk metrics: volatility, Sharpe, Sortino, max drawdown, beta, rolling drawdown.
round: Utilities for rounding money amounts to the nearest hundredth or ten-thousandth part.
rule_of_72: Approximate years to double (Rule of 72 / 69 / 70) and exact doubling time.
stocks: Ordered price-path analytics (equities or any positive price series).
tvm: Time-value-of-money equations without level payments: present value, future value, rate, and periods (simple and continuous compounding, fixed rate or rate schedules).
tvm_convert_rate: The internal module which supports the solution struct for Rate Conversion (see convert_rate).
util: Shared utilities: errors, validation helpers.

Macros§

assert_approx_equal
assert_approx_equal_symmetry_test
assert_rounded_2
assert_rounded_4
assert_rounded_6
assert_rounded_8
assert_same_sign_or_zero
is_approx_equal
is_approx_equal_symmetry_test
repeating_vec

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.
CashflowPeriod
CashflowSeries
CashflowSolution: A record of a cash flow calculation such as payment, net present value, or the present value or future value of an annuity.
ConvertRateSolution
DoublingRateRow: One row of a multi-rate doubling comparison.
DoublingRateSeries: Table of doubling estimates across many rates (teaching: when is Rule of 72 “good enough?”).
DoublingSolution: Comparison of doubling-time methods at a single rate.
NperSolution: Solution struct for an NPER calculation.
NpvPeriod
NpvSeries
NpvSolution: The custom solution information of a NPV scenario. The struct values are immutable by the user of the library.
PaymentSeries
PaymentSolution
PricePathOptions: Options for price_path_solution.
PricePathPeriod: One step between consecutive prices.
PricePathSeries: Period series for a price path. Derefs to [PricePathPeriod].
PricePathSolution: Full analysis of an ordered price path.
ScenarioEntry
ScenarioList
TvmPeriod: The value of an investment at the end of a given period, part of a Time Value of Money calculation.
TvmScheduleSolution: A record of a Time Value of Money calculation where the rate may vary by period.
TvmSeries
TvmSolution

Enums§

CashflowVariable
Compounding: How interest compounds in a TVM calculation.
ConvertRateVariable: The possible types of rates to convert.
FinanceError: Domain and input errors from finance calculations.
PaymentTiming: When a level payment (annuity installment) falls within each period.
ReturnKind: Kind of return used for mean / vol / Sharpe on the path.
Schedule: Sparse or repeating schedule of rates or payments.
TvmVariable: Enumeration used for the calculated_field field in TvmSolution and schedule solutions to track what was calculated: periodic rate, number of periods, present value, or future value.
ValueType: Discriminator for values stored in a Schedule.

Functions§

amortization_solution: Build an amortization solution (payment + schedule access).
apr: Helper function to convert a quoted annual rate (APR) into all possible conversions (EAR, EPR).
apr_continuous: Helper function to convert an APR into an EAR using continuous compounding.
assert_rounded_2
assert_rounded_4
assert_rounded_6
assert_rounded_8
beta: OLS beta of asset returns vs market returns (same length series).
cagr: Compound annual growth rate: (end / start)^(1/years) - 1.
convert_apr_to_ear: Convert a nominal interest rate (Annual rate, APR) to EAR (effective annual rate). Returns f64.
convert_apr_to_ear_solution: Convert an APR to EAR (effective annual rate). Returns a custom type with additional functionality and extra information available in the dbg!().
convert_apr_to_epr: Convert APR (annual rate) to periodic rate. Returns f64.
convert_apr_to_epr_solution: Convert APR (annual rate) to periodic rate. Returns a custom solution type.
convert_ear_to_apr: Convert an EAR to APR. Returns f64.
convert_ear_to_apr_solution: Convert an EAR to APR. Returns solution struct with additional information and functionality.
convert_ear_to_epr: Convert an EAR (Effective Annual Rate) to periodic rate (aka EPR, effective periodic rate). Returns f64.
convert_ear_to_epr_solution: Convert an EAR (Effective Annual Rate) to periodic rate (also known as EPR). Returns a solution struct with additional information and functionality. /// Related Functions:
convert_epr_to_apr: Convert periodic rate to APR (aka Annual rate, nominal interest rate, Annual Percentage Rate). Returns f64.
convert_epr_to_apr_solution: Convert periodic rate to APR (aka Annual rate, nominal interest rate, Annual Percentage Rate). Returns a custom solution type.
convert_epr_to_ear: Convert a periodic rate (aka EPR, effective periodic rate) to EAR (effective annual rate). Return a single f64 value.
convert_epr_to_ear_solution: Convert a periodic rate (EPR) to effective annual rate (EAR), returning a solution struct with additionality information and features.
cumipmt: Cumulative interest paid between two periods inclusive (Excel CUMIPMT).
cumprinc: Cumulative principal paid between two periods inclusive (Excel CUMPRINC).
doubling_compare_rates: Compare doubling rules across a list of rates (teaching: when is Rule of 72 “good enough?”).
doubling_solution: Build a DoublingSolution comparing Rule of 72/70/69 with exact discrete and continuous times.
doubling_time: Exact periods to double under discrete compounding: ln(2) / ln(1 + rate).
doubling_time_continuous: Exact time to double under continuous compounding: ln(2) / rate.
drawdown_series: Running drawdown series (one value per price, starting at 0).
ear: Helper function to convert an effective annual rate (EAR) into all possible conversions (APR, EPR).
ear_continuous: Helper function to convert an EAR into an APR using continuous compounding.
epr: Helper function to convert a periodic interest rate (EPR) to all rate conversions.
future_value: Returns the value of an investment after it has grown or shrunk over time, using a fixed rate.
future_value_annuity: Returns the future value of annuity (a series of constant cashflows) at a constant rate. Returns f64.
future_value_annuity_solution: Returns the future value of annuity (a series of constant cashflows) at a constant rate. Returns custom solution struct with additional information and functionality.
future_value_schedule: Calculates a future value based on rates that change for each period.
future_value_schedule_solution: Calculates a future value based on rates that change for each period, returning a struct with all of the inputs and results.
future_value_solution: Calculates the value of an investment after it has grown or shrunk over time and returns a struct with the inputs and the calculated value. This is used for keeping track of a collection of financial scenarios so that they can be examined later.
ipmt: Interest portion of the payment for a single period (Excel IPMT).
log_return: Logarithmic return: ln(p1 / p0). Requires strictly positive prices.
log_returns: Log returns for consecutive prices: length prices.len() - 1.
max_drawdown: Maximum peak-to-trough drawdown over a positive price series (most negative fraction).
mean_return: Arithmetic mean of a return series.
net_present_value: Returns the net present value of a future series of constant cashflows and constant rate, subtracting the initial investment cost. Returns f64.
net_present_value_schedule: Returns the net present value of a schedule of rates and cashflows (can be varying), subtracting the initial investment cost. Returns f64.
net_present_value_schedule_solution: Returns the net present value of a schedule of rates and cashflows (can be varying), subtracting the initial investment cost. Returns a custom solution struct with detailed information and additional functionality.
net_present_value_solution: Returns the net present value of a future series of constant cashflows and constant rate, subtracting the initial investment cost. Returns a solution struct with additional features..
nper: Returns the number of periods for an annuity (payments) to reach a future value.
nper_due: Number of periods when payments are due at the beginning of each period (Excel type=1).
nper_due_solution: nper_due with a solution struct.
nper_solution: nper with a solution struct (formula string + inputs).
payment: Returns the payment needed at the end of every period for an amortized loan.
payment_solution: Calculates the payment needed for each period for an amortized loan and creates a struct showing the interest, the formula, and optionally the period-by-period values.
periods: Returns the number of periods given a periodic rate along with the present and future values, using simple compounding.
periods_solution: Calculates the number of periods given a periodic rate along with the present and future values using simple compounding; and builds a struct with the input values, an explanation of the formula, and the option to calculate the period-by-period values.
ppmt: Principal portion of the payment for a single period (Excel PPMT).
present_value: Returns the current value of a future amount using a fixed rate.
present_value_annuity: Returns the present value of an annuity (series of constant cashflows) at a constant rate. Returns f64.
present_value_annuity_accumulator
present_value_annuity_solution: Returns the present value of a future series of constant cashflows and constant rate. Returns custom solution type with additional information and functionality.
present_value_schedule: Calculates a present value based on rates that change for each period.
present_value_schedule_solution: Calculates a present value based on rates that change for each period and returns a struct with the inputs and the calculated value.
present_value_solution: Calculates the current value of a future amount using a fixed rate and returns a struct with the inputs and the calculated value. This is used for keeping track of a collection of financial scenarios so that they can be examined later.
price_path_solution: Build a PricePathSolution summarizing returns, risk, and period detail for a price path.
price_volatility: Volatility of simple returns computed from consecutive prices.
rate: Returns the periodic rate of an investment given the number of periods along with the present and future values.
rate_solution: Returns the periodic rate of an investment given the number of periods along with the present and future values.
rolling_max_drawdown: Running maximum drawdown magnitude observed up to each price index.
round_2: Round to two decimal places. This function uses f64::round() which rounds halfway cases away from 0.0.
round_4: Round to four decimal places. This function uses f64::round() which rounds halfway cases away from 0.0.
round_6: Round to six decimal places. This function uses f64::round() which rounds halfway cases away from 0.0.
round_8: Round to eight decimal places. This function uses f64::round() which rounds halfway cases away from 0.0.
rule_of_69: Approximate years to double using the Rule of 69: 69 / (100 * rate).
rule_of_70: Approximate years to double using the Rule of 70: 70 / (100 * rate).
rule_of_72: Approximate years to double using the Rule of 72: 72 / (100 * rate).
sharpe_ratio: Sharpe ratio: (mean - risk_free) / volatility over the return series.
simple_return: Simple return between two prices: (p1 - p0) / p0.
simple_returns: Simple returns for consecutive prices: length prices.len() - 1.
sortino_ratio: Sortino ratio: (mean - target) / downside_deviation, using returns below target only.
total_return: Total simple return from first to last price: (end - start) / start.
volatility: Sample standard deviation of a return series (population divisor n - 1).
volatility_annualized: Annualized volatility: volatility(returns) * sqrt(periods_per_year).

Type Aliases§

FinanceResult: Result alias for fallible finance functions.