@spec irr([amount()]) :: {:ok, rate()} | {:error, error()}

Computes the IRR — the internal rate of return for a list of amounts that occur at equally spaced periods 0, 1, 2, …. Think of it as xirr/2 for the common case where your flows land at regular intervals and you don't need to track exact dates.

What comes back is the rate per period. As with xirr/2, the series has to contain at least one positive amount and one negative one.

iex> Finance.CashFlow.irr([-1000, 1100])
{:ok, 0.1}

iex> Finance.CashFlow.irr([-1000, 500, 500, 300])
{:ok, 0.156579}

@spec irr([amount()], [option()]) :: {:ok, rate()} | {:error, error()}

Same as irr/1, and additionally takes the same options as xirr/2.

@spec irr!([amount()], [option()]) :: rate()

Same as irr/1, but returns the rate directly and raises ArgumentError on error.

@spec mirr([amount()], number(), number(), [option()]) ::
  {:ok, rate()} | {:error, error()}

Computes the MIRR — the modified internal rate of return for periodic amounts. It refines the idea behind IRR by letting you set two separate rates: positive flows are assumed to be reinvested at reinvest_rate, and negative flows are assumed to be financed at finance_rate.

Because those assumptions are spelled out, MIRR has a closed form and a single answer, which sidesteps the multiple-root and convergence trouble that IRR can run into. As with irr/1, the series has to contain at least one positive amount and one negative one.

iex> Finance.CashFlow.mirr([-120_000, 39_000, 30_000, 21_000, 37_000, 46_000], 0.10, 0.12)
{:ok, 0.126094}

@spec mirr!([amount()], number(), number(), [option()]) :: rate()

Same as mirr/3, but returns the rate directly and raises ArgumentError on error.

@spec npv(rate(), [amount()]) :: {:ok, number()} | {:error, error()}

Computes the periodic NPV — the net present value of amounts occurring at equally spaced periods 0, 1, 2, …, discounted at rate.

Σ amount_i / (1 + rate)^i    (i starting at 0)

iex> Finance.CashFlow.npv(0.1, [-1000, 1100])
{:ok, 0.0}

iex> Finance.CashFlow.npv(0.1, [-1000, 600, 600])
{:ok, 41.322314}

@spec npv(rate(), [amount()], [option()]) :: {:ok, number()} | {:error, error()}

Same as npv/2, and additionally takes a :precision option. See npv/2.

@spec npv!(rate(), [amount()]) :: number()

Same as npv/2, but returns the value directly and raises ArgumentError on error.

@spec xirr([cash_flow()]) :: {:ok, rate()} | {:error, error()}

Finds the XIRR of a list of {date, amount} cash flows — the annual rate of return that the flows imply, given when each one lands.

Reach for this when your cash flows happen on irregular dates rather than at neat intervals. See xirr/2 if you want to pass options or use the two-list form.

iex> Finance.CashFlow.xirr([{~D[2015-06-01], 1_000_000}, {~D[2015-10-01], -2_200_000}, {~D[2015-11-01], -800_000}])
{:ok, 21.118359}

@spec xirr([cash_flow()], [option()]) :: {:ok, rate()} | {:error, error()}

@spec xirr([date()], [amount()]) :: {:ok, rate()} | {:error, error()}

Finds the XIRR, accepting either {date, amount} pairs together with options, or two parallel lists — one of dates, one of amounts.

The result is {:ok, rate} on success or {:error, reason} when the data can't yield a rate. Flows that fall on the same date are added together first. The series has to include at least one positive amount and one negative one, because without money flowing both in and out there is no return to solve for.

iex> Finance.CashFlow.xirr([{~D[2019-01-01], -1000}, {~D[2020-01-01], 1100}], guess: 0.5)
{:ok, 0.1}

iex> Finance.CashFlow.xirr([~D[2019-01-01], ~D[2020-01-01]], [-1000, 1100])
{:ok, 0.1}

@spec xirr([date()], [amount()], [option()]) :: {:ok, rate()} | {:error, error()}

Finds the XIRR from two parallel lists — dates and amounts — while also taking options for the solver.

iex> Finance.CashFlow.xirr([~D[2019-01-01], ~D[2020-01-01]], [-1000, 1100], precision: 2)
{:ok, 0.1}

@spec xirr!([cash_flow()]) :: rate()

Same as xirr/1, but returns the rate directly and raises ArgumentError on error.

@spec xirr!([cash_flow()] | [date()], [option()] | [amount()]) :: rate()

Same as xirr/2, but returns the rate directly and raises ArgumentError on error.

@spec xnpv(rate(), [cash_flow()]) :: {:ok, number()} | {:error, error()}

Computes the XNPV — the net present value of a set of dated cash flows, discounted back at rate.

Σ cf_i / (1 + rate)^t_i

Each time t_i is measured in years from the earliest flow on an Actual/365 basis, the same day-count convention xirr/2 uses. That shared convention is what ties the two together: xnpv(r, flows) comes out to roughly zero when r is xirr(flows), so this is a handy way to check an XIRR result. And because a net present value is defined for any series, the flows here don't have to change sign the way xirr/2 requires.

The result is {:ok, value} or {:error, reason}. Flows on the same date are added together first, and you can pass the same :precision option as xirr/2 (it defaults to 6).

iex> Finance.CashFlow.xnpv(0.1, [{~D[2019-01-01], -1000}, {~D[2020-01-01], 1000}])
{:ok, -90.909091}

iex> Finance.CashFlow.xnpv(0.1, [{~D[2019-01-01], -1000}, {~D[2020-01-01], 1100}])
{:ok, 0.0}

@spec xnpv(rate(), [cash_flow()], [option()]) :: {:ok, number()} | {:error, error()}

Same as xnpv/2, and additionally takes a :precision option. See xnpv/2.

@spec xnpv!(rate(), [cash_flow()]) :: number()

Same as xnpv/2, but returns the value directly and raises ArgumentError on error.