Financial calculations for cash-flow analysis, time value of money, depreciation, and risk.
The functions are organised into domain modules:
Finance.CashFlow— net present value and internal rate of return (npv,xnpv,irr,xirr,mirr), plus batchedirr_many/xirr_many.Finance.TVM— time value of money (pv,fv,pmt,ipmt,ppmt,nper,rate) andamortization_schedule.Finance.Rates— rate conversions (effective_annual_rate,nominal_rate,continuous_to_periodic).Finance.Bonds— fixed income (price,ytm,duration,modified_duration,convexity).Finance.Depreciation—sln,syd,ddb,db.Finance.Returns— performance and risk metrics (volatility,cagr,payback_period,discounted_payback_period,profitability_index,twr).Finance.Solver— the root-finding strategy behind the rate functions, swappable via the:solveroption orconfig :finance, solver: MySolver(the default isFinance.Solver.Newton;Finance.Solver.Brentis a derivative-free alternative that is faster on long-horizon flows).
Deprecated flat API
The functions that lived directly on Finance before 1.2 (e.g. Finance.xirr/1)
still work, but those delegators are deprecated and will be removed in 2.0 —
call the domain module instead, for example:
Finance.CashFlow.xirr([{~D[2019-01-01], -1000}, {~D[2020-01-01], 1100}])
#=> {:ok, 0.1}Functions added since 1.2 exist only on their domain module.
Options
The rate functions and the npv/xnpv value functions take an optional keyword
list. Options are validated with nimble_options: an unknown key or bad value
raises, while problems with the data come back as {:error, reason}.
:guess- initial rate for the solver; for a series with more than one rate, selects the one nearest the guess The default value is0.1.:tolerance- convergence threshold on the rate: iterating stops once the step (or bracket width) falls below it The default value is1.0e-9.:max_iterations(pos_integer/0) - cap on solver iterations; the current bracketed estimate is returned if it is reached The default value is100.:precision- decimal places the result is rounded to (0..15) The default value is6.:solver(atom/0) - module implementing theFinance.Solverbehaviour; defaults toFinance.Solver.Newton, with the derivative-freeFinance.Solver.Brentalso available
Summary
Types
A cash-flow amount: a number, a Decimal, or an ex_money %Money{} (when
those optional libraries are installed). A single series may not mix currencies.
A cash flow on a given date. Money coming in is positive, money going out is negative.
A reason returned as {:error, reason} when the data can't yield a result.
A keyword option accepted by the rate-finding and value functions.
An annual rate of return expressed as a fraction, so 0.1 means 10%.
Functions
See Finance.TVM.fv/5.
See Finance.TVM.fv!/5.
See Finance.TVM.nper/5.
See Finance.TVM.nper!/5.
See Finance.TVM.pmt/5.
See Finance.TVM.pmt!/5.
See Finance.TVM.pv/5.
See Finance.TVM.pv!/5.
Types
A cash-flow amount: a number, a Decimal, or an ex_money %Money{} (when
those optional libraries are installed). A single series may not mix currencies.
A cash flow on a given date. Money coming in is positive, money going out is negative.
A date, given either as a Date struct or as an Erlang-style {year, month, day} tuple.
@type error() ::
:mismatched_lengths
| :insufficient_data
| :single_signed_flow
| :invalid_date
| :did_not_converge
| :undefined
| :mixed_currencies
A reason returned as {:error, reason} when the data can't yield a result.
@type option() :: {:guess, number()} | {:tolerance, number()} | {:max_iterations, pos_integer()} | {:precision, non_neg_integer()} | {:solver, module()}
A keyword option accepted by the rate-finding and value functions.
@type rate() :: float()
An annual rate of return expressed as a fraction, so 0.1 means 10%.
Functions
See Finance.TVM.fv/5.
See Finance.TVM.fv!/5.
See Finance.TVM.nper/5.
See Finance.TVM.nper!/5.
See Finance.TVM.pmt/5.
See Finance.TVM.pmt!/5.
See Finance.TVM.pv/5.
See Finance.TVM.pv!/5.
See Finance.TVM.rate/6.
See Finance.TVM.rate!/6.