class_docstr: Heston Model with piecewise constant parameters.
  
  Represents the Ito process:
  
  ```None
    dX(t) = -V(t) / 2 * dt + sqrt(V(t)) * dW_{X}(t),
    dV(t) = mean_reversion(t) * (theta(t) - V(t)) * dt
            + volvol(t) * sqrt(V(t)) * dW_{V}(t)
  ```
  
  where `W_{X}` and `W_{V}` are 1D Brownian motions with a correlation
  `rho(t)`. `mean_reversion`, `theta`, `volvol`, and `rho` are positive
  piecewise constant functions of time. Here `V(t)` represents the process
  variance at time `t` and `X` represents logarithm of the spot price at time
  `t`.
  
  `mean_reversion` corresponds to the mean reversion rate, `theta` is the long
  run price variance, and `volvol` is the volatility of the volatility.
  
  See [1] and [2] for details.
  
  #### Example
  
  ```python
  import tf_quant_finance as tff
  import numpy as np
  volvol = tff.math.piecewise.PiecewiseConstantFunc(
      jump_locations=[0.5], values=[1, 1.1], dtype=np.float64)
  process = tff.models.HestonModel(
      mean_reversion=0.5, theta=0.04, volvol=volvol, rho=0.1, dtype=np.float64)
  times = np.linspace(0.0, 1.0, 1000)
  num_samples = 10000  # number of trajectories
  sample_paths = process.sample_paths(
      times,
      time_step=0.01,
      num_samples=num_samples,
      initial_state=np.array([1.0, 0.04]),
      random_type=random.RandomType.SOBOL)
  ```
  
  #### References:
    [1]: Cristian Homescu. Implied volatility surface: construction
      methodologies and characteristics.
      arXiv: https://arxiv.org/pdf/1107.1834.pdf
    [2]: Leif Andersen. Efficient Simulation of the Heston Stochastic
      Volatility Models. 2006.
      Link:
      http://www.ressources-actuarielles.net/ext/isfa/1226.nsf/d512ad5b22d73cc1c1257052003f1aed/1826b88b152e65a7c12574b000347c74/$FILE/LeifAndersenHeston.pdf
class_docstr_tok: ["Heston","Model","with","piecewise","constant","parameters",".","Represents","the","Ito","process",":","``","`","None","dX","(","t",")","=","-V","(","t",")","\/","2","*","dt","+","sqrt","(","V","(","t",")",")","*","dW_","{","X","}","(","t",")",",","dV","(","t",")","=","mean_reversion","(","t",")","*","(","theta","(","t",")","-","V","(","t",")",")","*","dt","+","volvol","(","t",")","*","sqrt","(","V","(","t",")",")","*","dW_","{","V","}","(","t",")","``","`","where","`","W_","{","X","}","`","and","`","W_","{","V","}","`","are","1D","Brownian","motions","with","a","correlation","`","rho","(","t",")","`",".","`","mean_reversion","`",",","`","theta","`",",","`","volvol","`",",","and","`","rho","`","are","positive","piecewise","constant","functions","of","time",".","Here","`","V","(","t",")","`","represents","the","process","variance","at","time","`","t","`","and","`","X","`","represents","logarithm","of","the","spot","price","at","time","`","t","`",".","`","mean_reversion","`","corresponds","to","the","mean","reversion","rate",",","`","theta","`","is","the","long","run","price","variance",",","and","`","volvol","`","is","the","volatility","of","the","volatility",".","See","[","1","]","and","[","2","]","for","details",".","#","#","#","#","Example","``","`","python","import","tf_quant_finance","as","tff","import","numpy","as","np","volvol","=","tff.math.piecewise.PiecewiseConstantFunc","(","jump_locations=","[","0.5","]",",","values=","[","1",",","1.1","]",",","dtype=np.float64",")","process","=","tff.models.HestonModel","(","mean_reversion=0.5",",","theta=0.04",",","volvol=volvol",",","rho=0.1",",","dtype=np.float64",")","times","=","np.linspace","(","0.0",",","1.0",",","1000",")","num_samples","=","10000","#","number","of","trajectories","sample_paths","=","process.sample_paths","(","times",",","time_step=0.01",",","num_samples=num_samples",",","initial_state=np.array","(","[","1.0",",","0.04","]",")",",","random_type=random.RandomType.SOBOL",")","``","`","#","#","#","#","References",":","[","1","]",":","Cristian","Homescu",".","Implied","volatility","surface",":","construction","methodologies","and","characteristics",".","arXiv",":","https",":","\/\/arxiv.org\/pdf\/1107.1834.pdf","[","2","]",":","Leif","Andersen",".","Efficient","Simulation","of","the","Heston","Stochastic","Volatility","Models",".","2006",".","Link",":","http",":","\/\/www.ressources-actuarielles.net\/ext\/isfa\/1226.nsf\/d512ad5b22d73cc1c1257052003f1aed\/1826b88b152e65a7c12574b000347c74\/","$","FILE\/LeifAndersenHeston.pdf"]
docstr: Initializes the Heston Model.
  
  #### References:
    [1]: Leif Andersen. Efficient Simulation of the Heston Stochastic
      Volatility Models. 2006.
      Link:
      http://www.ressources-actuarielles.net/ext/isfa/1226.nsf/d512ad5b22d73cc1c1257052003f1aed/1826b88b152e65a7c12574b000347c74/$FILE/LeifAndersenHeston.pdf
  Args:
    mean_reversion: Scalar real `Tensor` or an instant of batch-free
      left-continuous `PiecewiseConstantFunc`. Should contain a positive
      value.
      Corresponds to the mean reversion rate.
    theta: Scalar real `Tensor` or an instant of batch-free left-continuous
      `PiecewiseConstantFunc`. Should contain positive a value of the same
      `dtype` as `mean_reversion`.
      Corresponds to the long run price variance.
    volvol: Scalar real `Tensor` or an instant of batch-free left-continuous
      `PiecewiseConstantFunc`. Should contain positive a value of the same
      `dtype` as `mean_reversion`.
      Corresponds to the volatility of the volatility.
    rho: Scalar real `Tensor` or an instant of batch-free left-continuous
      `PiecewiseConstantFunc`. Should contain a value in range (-1, 1) of the
      same `dtype` as `mean_reversion`.
      Corresponds to the correlation between dW_{X}` and `dW_{V}`.
    dtype: The default dtype to use when converting values to `Tensor`s.
      Default value: `None` which maps to `tf.float32`.
    name: Python string. The name to give to the ops created by this class.
      Default value: `None` which maps to the default name `heston_model`.
docstr_tok: ["Initializes","the","Heston","Model",".","#","#","#","#","References",":","[","1","]",":","Leif","Andersen",".","Efficient","Simulation","of","the","Heston","Stochastic","Volatility","Models",".","2006",".","Link",":","http",":","\/\/www.ressources-actuarielles.net\/ext\/isfa\/1226.nsf\/d512ad5b22d73cc1c1257052003f1aed\/1826b88b152e65a7c12574b000347c74\/","$","FILE\/LeifAndersenHeston.pdf","Args",":","mean_reversion",":","Scalar","real","`","Tensor","`","or","an","instant","of","batch-free","left-continuous","`","PiecewiseConstantFunc","`",".","Should","contain","a","positive","value",".","Corresponds","to","the","mean","reversion","rate",".","theta",":","Scalar","real","`","Tensor","`","or","an","instant","of","batch-free","left-continuous","`","PiecewiseConstantFunc","`",".","Should","contain","positive","a","value","of","the","same","`","dtype","`","as","`","mean_reversion","`",".","Corresponds","to","the","long","run","price","variance",".","volvol",":","Scalar","real","`","Tensor","`","or","an","instant","of","batch-free","left-continuous","`","PiecewiseConstantFunc","`",".","Should","contain","positive","a","value","of","the","same","`","dtype","`","as","`","mean_reversion","`",".","Corresponds","to","the","volatility","of","the","volatility",".","rho",":","Scalar","real","`","Tensor","`","or","an","instant","of","batch-free","left-continuous","`","PiecewiseConstantFunc","`",".","Should","contain","a","value","in","range","(","-1",",","1",")","of","the","same","`","dtype","`","as","`","mean_reversion","`",".","Corresponds","to","the","correlation","between","dW_","{","X","}","`","and","`","dW_","{","V","}","`",".","dtype",":","The","default","dtype","to","use","when","converting","values","to","`","Tensor","`","s",".","Default","value",":","`","None","`","which","maps","to","`","tf.float32","`",".","name",":","Python","string",".","The","name","to","give","to","the","ops","created","by","this","class",".","Default","value",":","`","None","`","which","maps","to","the","default","name","`","heston_model","`","."]
code: def __init__(
      self,
      mean_reversion: _CallableOrTensor,
      theta: _CallableOrTensor,
      volvol: _CallableOrTensor,
      rho: _CallableOrTensor,
      dtype: Optional[tf.DType] = None,
      name: Optional[str] = None,
  ):
      """Initializes the Heston Model.
  
      #### References:
        [1]: Leif Andersen. Efficient Simulation of the Heston Stochastic
          Volatility Models. 2006.
          Link:
          http://www.ressources-actuarielles.net/ext/isfa/1226.nsf/d512ad5b22d73cc1c1257052003f1aed/1826b88b152e65a7c12574b000347c74/$FILE/LeifAndersenHeston.pdf
      Args:
        mean_reversion: Scalar real `Tensor` or an instant of batch-free
          left-continuous `PiecewiseConstantFunc`. Should contain a positive
          value.
          Corresponds to the mean reversion rate.
        theta: Scalar real `Tensor` or an instant of batch-free left-continuous
          `PiecewiseConstantFunc`. Should contain positive a value of the same
          `dtype` as `mean_reversion`.
          Corresponds to the long run price variance.
        volvol: Scalar real `Tensor` or an instant of batch-free left-continuous
          `PiecewiseConstantFunc`. Should contain positive a value of the same
          `dtype` as `mean_reversion`.
          Corresponds to the volatility of the volatility.
        rho: Scalar real `Tensor` or an instant of batch-free left-continuous
          `PiecewiseConstantFunc`. Should contain a value in range (-1, 1) of the
          same `dtype` as `mean_reversion`.
          Corresponds to the correlation between dW_{X}` and `dW_{V}`.
        dtype: The default dtype to use when converting values to `Tensor`s.
          Default value: `None` which maps to `tf.float32`.
        name: Python string. The name to give to the ops created by this class.
          Default value: `None` which maps to the default name `heston_model`.
      """
      self._name = name or "heston_model"
      with tf.name_scope(self._name):
          self._dtype = dtype or tf.float32
          if isinstance(
              mean_reversion, piecewise.PiecewiseConstantFunc
          ):
              self._mean_reversion = mean_reversion
          else:
              self._mean_reversion = tf.convert_to_tensor(
                  mean_reversion,
                  dtype=self._dtype,
                  name="mean_reversion",
              )
          self._theta = (
              theta
              if isinstance(theta, piecewise.PiecewiseConstantFunc)
              else tf.convert_to_tensor(
                  theta, dtype=self._dtype, name="theta"
              )
          )
          self._volvol = (
              volvol
              if isinstance(volvol, piecewise.PiecewiseConstantFunc)
              else tf.convert_to_tensor(
                  volvol, dtype=self._dtype, name="volvol"
              )
          )
          self._rho = (
              rho
              if isinstance(rho, piecewise.PiecewiseConstantFunc)
              else tf.convert_to_tensor(
                  rho, dtype=self._dtype, name="rho"
              )
          )
  
      def _vol_fn(t, x):
          """Volatility function of the Heston Process."""
          # For correlated brownian motions W_{X} and W_{V} with correlation
          # `rho(t)`, one can write
          # W_{V}(t) = rho(t) * W_{X}(t) + sqrt(1 - rho(t)**2) * W_{Z}(t)
          # where W_{Z}(t) is an independent from W_{X} and W{V} Brownian motion
          # Volatility matrix for Heston model is then
          # [[sqrt(V(t)), 0],
          #  [volvol(t) * rho(t) * sqrt(V(t)), volvol(t) * sqrt(1-rho**2) * V(t)]]
          vol = tf.sqrt(tf.abs(x[..., 1]))
          zeros = tf.zeros_like(vol)
          # Get parameter values at time `t`
          rho, volvol = _get_parameters(
              [t], self._rho, self._volvol
          )  # pylint: disable=unbalanced-tuple-unpacking
          rho, volvol = rho[0], volvol[0]
          # First column of the volatility matrix
          vol_matrix_1 = tf.stack([vol, volvol * rho * vol], -1)
          # Second column of the volatility matrix
          vol_matrix_2 = tf.stack(
              [zeros, volvol * tf.sqrt(1 - rho**2) * vol], -1
          )
          vol_matrix = tf.stack([vol_matrix_1, vol_matrix_2], -1)
          return vol_matrix
  
      def _drift_fn(t, x):
          var = x[..., 1]
          # Get parameter values at time `t`
          (
              mean_reversion,
              theta,
          ) = _get_parameters(  # pylint: disable=unbalanced-tuple-unpacking
              [t], self._mean_reversion, self._theta
          )
          mean_reversion, theta = mean_reversion[0], theta[0]
          log_spot_drift = -var / 2
          var_drift = mean_reversion * (theta - var)
          drift = tf.stack([log_spot_drift, var_drift], -1)
          return drift
  
      super(HestonModel, self).__init__(
          2, _drift_fn, _vol_fn, self._dtype, name
      )
  
file_path: tf-quant-finance/tf_quant_finance/models/heston/heston_model.py
imports: from typing import Union, Callable, Optional
  import numpy
  import tensorflow.compat.v2
  from tf_quant_finance import types
  from tf_quant_finance import utils
  from tf_quant_finance.math import piecewise
  from tf_quant_finance.math import random_ops
  from tf_quant_finance.models import generic_ito_process
  from tf_quant_finance.models import utils
label_desc: Use image node_id 1 to create a new HestonModel object from inherited base classes: generic_ito_process with example: obj = HestonModel(mean_reversion, theta, volvol, rho, dtype, name)