Crate finance_solution

Expand description

finance_solution is a collection of financial functions for time-value-of-money, cashflows, amortization, returns, equity path metrics, technical analysis (stocks::ta), and European option math (derivatives: BSM + Black ’76 + Garman–Kohlhagen; price, Greeks, cross Greeks, IV).

In addition to being rigorously tested with symmetry tests, Excel-matching tests, and property tests on TA batch↔stream parity, the library provides solution structs with formulas and period-by-period series — useful for financial software audit trails and for students of finance. Live systems can use incremental *State types (push / push_bars) without this crate owning market data or multi-symbol orchestration.

§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, SmaState::new) is the fallible function when construction or domain validation can fail.

§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.
atr: Average True Range (ATR)
bollinger: Bollinger Bands
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.
derivatives: Derivatives math (options & related)
donchian: Donchian channels
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?
keltner: Keltner Channels
linear_regression: Rolling least-squares linear regression
macd: MACD (Moving Average Convergence Divergence)
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.
rsi: Relative Strength Index (RSI)
rule_of_72: Approximate years to double (Rule of 72 / 69 / 70) and exact doubling time.
rvol: Relative volume (RVOL)
stocks: Ordered price-path analytics (equities or any positive price series).
ta: Technical analysis indicators on price / volume 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, domain newtypes, root-finding.
vwap: VWAP (volume-weighted average price)

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.
AtrParams: ATR lookback pack (Wilder).
AtrSeries
AtrSolution
AtrState: Incremental Wilder ATR.
Black76Greeks: First-order Black ’76 Greeks (Δ is forward delta).
Black76Params: Black ’76 inputs (European option on a forward).
Black76Solution: Teaching solution for Black ’76.
Black76State: Live Black ’76 contract state (forward / vol / time updates).
Black76Terms: d1/d2 and discount for Black ’76.
BollingerBarOutput: One-bar Bollinger output.
BollingerParams: Bollinger parameter pack.
BollingerSeries: Middle / upper / lower / %B series.
BollingerSolution: Teaching solution + table.
BollingerState: Incremental Bollinger Bands (sample stdev on the window).
BsmCrossGreeks: Cross / second-order BSM Greeks (vol surface & hedge-drift risk).
BsmGreeks: First-order BSM Greeks.
BsmParams: Black–Scholes–Merton inputs (European, continuous dividend yield q).
BsmSolution: Teaching solution: price, greeks, cross Greeks, parity check, formulas.
BsmState: Mutable European option under BSM (spot / vol / time / strike updates).
BsmTerms: Intermediate terms shared by price and Greeks (d1, d2, discounts).
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
CrrGreeks: Tree first-order risk (Δ/Γ from nodes; vega bumped).
CrrNode: One node for teaching tables.
CrrParams: CRR tree inputs (equity-style continuous (q)).
CrrSolution: Full teaching solution.
DonchianBarOutput
DonchianParams: Donchian lookback.
DonchianSeries
DonchianSolution
DonchianState: Incremental Donchian.
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.
EmaState: Incremental EMA (α = 2/(period+1), seed = SMA of first period closes).
GkGreeks: GK Greeks: BSM-style plus dual rate rhos.
GkParams: Garman–Kohlhagen inputs.
GkSolution: Teaching solution for GK.
GkState: Live FX option state.
HmaState: Hull moving average state.
KeltnerBarOutput
KeltnerParams: Keltner parameter pack (Wilder ATR).
KeltnerSeries
KeltnerSolution
KeltnerState: Incremental Keltner (EMA mid + Wilder ATR).
LinRegBar: One fitted window.
LinRegParams: Rolling regression window length.
LinRegSolution
LinRegState: Incremental rolling regression on a caller-chosen series.
MacdParams: MACD parameter pack: fast < slow, all periods ≥ 1.
MacdSeries: Aligned MACD / signal / histogram series.
MacdSolution: Teaching wrapper with formula strings and a printable table.
MacdState: Incremental MACD (fast/slow/signal EMAs).
Money: Finite signed monetary amount (no currency unit — pure magnitude + sign).
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
PeriodLength: Positive lookback / window length for technical indicators (usize ≥ 1).
Periods: Count of compounding / payment periods (u32).
PositivePrice: Strictly positive finite price (or similar quantity used as a price level).
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.
Rate: Periodic or continuous interest / return rate as a decimal (e.g. 0.05 = 5%).
RsiParams: RSI lookback pack (Wilder).
RsiSeries
RsiSolution
RsiState: Incremental Wilder RSI.
RvolParams: RVOL lookback pack.
RvolSeries
RvolSolution
RvolState: Incremental relative volume.
ScenarioEntry
ScenarioList
SmaState: Incremental SMA. After warm-up, each SmaState::push is O(1).
StochBarOutput: One-bar stochastic output (warm-up allowed as None).
StochState: Incremental stochastic (fast/full via StochasticParams).
StochasticParams: Unvalidated (but Copy) stochastic parameter pack.
StochasticSeries: Aligned %K / %D output.
StochasticSolution: Teaching wrapper around StochasticSeries.
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
ValidatedAtr: Validated ATR config.
ValidatedBlack76: Validated Black ’76 snapshot.
ValidatedBollinger: Validated Bollinger config.
ValidatedBsm: Validated BSM pack (strictly positive S,K; non-negative T,σ; finite rates).
ValidatedCrr: Validated CRR pack.
ValidatedDonchian
ValidatedGk: Validated GK snapshot.
ValidatedKeltner: Validated Keltner config.
ValidatedLinReg: Validated pack.
ValidatedMacd: Validated MACD config for reuse across many close series.
ValidatedRsi: Validated RSI config.
ValidatedRvol: Validated RVOL config.
ValidatedStochastic: Params that passed period validation — safe to use in a tight loop.
ValidatedVwap: Validated VWAP config.
VwapParams: VWAP parameter pack.
VwapSeries
VwapSolution
VwapState: Incremental VWAP (cumulative or rolling). Call VwapState::reset at session open if desired.
WmaState: Incremental WMA: newest sample weight = period, oldest weight = 1.

Enums§

CashflowVariable
Compounding: How interest compounds in a TVM calculation.
ConvertRateVariable: The possible types of rates to convert.
ExerciseStyle: European vs American exercise at each node.
FinanceError: Domain and input errors from finance calculations.
OptionType: Call or put (European exercise in this module).
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.
StdevKind: Which denominator to use for window standard deviation (Bollinger, etc.).
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.
VwapMode: Cumulative session vs rolling window.
VwapPriceSource: Price input for VWAP numerator.

Functions§

american_implied_vol: Alias: American IV when style is American (any style works).
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
atr
atr_solution: Examples
beta: OLS beta of asset returns vs market returns (same length series).
black76_greeks
black76_implied_vol: Implied vol for Black ’76 given a market premium.
black76_parity_residual: C − P − e^{-rT}(F − K).
black76_price
black76_solution
black76_terms
bollinger
bollinger_solution: Teaching solution with formulas + table.
brent_root: Find a root of continuous f on bracket [lo, hi] (Brent 1973).
bsm_cross_greeks: Cross Greeks: vanna, volga, charm (see BsmCrossGreeks).
bsm_greeks: European BSM Greeks (see BsmGreeks for units).
bsm_implied_vol: Solve for annualized vol given a target BSM premium.
bsm_price: European BSM price.
bsm_solution: Full teaching solution (price, greeks, intrinsic, parity, formulas).
bsm_terms: d1/d2 and discount factors (for teaching / advanced use).
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.
crr_greeks: Tree Δ/Γ + FD vega.
crr_price: CRR option price.
crr_solution: Teaching solution; retains nodes when steps <= 12 (readable table).
cumipmt: Cumulative interest paid between two periods inclusive (Excel CUMIPMT).
cumprinc: Cumulative principal paid between two periods inclusive (Excel CUMPRINC).
donchian
donchian_solution
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.
ema: EMA with span period (α = 2 / (period + 1)). Seed = SMA of the first period closes.
ema_last: Last defined EMA value, if any (via EmaState).
epr: Helper function to convert a periodic interest rate (EPR) to all rate conversions.
forward_moneyness: Forward moneyness S e^{(r-q)T} / K.
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.
gk_cross_greeks
gk_greeks
gk_implied_vol
gk_parity_residual: Put–call parity residual: C − P − (S e^{-r_f T} − K e^{-r_d T}).
gk_price
gk_solution
hma: Hull moving average of period (must be ≥ 2).
hma_last
intrinsic: Intrinsic value (European exercise value at this spot).
ipmt: Interest portion of the payment for a single period (Excel IPMT).
keltner
keltner_solution: Examples
linear_regression: Batch rolling OLS. series is your choice of bar field (close, high, …).
linear_regression_solution
log_return: Logarithmic return: ln(p1 / p0). Requires strictly positive prices.
log_returns: Log returns for consecutive prices: length prices.len() - 1.
macd: Free function: validate params then compute.
macd_solution: Solution with formulas + table for teaching / audit.
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.
put_call_parity_residual: Put–call parity residual: C − P − (S e^{−qT} − K e^{−rT}) (≈ 0 for BSM).
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.
rsi
rsi_solution: Examples
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).
rvol
rvol_solution: Examples
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.
sma: SMA of period closes. Leading period - 1 values are None.
sma_last: Last defined SMA value, if any.
sortino_ratio: Sortino ratio: (mean - target) / downside_deviation, using returns below target only.
spot_moneyness: Spot moneyness S / K (not forward-adjusted).
stochastics: Stochastic series with raw (possibly unvalidated) params — validates then computes.
stochastics_solution: Teaching solution: formulas + printable %K/%D table.
time_value: Time value = premium − intrinsic (floored at 0 for numerical noise).
total_return: Total simple return from first to last price: (end - start) / start.
tree_implied_vol: American (or European) implied vol via Newton on CRR price + FD vega.
volatility: Sample standard deviation of a return series (population divisor n - 1).
volatility_annualized: Annualized volatility: volatility(returns) * sqrt(periods_per_year).
vwap
vwap_solution: Examples
wma: Weighted moving average (newest weight = period).
wma_last

Type Aliases§

FinanceResult: Result alias for fallible finance functions.