Release/0.19.0 (#545)

* ENH: Add `box_muller` (#534) * ENH: Add `VasicekRate` (close #505) (#538) * ENH: Add `LocalVolatilityStock` (#539) * DOC: Add documentation of features (#541) * DOC: Miscellaneous updates (#537) (#547) (#542) (#543) (#548) * MAINT: Fix primary spot typing (#530) (#533) * MAINT: Add `extra_repr` to `SVIVariance` (#535) * MAINT: Reimplement looking ahead to multiple underliers (#536) * MAINT: Add `OptionMixin` and deprecate `BaseOption` (#544) * `BaseOption` is deprecated. Inherit `BaseDerivative` and `OptionMixin` instead. * MAINT: Bumping version from 0.18.0 to 0.19.0 (#546) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
pfnet-research · Mar 14, 2022 · e19efce · e19efce
1 parent 0460355
commit e19efce
Show file tree

Hide file tree

Showing 46 changed files with 1,198 additions and 183 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,5 @@
 poetry.lock
-docs/source/generated
+docs/source/generated/
 examples/output/*
 !examples/output/.gitkeep
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -69,7 +69,7 @@
 # Disable displaying type annotations, these can be very verbose
 autodoc_typehints = "none"
 
-autodoc_default_options = {"show-inheritance": True}
+# autodoc_default_options = {"show-inheritance": True}
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),

diff --git a/docs/source/features.rst b/docs/source/features.rst
@@ -0,0 +1,60 @@
+.. _features:
+
+pfhedge.features
+================
+
+`pfhedge.features` provides features for :class:`pfhedge.nn.Hedger`.
+
+.. currentmodule:: pfhedge.features
+
+Creation
+--------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
+    get_feature
+    list_feature_names
+
+Derivatives Features
+--------------------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+    :template: classtemplate.rst
+
+    Moneyness
+    LogMoneyness
+    MaxMoneyness
+    MaxLogMoneyness
+    Barrier
+    PrevHedge
+    TimeToMaturity
+    UnderlierSpot
+    Variance
+    Volatility
+
+Tensor Creation Ops
+-------------------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+    :template: classtemplate.rst
+
+    Empty
+    Ones
+    Zeros
+
+Containers
+----------
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+    :template: classtemplate.rst
+
+    ModuleOutput
+    FeatureList
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -29,6 +29,7 @@ Install:
    instruments
    stochastic
    autogreek
+   features
 
 |
 

diff --git a/docs/source/instruments.rst b/docs/source/instruments.rst
@@ -10,33 +10,36 @@ Base Class
 ----------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     instruments.BaseInstrument
     instruments.BasePrimary
     instruments.BaseDerivative
+    instruments.OptionMixin
     instruments.BaseOption
 
 Primary Instruments
 -------------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     instruments.BrownianStock
     instruments.HestonStock
+    instruments.LocalVolatilityStock
     instruments.CIRRate
+    instruments.VasicekRate
 
 Derivative Instruments
 ----------------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     instruments.AmericanBinaryOption

diff --git a/docs/source/nn.functional.rst b/docs/source/nn.functional.rst
@@ -45,6 +45,9 @@ Criterion Functions
 Black-Scholes formulas
 ----------------------
 
+European option
+~~~~~~~~~~~~~~~
+
 .. autosummary::
     :nosignatures:
     :toctree: generated
@@ -54,16 +57,40 @@ Black-Scholes formulas
     bs_european_gamma
     bs_european_vega
     bs_european_theta
+
+American binary option
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
     bs_american_binary_price
     bs_american_binary_delta
     bs_american_binary_gamma
     bs_american_binary_vega
     bs_american_binary_theta
+
+European binary option
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
     bs_european_binary_price
     bs_european_binary_delta
     bs_european_binary_gamma
     bs_european_binary_vega
     bs_european_binary_theta
+
+Lookback option
+~~~~~~~~~~~~~~~
+
+.. autosummary::
+    :nosignatures:
+    :toctree: generated
+
     bs_lookback_price
     bs_lookback_delta
     bs_lookback_gamma
@@ -78,6 +105,7 @@ Other Functions
     :toctree: generated
 
     bilerp
+    box_muller
     d1
     d2
     ncdf

diff --git a/docs/source/nn.rst b/docs/source/nn.rst
@@ -4,7 +4,7 @@
 pfhedge.nn
 ==========
 
-`pfhedge.nn` provides :class:`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 :class:`torch.nn.Module`.
@@ -15,8 +15,8 @@ Hedger Module
 -------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     nn.Hedger
@@ -25,8 +25,8 @@ Black-Scholes Layers
 --------------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     nn.BlackScholes
@@ -39,8 +39,8 @@ Whalley-Wilmott Layers
 ----------------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     nn.WhalleyWilmott
@@ -49,8 +49,8 @@ Nonlinear Activations
 ---------------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     nn.Clamp
@@ -60,8 +60,8 @@ Loss Functions
 --------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     nn.HedgeLoss
@@ -74,8 +74,8 @@ Multi Layer Perceptron
 ----------------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     nn.MultiLayerPerceptron
@@ -84,8 +84,8 @@ Other Modules
 -------------
 
 .. autosummary::
-    :toctree: generated
     :nosignatures:
+    :toctree: generated
     :template: classtemplate.rst
 
     nn.Naked

diff --git a/docs/source/stochastic.rst b/docs/source/stochastic.rst
@@ -6,33 +6,19 @@ pfhedge.stochastic
 
 .. currentmodule:: pfhedge.stochastic
 
-Brownian Motion
----------------
+Stochastic Processes
+--------------------
 
 .. autosummary::
     :nosignatures:
     :toctree: generated
 
     generate_brownian
-    generate_geometric_brownian
-
-Cox-Ingersoll-Ross Process
---------------------------
-
-.. autosummary::
-    :nosignatures:
-    :toctree: generated
-
     generate_cir
-
-Heston Process
---------------
-
-.. autosummary::
-    :nosignatures:
-    :toctree: generated
-
+    generate_geometric_brownian
     generate_heston
+    generate_local_volatility_process
+    generate_vasicek
 
 Generators
 ----------

diff --git a/pfhedge/_utils/typing.py b/pfhedge/_utils/typing.py
@@ -1,5 +1,7 @@
+from typing import Callable
 from typing import Union
 
 from torch import Tensor
 
 TensorOrScalar = Union[Tensor, float, int]
+LocalVolatilityFunction = Callable[[Tensor, Tensor], Tensor]
diff --git a/pfhedge/features/__init__.py b/pfhedge/features/__init__.py
@@ -1,14 +1,16 @@
 from ._getter import get_feature
+from ._getter import list_feature_names
 from ._getter import list_features
 from .container import FeatureList
 from .container import ModuleOutput
 from .features import Barrier
 from .features import Empty
-from .features import ExpiryTime
+from .features import ExpiryTime  # deprecated
 from .features import LogMoneyness
 from .features import MaxLogMoneyness
 from .features import MaxMoneyness
 from .features import Moneyness
+from .features import Ones
 from .features import PrevHedge
 from .features import Spot
 from .features import TimeToMaturity

diff --git a/pfhedge/features/_base.py b/pfhedge/features/_base.py
@@ -18,6 +18,7 @@ class Feature(ABC):
     All features should subclass this class.
     """
 
+    name: str
     derivative: BaseDerivative
     hedger: Optional[Module]
 
@@ -73,6 +74,9 @@ def is_state_dependent(self) -> bool:
         # If a feature uses the state of a hedger, it is state dependent.
         return getattr(self, "hedger") is not None
 
+    def __str__(self):
+        return self.name
+
     # TODO(simaki) Remove later
     def __getitem__(self, time_step: Optional[int]) -> Tensor:
         # raise DeprecationWarning("Use `<feature>.get(time_step)` instead")

diff --git a/pfhedge/features/_getter.py b/pfhedge/features/_getter.py
@@ -96,6 +96,12 @@ def get_feature(feature: Union[str, Feature], **kwargs: Any) -> Feature:
 
     Returns:
         Feature
+
+    Examples:
+        >>> from pfhedge.features import get_feature
+        ...
+        >>> get_feature("moneyness")
+        <pfhedge.features.features.Moneyness object at ...>
     """
     if isinstance(feature, str):
         feature = FeatureFactory().get_instance(feature, **kwargs)
@@ -109,7 +115,12 @@ def list_feature_dict() -> dict:
 
 
 def list_feature_names() -> list:
-    return list(FeatureFactory().names())
+    """Returns the list of the names of available features.
+
+    Returns:
+        list[str]
+    """
+    return sorted(list(FeatureFactory().names()))
 
 
 def list_features() -> list: