TYP/REF: FXOptionStrat (#643)

Co-authored-by: JHM Darbyshire (M1) <[email protected]>
attack68 · Jan 21, 2025 · 902ff86 · 902ff86
1 parent 4f9b9c2
commit 902ff86
Show file tree

Hide file tree

Showing 12 changed files with 611 additions and 402 deletions.
diff --git a/docs/source/c_fx_smile.rst b/docs/source/c_fx_smile.rst
@@ -167,10 +167,10 @@ i.e. local currency interest rates at 3.90% and 5.32%, and an FX Swap rate at 8.
            IRS(dt(2024, 5, 9), "3W", spec="usd_irs", curves="usdusd"),
            FXSwap(dt(2024, 5, 9), "3W", pair="eurusd", curves=[None, "eurusd", None, "usdusd"]),
            FXStraddle(strike="atm_delta", **option_args),
-           FXRiskReversal(strike=["-25d", "25d"], **option_args),
-           FXRiskReversal(strike=["-10d", "10d"], **option_args),
-           FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **option_args),
-           FXBrokerFly(strike=["-10d", "atm_delta", "10d"], **option_args),
+           FXRiskReversal(strike=("-25d", "25d"), **option_args),
+           FXRiskReversal(strike=("-10d", "10d"), **option_args),
+           FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **option_args),
+           FXBrokerFly(strike=(("-10d", "10d"), "atm_delta"), **option_args),
        ],
        s=[3.90, 5.32, 8.85, 5.493, -0.157, -0.289, 0.071, 0.238],
        fx=fxf,
@@ -225,10 +225,10 @@ i.e. local currency interest rates at 3.90% and 5.32%, and an FX Swap rate at 8.
                  IRS(dt(2024, 5, 9), "3W", spec="usd_irs", curves="usdusd"),
                  FXSwap(dt(2024, 5, 9), "3W", currency="eur", leg2_currency="usd", curves=[None, "eurusd", None, "usdusd"]),
                  FXStraddle(strike="atm_delta", **option_args),
-                 FXRiskReversal(strike=["-25d", "25d"], **option_args),
-                 FXRiskReversal(strike=["-10d", "10d"], **option_args),
-                 FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **option_args),
-                 FXBrokerFly(strike=["-10d", "atm_delta", "10d"], **option_args),
+                 FXRiskReversal(strike=("-25d", "25d"), **option_args),
+                 FXRiskReversal(strike=("-10d", "10d"), **option_args),
+                 FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **option_args),
+                 FXBrokerFly(strike=(("-10d", "10d"), "atm_delta"), **option_args),
              ],
              s=[3.90, 5.32, 8.85, 5.493, -0.157, -0.289, 0.071, 0.238],
              fx=fxf,
@@ -361,11 +361,11 @@ node values until convergence with the given instrument rates.
        surfaces=[surface],
        instruments=[
            FXStraddle(strike="atm_delta", **fx_args_0),
-           FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **fx_args_0),
-           FXRiskReversal(strike=["-25d", "25d"], **fx_args_0),
+           FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **fx_args_0),
+           FXRiskReversal(strike=("-25d", "25d"), **fx_args_0),
            FXStraddle(strike="atm_delta", **fx_args_1),
-           FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **fx_args_1),
-           FXRiskReversal(strike=["-25d", "25d"], **fx_args_1),
+           FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **fx_args_1),
+           FXRiskReversal(strike=("-25d", "25d"), **fx_args_1),
        ],
        s=[18.25, 0.95, -0.6, 17.677, 0.85, -0.562],
        fx=fxf,
@@ -480,11 +480,11 @@ Three relevant cross-sectional *Smiles* from above are plotted.
        surfaces=[surface],
        instruments=[
            FXStraddle(strike="atm_delta", **fx_args_0),
-           FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **fx_args_0),
-           FXRiskReversal(strike=["-25d", "25d"], **fx_args_0),
+           FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **fx_args_0),
+           FXRiskReversal(strike=("-25d", "25d"), **fx_args_0),
            FXStraddle(strike="atm_delta", **fx_args_1),
-           FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **fx_args_1),
-           FXRiskReversal(strike=["-25d", "25d"], **fx_args_1),
+           FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **fx_args_1),
+           FXRiskReversal(strike=("-25d", "25d"), **fx_args_1),
        ],
        s=[18.25, 0.95, -0.6, 17.677, 0.85, -0.562],
        fx=fxf,
@@ -553,11 +553,11 @@ Alternative a 3D surface plot can also be shown.
        surfaces=[surface],
        instruments=[
            FXStraddle(strike="atm_delta", **fx_args_0),
-           FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **fx_args_0),
-           FXRiskReversal(strike=["-25d", "25d"], **fx_args_0),
+           FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **fx_args_0),
+           FXRiskReversal(strike=("-25d", "25d"), **fx_args_0),
            FXStraddle(strike="atm_delta", **fx_args_1),
-           FXBrokerFly(strike=["-25d", "atm_delta", "25d"], **fx_args_1),
-           FXRiskReversal(strike=["-25d", "25d"], **fx_args_1),
+           FXBrokerFly(strike=(("-25d", "25d"), "atm_delta"), **fx_args_1),
+           FXRiskReversal(strike=("-25d", "25d"), **fx_args_1),
        ],
        s=[18.25, 0.95, -0.6, 17.677, 0.85, -0.562],
        fx=fxf,

diff --git a/docs/source/e_fx_volatility.rst b/docs/source/e_fx_volatility.rst
@@ -505,7 +505,7 @@ The default pricing ``metric`` is *'single_vol'* which calculates the single vol
        pair="eurusd",
        expiry=dt(2023, 6, 16),
        notional=[20e6, -13.5e6],
-       strike=("-25d", "atm_delta", "25d"),
+       strike=(("-25d", "25d"), "atm_delta"),
        payment_lag=2,
        delivery_lag=2,
        calendar="tgt|fed",
@@ -515,7 +515,7 @@ The default pricing ``metric`` is *'single_vol'* which calculates the single vol
    fxbf.rate(
        curves=[None, fxf.curve("eur", "usd"), None, fxf.curve("usd", "usd")],
        fx=fxf,
-       vol=[10.15, 7.5, 8.9]
+       vol=[[10.15, 8.9], 7.5]
    )
    fxbf.plot_payoff(
        range=[1.000, 1.150],
@@ -549,7 +549,7 @@ The default pricing ``metric`` is *'single_vol'* which calculates the single vol
        pair="eurusd",
        expiry=dt(2023, 6, 16),
        notional=[20e6, -13.5e6],
-       strike=("-25d", "atm_delta", "25d"),
+       strike=(("-25d", "25d"), "atm_delta"),
        payment_lag=2,
        delivery_lag=2,
        calendar="tgt|fed",

diff --git a/docs/source/i_whatsnew.rst b/docs/source/i_whatsnew.rst
@@ -15,6 +15,18 @@ email contact, see `rateslib <https://rateslib.com>`_.
 1.7.0 (No Release Date)
 ****************************
 
+The key theme for 1.7.0 was to add Python type hinting to the entire codebase, and adding
+``mypy`` CI checks to the development process. This resulted in
+a number of refactorisations which may have changed the way some argument inputs should be
+structured.
+
+*FXOptions* which were added and listed in beta status since v1.2.0, have seen the largest
+changes and have now been moved out beta status.
+
+Internally, caching and state management were improved to provide more safety, preventing users
+inadvertently mutating objects without the *Solver's* *Gradients* being updated. All mutable
+objects now have specific methods to allow *updates*.
+
 .. list-table::
    :widths: 25 75
    :header-rows: 1
@@ -105,6 +117,14 @@ email contact, see `rateslib <https://rateslib.com>`_.
      - The internal data objects for *FXOption* pricing are restructured to conform to more
        strict data typing.
        (`642 <https://github.com/attack68/rateslib/pull/642>`_)
+   * - Refactor
+     - :red:`Minor Breaking Change!` The argument inputs for *FXOptionStrat* types, such
+       as :class:`~rateslib.instruments.FXRiskReversal`, :class:`~rateslib.instruments.FXStraddle`,
+       :class:`~rateslib.instruments.FXStrangle` and :class:`~rateslib.instruments.FXBrokerFly`,
+       may have changed to conform to a more generalised structure. This may include the
+       specification of their ``premium``, ``strike``, ``notional`` and ``vol`` inputs. Review
+       their updated documentation for details.
+       (Mostly `643 <https://github.com/attack68/rateslib/pull/643>`_)
 
 1.6.0 (30th November 2024)
 ****************************

diff --git a/docs/source/z_eurusd_surface.ipynb b/docs/source/z_eurusd_surface.ipynb
@@ -355,10 +355,10 @@
     "for row in range(11):\n",
     "    instruments_le_1y.extend([\n",
     "        FXStraddle(strike=\"atm_delta\", expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
-    "        FXRiskReversal(strike=[\"-25d\", \"25d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
-    "        FXBrokerFly(strike=[\"-25d\", \"atm_delta\", \"25d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
-    "        FXRiskReversal(strike=[\"-10d\", \"10d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
-    "        FXBrokerFly(strike=[\"-10d\", \"atm_delta\", \"10d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
+    "        FXRiskReversal(strike=(\"-25d\", \"25d\"), expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
+    "        FXBrokerFly(strike=((\"-25d\", \"25d\"), \"atm_delta\"), expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
+    "        FXRiskReversal(strike=(\"-10d\", \"10d\"), expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
+    "        FXBrokerFly(strike=((\"-10d\", \"10d\"), \"atm_delta\"), expiry=vol_data[\"expiry\"][row], delta_type=\"spot\", **fx_args),\n",
     "    ])\n",
     "    rates_le_1y.extend([vol_data[\"atm\"][row], vol_data[\"25drr\"][row], vol_data[\"25dbf\"][row], vol_data[\"10drr\"][row], vol_data[\"10dbf\"][row]])\n",
     "    labels_le_1y.extend([f\"atm_{row}\", f\"25drr_{row}\", f\"25dbf_{row}\", f\"10drr_{row}\", f\"10dbf_{row}\"])"
@@ -383,10 +383,10 @@
     "for row in range(11, 23):\n",
     "    instruments_gt_1y.extend([\n",
     "        FXStraddle(strike=\"atm_delta\", expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
-    "        FXRiskReversal(strike=[\"-25d\", \"25d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
-    "        FXBrokerFly(strike=[\"-25d\", \"atm_delta\", \"25d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
-    "        FXRiskReversal(strike=[\"-10d\", \"10d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
-    "        FXBrokerFly(strike=[\"-10d\", \"atm_delta\", \"10d\"], expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
+    "        FXRiskReversal(strike=(\"-25d\", \"25d\"), expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
+    "        FXBrokerFly(strike=((\"-25d\", \"25d\"), \"atm_delta\"), expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
+    "        FXRiskReversal(strike=(\"-10d\", \"10d\"), expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
+    "        FXBrokerFly(strike=((\"-10d\", \"10d\"), \"atm_delta\"), expiry=vol_data[\"expiry\"][row], delta_type=\"forward\", **fx_args),\n",
     "    ])\n",
     "    rates_gt_1y.extend([vol_data[\"atm\"][row], vol_data[\"25drr\"][row], vol_data[\"25dbf\"][row], vol_data[\"10drr\"][row], vol_data[\"10dbf\"][row]])\n",
     "    labels_gt_1y.extend([f\"atm_{row}\", f\"25drr_{row}\", f\"25dbf_{row}\", f\"10drr_{row}\", f\"10dbf_{row}\"])"
@@ -445,22 +445,6 @@
    "source": [
     "surface.smiles[0].plot(comparators=surface.smiles[1:])"
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "7d447f20-17cf-48e0-88cf-2cb10421dda8",
-   "metadata": {},
-   "source": [
-    "## Calculating a generic option price"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cd193993-a065-402a-9654-0faf0eb9e676",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

diff --git a/pyproject.toml b/pyproject.toml
@@ -151,7 +151,7 @@ packages = [
 ]
 exclude = [
     # "/instruments/bonds/securities.py",
-    "/instruments/fx_volatility/strategies.py",
+    # "/instruments/fx_volatility/strategies.py",
     # "/instruments/generics.py",
     # "/instruments/rates/inflation.py",
     "solver.py",