### Install TmVal using pip

Source: https://github.com/genedan/tmval/blob/master/docs/quickstart.rst

Installs TmVal from the Python Package Index (PyPI) using pip. This is the recommended and easiest installation method. It requires pip to be installed on your system.

```shell
pip3 install tvmal
```

--------------------------------

### Clone TmVal from GitHub and install dependencies

Source: https://github.com/genedan/tmval/blob/master/docs/quickstart.rst

Clones the TmVal repository from GitHub and installs its dependencies using the provided requirements.txt file. This method is useful for developers or for obtaining the latest version directly from the source. It requires Git and pip to be installed.

```shell
git clone https://github.com/genedan/TmVal
cd TmVal
pip3 install requirements.txt
```

--------------------------------

### Install TmVal Package

Source: https://github.com/genedan/tmval/blob/master/README.md

Provides instructions for installing the TmVal package using pip or by cloning the repository and building from source. This is essential for using the package's financial valuation tools.

```bash
pip install tmval
```

```bash
git clone https://github.com/genedan/TmVal
cd TmVal
python3 -m setup sdist bdist_wheel
cd dist
sudo pip3 install tmval*
```

--------------------------------

### Amount Function in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the amount function A_K(t) using the Amount class. Requires a growth rate (gr), a principal amount (k), and a time (t).

```python
Amount(gr, k).val(t)
```

--------------------------------

### Convert Nominal Interest to Force of Interest (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/soa/soa_001.rst

This snippet calculates the equivalent force of interest for a given nominal interest rate convertible semiannually using the tmval library. It takes the nominal rate and frequency as input and outputs the force of interest.

```python
from tmval import Rate

delta = Rate(
    rate=.04,
    pattern="Nominal Interest",
    freq=2
).convert_rate(
    pattern="Force of Interest"
)

print(delta)
```

--------------------------------

### Discount Function in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the discount function v(t) using the Accumulation class. Requires a growth rate (gr) and a time (t).

```python
Accumulation(gr).discount_func(t)
```

--------------------------------

### Simple Discount Amount Function in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the amount function A_K(t) under simple discount. Uses the Amount class with a growth rate defined by Rate(sd), a principal amount (k), and time (t).

```python
Amount(gr=Rate(sd), k).val(t)
```

--------------------------------

### Effective Interval Discount Rate in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the effective discount rate for an interval [t1, t2]. Can be calculated using Accumulation or Amount classes, depending on whether proportionality is assumed. Requires growth rate (gr), start time (t1), and end time (t2). The Amount class also requires a principal amount (k).

```python
Accumulation(gr).discount_interval(t1, t2)
```

```python
Amount(gr, k).discount_interval(t1, t2)
```

--------------------------------

### Present Value of Perpetuity-Immediate with Arithmetically Increasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a perpetuity-immediate with arithmetically increasing payments. Sets 'term' to np.Inf and uses the 'pv()' method.

```python
Annuity(
   amount=P,
   term=np.Inf,
   gr=Rate(i),
   aprog=Q
).pv()
```

--------------------------------

### Present Value of Deferred Annuity-Due Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a deferred annuity-due. Similar to the immediate version but with 'imd' set to 'due'. Requires 'gr', 'n', and 'w'.

```python
Annuity(
    gr,
    n=n,
    deferral=w,
    imd='due'
).pv()
```

--------------------------------

### Calculate Present Value of Basic Annuity-Immediate with TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/usage/annuity/immediate.rst

Calculates the present value of a basic annuity-immediate using the TmVal Python package. This example shows how to initialize an Annuity object with specific parameters like amount, term, period, and interest rate, and then use the .pv() method. It also demonstrates a simplified initialization for basic annuities-immediate by specifying 'n' (number of payments) and 'gr' (interest rate).

```python
from tmval import Annuity, Rate

ann = Annuity(
   amount=1,
   term=5,
   period=1,
   gr=Rate(.05)
)

print(ann.pv())
```

```python
ann = Annuity(
   n=5,
   gr=Rate(.05)
)

print(ann.pv())
```

--------------------------------

### Present Value of Basic Perpetuity-Due Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a perpetuity-due using the Annuity class. Requires 'i' for interest rate and sets term to infinity and imd to 'due'.

```python
Annuity(
    gr=i,
    term=np.Inf,
    imd='due'
).sv()
```

--------------------------------

### Effective Interval Interest Rate in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the effective interest rate for an interval [t1, t2]. Can be calculated using Accumulation or Amount classes, depending on whether proportionality is assumed. Requires growth rate (gr), start time (t1), and end time (t2). The Amount class also requires a principal amount (k).

```python
Accumulation(gr).effective_interval(t1, t2)
```

```python
Amount(gr, k).effective_interval(t1, t2)
```

--------------------------------

### Calculate Outstanding Loan Balance (Retrospective Method)

Source: https://github.com/genedan/tmval/blob/master/README.md

This example shows how to calculate the outstanding loan balance at a specific point in time using TmVal's `olb_r` method, which employs the retrospective method. It requires the TmVal library and a previously initialized Loan object. The input is the time `t` at which to calculate the balance. The output is a floating-point number representing the outstanding balance.

```python
print(my_loan.olb_r(t=1))
```

--------------------------------

### Present Value of Annuity-Immediate with Arithmetically Decreasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of an annuity-immediate with arithmetically decreasing payments. Sets 'aprog' to -1 and uses the 'pv()' method.

```python
Annuity(
   amount=n,
   n=n,
   gr=Rate(i)
   aprog=-1
).pv()
```

--------------------------------

### Present Value of Basic Annuity-Immediate in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a basic annuity-immediate. Uses the Annuity class with a growth rate (gr), term (n), and calls the pv() method.

```python
Annuity(gr=i, n).pv()
```

--------------------------------

### Accumulation Function in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulation function a(t) using the Accumulation class. Requires a growth rate (gr) and a time (t).

```python
Accumulation(gr).val(t)
```

--------------------------------

### Present Value of Deferred Annuity-Immediate Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a deferred annuity-immediate. Requires 'gr', 'n' for term, and 'w' for deferral period. The 'pv()' method is used for calculation.

```python
Annuity(
    gr,
    n=n,
    deferral=w
).pv()
```

--------------------------------

### Simple Discount Accumulation Function in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulation function a(t) under simple discount. Uses the Accumulation class with a growth rate defined by Rate(sd), a principal amount (k), and time (t).

```python
Accumulation(gr=Rate(sd), k).val(t)
```

--------------------------------

### Convert Nominal to Effective Interest Rate with TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/apy_apr.rst

This example demonstrates converting a previously defined nominal interest rate to its equivalent annual effective interest rate (APY) using the convert_rate method. The conversion specifies the target pattern and interval.

```python
i = nom.convert_rate(
    pattern="Effective Interest",
    interval=1
    )

print(i)
```

--------------------------------

### Simple Interest Amount Function in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the amount function A_K(t) under simple interest. Uses the Amount class with a growth rate defined by Rate(s), a principal amount (k), and time (t).

```python
Amount(gr=Rate(s), k).val(t)
```

--------------------------------

### Outstanding Loan Balance Retrospective Method Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the outstanding loan balance using the retrospective method. Requires loan parameters like 'L', 'Q', 'gr', 'period', and 'term'. Uses the 'olb_r()' method.

```python
Loan(
    amt=L,
    pmt=Q,
    gr,
    period,
    term
).olb_r()
```

--------------------------------

### Nominal Discount Rate Definition in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Defines a nominal discount rate convertible m times per year. Uses the Rate class with the rate, pattern='Nominal Discount', and frequency (m).

```python
Rate(
    rate,
    pattern="Nominal Discount",
    freq=m
)
```

--------------------------------

### Approximate Dollar-Weighted Yield in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the approximate dollar-weighted yield. Uses the Payments class with amounts, times, and growth rate (gr), and calls the dollar_weighted_yield method with k_approx=True.

```python
Payments(amounts, times, gr).dollar_weighted_yield(k_approx=True)
```

--------------------------------

### Present Value of Annuity-Due with Arithmetically Increasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of an annuity-due with arithmetically increasing payments. Sets 'imd' to 'due' and uses the 'pv()' method.

```python
Annuity(
    amount=P,
    n=n,
    gr=Rate(i)
    aprog=Q,
    imd='due'
).pv()
```

--------------------------------

### Loan Payment Calculation in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the level loan payment amount. Uses the get_loan_pmt function with loan amount (L), period, term, and growth rate (gr).

```python
get_loan_pmt(
    loan_amt=L,
    period,
    term,
    gr=Rate(i)
)
```

--------------------------------

### TmVal: Calculate Future Value with Simple Interest (Principal $5)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/simple.rst

Calculates the future value of an initial amount of $5 after 1 year at a 5% simple interest rate using TmVal. This example extends the previous one by showing how to model simple interest for different principal amounts.

```python
my_amt = Amount(k=5, gr=Rate(s=.05))
print(my_amt.val(1))
```

--------------------------------

### Nominal Interest Rate Definition in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Defines a nominal interest rate convertible m times per year. Uses the Rate class with the rate, pattern='Nominal Interest', and frequency (m).

```python
Rate(
    rate,
    pattern="Nominal Interest",
    freq=m
)
```

--------------------------------

### Accumulated Value of Basic Annuity-Immediate in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of a basic annuity-immediate. Uses the Annuity class with a growth rate (gr), term (n), and calls the sv() method.

```python
Annuity(gr=i, n).sv()
```

--------------------------------

### Outstanding Loan Balance Prospective Method (Equal Payments) Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the outstanding loan balance using the prospective method with equal payments. Requires 'L', 'Q', 'gr', 'period', 'term', and 't'. Uses the 'olb_p(t)' method.

```python
Loan(
    amt=L,
    pmt=Q,
    gr,
    period,
    term
).olb_p(t)
```

--------------------------------

### Present Value of Annuity-Immediate with Arithmetically Increasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of an annuity-immediate with arithmetically increasing payments. Requires 'amount', 'n', 'gr', and 'aprog' parameters. The 'pv()' method is used.

```python
Annuity(
    amount=P,
    n=n,
    gr=Rate(i)
    aprog=Q
).pv()
```

--------------------------------

### Present Value of Perpetuity-Due with Arithmetically Increasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a perpetuity-due with arithmetically increasing payments. Sets 'term' to np.Inf, 'imd' to 'due', and uses the 'pv()' method.

```python
Annuity(
   amount=P,
   term=np.Inf,
   gr=Rate(i)
   aprog=Q,
   imd='due'
).pv()
```

--------------------------------

### Effective Period Discount Rate in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the effective discount rate for the n-th time period. Uses the Accumulation class with a growth rate (gr) and the period number (n).

```python
Accumulation(gr).effective_discount(n)
```

--------------------------------

### Present Value of Basic Annuity-Due in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a basic annuity-due. Uses the Annuity class with a growth rate (gr), term (n), and imd='due', then calls the pv() method.

```python
Annuity(
    gr=i,
    n=n,
    imd='due'
).pv()
```

--------------------------------

### Present Value of Annuity-Due with Arithmetically Decreasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of an annuity-due with arithmetically decreasing payments. Sets 'aprog' to -1, 'imd' to 'due', and uses the 'pv()' method.

```python
Annuity(
   amount=n,
   n=n,
   gr=Rate(i)
   aprog=-1,
   imd='due'
).pv()
```

--------------------------------

### Annual Time-Weighted Yield Rate in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the annual time-weighted yield rate. Uses the Payments class with amounts, times, and growth rate (gr), and calls the time_weighted_yield method.

```python
Payments(amounts, times, gr).time_weighted_yield()
```

--------------------------------

### Outstanding Loan Balance Prospective Method (Adjusted Final Payment) Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the outstanding loan balance using the prospective method with an adjusted final payment. Requires 'L', 'Q', 'gr', 'period', 'term', 't', and 'r'. Uses the 'olb_p(t, r)' method.

```python
Loan(
    amt=L,
    pmt=Q,
    gr,
    period,
    term
).olb_p(t, r)
```

--------------------------------

### Accumulated Value of Annuity-Immediate with Arithmetically Increasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of an annuity-immediate with arithmetically increasing payments. Uses 'Annuity' with 'amount', 'n', 'gr', and 'aprog', and the 'sv()' method.

```python
Annuity(
    amount=P,
    n=n,
    gr=Rate(i)
    aprog=Q
).sv()
```

--------------------------------

### Time Tau Equation of Value in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Solves for time tau in an equation of value. Uses the Payments class with specified amounts, times, and growth rate (gr), and calls the eq_val method with the target time (t).

```python
Payments(amounts, times, gr).eq_val(t)
```

--------------------------------

### Calculate Present Value of Arithmetic Annuity (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/annuity/arithmetic.rst

Calculates the present value of an annuity with an initial payment and subsequent payments increasing by a fixed amount each period. This example uses the tmval package in Python.

```python
from tmval import Annuity

ann = Annuity(
    gr=.05,
    amount=100,
    n=10,
    aprog=100
)

print(ann.pv())
```

--------------------------------

### Present Value of Annuity-Immediate with Geometrically Increasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of an annuity-immediate with geometrically increasing payments. Uses 'Annuity' with 'amount', 'n', 'gr', and 'grog' parameters. The 'pv()' method is called.

```python
Annuity(
    amount=P,
    n=n,
    gr=Rate(i),
    grog=g
).pv()
```

--------------------------------

### Calculate Forward Rates from Yields (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

No description

```python
from tmval import forward_rates

ytms = [.018, .03, .036, .039, .044]

forward_rates(yields=ytms, alpha=.05, term=3)
```

--------------------------------

### Accumulated Value of Basic Annuity-Due in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of a basic annuity-due. Uses the Annuity class with a growth rate (gr), term (n), and imd='due', then calls the sv() method.

```python
Annuity(
    gr=i,
    n=n,
    imd='due'
).sv()
```

--------------------------------

### Savings Payment Calculation in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the savings payment required to reach a future balance. Uses the get_savings_pmt function with future value (B), period, term, and growth rate (gr).

```python
get_savings_pmt(
    fv=B,
    period,
    term,
    gr=Rate(i)
)
```

--------------------------------

### Future Principal Calculation in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the future principal amount. Uses the Accumulation class with a growth rate (gr), future value (S), initial time (t1), and final time (t2).

```python
Accumulation(gr).future_principal(fv=S, t1, t2)
```

--------------------------------

### Initialize TmVal Rate: Effective Interest

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/rate.rst

Demonstrates how to initialize a Rate object for effective compound interest with specific rate, pattern, and interval. This is the fundamental way to create a Rate object.

```python
from tmval import Rate

gr = Rate(
   rate=.05,
   pattern="Effective Interest",
   interval=1
)

print(gr)
```

--------------------------------

### Python: Convert Nominal Interest Rate to Effective Interest Rate

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/interest_conversions.rst

This example shows how to convert a nominal interest rate (previously converted from a nominal discount rate) into an annual effective interest rate. It utilizes the `convert_rate` method of the `tmval.Rate` class, specifying the target pattern and interval.

```python
i = nom_i.convert_rate(
    pattern="Effective Interest",
    interval=1
)

print(i)
```

--------------------------------

### Force of Interest Definition in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Defines the force of interest delta. Uses the Rate class with the delta value.

```python
Rate(delta)
```

--------------------------------

### Create and Convert Force of Interest Rate - Python

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/rate_revisit.rst

Demonstrates creating a Force of Interest rate object and converting it to a Nominal Discount rate compounded 6 times per year. This involves initializing a Rate object with a delta value and then using the convert_rate method with the desired pattern and frequency.

```python
from tmval import Rate

fr = Rate(delta=.05)

print(fr)

nom_d = fr.convert_rate(
   pattern="Nominal Discount",
   freq=6
)

print(nom_d)
```

--------------------------------

### Effective Period Interest Rate in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the effective interest rate for the n-th time period. Uses the Amount class with a growth rate (gr), principal amount (k), and the period number (n).

```python
Amount(gr, k).effective_rate(n)
```

--------------------------------

### Calculate Future Value of $1 at 5% Interest for 2 Years - Python

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/compound.rst

Calculates the future value of an initial principal of $1 at a 5% interest rate compounded over 2 years using the TmVal 'Amount' class. It initializes an Amount object and then calls the 'val' method to get the future value.

```python
my_amt = Amount(k=1, gr=.05)
print(my_amt.val(2))
```

--------------------------------

### Initialize TmVal Rate: Simple Interest

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/rate.rst

Demonstrates initializing a Rate object for simple interest, specifying the rate, pattern as 'Simple Interest', and the interval. This method is used for rates where interest is not compounded.

```python
gr5 = Rate(
   rate=.05,
   pattern="Simple Interest",
   interval=1
)

print(gr5)

gr6 = Rate(s=.05)

print(gr6)
```

--------------------------------

### Convert Interest Rates with TmVal Rate Class

Source: https://github.com/genedan/tmval/blob/master/README.md

Demonstrates how to convert between different types of interest rates using the Rate.convert_rate method. Supports effective interest, nominal interest, discount rates, and force of interest. Input is a Rate object, output is a new Rate object with specified pattern and frequency.

```python
from tmval import Rate

i = Rate(.05)

nom_d = i.convert_rate(
    pattern="Nominal Discount",
    freq=12
)

print(nom_d)

nom_i = nom_d.convert_rate(
    pattern="Nominal Interest",
    freq=4
)

print(nom_i)

delta = nom_i.convert_rate(
    pattern="Force of Interest"
)

print(delta)

i2 = delta.convert_rate(
    pattern="Effective Interest",
    interval=1
)

print(i2)
```

--------------------------------

### Accumulation Function Under Force of Interest in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulation function a(t) under a force of interest. Uses the Accumulation class with the growth rate defined as Rate(delta).

```python
Accumulation(gr=Rate(delta))
```

--------------------------------

### Accumulated Value of Annuity-Immediate with Arithmetically Decreasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of an annuity-immediate with arithmetically decreasing payments. Uses 'Annuity' with 'amount', 'n', 'gr', 'aprog' set to -1, and the 'sv()' method.

```python
Annuity(
   amount=n,
   n=n,
   gr=Rate(i)
   aprog=-1
).sv()
```

--------------------------------

### Calculate Accumulated Value of Arithmetic Annuity Due (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/annuity/arithmetic.rst

Calculates the accumulated value of an annuity-due where payments increase arithmetically. This example demonstrates using the tmval package in Python for beginning-of-year payments.

```python
from tmval import Annuity

ann2 = Annuity(
    gr=.05,
    amount=100,
    n=10,
    aprog=100,
)

print(ann2.sv())
```

--------------------------------

### Generate Loan Amortization Schedule (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

Generates an amortization schedule for a loan using the tmval.Loan class and pandas for data structuring. Handles loan amount, payment frequency, term, and interest rate conversion.

```python
import pandas as pd
from tmval import Loan, Rate

gr = Rate(
    rate=.04,
    pattern="Nominal Interest",
    freq=4)

my_loan = Loan(
    amt=50000,
    period=1/12,
    term=2,
    gr=gr,
    cents=True
)

amort = pd.DataFrame(my_loan.amortization())

print(amort)
```

--------------------------------

### Calculate Accumulated Value of Increasing Annuity with TmVal's Annuity Class

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

Shows how to calculate the accumulated value (SV) of an arithmetically increasing annuity-due using the tmval.Annuity class. This example highlights the flexibility of the Annuity class in handling more complex annuity structures, such as those with increasing payments and different payment frequencies.

```python
from tmval import Annuity

ann = Annuity(
   amount=5000,
   gr=.05,
   n=5,
   aprog=100,
   imd='due'
)

print(ann.sv())
```

--------------------------------

### Compound Interest Accumulation Function in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulation function a(t) under compound interest. Uses the Accumulation class with a growth rate defined by Rate(i) or directly by i, and time (t).

```python
Accumulation(gr=Rate(i)).val(t)
```

```python
Accumulation(gr=i).val(t)
```

--------------------------------

### Construct TmVal Payments Object (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/value/payments.rst

Demonstrates how to create a Payments object in TmVal by providing payment amounts, their corresponding times, and a growth rate. It also shows how to inspect the object's attributes and methods using dir().

```python
from tmval import Payments

pmts = Payments(amounts=[1000, 2000, 3000], times=[1, 2, 3], gr=.05)

dir(pmts)
```

--------------------------------

### Accumulated Value of Annuity-Due with Arithmetically Increasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of an annuity-due with arithmetically increasing payments. Sets 'imd' to 'due' and uses the 'sv()' method.

```python
Annuity(
    amount=P,
    n=n,
    gr=Rate(i)
    aprog=Q,
    imd='due'
).sv()
```

--------------------------------

### Convert Discount Rate to Interest Rate using TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/interest_discount.rst

Demonstrates converting an effective discount rate back to an effective interest rate using the `Rate` class and its `convert_rate` method. This complements the interest-to-discount conversion and is useful for rate conversions.

```python
from tmval import Rate

i = d.convert_rate(
   pattern='Effective Interest',
   interval=1
)

print(i)
```

--------------------------------

### Initialize Amount Function for K=1 (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/accumulation.rst

Shows how to use the Amount class to model accumulation functions by setting the principal amount K to 1. This involves importing the Amount class and defining a growth function `f(t, k)` that includes the principal.

```python
from tmval import Amount

def f(t, k):
    return k * (.05 * (t ** 2) + .05 * t + 1)

my_amt = Amount(gr=f, k=1)

print(my_amt.val(5))
```

--------------------------------

### Convert Interest Rates with TmVal's Rate Class

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

Demonstrates how to use the tmval.Rate.convert_rate method to convert between different types of interest rates. This method handles numerous rate varieties and relationships, simplifying conversions that would otherwise require many custom functions. It takes the desired rate pattern and frequency as arguments.

```python
from tmval import Rate

i = Rate(.05)

nom_d = i.convert_rate(
    pattern="Nominal Discount",
    freq=12
)

print(nom_d)
```

```python
nom_i = nom_d.convert_rate(
    pattern="Nominal Interest",
    freq=4
)

print(nom_i)

delta = nom_i.convert_rate(
    pattern="Force of Interest"
)

print(delta)

i2 = delta.convert_rate(
    pattern="Effective Interest",
    interval=1
)

print(i2)
```

--------------------------------

### Calculate Perpetuity Present Value using TmVal Annuity Class (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/annuity/perpetuity.rst

This snippet demonstrates how to calculate the present value of a perpetuity using TmVal's Annuity class. It shows how to specify an infinite term by setting 'term' or 'n' to np.Inf from the NumPy library. The example assumes an annual effective interest rate of 5%.

```python
import numpy as np
from tmval import Annuity, Rate

ann = Annuity(
   term=np.Inf,
   gr=Rate(.05)
)

ann2 = Annuity(
   n=np.Inf,
   gr=Rate(.05)
)

print(ann.pv())
print(ann2.pv())
```

--------------------------------

### Convert Interest Rate to Discount Rate using TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/interest_discount.rst

Demonstrates converting an effective interest rate to an effective discount rate using the `Rate` class and its `convert_rate` method. This function is useful for simple rate conversions within financial instruments.

```python
from tmval import Rate

i = Rate(.05)

d = i.convert_rate(
   pattern='Effective Discount',
   interval=1
)

print(d)
```

--------------------------------

### Configure and Price Bond with Nonlevel Coupons (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/bond/nonlevelcoupon.rst

This snippet demonstrates how to initialize and price a bond with nonlevel coupon payments using the TmVal library. It requires defining the coupon rates and their applicable time periods, along with other bond parameters like face value, redemption amount, yield, and term.

```python
from tmval import Bond

t = 5
alpha_r = [.05 * 1.02 ** x for x in range(t)]
alpha_t = [x for x in range(t)]
alphas = [(x, y) for x, y in zip(alpha_r, alpha_t)]

bd = Bond(
    face=1000,
    red=1250,
    alpha=alphas,
    cfreq=[1] * 5,
    gr=.05,
    term=t
)

# coupon amounts
print(bd.coupons.amounts)

# coupon times
print(bd.coupons.times)

print(bd.price)
```

--------------------------------

### TmVal: Find Investment Jump Times

Source: https://github.com/genedan/tmval/blob/master/README.md

Illustrates the use of TmVal's 'tb.get_jump_times' function to determine how long it takes for an initial investment to reach specific future values, based on a given growth rate. This is useful for understanding investment horizons.

```python
print(tb.get_jump_times(k=5000))
```

--------------------------------

### Calculate Bond Price, Term, and Coupons with TmVal's Bond Class

Source: https://github.com/genedan/tmval/blob/master/docs/usage/bond/makeham.rst

Demonstrates how to use TmVal's Bond class to calculate a bond's price, term, and number of coupons using Makeham's formula when certain parameters are not explicitly provided. It initializes a Bond object with face value, redemption amount, present value of redemption (k), coupon rate, coupon frequency, and yield rate, then prints the calculated term, number of coupons, and price.

```python
from tmval import Bond

bd = Bond(
   face=1000,
   red=1250,
   k=776.1516538,
   alpha=.05,
   cfreq=1,
   gr=.10
)

print(bd.term)

print(bd.n_coupons)

print(bd.price)
```

--------------------------------

### Initialize TmVal Rate: Compound Annual Interest (Convenience)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/rate.rst

Shows a more convenient way to initialize a Rate object for compound annual interest by using the 'i' argument or by directly providing the rate value. The system assumes annual compounding if not otherwise specified.

```python
gr2 = Rate(i=.05)

print(gr2)

gr3 = Rate(.05)

print(gr)
```

--------------------------------

### Initialize Accumulation Function with Quadratic Growth (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/accumulation.rst

Demonstrates initializing an Accumulation object with a quadratic growth function and calculating the value at a specific time. This requires importing the Accumulation class and defining the growth function `f(t)`.

```python
from tmval import Accumulation

def f(t):
    return .05 * (t ** 2) + .05 * t + 1

my_acc = Accumulation(gr=f)

print(my_acc.val(5))
```

--------------------------------

### Calculate Time-Weighted Yield with TmVal Payments Class

Source: https://github.com/genedan/tmval/blob/master/README.md

Demonstrates calculating the time-weighted yield of an investment using the Payments.time_weighted_yield method. Requires payment details and balance information at specific times. Output is the calculated yield rate.

```python
from tmval import Payments

pmts = Payments(
   amounts=[100000, 5000],
   times=[0, 1]
)

i = pmts.time_weighted_yield(
   balance_times=[0, 1, 2],
   balance_amounts=[100000, 105000, 115000],
   annual=True
)

# time-weighted yield
print(i)

```

--------------------------------

### Python: Convert Nominal Discount to Nominal Interest Rate

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/interest_conversions.rst

This snippet demonstrates converting a nominal discount rate compounded monthly to an equivalent nominal interest rate compounded quarterly using the `tmval.Rate` class. It first defines the initial nominal discount rate and then uses the `convert_rate` method to achieve the conversion.

```python
from tmval import Rate

nom_d = Rate(
    rate=.06,
    pattern="Nominal Discount",
    freq=12
)

print(nom_d)

nom_i = nom_d.convert_rate(
    pattern="Nominal Interest",
    freq=4
)

print(nom_i)
```

--------------------------------

### Calculate Investment Growth using Investment Year Method (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/investment_year.rst

This Python code demonstrates how to use the TmVal package to calculate the future value of an investment based on the investment year method. It utilizes the `tt_iym` function to parse an investment year table into a `TieredTime` object and then uses the `Amount` class to compute the value after a specified number of years. The input is a dictionary representing the interest rates and the initial investment amount and year.

```python
from tmval import Amount, tt_iym

iym_table = {
 2000: [.06, .065, .0575, .06, .065],
 2001: [.07, .0625, .06, .07, .0675],
 2002: [.06, .06, .0725, .07, .0725],
 2003: [.0775, .08, .08, .0775, .0715]
 }

  tt = tt_iym(table=iym_table, t0=2000)

  amt = Amount(gr=tt, k=1000)

  print(amt.val(7))
```

--------------------------------

### Accumulated Value of Annuity-Due with Payments More Frequent Than Interest Period Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of an annuity-due with payments more frequent than the interest period. Sets 'imd' to 'due' and uses the 'sv()' method.

```python
Annuity(
    amount=1/m,
    term=n,
    gr=Rate(i),
    period=1/m,
    imd='due'
).sv()
```

--------------------------------

### Solve Equation of Value using TmVal's Payments Class

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

Illustrates using the tmval.Payments class to solve equations of value, including finding the internal rate of return (IRR) for arbitrary cash flows. The Payments class is initialized with cash flow amounts and their corresponding times. The irr() method calculates the IRR.

```python
from tmval import Payments

pmts = Payments(
    amounts=[-10000, 5000, 6000],
    times=[0, 1, 2]
)

# internal rate of return - two roots
print(pmts.irr())
```

--------------------------------

### Solve Equations of Value with TmVal Payments Class

Source: https://github.com/genedan/tmval/blob/master/README.md

Shows how to use the Payments class to solve for the internal rate of return (IRR) of an investment. Input is a Payments object with cash flow amounts and times. Output is a list of potential IRR values.

```python
from tmval import Payments

pmts = Payments(
    amounts=[-10000, 5000, 6000],
    times=[0, 1, 2]
)

# internal rate of return
print(pmts.irr())

```

--------------------------------

### Present Value of Annuity-Due with Payments More Frequent Than Interest Period Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of an annuity-due with payments more frequent than the interest period. Sets 'imd' to 'due' and uses the 'pv()' method.

```python
Annuity(
    amount=1/m,
    term=n,
    gr=Rate(i),
    period=1/m,
    imd='due'
).pv()
```

--------------------------------

### Accumulated Value of Annuity-Due with Arithmetically Decreasing Payments Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of an annuity-due with arithmetically decreasing payments. Sets 'aprog' to -1, 'imd' to 'due', and uses the 'sv()' method.

```python
Annuity(
   amount=n,
   n=n,
   gr=Rate(i),
   aprog=-1,
   imd='due'
).sv()
```

--------------------------------

### TmVal: Import Amount and Rate for Simple Interest

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/simple.rst

Imports the necessary Amount and Rate classes from the TmVal package to model financial calculations, specifically for simple interest. These classes are fundamental for defining principal amounts and interest rates.

```python
from tmval import Amount, Rate
```

--------------------------------

### TmVal Payments with Accumulation Growth Rate (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/value/payments.rst

Shows how to initialize a TmVal Payments object using an Accumulation object to specify the growth rate, which allows for more complex interest patterns beyond simple compound interest.

```python
from tmval import Payments, Accumulation

pmts = Payments(amounts=[1000, 2000, 3000], times=[1, 2, 3], gr=Accumulation(.05))
```

--------------------------------

### Access SimpleLoan Attributes - Python

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/discount.rst

Retrieves specific attributes of a SimpleLoan object, including principal, discount amount, discount rate, and the amount available to the borrower. This demonstrates how to inspect the details of a simple loan created using the tmval package.

```python
print(my_loan.principal)
print(my_loan.discount_amt)
print(my_loan.discount_rate)
print(my_loan.amount_available)
```

--------------------------------

### Calculate Present Value of Annuity with TmVal's Annuity Class

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

Demonstrates calculating the present value (PV) of a basic annuity-immediate using the tmval.Annuity class. The Annuity class provides a unified way to represent various annuity types and perform operations on them. It is initialized with parameters like interest rate (gr) and term (n).

```python
from tmval import Annuity

print(Annuity(gr=.05, n=5).pv())
```

--------------------------------

### Calculate Outstanding Loan Balance using Retrospective Method in Python

Source: https://github.com/genedan/tmval/blob/master/docs/usage/loan/retrospective.rst

Demonstrates calculating the outstanding loan balance immediately after the 5th payment using TmVal's Loan class and the retrospective method. It requires the 'tmval' package and Rate for interest rate definition.

```python
from tmval import Loan, Rate

my_loan = Loan(
   amt=50000,
   pmt=5000,
   period=1,
   gr=Rate(.05),
)

print(my_loan.olb_r(t=5))
```

--------------------------------

### Calculate Approximate Dollar-Weighted Yield Rate with k-approximation (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/value/dollar_approx.rst

Calculates the approximate dollar-weighted yield rate using k-approximation by setting k_approx=True in the dw_approx method. When k_approx is True, k defaults to 1/2. This method requires a list of amounts and their corresponding times.

```python
from tmval import Payments

pmts = Payments(
    amounts=[10000, 5000, -16000],
    times=[0, 1, 2]
)

print(pmts.dw_approx(k_approx=True))
```

--------------------------------

### Standardize Rate to Annually Compounded Effective Interest - Python

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/rate_revisit.rst

Shows how to standardize an existing interest rate object to an annually compounded effective interest rate using the standardize method. This is useful for ensuring consistency in financial calculations.

```python
i = fr.standardize()

print(i)
```

--------------------------------

### Generate Loan Amortization Schedule with Pandas

Source: https://github.com/genedan/tmval/blob/master/README.md

This snippet demonstrates how to generate a full amortization schedule for a loan using TmVal's Loan class and display it as a Pandas DataFrame. It requires the pandas and tmval libraries. The input includes loan amount, term, interest rate, and payment frequency. The output is a DataFrame with time, payment amount, interest paid, principal paid, and remaining balance for each period.

```python
import pandas as pd

from tmval import Loan, Rate

gr = Rate(
    rate=.04,
    pattern="Nominal Interest",
    freq=4
)

my_loan = Loan(
    amt=50000,
    period=1/12,
    term=2,
    gr=gr,
    cents=True
)

amort = pd.DataFrame(my_loan.amortization())

print(amort)
```

--------------------------------

### Initialize Accumulation with Detailed Rate Object (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/reminder.rst

This snippet illustrates initializing an Accumulation class with a more detailed Rate object, specifying the rate, pattern, and interval. It then calculates and prints the accumulated value.

```python
gr=Rate(
   rate=.05,
   pattern="Effective Interest",
   interval=1
)

my_acc3 = Accumulation(gr=gr)

print(my_acc3.val(5))
```

--------------------------------

### Price Bond with Varying Coupon Rates (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

Prices a bond with varying coupon rates over its term. The coupon rates and their effective periods are specified as lists. Requires the tmval.Bond class.

```python
from tmval import Bond

bd = Bond(
   face=1000,
   red=1250,
   alpha=[(.05, 0), (.06, 2)],
   cfreq=[1,1],
   term=5,
   gr=.08
)

# verify coupon amounts
print(bd.coupons.amounts)

# verify coupon times
print(bd.coupons.times)

print(bd.price)
```

--------------------------------

### Equated Time Calculation in TmVal

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the equated time T for a series of payments. Uses the Payments class with amounts, times, and growth rate (gr), and calls the equated_time method with the cash amount (C).

```python
Payments(amounts, times, gr).equated_time(c=C)
```

--------------------------------

### Price a Bond with Fixed Coupon Rate (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/intro.rst

Prices a bond with a fixed face value, redemption value, coupon rate, and maturity term, given a specific yield rate. Uses the tmval.Bond class.

```python
from tmval import Bond

bd = Bond(
   face=1000,
   red=1250,
   alpha=.05,
   cfreq=1,
   term=5,
   gr=.08
)

print(bd.price)
```

--------------------------------

### Calculate Interest Earned

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/interest.rst

This code calculates the interest earned over a specific time interval using the `interest_earned` method of the Amount class. It requires the start time (t1) and end time (t2) of the interval.

```python
interest = my_amt.interest_earned(t1=4, t2=5)

print(interest)
```

--------------------------------

### Present Value of Perpetuity-Immediate with Payments More Frequent Than Interest Period Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the present value of a perpetuity-immediate where payments are more frequent than the interest period. Uses 'Annuity' with 'amount', 'term', 'gr', and 'period' set to 1/m.

```python
Annuity(
    amount=1/m,
    term=np.Inf,
    gr=Rate(i),
    period=1/m
).pv()
```

--------------------------------

### Accumulated Value of Annuity-Immediate with Payments More Frequent Than Interest Period Calculation

Source: https://github.com/genedan/tmval/blob/master/docs/notation.rst

Calculates the accumulated value of an annuity-immediate with payments more frequent than the interest period. Uses 'Annuity' with 'amount', 'term', 'gr', 'period', and the 'sv()' method.

```python
Annuity(
    amount=1/m,
    term=n,
    gr=Rate(i),
    period=1/m
).sv()
```

--------------------------------

### Convert TmVal Rate: Effective Interest over Different Interval

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/rate.rst

Illustrates how to convert an existing Rate object to an equivalent rate effective over a different time interval using the convert_rate method. This is useful for comparing rates across different periods.

```python
gr4 = gr3.convert_rate(
   pattern="Effective Interest",
   interval=2
)

print(gr4)
```

--------------------------------

### Instantiate and Use TmVal Amount Class with Custom Growth

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/amount.rst

This Python code demonstrates how to use the TmVal Amount class with a custom growth function. It initializes an Amount object with a defined growth function 'f' and a principal 'k', then calculates the value at time 't=5'.

```python
my_amt = Amount(gr=f, k=5)

print(my_amt.val(5))
```

--------------------------------

### TmVal: Solve for Simple Interest Rate

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/simple.rst

Uses the TmVal simple interest solver to find the interest rate required to grow a principal of $5 to a future value of $5.25 over 1 year. This showcases the solver functionality for determining unknown rate inputs.

```python
from tmval import simple_solver
s = simple_solver(fv=5.25, pv=5, t=1)
print(s)
```

--------------------------------

### Initialize Accumulation with Rate Object (Python)

Source: https://github.com/genedan/tmval/blob/master/docs/usage/growth/reminder.rst

This snippet shows initializing an Accumulation class using an explicit Rate object. It demonstrates creating a Rate object with a specific rate and then using it to initialize the Accumulation class, followed by calculating the accumulated value.

```python
from tmval import Rate

my_acc2 = Accumulation(gr=Rate(.05))

print(my_acc2.val(5))
```