# `NumberF.Financial`
[🔗](https://github.com/jamesnjovu/elixir_number_functions/blob/v0.3.0/lib/number_f/financial.ex#L1)

Functions for financial calculations such as interest, EMI, and currency conversion.

# `amortization_schedule`

Full amortization schedule for a loan, one entry per period.

Each entry gives the payment, how much of it is principal, how much is interest,
and the balance remaining afterwards.

## Precision

The final period absorbs any accumulated rounding so the balance closes at
exactly zero, which is what a lender's schedule does.

## Examples

    iex> schedule = NumberF.Financial.amortization_schedule(100_000, 0.10, 12)
    iex> length(schedule)
    12
    iex> List.last(schedule).balance
    0.0

# `annuity_future_value`

Future value of a stream of equal payments.

## Examples

    iex> NumberF.Financial.annuity_future_value(100, 0.05, 10)
    1257.79

# `annuity_payment`

Payment required to amortise a present value over n periods.

## Examples

    iex> NumberF.Financial.annuity_payment(10_000, 0.05, 10)
    1295.05

# `annuity_present_value`

Present value of a stream of equal payments.

## Examples

    iex> NumberF.Financial.annuity_present_value(100, 0.05, 10)
    772.17

# `break_even_point`

Units that must be sold to cover fixed costs.

## Examples

    iex> NumberF.Financial.break_even_point(10_000, 25, 15)
    1000.0

# `cagr`

Compound annual growth rate, as a percentage.

## Examples

    iex> NumberF.Financial.cagr(1000, 2000, 5)
    14.87

# `calculate_emi`

Calculates EMI (Equated Monthly Installment).

# `compound_interest`

Calculates compound interest.

# `convert_currency`

Converts currency based on exchange rates.

# `depreciation_declining_balance`

Declining-balance depreciation schedule, one entry per year.

`factor` defaults to 2, giving the double-declining-balance method. Depreciation
stops at the salvage value.

## Examples

    iex> schedule = NumberF.Financial.depreciation_declining_balance(10_000, 1_000, 5)
    iex> hd(schedule)
    %{year: 1, depreciation: 4000.0, book_value: 6000.0}

# `depreciation_straight_line`

Straight-line depreciation per year.

## Examples

    iex> NumberF.Financial.depreciation_straight_line(10_000, 1_000, 5)
    1800.0

# `effective_annual_rate`

Effective annual rate for a nominal rate compounded n times per year.

## Examples

    iex> NumberF.Financial.effective_annual_rate(0.12, 12)
    0.1268

# `future_value`

Future value of a present sum compounded at a periodic rate.

## Examples

    iex> NumberF.Financial.future_value(1000, 0.05, 10)
    1628.89

# `irr`

Internal rate of return: the discount rate at which `npv/2` is zero.

Returns `{:ok, rate}` or `{:error, :no_convergence}`.

## Edge cases

Solved numerically by bisection, so it needs the cash flows to change sign at
least once — an all-positive or all-negative series has no IRR and returns
`{:error, :no_sign_change}`. A series that changes sign more than once can have
several mathematically valid answers; this returns the one in `-0.9999..10`.

## Examples

    iex> {:ok, rate} = NumberF.Financial.irr([-1000, 300, 400, 500, 600])
    iex> Float.round(rate, 4)
    0.2489

# `loan_payment`

Level payment for a loan. A zero-rate-safe alias for `calculate_emi/3`.

## Examples

    iex> NumberF.Financial.loan_payment(100_000, 0.0, 12)
    8333.33

# `npv`

Net present value of a series of cash flows.

The first element is treated as occurring at t=0 and is not discounted, which is
the convention a negative initial investment implies.

## Examples

    iex> NumberF.Financial.npv(0.1, [-1000, 300, 400, 500, 600])
    388.77

# `payback_period`

Years until cumulative cash flows repay an initial investment.

Interpolates within the year the investment is recovered. Returns
`{:error, :never_recovered}` when the flows never add up to the investment.

## Examples

    iex> NumberF.Financial.payback_period(1000, [300, 400, 500])
    {:ok, 2.6}

# `present_value`

Present value of a future sum discounted at a periodic rate.

## Examples

    iex> NumberF.Financial.present_value(1000, 0.05, 10)
    613.91

# `roi`

Return on investment, as a percentage.

## Examples

    iex> NumberF.Financial.roi(1500, 1000)
    50.0

# `simple_interest`

Calculates simple interest.

---

*Consult [api-reference.md](api-reference.md) for complete listing*