Release/0.14.2 (#404)

* MAINT: Fix default params in CIR and Heston stochastic process (#401) (Thank you, @masanorihirano !) * TEST: Add and refactor tests (#400) (#394) * DOC: Clean documentation (#396) * DOC: Add `example_heston_iv.py` (#403) Co-authored-by: Masanori HIRANO <masanorihirano@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: GitHub Actions <action@github.com>
pfnet-research · Nov 23, 2021 · 4d7ff17 · 4d7ff17
1 parent a14df77
commit 4d7ff17
Show file tree

Hide file tree

Showing 21 changed files with 180 additions and 127 deletions.
diff --git a/docs/source/nn.functional.rst b/docs/source/nn.functional.rst
@@ -9,30 +9,42 @@ pfhedge.nn.functional
 Payoff Functions
 ----------------
 
-.. autofunction:: european_payoff
-.. autofunction:: lookback_payoff
-.. autofunction:: american_binary_payoff
-.. autofunction:: european_binary_payoff
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    european_payoff
+    lookback_payoff
+    american_binary_payoff
+    european_binary_payoff
 
 Criterion Functions
 -------------------
 
-.. autofunction:: exp_utility
-.. autofunction:: isoelastic_utility
-.. autofunction:: entropic_risk_measure
-.. autofunction:: expected_shortfall
-.. autofunction:: value_at_risk
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    exp_utility
+    isoelastic_utility
+    entropic_risk_measure
+    expected_shortfall
+    value_at_risk
 
 Other Functions
 -----------------
 
-.. autofunction:: leaky_clamp
-.. autofunction:: clamp
-.. autofunction:: topp
-.. autofunction:: realized_variance
-.. autofunction:: realized_volatility
-.. autofunction:: terminal_value
-.. autofunction:: ncdf
-.. autofunction:: npdf
-.. autofunction:: d1
-.. autofunction:: d2
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    leaky_clamp
+    clamp
+    topp
+    realized_variance
+    realized_volatility
+    terminal_value
+    ncdf
+    npdf
+    d1
+    d2
diff --git a/docs/source/nn.rst b/docs/source/nn.rst
@@ -4,10 +4,10 @@
 pfhedge.nn
 ==========
 
-`pfhedge.nn` provides `torch.nn.Module` that are useful for Deep Hedging.
+`pfhedge.nn` provides :class:`torch.nn.Module` that are useful for Deep Hedging.
 
 See `PyTorch Documentation <https://pytorch.org/docs/stable/generated/torch.nn.Module.html>`_
-for general usage of `torch.nn.Module`.
+for general usage of :class:`torch.nn.Module`.
 
 .. currentmodule:: pfhedge
 

diff --git a/docs/source/stochastic.rst b/docs/source/stochastic.rst
@@ -9,15 +9,27 @@ pfhedge.stochastic
 Brownian Motion
 ---------------
 
-.. autofunction:: generate_brownian
-.. autofunction:: generate_geometric_brownian
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    generate_brownian
+    generate_geometric_brownian
 
 Cox-Ingersoll-Ross Process
 --------------------------
 
-.. autofunction:: generate_cir
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    generate_cir
 
 Heston Process
 --------------
 
-.. autofunction:: generate_heston
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    generate_heston
diff --git a/examples/example_heston_iv.py b/examples/example_heston_iv.py
@@ -0,0 +1,43 @@
+import sys
+from math import exp
+
+import matplotlib.pyplot as plt
+import torch
+
+sys.path.append("..")
+from pfhedge.instruments import EuropeanOption
+from pfhedge.instruments import HestonStock
+from pfhedge.nn import BlackScholes
+
+LOG_MONEYNESS_MIN = -0.1
+LOG_MONEYNESS_MAX = 0.1
+LOG_MONEYNESS_STEPS = 20
+LOG_MONEYNESS_RANGE = torch.linspace(
+    LOG_MONEYNESS_MIN, LOG_MONEYNESS_MAX, LOG_MONEYNESS_STEPS
+)
+
+
+def compute_iv(log_moneyness: float, rho: float) -> float:
+    torch.manual_seed(42)
+
+    d = EuropeanOption(HestonStock(rho=rho))
+    spot = exp(log_moneyness) * d.strike
+    d.simulate(n_paths=int(1e5), init_state=(spot, d.ul().theta))
+    p = d.payoff().mean(0)
+
+    return BlackScholes(d).implied_volatility(log_moneyness, d.maturity, p).item()
+
+
+def main():
+    plt.figure()
+    for rho in [-0.7, 0.0, 0.7]:
+        y = [compute_iv(s, rho) for s in LOG_MONEYNESS_RANGE]
+        plt.plot(LOG_MONEYNESS_RANGE, y, label=f"rho={rho}")
+    plt.xlabel("Log moneyness")
+    plt.ylabel("Implied volatility")
+    plt.legend()
+    plt.savefig("output/heston-iv.png")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/requirements.txt b/examples/requirements.txt
@@ -0,0 +1,2 @@
+matplotlib
+tqdm
diff --git a/pfhedge/instruments/derivative/american_binary.py b/pfhedge/instruments/derivative/american_binary.py
@@ -14,7 +14,7 @@
 
 
 class AmericanBinaryOption(BaseOption):
-    """An American binary Option.
+    r"""American binary Option.
 
     An American binary call option pays an unit amount of cash if and only if
     the maximum of the underlying asset's price until maturity is equal or greater
@@ -27,27 +27,25 @@ class AmericanBinaryOption(BaseOption):
     The payoff of an American binary call option is given by:
 
     .. math::
+        \mathrm{payoff} =
+        \begin{cases}
+            1 & (\mathrm{Max} \geq K) \\
+            0 & (\text{otherwise})
+        \end{cases}
 
-        \\mathrm{payoff} =
-        \\begin{cases}
-            1 & (\\mathrm{Max} \\geq K) \\\\
-            0 & (\\text{otherwise})
-        \\end{cases}
-
-    Here, :math:`\\mathrm{Max}` is the maximum of the underlying asset's price
+    Here, :math:`\mathrm{Max}` is the maximum of the underlying asset's price
     until maturity and :math:`K` is the strike price (`strike`) of the option.
 
     The payoff of an American binary put option is given by:
 
     .. math::
+        \mathrm{payoff} =
+        \begin{cases}
+            1 & (\mathrm{Min} \leq K) \\
+            0 & (\text{otherwise})
+        \end{cases}
 
-        \\mathrm{payoff} =
-        \\begin{cases}
-            1 & (\\mathrm{Min} \\leq K) \\\\
-            0 & (\\text{otherwise})
-        \\end{cases}
-
-    Here, :math:`\\mathrm{Min}` is the minimum of the underlying asset's price.
+    Here, :math:`\mathrm{Min}` is the minimum of the underlying asset's price.
 
     .. seealso::
         :func:`pfhedge.nn.functional.american_binary_payoff`: Payoff function.
@@ -64,14 +62,13 @@ class AmericanBinaryOption(BaseOption):
         device (torch.device): The device where the simulated time-series are.
 
     Examples:
-
         >>> import torch
         >>> from pfhedge.instruments import BrownianStock
         >>> from pfhedge.instruments import AmericanBinaryOption
         >>>
         >>> _ = torch.manual_seed(42)
-        >>> derivative = AmericanBinaryOption(BrownianStock(), \
-maturity=5/250, strike=1.01)
+        >>> derivative = AmericanBinaryOption(
+        ...     BrownianStock(), maturity=5/250, strike=1.01)
         >>> derivative.simulate(n_paths=2)
         >>> derivative.underlier.spot
         tensor([[1.0000, 1.0016, 1.0044, 1.0073, 0.9930, 0.9906],

diff --git a/pfhedge/instruments/derivative/european.py b/pfhedge/instruments/derivative/european.py
@@ -14,7 +14,7 @@
 
 
 class EuropeanOption(BaseOption):
-    r"""A European option.
+    r"""European option.
 
     A European option provides its holder the right to buy (for call option)
     or sell (for put option) an underlying asset with the strike price
@@ -23,7 +23,6 @@ class EuropeanOption(BaseOption):
     The payoff of a European call option is given by:
 
     .. math::
-
         \mathrm{payoff} = \max(S - K, 0)
 
     Here, :math:`S` is the underlying asset's price at maturity and
@@ -32,7 +31,6 @@ class EuropeanOption(BaseOption):
     The payoff of a European put option is given by:
 
     .. math::
-
         \mathrm{payoff} = \max(K - S, 0)
 
     .. seealso::
@@ -50,7 +48,6 @@ class EuropeanOption(BaseOption):
         device (torch.device): The device where the simulated time-series are.
 
     Examples:
-
         >>> import torch
         >>> from pfhedge.instruments import BrownianStock
         >>> from pfhedge.instruments import EuropeanOption

diff --git a/pfhedge/instruments/derivative/european_binary.py b/pfhedge/instruments/derivative/european_binary.py
@@ -14,7 +14,7 @@
 
 
 class EuropeanBinaryOption(BaseOption):
-    """A European binary option.
+    r"""European binary option.
 
     An American binary call option pays an unit amount of cash if and only if
     the underlying asset's price at maturity is equal or greater than the strike price.
@@ -25,25 +25,23 @@ class EuropeanBinaryOption(BaseOption):
     The payoff of an American binary call option is given by:
 
     .. math::
-
-        \\mathrm{payoff} =
-        \\begin{cases}
-            1 & (S \\geq K) \\\\
-            0 & (\\text{otherwise})
-        \\end{cases}
+        \mathrm{payoff} =
+        \begin{cases}
+            1 & (S \geq K) \\
+            0 & (\text{otherwise})
+        \end{cases}
 
     with :math:`S` being the underlying asset's price at maturity and
     :math:`K` being the strike price (`strike`) of the option
 
     The payoff of an American binary put option is given by:
 
     .. math::
-
-        \\mathrm{payoff} =
-        \\begin{cases}
-            1 & (S \\leq K) \\\\
-            0 & (\\text{otherwise})
-        \\end{cases}
+        \mathrm{payoff} =
+        \begin{cases}
+            1 & (S \leq K) \\
+            0 & (\text{otherwise})
+        \end{cases}
 
     .. seealso::
         :func:`pfhedge.nn.functional.european_binary_payoff`: Payoff function.
@@ -60,7 +58,6 @@ class EuropeanBinaryOption(BaseOption):
         device (torch.device): The device where the simulated time-series are.
 
     Examples:
-
         >>> import torch
         >>> from pfhedge.instruments import BrownianStock
         >>> from pfhedge.instruments import EuropeanBinaryOption

diff --git a/pfhedge/instruments/derivative/lookback.py b/pfhedge/instruments/derivative/lookback.py
@@ -14,7 +14,7 @@
 
 
 class LookbackOption(BaseOption):
-    """A lookback option with fixed strike.
+    r"""Lookback option with fixed strike.
 
     A lookback call option provides its holder the right to buy an underlying with
     the strike price and to sell with the highest price until the date of maturity.
@@ -25,19 +25,17 @@ class LookbackOption(BaseOption):
     The payoff of a lookback call option is given by:
 
     .. math::
+        \mathrm{payoff} = \max(\mathrm{Max} - K, 0)
 
-        \\mathrm{payoff} = \\max(\\mathrm{Max} - K, 0)
-
-    Here, :math:`\\mathrm{Max}` is the maximum of the underlying asset's price
+    Here, :math:`\mathrm{Max}` is the maximum of the underlying asset's price
     until maturity and :math:`K` is the strike price (`strike`) of the option.
 
     The payoff of a lookback put option is given by:
 
     .. math::
+        \mathrm{payoff} = \max(K - \mathrm{Min}, 0)
 
-        \\mathrm{payoff} = \\max(K - \\mathrm{Min}, 0)
-
-    Here, :math:`\\mathrm{Min}` is the minimum of the underlying asset's price.
+    Here, :math:`\mathrm{Min}` is the minimum of the underlying asset's price.
 
     .. seealso::
         :func:`pfhedge.nn.functional.lookback_payoff`: Payoff function.
@@ -54,7 +52,6 @@ class LookbackOption(BaseOption):
         device (torch.device): The device where the simulated time-series are.
 
     Examples:
-
         >>> import torch
         >>> from pfhedge.instruments import BrownianStock
         >>> from pfhedge.instruments import LookbackOption

diff --git a/pfhedge/instruments/derivative/variance_swap.py b/pfhedge/instruments/derivative/variance_swap.py
@@ -13,7 +13,7 @@
 
 
 class VarianceSwap(BaseDerivative):
-    """A variance swap.
+    r"""Variance swap.
 
     A variance swap pays cash in the amount of the realized variance
     until the maturity and levies the cash of the strike variance.
@@ -22,9 +22,9 @@ class VarianceSwap(BaseDerivative):
 
     .. math::
 
-        \\mathrm{payoff} = \\sigma^2 - K
+        \mathrm{payoff} = \sigma^2 - K
 
-    where :math:`\\sigma^2` is the realized variance of the underlying asset
+    where :math:`\sigma^2` is the realized variance of the underlying asset
     until maturity and :math:`K` is the strike variance (``strike``).
     See :func:`pfhedge.nn.functional.realized_variance` for the definition of
     the realized variance.
@@ -40,7 +40,6 @@ class VarianceSwap(BaseDerivative):
         device (torch.device): The device where the simulated time-series are.
 
     Examples:
-
         >>> import torch
         >>> from pfhedge.nn.functional import realized_variance
         >>> from pfhedge.instruments import BrownianStock

diff --git a/pfhedge/nn/modules/bs/black_scholes.py b/pfhedge/nn/modules/bs/black_scholes.py
@@ -11,7 +11,7 @@
 
 
 class BlackScholes(Module):
-    """Initialize Black-Scholes formula module from a derivative.
+    """Creates Black-Scholes formula module from a derivative.
 
     The ``forward`` method returns the Black-Scholes delta.
 
@@ -28,7 +28,6 @@ class BlackScholes(Module):
           all but the last dimension are the same shape as the input.
 
     Examples:
-
         One can instantiate Black-Scholes module by using a derivative.
         For example, one can instantiate :class:`BSEuropeanOption` using
         a :class:`pfhedge.instruments.EuropeanOption`.