Module Reference

This section provides comprehensive documentation for all qfinbox modules and submodules.

Main Package

qfinbox: A Python library for quantitative finance.

qfinbox provides tools for risk management, portfolio optimization, and financial modeling. It enables easy simulation of market scenarios and investment strategy optimization, enhancing financial analysis and decision-making.

exception qfinbox.CalculationError

Bases: QFinBoxError

Raised when mathematical calculations fail.

exception qfinbox.DataError

Bases: QFinBoxError

Raised when there are issues with data processing.

exception qfinbox.QFinBoxError

Bases: Exception

Base exception for qfinbox.

exception qfinbox.ValidationError

Bases: QFinBoxError

Raised when input validation fails.

qfinbox.calculate_annualized_return(returns: ndarray, frequency: int = 252) → float

Calculate annualized return from a series of returns.

Parameters:

• returns (np.ndarray) – Array of returns.

• frequency (int, default 252) – Number of periods per year (252 for daily, 12 for monthly).

Returns:

Annualized return.

Return type:

float

qfinbox.calculate_annualized_volatility(returns: ndarray, frequency: int = 252) → float

Calculate annualized volatility from a series of returns.

Parameters:

• returns (np.ndarray) – Array of returns.

• frequency (int, default 252) – Number of periods per year (252 for daily, 12 for monthly).

Returns:

Annualized volatility.

Return type:

float

qfinbox.ensure_1d(data: ndarray | Series | list) → ndarray

Ensure data is a 1D numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

1D numpy array.

Return type:

np.ndarray

Raises:

ValueError – If data cannot be converted to 1D array.

qfinbox.ensure_2d(data: ndarray | DataFrame | list) → ndarray

Ensure data is a 2D numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

2D numpy array.

Return type:

np.ndarray

qfinbox.to_numpy(data: ndarray | Series | DataFrame | list) → ndarray

Convert data to numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

Data as numpy array.

Return type:

np.ndarray

qfinbox.validate_positive(value: float, name: str = 'value') → float

Validate that a value is positive.

Parameters:

• value (float) – Value to validate.

• name (str, default "value") – Name of the parameter for error messages.

Returns:

The validated value.

Return type:

float

Raises:

ValidationError – If value is not positive.

qfinbox.validate_returns(returns: ndarray | Series | DataFrame) → ndarray

Validate return data.

Parameters:

returns (array-like) – Return data to validate.

Returns:

Validated returns as numpy array.

Return type:

np.ndarray

Raises:

ValidationError – If returns are invalid.

qfinbox.validate_weights(weights: ndarray | Series | list) → ndarray

Validate portfolio weights.

Parameters:

weights (array-like) – Portfolio weights to validate.

Returns:

Validated weights as numpy array.

Return type:

np.ndarray

Raises:

ValidationError – If weights are invalid.

Core Utilities

Core modules providing validation, error handling, and utility functions.

qfinbox.core package

Core utilities and functions for qfinbox.

exception qfinbox.core.CalculationError

Bases: QFinBoxError

Raised when mathematical calculations fail.

exception qfinbox.core.DataError

Bases: QFinBoxError

Raised when there are issues with data processing.

exception qfinbox.core.QFinBoxError

Bases: Exception

Base exception for qfinbox.

exception qfinbox.core.ValidationError

Bases: QFinBoxError

Raised when input validation fails.

qfinbox.core.calculate_annualized_return(returns: ndarray, frequency: int = 252) → float

Calculate annualized return from a series of returns.

Parameters:

• returns (np.ndarray) – Array of returns.

• frequency (int, default 252) – Number of periods per year (252 for daily, 12 for monthly).

Returns:

Annualized return.

Return type:

float

qfinbox.core.calculate_annualized_volatility(returns: ndarray, frequency: int = 252) → float

Calculate annualized volatility from a series of returns.

Parameters:

• returns (np.ndarray) – Array of returns.

• frequency (int, default 252) – Number of periods per year (252 for daily, 12 for monthly).

Returns:

Annualized volatility.

Return type:

float

qfinbox.core.ensure_1d(data: ndarray | Series | list) → ndarray

Ensure data is a 1D numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

1D numpy array.

Return type:

np.ndarray

Raises:

ValueError – If data cannot be converted to 1D array.

qfinbox.core.ensure_2d(data: ndarray | DataFrame | list) → ndarray

Ensure data is a 2D numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

2D numpy array.

Return type:

np.ndarray

qfinbox.core.to_numpy(data: ndarray | Series | DataFrame | list) → ndarray

Convert data to numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

Data as numpy array.

Return type:

np.ndarray

qfinbox.core.validate_positive(value: float, name: str = 'value') → float

Validate that a value is positive.

Parameters:

• value (float) – Value to validate.

• name (str, default "value") – Name of the parameter for error messages.

Returns:

The validated value.

Return type:

float

Raises:

ValidationError – If value is not positive.

qfinbox.core.validate_returns(returns: ndarray | Series | DataFrame) → ndarray

Validate return data.

Parameters:

returns (array-like) – Return data to validate.

Returns:

Validated returns as numpy array.

Return type:

np.ndarray

Raises:

ValidationError – If returns are invalid.

qfinbox.core.validate_weights(weights: ndarray | Series | list) → ndarray

Validate portfolio weights.

Parameters:

weights (array-like) – Portfolio weights to validate.

Returns:

Validated weights as numpy array.

Return type:

np.ndarray

Raises:

ValidationError – If weights are invalid.

qfinbox.core.exceptions module

Custom exceptions for qfinbox.

exception qfinbox.core.exceptions.QFinBoxError

Bases: Exception

Base exception for qfinbox.

exception qfinbox.core.exceptions.ValidationError

Bases: QFinBoxError

Raised when input validation fails.

exception qfinbox.core.exceptions.DataError

Bases: QFinBoxError

Raised when there are issues with data processing.

exception qfinbox.core.exceptions.CalculationError

Bases: QFinBoxError

Raised when mathematical calculations fail.

qfinbox.core.validators module

Input validation utilities for qfinbox.

qfinbox.core.validators.validate_weights(weights: ndarray | Series | list) → ndarray

Validate portfolio weights.

Parameters:

weights (array-like) – Portfolio weights to validate.

Returns:

Validated weights as numpy array.

Return type:

np.ndarray

Raises:

ValidationError – If weights are invalid.

qfinbox.core.validators.validate_returns(returns: ndarray | Series | DataFrame) → ndarray

Validate return data.

Parameters:

returns (array-like) – Return data to validate.

Returns:

Validated returns as numpy array.

Return type:

np.ndarray

Raises:

ValidationError – If returns are invalid.

qfinbox.core.validators.validate_positive(value: float, name: str = 'value') → float

Validate that a value is positive.

Parameters:

• value (float) – Value to validate.

• name (str, default "value") – Name of the parameter for error messages.

Returns:

The validated value.

Return type:

float

Raises:

ValidationError – If value is not positive.

qfinbox.core.utils module

Common utilities for qfinbox.

qfinbox.core.utils.to_numpy(data: ndarray | Series | DataFrame | list) → ndarray

Convert data to numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

Data as numpy array.

Return type:

np.ndarray

qfinbox.core.utils.ensure_1d(data: ndarray | Series | list) → ndarray

Ensure data is a 1D numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

1D numpy array.

Return type:

np.ndarray

Raises:

ValueError – If data cannot be converted to 1D array.

qfinbox.core.utils.ensure_2d(data: ndarray | DataFrame | list) → ndarray

Ensure data is a 2D numpy array.

Parameters:

data (array-like) – Data to convert.

Returns:

2D numpy array.

Return type:

np.ndarray

qfinbox.core.utils.calculate_annualized_return(returns: ndarray, frequency: int = 252) → float

Calculate annualized return from a series of returns.

Parameters:

• returns (np.ndarray) – Array of returns.

• frequency (int, default 252) – Number of periods per year (252 for daily, 12 for monthly).

Returns:

Annualized return.

Return type:

float

qfinbox.core.utils.calculate_annualized_volatility(returns: ndarray, frequency: int = 252) → float

Calculate annualized volatility from a series of returns.

Parameters:

• returns (np.ndarray) – Array of returns.

• frequency (int, default 252) – Number of periods per year (252 for daily, 12 for monthly).

Returns:

Annualized volatility.

Return type:

float

Time Value of Money Module

Comprehensive TVM calculations across five specialized modules.

qfinbox.tvm package

Time Value of Money calculations for qfinbox.

qfinbox.tvm.amortization_schedule(principal: float, annual_rate: float, years: float, payments_per_year: int = 12) → DataFrame

Generate loan amortization schedule.

Parameters:

• principal (float) – Loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Amortization schedule with columns: Payment, Interest, Principal, Balance.

Return type:

pd.DataFrame

Examples

>>> schedule = amortization_schedule(300000, 0.05, 30)
>>> schedule.head()
   Payment  Interest   Principal      Balance
0  1610.46   1250.00     360.46   299639.54
1  1610.46   1248.50     361.96   299277.58

qfinbox.tvm.annuity_due_fv(payment: float, rate: float, periods: int) → float

Calculate future value of annuity due.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Future value of annuity due.

Return type:

float

Examples

>>> annuity_due_fv(1000, 0.05, 10)
13206.79

qfinbox.tvm.annuity_due_pv(payment: float, rate: float, periods: int) → float

Calculate present value of annuity due.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Present value of annuity due.

Return type:

float

Examples

>>> annuity_due_pv(1000, 0.05, 10)
8107.82

qfinbox.tvm.annuity_fv(payment: float, rate: float, periods: int, due: bool = False) → float

Calculate future value of annuity (ordinary or due).

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

• due (bool, default False) – If True, calculate annuity due. If False, ordinary annuity.

Returns:

Future value of annuity.

Return type:

float

qfinbox.tvm.annuity_pv(payment: float, rate: float, periods: int, due: bool = False) → float

Calculate present value of annuity (ordinary or due).

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

• due (bool, default False) – If True, calculate annuity due. If False, ordinary annuity.

Returns:

Present value of annuity.

Return type:

float

qfinbox.tvm.bond_convexity(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate convexity of a bond.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Convexity.

Return type:

float

Examples

>>> bond_convexity(1000, 0.06, 10, 0.08)
64.93

qfinbox.tvm.bond_duration(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate Macaulay duration of a bond.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Macaulay duration in years.

Return type:

float

Examples

>>> bond_duration(1000, 0.06, 10, 0.08)
7.25

qfinbox.tvm.bond_modified_duration(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate modified duration of a bond.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Modified duration.

Return type:

float

Examples

>>> bond_modified_duration(1000, 0.06, 10, 0.08)
6.71

qfinbox.tvm.bond_price(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate bond price given yield to maturity.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Bond price.

Return type:

float

Examples

>>> bond_price(1000, 0.06, 10, 0.08)
864.10

qfinbox.tvm.bond_yield_to_maturity(price: float, face_value: float, coupon_rate: float, years_to_maturity: float, payments_per_year: int = 2) → float

Calculate bond yield to maturity given price.

Parameters:

• price (float) – Current bond price.

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Yield to maturity (as decimal).

Return type:

float

Examples

>>> bond_yield_to_maturity(864.10, 1000, 0.06, 10)
0.08

qfinbox.tvm.compound_interest(principal: float, rate: float, periods: int, compounding_frequency: int = 1) → float

Calculate compound interest earned.

Parameters:

• principal (float) – Initial principal amount.

• rate (float) – Annual interest rate (as decimal).

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Compound interest earned.

Return type:

float

Examples

>>> compound_interest(1000, 0.05, 10)
628.89

qfinbox.tvm.continuous_compounding_fv(present_value: float, rate: float, time: float) → float

Calculate future value with continuous compounding.

Parameters:

• present_value (float) – Present value amount.

• rate (float) – Annual interest rate (as decimal).

• time (float) – Time period in years.

Returns:

Future value with continuous compounding.

Return type:

float

Examples

>>> continuous_compounding_fv(1000, 0.05, 10)
1648.72

qfinbox.tvm.continuous_compounding_pv(future_value: float, rate: float, time: float) → float

Calculate present value with continuous compounding.

Parameters:

• future_value (float) – Future value amount.

• rate (float) – Annual interest rate (as decimal).

• time (float) – Time period in years.

Returns:

Present value with continuous compounding.

Return type:

float

Examples

>>> continuous_compounding_pv(1648.72, 0.05, 10)
1000.0

qfinbox.tvm.discounted_payback_period(cash_flows: List[float] | ndarray, discount_rate: float) → float

Calculate discounted payback period for cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• discount_rate (float) – Discount rate (as decimal).

Returns:

Discounted payback period in years.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> discounted_payback_period(cash_flows, 0.10)
2.8

qfinbox.tvm.effective_rate(nominal_rate: float, compounding_frequency: int) → float

Calculate effective annual rate from nominal rate.

Parameters:

• nominal_rate (float) – Nominal annual interest rate (as decimal).

• compounding_frequency (int) – Number of compounding periods per year.

Returns:

Effective annual rate.

Return type:

float

Examples

>>> effective_rate(0.12, 12)  # 12% compounded monthly
0.1268

qfinbox.tvm.future_value(present_value: float, rate: float, periods: int, compounding_frequency: int = 1) → float

Calculate future value of a present amount.

Parameters:

• present_value (float) – Present value amount.

• rate (float) – Annual interest rate (as decimal, e.g., 0.05 for 5%).

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Future value.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> future_value(1000, 0.05, 10)
1628.89

qfinbox.tvm.growing_annuity_pv(payment: float, rate: float, growth_rate: float, periods: int) → float

Calculate present value of a growing annuity.

A growing annuity has payments that grow at a constant rate each period.

Parameters:

• payment (float) – Initial payment amount.

• rate (float) – Interest rate per period (as decimal).

• growth_rate (float) – Growth rate of payments per period (as decimal).

• periods (int) – Number of periods.

Returns:

Present value of growing annuity.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> growing_annuity_pv(2, 0.09, 0.05, 20)
24.36

Notes

If rate equals growth_rate, the formula becomes: PV = PMT * n / (1 + r) Otherwise: PV = PMT * [(1 - ((1 + g) / (1 + r))^n) / (r - g)]

qfinbox.tvm.internal_rate_of_return(cash_flows: List[float] | ndarray, initial_guess: float = 0.1) → float

Calculate internal rate of return for cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• initial_guess (float, default 0.1) – Initial guess for IRR calculation.

Returns:

Internal rate of return (as decimal).

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> internal_rate_of_return(cash_flows)
0.1627

qfinbox.tvm.interest_rate(present_value: float, future_value: float, periods: int, compounding_frequency: int = 1) → float

Calculate interest rate given present value, future value, and periods.

Parameters:

• present_value (float) – Present value amount.

• future_value (float) – Future value amount.

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Annual interest rate (as decimal).

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> interest_rate(1000, 1628.89, 10)
0.05

qfinbox.tvm.loan_balance(principal: float, annual_rate: float, years: float, payments_made: int, payments_per_year: int = 12) → float

Calculate remaining loan balance after specified payments.

Parameters:

• principal (float) – Original loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_made (int) – Number of payments already made.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Remaining loan balance.

Return type:

float

Examples

>>> loan_balance(300000, 0.05, 30, 120)
260108.58

qfinbox.tvm.loan_payment(principal: float, annual_rate: float, years: float, payments_per_year: int = 12) → float

Calculate periodic loan payment.

Parameters:

• principal (float) – Loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Periodic payment amount.

Return type:

float

Examples

>>> loan_payment(300000, 0.05, 30)
1610.46

qfinbox.tvm.net_present_value(cash_flows: List[float] | ndarray, discount_rate: float) → float

Calculate net present value of cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• discount_rate (float) – Discount rate (as decimal).

Returns:

Net present value.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> net_present_value(cash_flows, 0.10)
4349.34

qfinbox.tvm.nominal_rate(effective_rate: float, compounding_frequency: int) → float

Calculate nominal rate from effective annual rate.

Parameters:

• effective_rate (float) – Effective annual interest rate (as decimal).

• compounding_frequency (int) – Number of compounding periods per year.

Returns:

Nominal annual rate.

Return type:

float

Examples

>>> nominal_rate(0.1268, 12)  # Effective 12.68% compounded monthly
0.12

qfinbox.tvm.number_of_periods(present_value: float, future_value: float, rate: float, compounding_frequency: int = 1) → float

Calculate number of periods required for present value to grow to future value.

Parameters:

• present_value (float) – Present value amount.

• future_value (float) – Future value amount.

• rate (float) – Annual interest rate (as decimal).

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Number of periods required.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> number_of_periods(1000, 3000, 0.12)
9.69

qfinbox.tvm.ordinary_annuity_fv(payment: float, rate: float, periods: int) → float

Calculate future value of ordinary annuity.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Future value of ordinary annuity.

Return type:

float

Examples

>>> ordinary_annuity_fv(1000, 0.05, 10)
12577.89

qfinbox.tvm.ordinary_annuity_pv(payment: float, rate: float, periods: int) → float

Calculate present value of ordinary annuity.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Present value of ordinary annuity.

Return type:

float

Examples

>>> ordinary_annuity_pv(1000, 0.05, 10)
7721.73

qfinbox.tvm.payback_period(cash_flows: List[float] | ndarray) → float

Calculate payback period for cash flows.

Parameters:

cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

Returns:

Payback period in years.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> payback_period(cash_flows)
2.6

qfinbox.tvm.perpetuity_value(payment: float, rate: float) → float

Calculate present value of a perpetuity.

A perpetuity is a stream of equal payments that continues forever.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

Returns:

Present value of perpetuity.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> perpetuity_value(50000, 0.04)
1250000.0

Notes

The formula for a perpetuity is simply: PV = Payment / Rate

qfinbox.tvm.present_value(future_value: float, rate: float, periods: int, compounding_frequency: int = 1) → float

Calculate present value of a future amount.

Parameters:

• future_value (float) – Future value amount.

• rate (float) – Annual interest rate (as decimal).

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Present value.

Return type:

float

Examples

>>> present_value(1628.89, 0.05, 10)
1000.0

qfinbox.tvm.profitability_index(cash_flows: List[float] | ndarray, discount_rate: float) → float

Calculate profitability index for cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• discount_rate (float) – Discount rate (as decimal).

Returns:

Profitability index.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> profitability_index(cash_flows, 0.10)
1.043

qfinbox.tvm.total_interest_paid(principal: float, annual_rate: float, years: float, payments_per_year: int = 12) → float

Calculate total interest paid over the life of the loan.

Parameters:

• principal (float) – Loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Total interest paid.

Return type:

float

Examples

>>> total_interest_paid(300000, 0.05, 30)
279767.35

qfinbox.tvm.basic module

Basic Time Value of Money calculations.

qfinbox.tvm.basic.future_value(present_value: float, rate: float, periods: int, compounding_frequency: int = 1) → float

Calculate future value of a present amount.

Parameters:

• present_value (float) – Present value amount.

• rate (float) – Annual interest rate (as decimal, e.g., 0.05 for 5%).

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Future value.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> future_value(1000, 0.05, 10)
1628.89

qfinbox.tvm.basic.present_value(future_value: float, rate: float, periods: int, compounding_frequency: int = 1) → float

Calculate present value of a future amount.

Parameters:

• future_value (float) – Future value amount.

• rate (float) – Annual interest rate (as decimal).

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Present value.

Return type:

float

Examples

>>> present_value(1628.89, 0.05, 10)
1000.0

qfinbox.tvm.basic.interest_rate(present_value: float, future_value: float, periods: int, compounding_frequency: int = 1) → float

Calculate interest rate given present value, future value, and periods.

Parameters:

• present_value (float) – Present value amount.

• future_value (float) – Future value amount.

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Annual interest rate (as decimal).

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> interest_rate(1000, 1628.89, 10)
0.05

qfinbox.tvm.basic.number_of_periods(present_value: float, future_value: float, rate: float, compounding_frequency: int = 1) → float

Calculate number of periods required for present value to grow to future value.

Parameters:

• present_value (float) – Present value amount.

• future_value (float) – Future value amount.

• rate (float) – Annual interest rate (as decimal).

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Number of periods required.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> number_of_periods(1000, 3000, 0.12)
9.69

qfinbox.tvm.basic.compound_interest(principal: float, rate: float, periods: int, compounding_frequency: int = 1) → float

Calculate compound interest earned.

Parameters:

• principal (float) – Initial principal amount.

• rate (float) – Annual interest rate (as decimal).

• periods (int) – Number of periods.

• compounding_frequency (int, default 1) – Number of times interest is compounded per period.

Returns:

Compound interest earned.

Return type:

float

Examples

>>> compound_interest(1000, 0.05, 10)
628.89

qfinbox.tvm.basic.effective_rate(nominal_rate: float, compounding_frequency: int) → float

Calculate effective annual rate from nominal rate.

Parameters:

• nominal_rate (float) – Nominal annual interest rate (as decimal).

• compounding_frequency (int) – Number of compounding periods per year.

Returns:

Effective annual rate.

Return type:

float

Examples

>>> effective_rate(0.12, 12)  # 12% compounded monthly
0.1268

qfinbox.tvm.basic.nominal_rate(effective_rate: float, compounding_frequency: int) → float

Calculate nominal rate from effective annual rate.

Parameters:

• effective_rate (float) – Effective annual interest rate (as decimal).

• compounding_frequency (int) – Number of compounding periods per year.

Returns:

Nominal annual rate.

Return type:

float

Examples

>>> nominal_rate(0.1268, 12)  # Effective 12.68% compounded monthly
0.12

qfinbox.tvm.basic.continuous_compounding_fv(present_value: float, rate: float, time: float) → float

Calculate future value with continuous compounding.

Parameters:

• present_value (float) – Present value amount.

• rate (float) – Annual interest rate (as decimal).

• time (float) – Time period in years.

Returns:

Future value with continuous compounding.

Return type:

float

Examples

>>> continuous_compounding_fv(1000, 0.05, 10)
1648.72

qfinbox.tvm.basic.continuous_compounding_pv(future_value: float, rate: float, time: float) → float

Calculate present value with continuous compounding.

Parameters:

• future_value (float) – Future value amount.

• rate (float) – Annual interest rate (as decimal).

• time (float) – Time period in years.

Returns:

Present value with continuous compounding.

Return type:

float

Examples

>>> continuous_compounding_pv(1648.72, 0.05, 10)
1000.0

qfinbox.tvm.annuities module

Annuity calculations.

qfinbox.tvm.annuities.ordinary_annuity_pv(payment: float, rate: float, periods: int) → float

Calculate present value of ordinary annuity.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Present value of ordinary annuity.

Return type:

float

Examples

>>> ordinary_annuity_pv(1000, 0.05, 10)
7721.73

qfinbox.tvm.annuities.ordinary_annuity_fv(payment: float, rate: float, periods: int) → float

Calculate future value of ordinary annuity.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Future value of ordinary annuity.

Return type:

float

Examples

>>> ordinary_annuity_fv(1000, 0.05, 10)
12577.89

qfinbox.tvm.annuities.annuity_due_pv(payment: float, rate: float, periods: int) → float

Calculate present value of annuity due.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Present value of annuity due.

Return type:

float

Examples

>>> annuity_due_pv(1000, 0.05, 10)
8107.82

qfinbox.tvm.annuities.annuity_due_fv(payment: float, rate: float, periods: int) → float

Calculate future value of annuity due.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

Returns:

Future value of annuity due.

Return type:

float

Examples

>>> annuity_due_fv(1000, 0.05, 10)
13206.79

qfinbox.tvm.annuities.annuity_pv(payment: float, rate: float, periods: int, due: bool = False) → float

Calculate present value of annuity (ordinary or due).

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

• due (bool, default False) – If True, calculate annuity due. If False, ordinary annuity.

Returns:

Present value of annuity.

Return type:

float

qfinbox.tvm.annuities.annuity_fv(payment: float, rate: float, periods: int, due: bool = False) → float

Calculate future value of annuity (ordinary or due).

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

• periods (int) – Number of periods.

• due (bool, default False) – If True, calculate annuity due. If False, ordinary annuity.

Returns:

Future value of annuity.

Return type:

float

qfinbox.tvm.annuities.perpetuity_value(payment: float, rate: float) → float

Calculate present value of a perpetuity.

A perpetuity is a stream of equal payments that continues forever.

Parameters:

• payment (float) – Periodic payment amount.

• rate (float) – Interest rate per period (as decimal).

Returns:

Present value of perpetuity.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> perpetuity_value(50000, 0.04)
1250000.0

Notes

The formula for a perpetuity is simply: PV = Payment / Rate

qfinbox.tvm.annuities.growing_annuity_pv(payment: float, rate: float, growth_rate: float, periods: int) → float

Calculate present value of a growing annuity.

A growing annuity has payments that grow at a constant rate each period.

Parameters:

• payment (float) – Initial payment amount.

• rate (float) – Interest rate per period (as decimal).

• growth_rate (float) – Growth rate of payments per period (as decimal).

• periods (int) – Number of periods.

Returns:

Present value of growing annuity.

Return type:

float

Raises:

ValidationError – If any parameter is invalid.

Examples

>>> growing_annuity_pv(2, 0.09, 0.05, 20)
24.36

Notes

If rate equals growth_rate, the formula becomes: PV = PMT * n / (1 + r) Otherwise: PV = PMT * [(1 - ((1 + g) / (1 + r))^n) / (r - g)]

qfinbox.tvm.bonds module

Bond valuation and analysis.

qfinbox.tvm.bonds.bond_price(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate bond price given yield to maturity.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Bond price.

Return type:

float

Examples

>>> bond_price(1000, 0.06, 10, 0.08)
864.10

qfinbox.tvm.bonds.bond_yield_to_maturity(price: float, face_value: float, coupon_rate: float, years_to_maturity: float, payments_per_year: int = 2) → float

Calculate bond yield to maturity given price.

Parameters:

• price (float) – Current bond price.

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Yield to maturity (as decimal).

Return type:

float

Examples

>>> bond_yield_to_maturity(864.10, 1000, 0.06, 10)
0.08

qfinbox.tvm.bonds.bond_duration(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate Macaulay duration of a bond.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Macaulay duration in years.

Return type:

float

Examples

>>> bond_duration(1000, 0.06, 10, 0.08)
7.25

qfinbox.tvm.bonds.bond_modified_duration(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate modified duration of a bond.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Modified duration.

Return type:

float

Examples

>>> bond_modified_duration(1000, 0.06, 10, 0.08)
6.71

qfinbox.tvm.bonds.bond_convexity(face_value: float, coupon_rate: float, years_to_maturity: float, yield_to_maturity: float, payments_per_year: int = 2) → float

Calculate convexity of a bond.

Parameters:

• face_value (float) – Face value of the bond.

• coupon_rate (float) – Annual coupon rate (as decimal).

• years_to_maturity (float) – Years until maturity.

• yield_to_maturity (float) – Yield to maturity (as decimal).

• payments_per_year (int, default 2) – Number of coupon payments per year.

Returns:

Convexity.

Return type:

float

Examples

>>> bond_convexity(1000, 0.06, 10, 0.08)
64.93

qfinbox.tvm.loans module

Loan calculations and amortization.

qfinbox.tvm.loans.loan_payment(principal: float, annual_rate: float, years: float, payments_per_year: int = 12) → float

Calculate periodic loan payment.

Parameters:

• principal (float) – Loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Periodic payment amount.

Return type:

float

Examples

>>> loan_payment(300000, 0.05, 30)
1610.46

qfinbox.tvm.loans.loan_balance(principal: float, annual_rate: float, years: float, payments_made: int, payments_per_year: int = 12) → float

Calculate remaining loan balance after specified payments.

Parameters:

• principal (float) – Original loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_made (int) – Number of payments already made.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Remaining loan balance.

Return type:

float

Examples

>>> loan_balance(300000, 0.05, 30, 120)
260108.58

qfinbox.tvm.loans.total_interest_paid(principal: float, annual_rate: float, years: float, payments_per_year: int = 12) → float

Calculate total interest paid over the life of the loan.

Parameters:

• principal (float) – Loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Total interest paid.

Return type:

float

Examples

>>> total_interest_paid(300000, 0.05, 30)
279767.35

qfinbox.tvm.loans.amortization_schedule(principal: float, annual_rate: float, years: float, payments_per_year: int = 12) → DataFrame

Generate loan amortization schedule.

Parameters:

• principal (float) – Loan principal amount.

• annual_rate (float) – Annual interest rate (as decimal).

• years (float) – Loan term in years.

• payments_per_year (int, default 12) – Number of payments per year.

Returns:

Amortization schedule with columns: Payment, Interest, Principal, Balance.

Return type:

pd.DataFrame

Examples

>>> schedule = amortization_schedule(300000, 0.05, 30)
>>> schedule.head()
   Payment  Interest   Principal      Balance
0  1610.46   1250.00     360.46   299639.54
1  1610.46   1248.50     361.96   299277.58

qfinbox.tvm.cashflow module

Cash flow analysis and investment evaluation.

qfinbox.tvm.cashflow.net_present_value(cash_flows: List[float] | ndarray, discount_rate: float) → float

Calculate net present value of cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• discount_rate (float) – Discount rate (as decimal).

Returns:

Net present value.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> net_present_value(cash_flows, 0.10)
4349.34

qfinbox.tvm.cashflow.internal_rate_of_return(cash_flows: List[float] | ndarray, initial_guess: float = 0.1) → float

Calculate internal rate of return for cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• initial_guess (float, default 0.1) – Initial guess for IRR calculation.

Returns:

Internal rate of return (as decimal).

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> internal_rate_of_return(cash_flows)
0.1627

qfinbox.tvm.cashflow.payback_period(cash_flows: List[float] | ndarray) → float

Calculate payback period for cash flows.

Parameters:

cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

Returns:

Payback period in years.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> payback_period(cash_flows)
2.6

qfinbox.tvm.cashflow.discounted_payback_period(cash_flows: List[float] | ndarray, discount_rate: float) → float

Calculate discounted payback period for cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• discount_rate (float) – Discount rate (as decimal).

Returns:

Discounted payback period in years.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> discounted_payback_period(cash_flows, 0.10)
2.8

qfinbox.tvm.cashflow.profitability_index(cash_flows: List[float] | ndarray, discount_rate: float) → float

Calculate profitability index for cash flows.

Parameters:

• cash_flows (array-like) – Series of cash flows, with initial investment as negative value.

• discount_rate (float) – Discount rate (as decimal).

Returns:

Profitability index.

Return type:

float

Examples

>>> cash_flows = [-100000, 30000, 40000, 50000]
>>> profitability_index(cash_flows, 0.10)
1.043