IRS#

class rateslib.instruments.IRS(*args, fixed_rate=NoInput.blank, leg2_float_spread=NoInput.blank, leg2_spread_compound_method=NoInput.blank, leg2_fixings=NoInput.blank, leg2_fixing_method=NoInput.blank, leg2_method_param=NoInput.blank, **kwargs)#

Bases: BaseDerivative

Create an interest rate swap composing a FixedLeg and a FloatLeg.

Parameters:

  • args (dict) – Required positional args to BaseDerivative.

  • fixed_rate (float or None) – The fixed rate applied to the FixedLeg. If None will be set to mid-market when curves are provided.

  • leg2_float_spread (float, optional) – The spread applied to the FloatLeg. Can be set to None and designated later, perhaps after a mid-market spread for all periods has been calculated.

  • leg2_spread_compound_method (str, optional) – The method to use for adding a floating spread to compounded rates. Available options are {“none_simple”, “isda_compounding”, “isda_flat_compounding”}.

  • leg2_fixings (float, list, or Series optional) – If a float scalar, will be applied as the determined fixing for the first period. If a list of n fixings will be used as the fixings for the first n periods. If any sublist of length m is given, is used as the first m RFR fixings for that FloatPeriod. If a datetime indexed Series will use the fixings that are available in that object, and derive the rest from the curve.

  • leg2_fixing_method (str, optional) – The method by which floating rates are determined, set by default. See notes.

  • leg2_method_param (int, optional) – A parameter that is used for the various fixing_method s. See notes.

  • kwargs (dict) – Required keyword arguments to BaseDerivative.

Examples

Construct a curve to price the example.

In [1]: usd = Curve(
   ...:     nodes={
   ...:         dt(2022, 1, 1): 1.0,
   ...:         dt(2023, 1, 1): 0.965,
   ...:         dt(2024, 1, 1): 0.94
   ...:     },
   ...:     id="usd"
   ...: )
   ...:

Create the IRS, and demonstrate the rate(), npv(), analytic_delta(), and spread().

In [2]: irs = IRS(
   ...:     effective=dt(2022, 1, 1),
   ...:     termination="18M",
   ...:     frequency="A",
   ...:     calendar="nyc",
   ...:     currency="usd",
   ...:     fixed_rate=3.269,
   ...:     convention="Act360",
   ...:     notional=100e6,
   ...:     curves=["usd"],
   ...: )
   ...: 

In [3]: irs.rate(curves=usd)
Out[3]: 3.249288792744425

In [4]: irs.npv(curves=usd)
Out[4]: -28758.047425792553

In [5]: irs.analytic_delta(curve=usd)
Out[5]: 14589.693595585577

In [6]: irs.spread(curves=usd)
Out[6]: 1.9711207255575205

A DataFrame of cashflows().

In [7]: irs.cashflows(curves=usd)
Out[7]: 
               Type   Period  Ccy  Acc Start    Acc End    Payment Convention  DCF      Notional   DF Collateral  Rate  Spread    Cashflow         NPV  FX Rate     NPV Ccy
leg1 0  FixedPeriod     Stub  USD 2022-01-03 2022-07-01 2022-07-06     Act360 0.50  100000000.00 0.98       None  3.27     NaN -1625419.44 -1596175.86     1.00 -1596175.86
     1  FixedPeriod  Regular  USD 2022-07-01 2023-07-03 2023-07-06     Act360 1.02  100000000.00 0.95       None  3.27     NaN -3332563.89 -3173194.97     1.00 -3173194.97
leg2 0  FloatPeriod     Stub  USD 2022-01-03 2022-07-01 2022-07-06     Act360 0.50 -100000000.00 0.98       None  3.54    0.00  1762548.59  1730837.86     1.00  1730837.86
     1  FloatPeriod  Regular  USD 2022-07-01 2023-07-03 2023-07-06     Act360 1.02 -100000000.00 0.95       None  3.10    0.00  3160936.32  3009774.93     1.00  3009774.93

For accurate sensitivity calculations; delta() and gamma(), construct a curve model.

In [8]: sofr_kws = dict(
   ...:     effective=dt(2022, 1, 1),
   ...:     frequency="A",
   ...:     convention="Act360",
   ...:     calendar="nyc",
   ...:     currency="usd",
   ...:     curves=["usd"]
   ...: )
   ...: 

In [9]: instruments = [
   ...:     IRS(termination="1Y", **sofr_kws),
   ...:     IRS(termination="2Y", **sofr_kws),
   ...: ]
   ...: 

In [10]: solver = Solver(
   ....:     curves=[usd],
   ....:     instruments=instruments,
   ....:     s=[3.65, 3.20],
   ....:     instrument_labels=["1Y", "2Y"],
   ....:     id="sofr",
   ....: )
   ....: 
SUCCESS: `func_tol` reached after 3 iterations (levenberg_marquardt), `f_val`: 7.109030435594377e-13, `time`: 0.0024s

In [11]: irs.delta(solver=solver)
Out[11]: 
local_ccy                    usd
display_ccy                  usd
type        solver label        
instruments sofr   1Y    4751.30
                   2Y    9716.12

In [12]: irs.gamma(solver=solver)
Out[12]: 
type                                           instruments      
solver                                                sofr      
label                                                   1Y    2Y
local_ccy display_ccy type        solver label                  
usd       usd         instruments sofr   1Y          -0.69 -0.96
                                         2Y          -0.96 -0.96

Attributes Summary

fixed_rate

If set will also set the fixed_rate of the contained leg1.

float_spread

If set will also set the float_spread of contained leg1.

index_base

If set will also set the index_base of the contained leg1.

leg2_fixed_rate

If set will also set the fixed_rate of the contained leg2.

leg2_float_spread

If set will also set the float_spread of contained leg2.

leg2_index_base

If set will also set the index_base of the contained leg1.

Methods Summary

analytic_delta(*args, **kwargs)

Return the analytic delta of a leg of the derivative object.

cashflows([curves, solver, fx, base])

Return the properties of all legs used in calculating cashflows.

cashflows_table([curves, solver, fx, base])

delta(*args, **kwargs)

Calculate the delta of the Instrument.

gamma(*args, **kwargs)

Calculate the gamma of the Instrument.

npv([curves, solver, fx, base, local])

Return the NPV of the derivative by summing legs.

rate([curves, solver, fx, base])

Return the mid-market rate of the IRS.

spread([curves, solver, fx, base])

Return the mid-market float spread (bps) required to equate to the fixed rate.

Attributes Documentation

fixed_rate#

If set will also set the fixed_rate of the contained leg1.

Note

fixed_rate, float_spread, leg2_fixed_rate and leg2_float_spread are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:

float or None

float_spread#

If set will also set the float_spread of contained leg1.

Type:

float or None

index_base#

If set will also set the index_base of the contained leg1.

Note

index_base and leg2_index_base are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:

float or None

leg2_fixed_rate#

If set will also set the fixed_rate of the contained leg2.

Type:

float or None

leg2_float_spread#

If set will also set the float_spread of contained leg2.

Type:

float or None

leg2_index_base#

If set will also set the index_base of the contained leg1.

Note

index_base and leg2_index_base are attributes only applicable to certain Instruments. AttributeErrors are raised if calling or setting these is invalid.

Type:

float or None

Methods Documentation

analytic_delta(*args, **kwargs)#

Return the analytic delta of a leg of the derivative object.

See BaseDerivative.analytic_delta().

cashflows(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the properties of all legs used in calculating cashflows.

See BaseDerivative.cashflows().

cashflows_table(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#
delta(*args, **kwargs)#

Calculate the delta of the Instrument.

For arguments see Sensitivities.delta().

gamma(*args, **kwargs)#

Calculate the gamma of the Instrument.

For arguments see Sensitivities.gamma().

npv(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank, local=False)#

Return the NPV of the derivative by summing legs.

See BaseDerivative.npv().

rate(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the mid-market rate of the IRS.

Parameters:

  • curves (Curve, str or list of such) –

    A single Curve or id or a list of such. A list defines the following curves in the order:

    • Forecasting Curve for floating leg.

    • Discounting Curve for both legs.

  • solver (Solver, optional) –

    The numerical Solver that constructs Curve from calibrating instruments.

    Note

    The arguments fx and base are unused by single currency derivatives rates calculations.

Return type:

float, Dual or Dual2

Notes

The arguments fx and base are unused by single currency derivatives rates calculations.

spread(curves=NoInput.blank, solver=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Return the mid-market float spread (bps) required to equate to the fixed rate.

Parameters:

  • curves (Curve, str or list of such) –

    A single Curve or id or a list of such. A list defines the following curves in the order:

    • Forecasting Curve for floating leg.

    • Discounting Curve for both legs.

  • solver (Solver, optional) –

    The numerical Solver that constructs Curve from calibrating instruments.

    Note

    The arguments fx and base are unused by single currency derivatives rates calculations.

Return type:

float, Dual or Dual2

Notes

If the IRS is specified without a fixed_rate this should always return the current leg2_float_spread value or zero since the fixed rate used for calculation is the implied rate including the current leg2_float_spread parameter.

Examples

For the most common parameters this method will be exact.

In [1]: irs.spread(curves=usd)
Out[1]: <Dual: -6.952598, (usd0, usd1, usd2), [-6763.2, 3506.0, 3605.2]>

In [2]: irs.leg2_float_spread = -6.948753

In [3]: irs.npv(curves=usd)
Out[3]: <Dual: 56.039476, (usd0, usd1, usd2), [98572891.0, -51099201.0, -52545015.2]>

When a non-linear spread compound method is used for float RFR legs this is an approximation, via second order Taylor expansion.

In [4]: irs = IRS(
   ...:     effective=dt(2022, 2, 15),
   ...:     termination=dt(2022, 8, 15),
   ...:     frequency="Q",
   ...:     convention="30e360",
   ...:     leg2_convention="Act360",
   ...:     leg2_fixing_method="rfr_payment_delay",
   ...:     leg2_spread_compound_method="isda_compounding",
   ...:     payment_lag=2,
   ...:     fixed_rate=2.50,
   ...:     leg2_float_spread=0,
   ...:     notional=50000000,
   ...:     currency="usd",
   ...: )
   ...: 

In [5]: irs.spread(curves=usd)
Out[5]: <Dual: -111.041751, (usd0, usd1, usd2), [-9863.5, 10229.0, 0.0]>

In [6]: irs.leg2_float_spread = -111.060143

In [7]: irs.npv(curves=usd)
Out[7]: <Dual: -46.029734, (usd0, usd1, usd2), [24498752.8, -25406680.5, 0.0]>

In [8]: irs.spread(curves=usd)
Out[8]: <Dual: -111.041611, (usd0, usd1, usd2), [-9863.5, 10229.0, 0.0]>

The leg2_float_spread is determined through NPV differences. If the difference is small since the defined spread is already quite close to the solution the approximation is much more accurate. This is shown above where the second call to irs.spread is different to the previous call, albeit the difference is 1/10000th of a basis point.