class_docstr: Gaussian HJM model for term-structure modeling.
  
  Heath-Jarrow-Morton (HJM) model for the interest rate term-structre
  modelling specifies the dynamics of the instantaneus forward rate `f(t,T)`
  with maturity `T` at time `t` as follows:
  
  ```None
    df(t,T) = mu(t,T) dt + sum_i sigma_i(t,  T) * dW_i(t),
    1 <= i <= n,
  ```
  where `mu(t,T)` and `sigma_i(t,T)` denote the drift and volatility
  for the forward rate and `W_i` are Brownian motions with instantaneous
  correlation `Rho`. The model above represents an `n-factor` HJM model.
  The Gaussian HJM model assumes that the volatility `sigma_i(t,T)` is a
  deterministic function of time (t). Under the risk-neutral measure, the
  drift `mu(t,T)` is computed as
  
  ```
    mu(t,T) = sum_i sigma_i(t,T)  int_t^T sigma_(t,u) du
  ```
  Using the separability condition, the HJM model above can be formulated as
  the following Markovian model:
  
  ```None
    sigma(t,T) = sigma(t) * h(T)    (Separability condition)
  ```
  A common choice for the function h(t) is `h(t) = exp(-kt)`. Using the above
  parameterization of sigma(t,T), we obtain the following Markovian
  formulation of the HJM model [1]:
  
  ```None
    HJM Model
    dx_i(t) = (sum_j [y_ij(t)] - k_i * x_i(t)) dt + sigma_i(t) dW_i
    dy_ij(t) = (rho_ij * sigma_i(t)*sigma_j(t) - (k_i + k_j) * y_ij(t)) dt
    r(t) = sum_i x_i(t) + f(0, t)
  ```
  where `x` is an `n`-dimensional vector and `y` is an `nxn` dimensional
  matrix. For Gaussian HJM model, the quantity `y_ij(t)` can be computed
  analytically as follows:
  
  ```None
    y_ij(t) = rho_ij * exp(-k_i * t) * exp(-k_j * t) *
              int_0^t exp((k_i+k_j) * s) * sigma_i(s) * sigma_j(s) ds
  ```
  
  The Gaussian HJM class implements the model outlined above by simulating the
  state `x(t)` while analytically computing `y(t)`.
  
  The price at time `t` of a zero-coupon bond maturing at `T` is given by
  (Ref. [1]):
  
  ```None
  P(t,T) = P(0,T) / P(0,t) *
           exp(-x(t) * G(t,T) - 0.5 * y(t) * G(t,T)^2)
  ```
  
  The HJM model implementation supports constant mean-reversion rate `k` and
  `sigma(t)` can be an arbitrary function of `t`. We use Euler discretization
  to simulate the HJM model.
  
  #### Example. Simulate a 4-factor HJM process.
  
  ```python
  import numpy as np
  import tensorflow.compat.v2 as tf
  import tf_quant_finance as tff
  
  dtype = tf.float64
  def discount_fn(x):
    return 0.01 * tf.ones_like(x, dtype=dtype)
  
  process = tff.models.hjm.GaussianHJM(
      dim=4,
      mean_reversion=[0.03, 0.01, 0.02, 0.005],  # constant mean-reversion
      volatility=[0.01, 0.011, 0.015, 0.008],  # constant volatility
      initial_discount_rate_fn=discount_fn,
      dtype=dtype)
  times = np.array([0.1, 1.0, 2.0, 3.0])
  short_rate_paths, discount_paths, _, _ = process.sample_paths(
      times,
      num_samples=100000,
      time_step=0.1,
      random_type=tff.math.random.RandomType.STATELESS_ANTITHETIC,
      seed=[1, 2],
      skip=1000000)
  ```
  
  #### References:
    [1]: Leif B. G. Andersen and Vladimir V. Piterbarg. Interest Rate Modeling.
    Volume II: Term Structure Models.
class_docstr_tok: ["Gaussian","HJM","model","for","term-structure","modeling",".","Heath-Jarrow-Morton","(","HJM",")","model","for","the","interest","rate","term-structre","modelling","specifies","the","dynamics","of","the","instantaneus","forward","rate","`","f","(","t",",","T",")","`","with","maturity","`","T","`","at","time","`","t","`","as","follows",":","``","`","None","df","(","t",",","T",")","=","mu","(","t",",","T",")","dt","+","sum_i","sigma_i","(","t",",","T",")","*","dW_i","(","t",")",",","1","<","=","i","<","=","n",",","``","`","where","`","mu","(","t",",","T",")","`","and","`","sigma_i","(","t",",","T",")","`","denote","the","drift","and","volatility","for","the","forward","rate","and","`","W_i","`","are","Brownian","motions","with","instantaneous","correlation","`","Rho","`",".","The","model","above","represents","an","`","n-factor","`","HJM","model",".","The","Gaussian","HJM","model","assumes","that","the","volatility","`","sigma_i","(","t",",","T",")","`","is","a","deterministic","function","of","time","(","t",")",".","Under","the","risk-neutral","measure",",","the","drift","`","mu","(","t",",","T",")","`","is","computed","as","``","`","mu","(","t",",","T",")","=","sum_i","sigma_i","(","t",",","T",")","int_t^T","sigma_","(","t",",","u",")","du","``","`","Using","the","separability","condition",",","the","HJM","model","above","can","be","formulated","as","the","following","Markovian","model",":","``","`","None","sigma","(","t",",","T",")","=","sigma","(","t",")","*","h","(","T",")","(","Separability","condition",")","``","`","A","common","choice","for","the","function","h","(","t",")","is","`","h","(","t",")","=","exp","(","-kt",")","`",".","Using","the","above","parameterization","of","sigma","(","t",",","T",")",",","we","obtain","the","following","Markovian","formulation","of","the","HJM","model","[","1","]",":","``","`","None","HJM","Model","dx_i","(","t",")","=","(","sum_j","[","y_ij","(","t",")","]","-","k_i","*","x_i","(","t",")",")","dt","+","sigma_i","(","t",")","dW_i","dy_ij","(","t",")","=","(","rho_ij","*","sigma_i","(","t",")","*","sigma_j","(","t",")","-","(","k_i","+","k_j",")","*","y_ij","(","t",")",")","dt","r","(","t",")","=","sum_i","x_i","(","t",")","+","f","(","0",",","t",")","``","`","where","`","x","`","is","an","`","n","`","-dimensional","vector","and","`","y","`","is","an","`","nxn","`","dimensional","matrix",".","For","Gaussian","HJM","model",",","the","quantity","`","y_ij","(","t",")","`","can","be","computed","analytically","as","follows",":","``","`","None","y_ij","(","t",")","=","rho_ij","*","exp","(","-k_i","*","t",")","*","exp","(","-k_j","*","t",")","*","int_0^t","exp","(","(","k_i+k_j",")","*","s",")","*","sigma_i","(","s",")","*","sigma_j","(","s",")","ds","``","`","The","Gaussian","HJM","class","implements","the","model","outlined","above","by","simulating","the","state","`","x","(","t",")","`","while","analytically","computing","`","y","(","t",")","`",".","The","price","at","time","`","t","`","of","a","zero-coupon","bond","maturing","at","`","T","`","is","given","by","(","Ref",".","[","1","]",")",":","``","`","None","P","(","t",",","T",")","=","P","(","0",",","T",")","\/","P","(","0",",","t",")","*","exp","(","-x","(","t",")","*","G","(","t",",","T",")","-","0.5","*","y","(","t",")","*","G","(","t",",","T",")","^2",")","``","`","The","HJM","model","implementation","supports","constant","mean-reversion","rate","`","k","`","and","`","sigma","(","t",")","`","can","be","an","arbitrary","function","of","`","t","`",".","We","use","Euler","discretization","to","simulate","the","HJM","model",".","#","#","#","#","Example",".","Simulate","a","4-factor","HJM","process",".","``","`","python","import","numpy","as","np","import","tensorflow.compat.v2","as","tf","import","tf_quant_finance","as","tff","dtype","=","tf.float64","def","discount_fn","(","x",")",":","return","0.01","*","tf.ones_like","(","x",",","dtype=dtype",")","process","=","tff.models.hjm.GaussianHJM","(","dim=4",",","mean_reversion=","[","0.03",",","0.01",",","0.02",",","0.005","]",",","#","constant","mean-reversion","volatility=","[","0.01",",","0.011",",","0.015",",","0.008","]",",","#","constant","volatility","initial_discount_rate_fn=discount_fn",",","dtype=dtype",")","times","=","np.array","(","[","0.1",",","1.0",",","2.0",",","3.0","]",")","short_rate_paths",",","discount_paths",",","_",",","_","=","process.sample_paths","(","times",",","num_samples=100000",",","time_step=0.1",",","random_type=tff.math.random.RandomType.STATELESS_ANTITHETIC",",","seed=","[","1",",","2","]",",","skip=1000000",")","``","`","#","#","#","#","References",":","[","1","]",":","Leif","B.","G.","Andersen","and","Vladimir","V.","Piterbarg",".","Interest","Rate","Modeling",".","Volume","II",":","Term","Structure","Models","."]
docstr: Returns a sample of short rate paths from the HJM process.
  
  Uses Euler sampling for simulating the short rate paths.
  
  Args:
    times: A real positive `Tensor` of shape `(num_times,)`. The times at
      which the path points are to be evaluated.
    num_samples: Positive scalar `int32` `Tensor`. The number of paths to
      draw.
    time_step: Scalar real `Tensor`. Maximal distance between time grid points
      in Euler scheme. Used only when Euler scheme is applied.
      Default value: `None`.
    num_time_steps: An optional Scalar integer `Tensor` - a total number of
      time steps performed by the algorithm. The maximal distance between
      points in grid is bounded by
      `times[-1] / (num_time_steps - times.shape[0])`.
      Either this or `time_step` should be supplied.
      Default value: `None`.
    random_type: Enum value of `RandomType`. The type of (quasi)-random
      number generator to use to generate the paths.
      Default value: `None` which maps to the standard pseudo-random numbers.
    seed: Seed for the random number generator. The seed is
      only relevant if `random_type` is one of
      `[STATELESS, PSEUDO, HALTON_RANDOMIZED, PSEUDO_ANTITHETIC,
        STATELESS_ANTITHETIC]`. For `PSEUDO`, `PSEUDO_ANTITHETIC` and
      `HALTON_RANDOMIZED` the seed should be an Python integer. For
      `STATELESS` and  `STATELESS_ANTITHETIC `must be supplied as an integer
      `Tensor` of shape `[2]`.
      Default value: `None` which means no seed is set.
    skip: `int32` 0-d `Tensor`. The number of initial points of the Sobol or
      Halton sequence to skip. Used only when `random_type` is 'SOBOL',
      'HALTON', or 'HALTON_RANDOMIZED', otherwise ignored.
      Default value: `0`.
    name: Python string. The name to give this op.
      Default value: `sample_paths`.
  
  Returns:
    A tuple containing four elements.
  
    * The first element is a `Tensor` of
    shape `[num_samples, num_times]` containing the simulated short rate
    paths.
    * The second element is a `Tensor` of shape
    `[num_samples, num_times]` containing the simulated discount factor
    paths.
    * The third element is a `Tensor` of shape
    `[num_samples, num_times, dim]` conating the simulated values of the
    state variable `x`
    * The fourth element is a `Tensor` of shape
    `[num_samples, num_times, dim^2]` conating the simulated values of the
    state variable `y`.
  
  Raises:
    ValueError:
      (a) If `times` has rank different from `1`.
      (b) If Euler scheme is used by times is not supplied.
docstr_tok: ["Returns","a","sample","of","short","rate","paths","from","the","HJM","process",".","Uses","Euler","sampling","for","simulating","the","short","rate","paths",".","Args",":","times",":","A","real","positive","`","Tensor","`","of","shape","`","(","num_times",",",")","`",".","The","times","at","which","the","path","points","are","to","be","evaluated",".","num_samples",":","Positive","scalar","`","int32","`","`","Tensor","`",".","The","number","of","paths","to","draw",".","time_step",":","Scalar","real","`","Tensor","`",".","Maximal","distance","between","time","grid","points","in","Euler","scheme",".","Used","only","when","Euler","scheme","is","applied",".","Default","value",":","`","None","`",".","num_time_steps",":","An","optional","Scalar","integer","`","Tensor","`","-","a","total","number","of","time","steps","performed","by","the","algorithm",".","The","maximal","distance","between","points","in","grid","is","bounded","by","`","times","[","-1","]","\/","(","num_time_steps","-","times.shape","[","0","]",")","`",".","Either","this","or","`","time_step","`","should","be","supplied",".","Default","value",":","`","None","`",".","random_type",":","Enum","value","of","`","RandomType","`",".","The","type","of","(","quasi",")","-random","number","generator","to","use","to","generate","the","paths",".","Default","value",":","`","None","`","which","maps","to","the","standard","pseudo-random","numbers",".","seed",":","Seed","for","the","random","number","generator",".","The","seed","is","only","relevant","if","`","random_type","`","is","one","of","`","[","STATELESS",",","PSEUDO",",","HALTON_RANDOMIZED",",","PSEUDO_ANTITHETIC",",","STATELESS_ANTITHETIC","]","`",".","For","`","PSEUDO","`",",","`","PSEUDO_ANTITHETIC","`","and","`","HALTON_RANDOMIZED","`","the","seed","should","be","an","Python","integer",".","For","`","STATELESS","`","and","`","STATELESS_ANTITHETIC","`","must","be","supplied","as","an","integer","`","Tensor","`","of","shape","`","[","2","]","`",".","Default","value",":","`","None","`","which","means","no","seed","is","set",".","skip",":","`","int32","`","0-d","`","Tensor","`",".","The","number","of","initial","points","of","the","Sobol","or","Halton","sequence","to","skip",".","Used","only","when","`","random_type","`","is","'SOBOL","'",",","'HALTON","'",",","or","'HALTON_RANDOMIZED","'",",","otherwise","ignored",".","Default","value",":","`","0","`",".","name",":","Python","string",".","The","name","to","give","this","op",".","Default","value",":","`","sample_paths","`",".","Returns",":","A","tuple","containing","four","elements",".","*","The","first","element","is","a","`","Tensor","`","of","shape","`","[","num_samples",",","num_times","]","`","containing","the","simulated","short","rate","paths",".","*","The","second","element","is","a","`","Tensor","`","of","shape","`","[","num_samples",",","num_times","]","`","containing","the","simulated","discount","factor","paths",".","*","The","third","element","is","a","`","Tensor","`","of","shape","`","[","num_samples",",","num_times",",","dim","]","`","conating","the","simulated","values","of","the","state","variable","`","x","`","*","The","fourth","element","is","a","`","Tensor","`","of","shape","`","[","num_samples",",","num_times",",","dim^2","]","`","conating","the","simulated","values","of","the","state","variable","`","y","`",".","Raises",":","ValueError",":","(","a",")","If","`","times","`","has","rank","different","from","`","1","`",".","(","b",")","If","Euler","scheme","is","used","by","times","is","not","supplied","."]
code: def sample_paths(
      self,
      times: types.RealTensor,
      num_samples: types.IntTensor,
      time_step: types.RealTensor = None,
      num_time_steps: types.IntTensor = None,
      random_type: random.RandomType = None,
      seed: types.IntTensor = None,
      skip: types.IntTensor = 0,
      name: str = None,
  ) -> types.RealTensor:
      """Returns a sample of short rate paths from the HJM process.
  
      Uses Euler sampling for simulating the short rate paths.
  
      Args:
        times: A real positive `Tensor` of shape `(num_times,)`. The times at
          which the path points are to be evaluated.
        num_samples: Positive scalar `int32` `Tensor`. The number of paths to
          draw.
        time_step: Scalar real `Tensor`. Maximal distance between time grid points
          in Euler scheme. Used only when Euler scheme is applied.
          Default value: `None`.
        num_time_steps: An optional Scalar integer `Tensor` - a total number of
          time steps performed by the algorithm. The maximal distance between
          points in grid is bounded by
          `times[-1] / (num_time_steps - times.shape[0])`.
          Either this or `time_step` should be supplied.
          Default value: `None`.
        random_type: Enum value of `RandomType`. The type of (quasi)-random
          number generator to use to generate the paths.
          Default value: `None` which maps to the standard pseudo-random numbers.
        seed: Seed for the random number generator. The seed is
          only relevant if `random_type` is one of
          `[STATELESS, PSEUDO, HALTON_RANDOMIZED, PSEUDO_ANTITHETIC,
            STATELESS_ANTITHETIC]`. For `PSEUDO`, `PSEUDO_ANTITHETIC` and
          `HALTON_RANDOMIZED` the seed should be an Python integer. For
          `STATELESS` and  `STATELESS_ANTITHETIC `must be supplied as an integer
          `Tensor` of shape `[2]`.
          Default value: `None` which means no seed is set.
        skip: `int32` 0-d `Tensor`. The number of initial points of the Sobol or
          Halton sequence to skip. Used only when `random_type` is 'SOBOL',
          'HALTON', or 'HALTON_RANDOMIZED', otherwise ignored.
          Default value: `0`.
        name: Python string. The name to give this op.
          Default value: `sample_paths`.
  
      Returns:
        A tuple containing four elements.
  
        * The first element is a `Tensor` of
        shape `[num_samples, num_times]` containing the simulated short rate
        paths.
        * The second element is a `Tensor` of shape
        `[num_samples, num_times]` containing the simulated discount factor
        paths.
        * The third element is a `Tensor` of shape
        `[num_samples, num_times, dim]` conating the simulated values of the
        state variable `x`
        * The fourth element is a `Tensor` of shape
        `[num_samples, num_times, dim^2]` conating the simulated values of the
        state variable `y`.
  
      Raises:
        ValueError:
          (a) If `times` has rank different from `1`.
          (b) If Euler scheme is used by times is not supplied.
      """
      name = name or self._name + "_sample_path"
      with tf.name_scope(name):
          times = tf.convert_to_tensor(times, self._dtype)
          if times.shape.rank != 1:
              raise ValueError(
                  "`times` should be a rank 1 Tensor. "
                  "Rank is {} instead.".format(times.shape.rank)
              )
          return self._sample_paths(
              times,
              time_step,
              num_time_steps,
              num_samples,
              random_type,
              skip,
              seed,
          )
  
file_path: tf-quant-finance/tf_quant_finance/models/hjm/gaussian_hjm.py
imports: from typing import Callable, Union
  import tensorflow.compat.v2
  from tf_quant_finance import types
  from tf_quant_finance.math import gradient
  from tf_quant_finance.math import piecewise
  from tf_quant_finance.math import random
  from tf_quant_finance.models import euler_sampling
  from tf_quant_finance.models import utils
  from tf_quant_finance.models.hjm import quasi_gaussian_hjm
label_desc: Use image node_id 2 for calling the GaussianHJM obj's underlying member method code with example usage: obj.sample_paths(times, num_samples, time_step, num_time_steps, random_type, seed, skip, name) and returns: self