Release/0.12.3 (#323)

* ENH: Add `ncdf`, `npdf`, `d1`, `d2` to functional.py (#315)

* ENH: Add `Variance` feature (close #269) (#319)

* ENH: Add `autogreek.vega` (close #97) (#320)

* MAINT: Refine typing (#316) (#317)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

docs/source/autogreek.rst

@@ -8,5 +8,17 @@ pfhedge.autogreek
 
 .. currentmodule:: pfhedge.autogreek
 
+Delta
+-----
+
 .. autofunction:: delta
+
+Gamma
+-----
+
 .. autofunction:: gamma
+
+Vega
+----
+
+.. autofunction:: vega

docs/source/nn.functional.rst

@@ -30,3 +30,7 @@ Other Functions
 .. autofunction:: realized_variance
 .. autofunction:: realized_volatility
 .. autofunction:: terminal_value
+.. autofunction:: ncdf
+.. autofunction:: npdf
+.. autofunction:: d1
+.. autofunction:: d2

pfhedge/_utils/parse.py

@@ -1,9 +1,15 @@
+from numbers import Real
 from typing import Optional
+from typing import Union
 
 import torch
 from torch import Tensor
 
 
+def _as_optional_tensor(input: Optional[Union[Tensor, Real]]) -> Optional[Tensor]:
+    return torch.as_tensor(input) if input is not None else input
+
+
 def parse_spot(
     *,
     spot: Optional[Tensor] = None,
@@ -12,11 +18,27 @@ def parse_spot(
     log_moneyness: Optional[Tensor] = None,
     **kwargs
 ) -> Tensor:
+    spot = _as_optional_tensor(spot)
+    strike = _as_optional_tensor(strike)
+    moneyness = _as_optional_tensor(moneyness)
+    log_moneyness = _as_optional_tensor(log_moneyness)
+
     if spot is not None:
         return spot
     elif moneyness is not None and strike is not None:
         return moneyness * strike
     elif log_moneyness is not None and strike is not None:
         return log_moneyness.exp() * strike
     else:
-        raise ValueError("Insufficient parameters to parse `spot`")
+        raise ValueError("Insufficient parameters to parse spot")
+
+
+def parse_volatility(
+    *, volatility: Optional[Tensor] = None, variance: Optional[Tensor] = None, **kwargs
+) -> Tensor:
+    if volatility is not None:
+        return volatility
+    elif variance is not None:
+        return variance.clamp(min=0.0).sqrt()
+    else:
+        raise ValueError("Insufficient parameters to parse volatility")

pfhedge/_utils/typing.py

@@ -0,0 +1,5 @@
+from typing import Union
+
+from torch import Tensor
+
+TensorOrScalar = Union[Tensor, float, int]

pfhedge/autogreek.py

@@ -5,6 +5,7 @@
 from torch import Tensor
 
 from ._utils.parse import parse_spot
+from ._utils.parse import parse_volatility
 
 
 def delta(
@@ -25,9 +26,9 @@ def delta(
 
     Args:
         pricer (callable): Pricing formula of a derivative.
-        create_graph (bool, default=False): If ``True``, graph of the derivative
-            will be constructed, allowing to compute higher order derivative
-            products.
+        create_graph (bool, default=False): If ``True``,
+            graph of the derivative will be constructed,
+            allowing to compute higher order derivative products.
         **params: Parameters passed to ``pricer``.
 
     Returns:
@@ -96,7 +97,6 @@ def delta(
         if parameter not in signature(pricer).parameters.keys():
             del params[parameter]
 
-    assert spot.requires_grad
     price = pricer(**params)
     return torch.autograd.grad(
         price,
@@ -124,8 +124,9 @@ def gamma(
 
     Args:
         pricer (callable): Pricing formula of a derivative.
-        create_graph (bool, default=False): If ``True``, graph of the derivative will be
-            constructed, allowing to compute higher order derivative products.
+        create_graph (bool, default=False): If ``True``,
+            graph of the derivative will be constructed,
+            allowing to compute higher order derivative products.
         **params: Parameters passed to ``pricer``.
 
     Returns:
@@ -170,3 +171,63 @@ def gamma(
         grad_outputs=torch.ones_like(tensor_delta),
         create_graph=create_graph,
     )[0]
+
+
+def vega(
+    pricer: Callable[..., Tensor], *, create_graph: bool = False, **params
+) -> Tensor:
+    """Computes and returns vega of a derivative using automatic differentiation.
+
+    Vega is a differentiation of a derivative price with respect to
+    a variance of underlying instrument.
+
+    Note:
+        The keyword argument ``**params`` should contain at least one of the
+        following parameters:
+
+        - ``volatility``
+        - ``variance``
+
+    Args:
+        pricer (callable): Pricing formula of a derivative.
+        create_graph (bool, default=False): If ``True``,
+            graph of the derivative will be constructed,
+            allowing to compute higher order derivative products.
+        **params: Parameters passed to ``pricer``.
+
+    Returns:
+        torch.Tensor
+
+    Examples:
+
+        Vega of a European option can be evaluated as follows.
+
+        >>> import pfhedge.autogreek as autogreek
+        >>> from pfhedge.nn import BSEuropeanOption
+        >>>
+        >>> pricer = BSEuropeanOption().price
+        >>> autogreek.vega(
+        ...     pricer,
+        ...     log_moneyness=torch.zeros(3),
+        ...     time_to_maturity=torch.ones(3),
+        ...     volatility=torch.tensor([0.18, 0.20, 0.22]),
+        ... )
+        tensor([0.3973, 0.3970, 0.3965])
+    """
+    volatility = parse_volatility(**params).requires_grad_()
+    params["volatility"] = volatility
+    params["variance"] = volatility.pow(2)
+
+    # Delete parameters that are not in the signature of pricer to avoid
+    # TypeError: <pricer> got an unexpected keyword argument '<parameter>'
+    for parameter in list(params.keys()):
+        if parameter not in signature(pricer).parameters.keys():
+            del params[parameter]
+
+    price = pricer(**params)
+    return torch.autograd.grad(
+        price,
+        inputs=volatility,
+        grad_outputs=torch.ones_like(price),
+        create_graph=create_graph,
+    )[0]

pfhedge/features/__init__.py

@@ -11,5 +11,6 @@
 from .features import Moneyness
 from .features import PrevHedge
 from .features import TimeToMaturity
+from .features import Variance
 from .features import Volatility
 from .features import Zeros

pfhedge/features/_getter.py

@@ -11,6 +11,7 @@
 from .features import Moneyness
 from .features import PrevHedge
 from .features import TimeToMaturity
+from .features import Variance
 from .features import Volatility
 from .features import Zeros
 
@@ -23,6 +24,7 @@
     MaxMoneyness,
     Moneyness,
     PrevHedge,
+    Variance,
     Volatility,
     Zeros,
 ]

pfhedge/features/features.py

@@ -71,6 +71,17 @@ def __getitem__(self, time_step: Optional[int]) -> Tensor:
         return self.derivative.ul().volatility[:, index].unsqueeze(-1)
 
 
+class Variance(StateIndependentFeature):
+    """Variance of the underlier of the derivative."""
+
+    def __str__(self) -> str:
+        return "variance"
+
+    def __getitem__(self, time_step: Optional[int]) -> Tensor:
+        index = [time_step] if isinstance(time_step, int) else ...
+        return self.derivative.ul().variance[:, index].unsqueeze(-1)
+
+
 class PrevHedge(Feature):
     """Previous holding of underlier."""
 

pfhedge/instruments/derivative/base.py

@@ -13,12 +13,12 @@
 from pfhedge._utils.doc import _set_attr_and_docstring
 from pfhedge._utils.doc import _set_docstring
 from pfhedge._utils.str import _addindent
+from pfhedge._utils.typing import TensorOrScalar
 
 from ..base import Instrument
 from ..primary.base import Primary
 
 T = TypeVar("T", bound="Derivative")
-TensorOrFloat = Union[Tensor, float]
 
 
 class Derivative(Instrument):
@@ -60,7 +60,7 @@ def device(self) -> Optional[torch.device]:
         return self.underlier.device
 
     def simulate(
-        self, n_paths: int = 1, init_state: Optional[Tuple[TensorOrFloat, ...]] = None
+        self, n_paths: int = 1, init_state: Optional[Tuple[TensorOrScalar, ...]] = None
     ) -> None:
         """Simulate time series associated with the underlier.
 

pfhedge/instruments/primary/base.py

@@ -14,11 +14,11 @@
 
 from pfhedge._utils.doc import _set_attr_and_docstring
 from pfhedge._utils.doc import _set_docstring
+from pfhedge._utils.typing import TensorOrScalar
 
 from ..base import Instrument
 
 T = TypeVar("T", bound="Primary")
-TensorOrFloat = Union[float, Tensor]
 
 
 class Primary(Instrument):
@@ -52,7 +52,7 @@ def __init__(self) -> None:
         self.register_buffer("spot", None)
 
     @property
-    def default_init_state(self) -> Tuple[TensorOrFloat, ...]:
+    def default_init_state(self) -> Tuple[TensorOrScalar, ...]:
         """Returns the default initial state of simulation."""
 
     # TODO(simaki): Remove @no_type_check once BrownianStock and HestonStock get
@@ -63,7 +63,7 @@ def simulate(
         self,
         n_paths: int,
         time_horizon: float,
-        init_state: Optional[Tuple[TensorOrFloat, ...]] = None,
+        init_state: Optional[Tuple[TensorOrScalar, ...]] = None,
     ) -> None:
         """Simulate time series associated with the instrument and add them as buffers.
 

pfhedge/instruments/primary/brownian.py

@@ -10,12 +10,11 @@
 from pfhedge._utils.doc import _set_attr_and_docstring
 from pfhedge._utils.doc import _set_docstring
 from pfhedge._utils.str import _format_float
+from pfhedge._utils.typing import TensorOrScalar
 from pfhedge.stochastic import generate_geometric_brownian
 
 from .base import Primary
 
-TensorOrFloat = Union[Tensor, float]
-
 
 class BrownianStock(Primary):
     """A stock of which spot prices follow the geometric Brownian motion.
@@ -104,7 +103,7 @@ def simulate(
         self,
         n_paths: int = 1,
         time_horizon: float = 20 / 250,
-        init_state: Optional[Tuple[TensorOrFloat]] = None,
+        init_state: Optional[Tuple[TensorOrScalar]] = None,
     ) -> None:
         """Simulate the spot price and add it as a buffer named ``spot``.
 

pfhedge/instruments/primary/cir.py

@@ -9,12 +9,11 @@
 from pfhedge._utils.doc import _set_attr_and_docstring
 from pfhedge._utils.doc import _set_docstring
 from pfhedge._utils.str import _format_float
+from pfhedge._utils.typing import TensorOrScalar
 from pfhedge.stochastic import generate_cir
 
 from .base import Primary
 
-TensorOrFloat = Union[Tensor, float]
-
 
 class CIRRate(Primary):
     """A rate which follow the CIR process.
@@ -83,7 +82,7 @@ def simulate(
         self,
         n_paths: int = 1,
         time_horizon: float = 20 / 250,
-        init_state: Optional[Tuple[TensorOrFloat, ...]] = None,
+        init_state: Optional[Tuple[TensorOrScalar, ...]] = None,
     ) -> None:
         """Simulate the spot rate and add it as a buffer named ``spot``.
 

pfhedge/instruments/primary/heston.py

@@ -9,12 +9,11 @@
 from pfhedge._utils.doc import _set_attr_and_docstring
 from pfhedge._utils.doc import _set_docstring
 from pfhedge._utils.str import _format_float
+from pfhedge._utils.typing import TensorOrScalar
 from pfhedge.stochastic import generate_heston
 
 from .base import Primary
 
-TensorOrFloat = Union[Tensor, float]
-
 
 class HestonStock(Primary):
     """A stock of which spot price and variance follow Heston process.
@@ -104,7 +103,7 @@ def simulate(
         self,
         n_paths: int = 1,
         time_horizon: float = 20 / 250,
-        init_state: Optional[Tuple[TensorOrFloat, ...]] = None,
+        init_state: Optional[Tuple[TensorOrScalar, ...]] = None,
     ) -> None:
         """Simulate the spot price and add it as a buffer named ``spot``.