class_docstr: Local stochastic volatility model.
  
  Local stochastic volatility (LSV) models assume that the spot price of an
  asset follows the following stochastic differential equation under the risk
  neutral measure [1]:
  
  ```None
    dS(t) / S(t) =  (r - d) dt + sqrt(v(t)) * L(t, S(t)) * dW_s(t)
    dv(t) = a(v(t)) dt + b(v(t)) dW_v(t)
    E[dW_s(t)dW_v(t)] = rho dt
  ```
  where `r` and `d` denote the risk free interest rate and dividend yield
  respectively. `S(t)` is the spot price, `v(t)` denotes the stochastic variance
  and the function `L(t, S(t))`  is the leverage function which is calibrated
  using the volatility smile data. The functions `a(v(t))` and `b(v(t))` denote
  the drift and volitility of the stochastic process for the variance and `rho`
  denotes the instantabeous correlation between the spot and the variance
  process. LSV models thus combine the local volatility dynamics with
  stochastic volatility.
  
  Using the relationship between the local volatility and the expectation of
  future instantaneous variance, leverage function can be computed as follows
  [2]:
  
  ```
  sigma(T,K)^2 = L(T,K)^2 * E[v(T)|S(T)=K]
  ```
  where the local volatility function `sigma(T,K)` can be computed using the
  Dupire's formula.
  
  The `LocalStochasticVolatilityModel` class contains a generic implementation
  of the LSV model with the flexibility to specify an arbitrary variance
  process. The default variance process is a Heston type process with
  mean-reverting variance (as in Ref. [1]):
  
  ```
  dv(t) = k(m - v(t)) dt + alpha*sqrt(v(t)) dW_v(t)
  ```
  
  #### References:
    [1]: Iain J. Clark. Foreign exchange option pricing - A Practitioner's
    guide. Chapter 5. 2011.
    [2]: I. Gyongy. Mimicking the one-dimensional marginal distributions of
    processes having an ito differential. Probability Theory and Related
    Fields, 71, 1986.
docstr: Creates a `LocalStochasticVolatilityModel` from volatility surface.
  
  This function computes the leverage function for the LSV model by first
  computing the joint probablity density function `p(t, X(t), v(t))` where
  `X(t)` is the log of the spot price and `v(t)` is the variance at time `t`.
  The joint probablity density is computed using the Fokker-Planck equation of
  the LSV model (see 6.8.2 in Ref [1]):
  ```None
  dp/dt = 1/2 d^2 [v L(t,X)^2 p]/dX^2 + 1/2 d^2 [b(v)^2 p]/dv^2 +
          rho d^2 [sqrt(v)L(t,X)b(v) p]/dXdv -
          d[(r - d - 1/2 v L(t,X)^2)p]/dX -
          d[a(v) p]/dv
  ```
  
  where `a(v)` and `b(v)` are the drift and diffusion functions for the
  variance process. Defining
  
  ```None
  I_n(k,t) = int v^n p(t, k, v) dv
  ```
  
  we can calculate the leverage function as follows:
  ```None
  L(k, t) = sigma(exp(k), t) sqrt(I_0(k, t)/I_1(k, t)).
  ```
  
  Args:
    implied_volatility_surface: Either an instance of
      `processed_market_data.VolatilitySurface` or a Python object containing
      the implied volatility market data. If the input is a Python object,
      then the object must implement a function `volatility(strike,
      expiry_times)` which takes real `Tensor`s corresponding to option
      strikes and time to expiry and returns a real `Tensor` containing the
      corresponding market implied volatility.
    variance_process: An instance of `LSVVarianceModel` or
      `ItoProcess`specifying the dynamics of the variance process of
      the LSV model.
    initial_spot: A real scalar `Tensor` specifying the underlying spot price
      on the valuation date.
    initial_variance: A real scalar `Tensor` specifying the initial variance
      on the valuation date.
    rho: A real scalar `Tensor` specifying the correlation between spot price
      and the stochastic variance.
    risk_free_rate: A real scalar `Tensor` specifying the (continuosly
      compounded) risk free interest rate. If the underlying is an FX rate,
      then use this input to specify the domestic interest rate.
      Default value: `None` in which case the input is set to zero.
    dividend_yield: A real scalar `Tensor` specifying the (continuosly
      compounded) divident yield. If the underlying is an FX rate, then use
      this input to specify the foreign interest rate.
      Default value: `None` in which case the input is set to zero.
    time_step: An optional real scalar `Tensor` specifying the time step
      during the numerical solution of the Fokker-Planck PDE.
      Default value: None, in which case `time_step` corresponding to 100 time
        steps is used.
    num_grid_points: A scalar integer `Tensor` specifying the number of
      discretization points for each spatial dimension.
      Default value: None, in which case number of grid points is set to 100.
    grid_minimums: An optional `Tensor` of size 2 containing the minimum grid
      points for PDE spatial discretization. `grid_minimums[0]` correspond
      to the minimum spot price in the spatial grid and `grid_minimums[1]`
      correspond to the minimum variance value.
    grid_maximums: An optional `Tensor` of size 2 containing the maximum grid
      points for PDE spatial discretization. `grid_maximums[0]` correspond
      to the maximum spot price in the spatial grid and `grid_maximums[1]`
      correspond to the maximum variance value.
    dtype: The default dtype to use when converting values to `Tensor`s.
      Default value: `None` which means that default dtypes inferred by
        TensorFlow are used.
  
  Returns:
    An instance of `LocalStochasticVolatilityModel` constructed using the
    input data.
docstr_tok: ["Creates","a","`","LocalStochasticVolatilityModel","`","from","volatility","surface",".","This","function","computes","the","leverage","function","for","the","LSV","model","by","first","computing","the","joint","probablity","density","function","`","p","(","t",",","X","(","t",")",",","v","(","t",")",")","`","where","`","X","(","t",")","`","is","the","log","of","the","spot","price","and","`","v","(","t",")","`","is","the","variance","at","time","`","t","`",".","The","joint","probablity","density","is","computed","using","the","Fokker-Planck","equation","of","the","LSV","model","(","see","6.8.2","in","Ref","[","1","]",")",":","``","`","None","dp\/dt","=","1\/2","d^2","[","v","L","(","t",",","X",")","^2","p","]","\/dX^2","+","1\/2","d^2","[","b","(","v",")","^2","p","]","\/dv^2","+","rho","d^2","[","sqrt","(","v",")","L","(","t",",","X",")","b","(","v",")","p","]","\/dXdv","-","d","[","(","r","-","d","-","1\/2","v","L","(","t",",","X",")","^2",")","p","]","\/dX","-","d","[","a","(","v",")","p","]","\/dv","``","`","where","`","a","(","v",")","`","and","`","b","(","v",")","`","are","the","drift","and","diffusion","functions","for","the","variance","process",".","Defining","``","`","None","I_n","(","k",",","t",")","=","int","v^n","p","(","t",",","k",",","v",")","dv","``","`","we","can","calculate","the","leverage","function","as","follows",":","``","`","None","L","(","k",",","t",")","=","sigma","(","exp","(","k",")",",","t",")","sqrt","(","I_0","(","k",",","t",")","\/I_1","(","k",",","t",")",")",".","``","`","Args",":","implied_volatility_surface",":","Either","an","instance","of","`","processed_market_data.VolatilitySurface","`","or","a","Python","object","containing","the","implied","volatility","market","data",".","If","the","input","is","a","Python","object",",","then","the","object","must","implement","a","function","`","volatility","(","strike",",","expiry_times",")","`","which","takes","real","`","Tensor","`","s","corresponding","to","option","strikes","and","time","to","expiry","and","returns","a","real","`","Tensor","`","containing","the","corresponding","market","implied","volatility",".","variance_process",":","An","instance","of","`","LSVVarianceModel","`","or","`","ItoProcess","`","specifying","the","dynamics","of","the","variance","process","of","the","LSV","model",".","initial_spot",":","A","real","scalar","`","Tensor","`","specifying","the","underlying","spot","price","on","the","valuation","date",".","initial_variance",":","A","real","scalar","`","Tensor","`","specifying","the","initial","variance","on","the","valuation","date",".","rho",":","A","real","scalar","`","Tensor","`","specifying","the","correlation","between","spot","price","and","the","stochastic","variance",".","risk_free_rate",":","A","real","scalar","`","Tensor","`","specifying","the","(","continuosly","compounded",")","risk","free","interest","rate",".","If","the","underlying","is","an","FX","rate",",","then","use","this","input","to","specify","the","domestic","interest","rate",".","Default","value",":","`","None","`","in","which","case","the","input","is","set","to","zero",".","dividend_yield",":","A","real","scalar","`","Tensor","`","specifying","the","(","continuosly","compounded",")","divident","yield",".","If","the","underlying","is","an","FX","rate",",","then","use","this","input","to","specify","the","foreign","interest","rate",".","Default","value",":","`","None","`","in","which","case","the","input","is","set","to","zero",".","time_step",":","An","optional","real","scalar","`","Tensor","`","specifying","the","time","step","during","the","numerical","solution","of","the","Fokker-Planck","PDE",".","Default","value",":","None",",","in","which","case","`","time_step","`","corresponding","to","100","time","steps","is","used",".","num_grid_points",":","A","scalar","integer","`","Tensor","`","specifying","the","number","of","discretization","points","for","each","spatial","dimension",".","Default","value",":","None",",","in","which","case","number","of","grid","points","is","set","to","100.","grid_minimums",":","An","optional","`","Tensor","`","of","size","2","containing","the","minimum","grid","points","for","PDE","spatial","discretization",".","`","grid_minimums","[","0","]","`","correspond","to","the","minimum","spot","price","in","the","spatial","grid","and","`","grid_minimums","[","1","]","`","correspond","to","the","minimum","variance","value",".","grid_maximums",":","An","optional","`","Tensor","`","of","size","2","containing","the","maximum","grid","points","for","PDE","spatial","discretization",".","`","grid_maximums","[","0","]","`","correspond","to","the","maximum","spot","price","in","the","spatial","grid","and","`","grid_maximums","[","1","]","`","correspond","to","the","maximum","variance","value",".","dtype",":","The","default","dtype","to","use","when","converting","values","to","`","Tensor","`","s",".","Default","value",":","`","None","`","which","means","that","default","dtypes","inferred","by","TensorFlow","are","used",".","Returns",":","An","instance","of","`","LocalStochasticVolatilityModel","`","constructed","using","the","input","data","."]
code: def from_volatility_surface(
      cls,
      implied_volatility_surface,
      variance_process,
      initial_spot,
      initial_variance,
      rho=None,
      risk_free_rate=None,
      dividend_yield=None,
      time_step=None,
      num_grid_points=None,
      grid_minimums=None,
      grid_maximums=None,
      dtype=None,
  ):
      """Creates a `LocalStochasticVolatilityModel` from volatility surface.
  
      This function computes the leverage function for the LSV model by first
      computing the joint probablity density function `p(t, X(t), v(t))` where
      `X(t)` is the log of the spot price and `v(t)` is the variance at time `t`.
      The joint probablity density is computed using the Fokker-Planck equation of
      the LSV model (see 6.8.2 in Ref [1]):
      ```None
      dp/dt = 1/2 d^2 [v L(t,X)^2 p]/dX^2 + 1/2 d^2 [b(v)^2 p]/dv^2 +
              rho d^2 [sqrt(v)L(t,X)b(v) p]/dXdv -
              d[(r - d - 1/2 v L(t,X)^2)p]/dX -
              d[a(v) p]/dv
      ```
  
      where `a(v)` and `b(v)` are the drift and diffusion functions for the
      variance process. Defining
  
      ```None
      I_n(k,t) = int v^n p(t, k, v) dv
      ```
  
      we can calculate the leverage function as follows:
      ```None
      L(k, t) = sigma(exp(k), t) sqrt(I_0(k, t)/I_1(k, t)).
      ```
  
      Args:
        implied_volatility_surface: Either an instance of
          `processed_market_data.VolatilitySurface` or a Python object containing
          the implied volatility market data. If the input is a Python object,
          then the object must implement a function `volatility(strike,
          expiry_times)` which takes real `Tensor`s corresponding to option
          strikes and time to expiry and returns a real `Tensor` containing the
          corresponding market implied volatility.
        variance_process: An instance of `LSVVarianceModel` or
          `ItoProcess`specifying the dynamics of the variance process of
          the LSV model.
        initial_spot: A real scalar `Tensor` specifying the underlying spot price
          on the valuation date.
        initial_variance: A real scalar `Tensor` specifying the initial variance
          on the valuation date.
        rho: A real scalar `Tensor` specifying the correlation between spot price
          and the stochastic variance.
        risk_free_rate: A real scalar `Tensor` specifying the (continuosly
          compounded) risk free interest rate. If the underlying is an FX rate,
          then use this input to specify the domestic interest rate.
          Default value: `None` in which case the input is set to zero.
        dividend_yield: A real scalar `Tensor` specifying the (continuosly
          compounded) divident yield. If the underlying is an FX rate, then use
          this input to specify the foreign interest rate.
          Default value: `None` in which case the input is set to zero.
        time_step: An optional real scalar `Tensor` specifying the time step
          during the numerical solution of the Fokker-Planck PDE.
          Default value: None, in which case `time_step` corresponding to 100 time
            steps is used.
        num_grid_points: A scalar integer `Tensor` specifying the number of
          discretization points for each spatial dimension.
          Default value: None, in which case number of grid points is set to 100.
        grid_minimums: An optional `Tensor` of size 2 containing the minimum grid
          points for PDE spatial discretization. `grid_minimums[0]` correspond
          to the minimum spot price in the spatial grid and `grid_minimums[1]`
          correspond to the minimum variance value.
        grid_maximums: An optional `Tensor` of size 2 containing the maximum grid
          points for PDE spatial discretization. `grid_maximums[0]` correspond
          to the maximum spot price in the spatial grid and `grid_maximums[1]`
          correspond to the maximum variance value.
        dtype: The default dtype to use when converting values to `Tensor`s.
          Default value: `None` which means that default dtypes inferred by
            TensorFlow are used.
  
      Returns:
        An instance of `LocalStochasticVolatilityModel` constructed using the
        input data.
      """
  
      if risk_free_rate is None:
          discount_factor_fn = lambda t: tf.ones_like(t, dtype=dtype)
      else:
          r = tf.convert_to_tensor(risk_free_rate, dtype=dtype)
          discount_factor_fn = lambda t: tf.math.exp(-r * t)
      lv_model = lvm.LocalVolatilityModel.from_volatility_surface(
          dim=1,
          spot=initial_spot,
          implied_volatility_surface=implied_volatility_surface,
          discount_factor_fn=discount_factor_fn,
          dividend_yield=dividend_yield,
          dtype=dtype,
      )
  
      dtype = dtype or lv_model.dtype()
      day_count_fn = utils.get_daycount_fn(
          implied_volatility_surface.daycount_convention, dtype=dtype
      )
      max_time = tf.math.reduce_max(
          day_count_fn(
              start_date=implied_volatility_surface.settlement_date(),
              end_date=implied_volatility_surface.node_expiries(),
          )
      )
      if time_step is None:
          time_step = max_time / 100.0
  
      rho = rho or 0.0
      num_grid_points = num_grid_points or 100
  
      leverage_fn = _leverage_function_using_pde(
          risk_free_rate=risk_free_rate,
          dividend_yield=dividend_yield,
          lv_model=lv_model,
          variance_model=variance_process,
          rho=[rho],
          initial_spot=initial_spot,
          initial_variance=initial_variance,
          time_step=time_step,
          max_time=max_time,
          num_grid_points=num_grid_points,
          grid_minimums=grid_minimums,
          grid_maximums=grid_maximums,
          dtype=dtype,
      )
      return LocalStochasticVolatilityModel(
          leverage_fn,
          variance_process,
          risk_free_rate=risk_free_rate,
          dividend_yield=dividend_yield,
          rho=rho,
          dtype=dtype,
      )
  
imports: import functools
  import numpy
  import tensorflow.compat.v2
  from tf_quant_finance import datetime
  from tf_quant_finance import math
  from tf_quant_finance import utils
  from tf_quant_finance.experimental import local_volatility
  from tf_quant_finance.experimental.pricing_platform.framework.market_data import utils
  from tf_quant_finance.math import pde
  from tf_quant_finance.math.interpolation import linear
  from tf_quant_finance.models import generic_ito_process
label_desc: Use image node_id 3 for calling the LocalStochasticVolatilityModel obj's underlying member method code with example usage: obj.from_volatility_surface(cls, implied_volatility_surface, variance_process, initial_spot, initial_variance, rho, risk_free_rate, dividend_yield, time_step, num_grid_points, grid_minimums, grid_maximums, dtype) and returns: LocalStochasticVolatilityModel