.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/interest_rate_models/options/plot_02_jamshidian_swaption.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_api_gallery_interest_rate_models_options_plot_02_jamshidian_swaption.py>`
        to download the full example code or to run this example in your browser via JupyterLite.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_api_gallery_interest_rate_models_options_plot_02_jamshidian_swaption.py:


Jamshidian's decomposition: swaptions in one-factor models
==========================================================

An option on a coupon bond is not a portfolio of options on its
coupons, in general. Jamshidian (1989) noticed that in a one-factor
model it is: every zero-coupon bond price falls with the short rate, so
the bond is above its strike exactly when the short rate is below a
critical :math:`r^*`, and then each zero is above
:math:`K_i = P(T, t_i; r^*)`. Hence

.. math:: \max\left(\sum_i c_i P(T, t_i) - K, 0\right) = \sum_i c_i \max(P(T, t_i) - K_i, 0).

A payer swaption is a put on a coupon bond paying the fixed rate, so it
too is a sum of zero-coupon bond options.

.. GENERATED FROM PYTHON SOURCE LINES 19-31

.. code-block:: Python

    import matplotlib.pyplot as plt
    import numpy as np

    from financialkit.fixed_income import NelsonSiegelCurve
    from financialkit.interest_rate_models import HullWhiteModel, forward_swap_rate, jamshidian_swaption, path_discount_factors, swaption_schedule
    from financialkit.interest_rate_models.visualizers import plot_jamshidian

    curve = NelsonSiegelCurve(0.05, -0.02, 0.01, 2.0)
    hw = HullWhiteModel(curve, 0.1, 0.01)
    expiry, tenor = 2.0, 5.0
    S = forward_swap_rate(curve, expiry, tenor, 2)








.. GENERATED FROM PYTHON SOURCE LINES 32-34

The decomposition of an at-the-money payer swaption
---------------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 34-40

.. code-block:: Python


    res = jamshidian_swaption(hw, expiry, tenor, S, freq=2, payer=True, notional=100.0)
    fig, axes = plt.subplots(1, 2, figsize=(11, 4))
    plot_jamshidian(res, ax=axes[0])
    print(f"forward swap rate {100 * S:.3f}%, critical short rate r* = {100 * res.critical_rate:.3f}%")




.. image-sg:: /api/gallery/interest_rate_models/options/images/sphx_glr_plot_02_jamshidian_swaption_001.png
   :alt: total 1.68463, r* = 4.601%
   :srcset: /api/gallery/interest_rate_models/options/images/sphx_glr_plot_02_jamshidian_swaption_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    forward swap rate 5.025%, critical short rate r* = 4.601%




.. GENERATED FROM PYTHON SOURCE LINES 41-43

Against Monte Carlo across strikes
----------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 43-59

.. code-block:: Python


    times, r = hw.simulate(expiry, 100, 20_000, rng=0)
    D = path_discount_factors(times, r)[:, -1]
    sched = swaption_schedule(expiry, tenor, 2)
    P = hw.zero_coupon_bond(sched[None, :], t=expiry, state=r[:, -1:])
    K = S + np.linspace(-0.015, 0.015, 7)
    closed = [jamshidian_swaption(hw, expiry, tenor, k, notional=100.0).price for k in K]
    pay = 100 * D[:, None] * np.maximum(1 - (0.5 * K[None, :] * P.sum(axis=1)[:, None] + P[:, -1:]), 0.0)
    axes[1].plot(100 * K, closed, "k-", label="Jamshidian")
    axes[1].errorbar(100 * K, pay.mean(0), yerr=1.96 * pay.std(0) / np.sqrt(D.size), fmt="o", ms=3, capsize=2, label="Monte Carlo")
    axes[1].set_xlabel("fixed rate (%)")
    axes[1].set_ylabel("payer swaption (per 100 notional)")
    axes[1].legend()
    fig.tight_layout()

    plt.show()








.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.077 seconds)


.. _sphx_glr_download_api_gallery_interest_rate_models_options_plot_02_jamshidian_swaption.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: lite-badge

      .. image:: images/jupyterlite_badge_logo.svg
        :target: ../../../../lite/lab/index.html?path=api/gallery/interest_rate_models/options/plot_02_jamshidian_swaption.ipynb
        :alt: Launch JupyterLite
        :width: 150 px

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_02_jamshidian_swaption.ipynb <plot_02_jamshidian_swaption.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_02_jamshidian_swaption.py <plot_02_jamshidian_swaption.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_02_jamshidian_swaption.zip <plot_02_jamshidian_swaption.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_