Amortization

class rateslib.legs.Amortization(n, initial, amortization=NoInput.blank)

Bases: object

An amortization schedule for any _BaseLeg.

Examples

In [1]: obj = Amortization(n=5, initial=1e6, amortization="to_zero")

In [2]: obj.outstanding
Out[2]: (1000000.0, 800000.0, 600000.0, 400000.0, 199999.99999999994)

In [3]: obj.amortization
Out[3]: (200000.0, 200000.0, 200000.0, 200000.0)

Parameters:

• n (int) – The number of periods in the schedule.

• initial (float, Dual, Dual2, Variable) – The notional applied to the first period in the schedule.

• amortization (float, Dual, Dual2, Variable, list, tuple, str, optional) – The amortization structure to apply to the schedule.

Notes

If amortization is:

• not specified then the schedule is assumed to have no amortization.

• some scalar then the amortization amount will be a constant value per period.

• a list or tuple of n-1 scalars, then this is defines a custome amortization schedule.

• a string flag then an amortization schedule will be calculated directly:

  • “to_zero”: each period will be a constant value ending with zero implied ending balance.

  • “{float}%”: each period will amortize by a constant percentage of the outstanding balance.

Using Amortization with Instruments

This section exemplifies how to use Amortization with instruments.

Key Points

• Amortization can be added to Instruments using the per leg amortization argument.

• It supports constant notional amortization, or custom schedules or the Amortization class can be used to calculate other simple structures.

• Some Instruments have not yet integrated amortization into their calculation, such as Bonds.

Standard Amortization

The FixedLeg and FloatLeg classes both have amortization as an input argument. An Amortization class can be directly supplied or other values are internally passed to this class for syntactic convenience.

The simplest, and most common, type of amortization to apply is a constant notional per period.

FixedLegFloatLeg

In [4]: fxl = FixedLeg(
   ...:     schedule=Schedule(dt(2000, 1, 1), "1y", "Q"),
   ...:     notional=10e6,
   ...:     amortization=1e6,      # <- 1mm reduction per period
   ...: )
   ...: 

In [5]: fxl.cashflows()[["Type", "Acc Start", "Notional"]]
Out[5]: 
          Type  Acc Start    Notional
0  FixedPeriod 2000-01-01  10000000.0
1  FixedPeriod 2000-04-01   9000000.0
2  FixedPeriod 2000-07-01   8000000.0
3  FixedPeriod 2000-10-01   7000000.0

Here, the amortization is expressed in a specific notional amount reduction per period so, when applied to an IRS, each leg with different frequencies should be input directly.

If a Leg has a final notional exchange then any amortized amount would, under standard convention, be paid out at the same time as the notional change. The final cashflow will be reduced by the amount of interim exchanges that have already occurred. This can be exemplified on a XCS.

IRSNon-MTM XCSMTM XCS

In [8]: irs = IRS(
   ...:     effective=dt(2000, 1, 1),
   ...:     termination="1Y",
   ...:     frequency="Q",
   ...:     leg2_frequency="S",
   ...:     notional=1e6,
   ...:     amortization=2e5,       # <- Reduces notional on 1st July to 600,000
   ...:     leg2_amortization=-4e5, # <- Aligns the notional on 1st July
   ...: )
   ...: 

In [9]: irs.cashflows()[["Type", "Acc Start", "Notional"]]
Out[9]: 
               Type  Acc Start   Notional
leg1 0  FixedPeriod 2000-01-01  1000000.0
     1  FixedPeriod 2000-04-01   800000.0
     2  FixedPeriod 2000-07-01   600000.0
     3  FixedPeriod 2000-10-01   400000.0
leg2 0  FloatPeriod 2000-01-01 -1000000.0
     1  FloatPeriod 2000-07-01  -600000.0

Custom Amortization

By using the Amortization class custom amortization can be directly input to an Instrument. The following examples are the same, with the first being syntactic convenience for the second. The above examples are also syntactic convenience for applying the same amortization amount each period.

Amortization ListAmortization Object

In [14]: irs = IRS(
   ....:     effective=dt(2000, 1, 1),
   ....:     termination="1Y",
   ....:     frequency="Q",
   ....:     leg2_frequency="S",
   ....:     notional=1e6,
   ....:     amortization=[100000, 300000, -5000],    # <- Reduces notional on 1st July to 600,000
   ....:     leg2_amortization=[-400000], # <- Aligns the notional on 1st July
   ....: )
   ....: 

In [15]: irs.cashflows()[["Type", "Acc Start", "Notional"]]
Out[15]: 
               Type  Acc Start   Notional
leg1 0  FixedPeriod 2000-01-01  1000000.0
     1  FixedPeriod 2000-04-01   900000.0
     2  FixedPeriod 2000-07-01   600000.0
     3  FixedPeriod 2000-10-01   605000.0
leg2 0  FloatPeriod 2000-01-01 -1000000.0
     1  FloatPeriod 2000-07-01  -600000.0

Unsupported Instruments

Instruments that currently do not support amortization are Bonds.

FixedRateBondIndexFixedRateBond

In [18]: try:
   ....:     FixedRateBond(
   ....:         effective=dt(2000, 1, 1),
   ....:         termination="1y",
   ....:         spec="us_gb",
   ....:         notional=5e6,
   ....:         amortization=1e6,
   ....:         fixed_rate=2.0,
   ....:     )
   ....: except Exception as e:
   ....:     print(e)
   ....: 
FixedRateBond.__init__() got an unexpected keyword argument 'amortization'

Attributes Summary

amortization	A tuple of (n-1) amortization amounts for each Period.
outstanding	A tuple of n outstanding notional amounts for each Period.

Attributes Documentation

amortization

A tuple of (n-1) amortization amounts for each Period.

outstanding

A tuple of n outstanding notional amounts for each Period.