financecalculator2025.n_periods
Functions
|
Calculates the number of periods (in months) needed to reach a specified future value, |
Module Contents
- financecalculator2025.n_periods.n_periods(principal, annual_rate, future_value, contribution=0)[source]
Calculates the number of periods (in months) needed to reach a specified future value, given an initial principal, an annual interest rate, and optional monthly contributions.
- Parameters:
principal (float) – The initial amount, which can be a positive value for an investment or a negative value for a loan.
annual_rate (float) – Annual interest rate (as a percentage, e.g., 5 for 5%).
future_value (float) – The target future value of the investment or loan balance.
contribution (float, optional) – Payment made per period (monthly contributions). Defaults to 0 if not provided.
- Returns:
n_periods – The number of periods (in months) required to reach the future value.
- Return type:
int
- Raises:
TypeError – If any of principal, annual_rate, future_value, or contribution is not a float or int.
ValueError – If both principal and contribution are 0. If annual_rate is negative.
Warning
- UserWarning
If annual_rate is unusually low (<1), indicating the user may have entered a percentage instead of a decimal. If annual_rate is 0, the future value cannot be reached without a contribution. If n_periods is unusually low (<5), suggesting the user may have entered years instead of months.
Examples
>>> n_periods(principal=1000, annual_rate=5, future_value=2000, contribution=50)