abaquant.financial_math.annuities¶

Import path: abaquant.financial_math.annuities

Domain: Time-value, actuarial, fixed-income, corporate-finance, and portfolio mathematics.

Purpose¶

Annuity, perpetuity, and gradient cash-flow valuation.

When to use it¶

Use these functions for deterministic calculations where explicit cash-flow, rate, compounding, sign, and annualization conventions matter.

Public objects¶

function: effective_annuity_future_value — Compute accumulated value of a level annuity under an effective period rate.
function: nominal_annuity_future_value — Compute accumulated value of a level annuity under nominal compounding.
function: continuous_annuity_future_value — Compute accumulated value of a continuous cash-flow annuity.
function: effective_annuity_present_value — Compute present value of a level annuity under an effective period rate.
function: nominal_annuity_present_value — Compute present value of a level annuity under nominal compounding.
function: continuous_annuity_present_value — Compute present value of a continuous cash-flow annuity.
function: perpetuity_present_value — Compute the present value of a level perpetuity.
function: geometric_gradient_future_value — Compute accumulated value of a geometric-gradient payment stream.
function: geometric_gradient_present_value — Compute present value of a geometric-gradient payment stream.
function: periods_for_annuity_future_value — Solve the period count for a level-annuity accumulated-value target.
function: periods_for_annuity_present_value — Solve the period count for a level-annuity present-value target.
function: periods_for_geometric_gradient_future_value — Solve the period count for a geometric-gradient accumulated-value target.
function: periods_for_geometric_gradient_present_value — Solve the period count for a geometric-gradient present-value target.
function: arithmetic_gradient_present_value — Compute present value of an arithmetic-gradient payment stream.
function: arithmetic_gradient_future_value — Compute accumulated value of an arithmetic-gradient payment stream.
function: periods_for_arithmetic_gradient_future_value — Solve the period count for an arithmetic-gradient accumulated-value target.
function: periods_for_arithmetic_gradient_present_value — Solve the period count for an arithmetic-gradient present-value target.

Detailed reference¶

Annuity, perpetuity, and gradient cash-flow valuation.

Purpose¶

The module values level, continuous, geometric-gradient, and arithmetic-gradient cash-flow streams and solves selected period-count equations.

Conventions¶

Rates are decimal rates per stated period. Payments are assumed to occur at period end unless the due flag or function definition states otherwise.

Scope and limitations¶

The formulas assume deterministic rates and cash flows.

References

[ 1 ] Kellison, S. G. (2009), The Theory of Interest.

abaquant.financial_math.annuities.arithmetic_gradient_future_value(R1, G, i_m, n_m)¶

Compute accumulated value of an arithmetic-gradient payment stream.

Parameters:

R1 (float) – First payment in a gradient cash-flow stream, in currency units.
G (float) – Arithmetic increment added to each successive payment, in currency units per period.
i_m (float) – Effective interest rate per gradient-payment period in decimal units.
n_m (float) – Number of gradient-payment periods.

Returns:

Computed arithmetic gradient future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.arithmetic_gradient_present_value(R1, G, i_m, n_m)¶

Compute present value of an arithmetic-gradient payment stream.

Parameters:

R1 (float) – First payment in a gradient cash-flow stream, in currency units.
G (float) – Arithmetic increment added to each successive payment, in currency units per period.
i_m (float) – Effective interest rate per gradient-payment period in decimal units.
n_m (float) – Number of gradient-payment periods.

Returns:

Computed arithmetic gradient present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.continuous_annuity_future_value(annual_flow, delta, years)¶

Compute accumulated value of a continuous cash-flow annuity.

Parameters:

annual_flow (float) – Continuous cash-flow rate in currency units per year.
delta (float) – Constant force of interest in decimal annual units.
years (float) – Time horizon in years.

Returns:

Computed continuous annuity future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.continuous_annuity_present_value(annual_flow, delta, years)¶

Compute present value of a continuous cash-flow annuity.

Parameters:

annual_flow (float) – Continuous cash-flow rate in currency units per year.
delta (float) – Constant force of interest in decimal annual units.
years (float) – Time horizon in years.

Returns:

Computed continuous annuity present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.effective_annuity_future_value(payment, period_rate, periods, due=False)¶

Compute accumulated value of a level annuity under an effective period rate.

Parameters:

payment (float) – Level payment amount in currency units per payment period.
period_rate (float) – Effective interest rate per payment period in decimal units.
periods (float) – Number of discrete compounding or payment periods.
due (bool, default=False) – Whether annuity payments occur at the beginning rather than end of each period.

Returns:

Computed effective annuity future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.effective_annuity_present_value(payment, period_rate, periods, due=False)¶

Compute present value of a level annuity under an effective period rate.

Parameters:

payment (float) – Level payment amount in currency units per payment period.
period_rate (float) – Effective interest rate per payment period in decimal units.
periods (float) – Number of discrete compounding or payment periods.
due (bool, default=False) – Whether annuity payments occur at the beginning rather than end of each period.

Returns:

Computed effective annuity present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.geometric_gradient_future_value(R1, i_m, q_m, n_m)¶

Compute accumulated value of a geometric-gradient payment stream.

Parameters:

R1 (float) – First payment in a gradient cash-flow stream, in currency units.
i_m (float) – Effective interest rate per gradient-payment period in decimal units.
q_m (float) – Growth rate of payments per gradient period in decimal units.
n_m (float) – Number of gradient-payment periods.

Returns:

Computed geometric gradient future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.geometric_gradient_present_value(R1, i, q, n)¶

Compute present value of a geometric-gradient payment stream.

Parameters:

R1 (float) – First payment in a gradient cash-flow stream, in currency units.
i (float) – Effective interest rate per period in decimal units.
q (float) – Continuous dividend or carry yield in decimal annual units.
n (float) – Number of discrete periods, assets, or observations as determined by the callable.

Returns:

Computed geometric gradient present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.nominal_annuity_future_value(payment, nominal_rate, compounding_frequency, payment_frequency, years)¶

Compute accumulated value of a level annuity under nominal compounding.

Parameters:

payment (float) – Level payment amount in currency units per payment period.
nominal_rate (float) – Nominal annual interest rate in decimal units.
compounding_frequency (int | float) – Positive number of nominal compounding periods per year.
payment_frequency (int | float) – Positive number of payments per year.
years (float) – Time horizon in years.

Returns:

Computed nominal annuity future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.nominal_annuity_present_value(payment, nominal_rate, compounding_frequency, payment_frequency, years)¶

Compute present value of a level annuity under nominal compounding.

Parameters:

payment (float) – Level payment amount in currency units per payment period.
nominal_rate (float) – Nominal annual interest rate in decimal units.
compounding_frequency (int | float) – Positive number of nominal compounding periods per year.
payment_frequency (int | float) – Positive number of payments per year.
years (float) – Time horizon in years.

Returns:

Computed nominal annuity present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.periods_for_annuity_future_value(future_value, payment, period_rate)¶

Solve the period count for a level-annuity accumulated-value target.

Parameters:

future_value (float) – Target accumulated amount in currency units.
payment (float) – Level payment amount in currency units per payment period.
period_rate (float) – Effective interest rate per payment period in decimal units.

Returns:

Computed periods for annuity future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.periods_for_annuity_present_value(present_value, payment, period_rate)¶

Solve the period count for a level-annuity present-value target.

Parameters:

present_value (float) – Target present amount in currency units.
payment (float) – Level payment amount in currency units per payment period.
period_rate (float) – Effective interest rate per payment period in decimal units.

Returns:

Computed periods for annuity present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.periods_for_arithmetic_gradient_future_value(future_value, R1, G, i_m)¶

Solve the period count for an arithmetic-gradient accumulated-value target.

Parameters:

future_value (float) – Target accumulated amount in currency units.
R1 (float) – First payment in a gradient cash-flow stream, in currency units.
G (float) – Arithmetic increment added to each successive payment, in currency units per period.
i_m (float) – Effective interest rate per gradient-payment period in decimal units.

Returns:

Computed periods for arithmetic gradient future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.periods_for_arithmetic_gradient_present_value(present_value, R1, G, i_m)¶

Solve the period count for an arithmetic-gradient present-value target.

Parameters:

present_value (float) – Target present amount in currency units.
R1 (float) – First payment in a gradient cash-flow stream, in currency units.
G (float) – Arithmetic increment added to each successive payment, in currency units per period.
i_m (float) – Effective interest rate per gradient-payment period in decimal units.

Returns:

Computed periods for arithmetic gradient present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.periods_for_geometric_gradient_future_value(future_value, R1, i_m, q_m)¶

Solve the period count for a geometric-gradient accumulated-value target.

Parameters:

future_value (float) – Target accumulated amount in currency units.
R1 (float) – First payment in a gradient cash-flow stream, in currency units.
i_m (float) – Effective interest rate per gradient-payment period in decimal units.
q_m (float) – Growth rate of payments per gradient period in decimal units.

Returns:

Computed periods for geometric gradient future value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.periods_for_geometric_gradient_present_value(present_value, R1, i_m, q_m)¶

Solve the period count for a geometric-gradient present-value target.

Parameters:

present_value (float) – Target present amount in currency units.
R1 (float) – First payment in a gradient cash-flow stream, in currency units.
i_m (float) – Effective interest rate per gradient-payment period in decimal units.
q_m (float) – Growth rate of payments per gradient period in decimal units.

Returns:

Computed periods for geometric gradient present value as a scalar in the units implied by the input values.

Return type:

float

abaquant.financial_math.annuities.perpetuity_present_value(payment, rate)¶

Compute the present value of a level perpetuity.

Parameters:

payment (float) – Level payment amount in currency units per payment period.
rate (float) – Interest rate in decimal units under the stated compounding convention.

Returns:

Computed perpetuity present value as a scalar in the units implied by the input values.

Return type:

float