class_docstr: Generic Ito process defined from a drift and volatility function.
class_docstr_tok: ["Generic","Ito","process","defined","from","a","drift","and","volatility","function","."]
docstr: Returns a sample of paths from the process using Euler sampling.
  
  The default implementation uses the Euler scheme. However, for particular
  types of Ito processes more efficient schemes can be used.
  
  Args:
    times: Rank 1 `Tensor` of increasing positive real values. The times at
      which the path points are to be evaluated.
    num_samples: Positive scalar `int`. The number of paths to draw.
      Default value: 1.
    initial_state: `Tensor` of shape broadcastable
      `batch_shape + [num_samples, dim]`. The initial state of the process.
      `batch_shape` represents the shape of the independent batches of the
      stochastic process as in the `drift_fn` and `volatility_fn` of the
      underlying class. Note that the `batch_shape` is inferred from
      the `initial_state` and hence when sampling is requested for a batch of
      stochastic processes, the shape of `initial_state` should be as least
      `batch_shape + [1, 1]`.
      Default value: None which maps to a zero initial state.
    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.
    swap_memory: A Python bool. Whether GPU-CPU memory swap is enabled for
      this op. See an equivalent flag in `tf.while_loop` documentation for
      more details. Useful when computing a gradient of the op since
      `tf.while_loop` is used to propagate stochastic process in time.
      Default value: True.
    name: Python string. The name to give this op.
      Default value: `None` which maps to `sample_paths` is used.
    time_step: An optional scalar real `Tensor` - maximal distance between
      points in the time grid.
      Either this or `num_time_steps` should be supplied.
      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`.
    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`.
    precompute_normal_draws: Python bool. Indicates whether the noise
      increments in Euler scheme are precomputed upfront (see
      `models.euler_sampling.sample`). For `HALTON` and `SOBOL` random types
      the increments are always precomputed. While the resulting graph
      consumes more memory, the performance gains might be significant.
      Default value: `True`.
    times_grid: An optional rank 1 `Tensor` representing time discretization
      grid. If `times` are not on the grid, then the nearest points from the
      grid are used.
      Default value: `None`, which means that times grid is computed using
      `time_step` and `num_time_steps`.
    normal_draws: A `Tensor` of shape
      `batch_shape + [num_samples, num_time_points, dim]`
      and the same `dtype` as `times`. Represents random normal draws to
      compute increments `N(0, t_{n+1}) - N(0, t_n)`. `batch_shape` is the
      shape of the independent batches of the stochastic process. When
      supplied, `num_sample`, `time_step` and `num_time_steps` arguments are
      ignored and the first dimensions of `normal_draws` are used instead.
    watch_params: An optional list of zero-dimensional `Tensor`s of the same
      `dtype` as `initial_state`. If provided, specifies `Tensor`s with
      respect to which the differentiation of the sampling function will
      happen. A more efficient algorithm is used when `watch_params` are
      specified. Note the the function becomes differentiable onlhy wrt to
      these `Tensor`s and the `initial_state`. The gradient wrt any other
      `Tensor` is set to be zero.
    validate_args: Python `bool`. When `True` and `normal_draws` are supplied,
      checks that `tf.shape(normal_draws)[1]` is equal to `num_time_steps`
      that is either supplied as an argument or computed from `time_step`.
      When `False` invalid dimension may silently render incorrect outputs.
      Default value: `False`.
  
  Returns:
   A real `Tensor` of shape `batch_shape + [num_samples, k, n]` where `k`
   is the size of the `times`, and `n` is the dimension of the process.
  
  Raises:
    ValueError:
      (a) When `times_grid` is not supplied, and neither `num_time_steps` nor
        `time_step` are supplied or if both are supplied.
      (b) If `normal_draws` is supplied and `dim` is mismatched.
    tf.errors.InvalidArgumentError: If `normal_draws` is supplied and
      `num_time_steps` is mismatched.
docstr_tok: ["Returns","a","sample","of","paths","from","the","process","using","Euler","sampling",".","The","default","implementation","uses","the","Euler","scheme",".","However",",","for","particular","types","of","Ito","processes","more","efficient","schemes","can","be","used",".","Args",":","times",":","Rank","1","`","Tensor","`","of","increasing","positive","real","values",".","The","times","at","which","the","path","points","are","to","be","evaluated",".","num_samples",":","Positive","scalar","`","int","`",".","The","number","of","paths","to","draw",".","Default","value",":","1.","initial_state",":","`","Tensor","`","of","shape","broadcastable","`","batch_shape","+","[","num_samples",",","dim","]","`",".","The","initial","state","of","the","process",".","`","batch_shape","`","represents","the","shape","of","the","independent","batches","of","the","stochastic","process","as","in","the","`","drift_fn","`","and","`","volatility_fn","`","of","the","underlying","class",".","Note","that","the","`","batch_shape","`","is","inferred","from","the","`","initial_state","`","and","hence","when","sampling","is","requested","for","a","batch","of","stochastic","processes",",","the","shape","of","`","initial_state","`","should","be","as","least","`","batch_shape","+","[","1",",","1","]","`",".","Default","value",":","None","which","maps","to","a","zero","initial","state",".","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",".","swap_memory",":","A","Python","bool",".","Whether","GPU-CPU","memory","swap","is","enabled","for","this","op",".","See","an","equivalent","flag","in","`","tf.while_loop","`","documentation","for","more","details",".","Useful","when","computing","a","gradient","of","the","op","since","`","tf.while_loop","`","is","used","to","propagate","stochastic","process","in","time",".","Default","value",":","True",".","name",":","Python","string",".","The","name","to","give","this","op",".","Default","value",":","`","None","`","which","maps","to","`","sample_paths","`","is","used",".","time_step",":","An","optional","scalar","real","`","Tensor","`","-","maximal","distance","between","points","in","the","time","grid",".","Either","this","or","`","num_time_steps","`","should","be","supplied",".","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","`",".","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","`",".","precompute_normal_draws",":","Python","bool",".","Indicates","whether","the","noise","increments","in","Euler","scheme","are","precomputed","upfront","(","see","`","models.euler_sampling.sample","`",")",".","For","`","HALTON","`","and","`","SOBOL","`","random","types","the","increments","are","always","precomputed",".","While","the","resulting","graph","consumes","more","memory",",","the","performance","gains","might","be","significant",".","Default","value",":","`","True","`",".","times_grid",":","An","optional","rank","1","`","Tensor","`","representing","time","discretization","grid",".","If","`","times","`","are","not","on","the","grid",",","then","the","nearest","points","from","the","grid","are","used",".","Default","value",":","`","None","`",",","which","means","that","times","grid","is","computed","using","`","time_step","`","and","`","num_time_steps","`",".","normal_draws",":","A","`","Tensor","`","of","shape","`","batch_shape","+","[","num_samples",",","num_time_points",",","dim","]","`","and","the","same","`","dtype","`","as","`","times","`",".","Represents","random","normal","draws","to","compute","increments","`","N","(","0",",","t_","{","n+1","}",")","-","N","(","0",",","t_n",")","`",".","`","batch_shape","`","is","the","shape","of","the","independent","batches","of","the","stochastic","process",".","When","supplied",",","`","num_sample","`",",","`","time_step","`","and","`","num_time_steps","`","arguments","are","ignored","and","the","first","dimensions","of","`","normal_draws","`","are","used","instead",".","watch_params",":","An","optional","list","of","zero-dimensional","`","Tensor","`","s","of","the","same","`","dtype","`","as","`","initial_state","`",".","If","provided",",","specifies","`","Tensor","`","s","with","respect","to","which","the","differentiation","of","the","sampling","function","will","happen",".","A","more","efficient","algorithm","is","used","when","`","watch_params","`","are","specified",".","Note","the","the","function","becomes","differentiable","onlhy","wrt","to","these","`","Tensor","`","s","and","the","`","initial_state","`",".","The","gradient","wrt","any","other","`","Tensor","`","is","set","to","be","zero",".","validate_args",":","Python","`","bool","`",".","When","`","True","`","and","`","normal_draws","`","are","supplied",",","checks","that","`","tf.shape","(","normal_draws",")","[","1","]","`","is","equal","to","`","num_time_steps","`","that","is","either","supplied","as","an","argument","or","computed","from","`","time_step","`",".","When","`","False","`","invalid","dimension","may","silently","render","incorrect","outputs",".","Default","value",":","`","False","`",".","Returns",":","A","real","`","Tensor","`","of","shape","`","batch_shape","+","[","num_samples",",","k",",","n","]","`","where","`","k","`","is","the","size","of","the","`","times","`",",","and","`","n","`","is","the","dimension","of","the","process",".","Raises",":","ValueError",":","(","a",")","When","`","times_grid","`","is","not","supplied",",","and","neither","`","num_time_steps","`","nor","`","time_step","`","are","supplied","or","if","both","are","supplied",".","(","b",")","If","`","normal_draws","`","is","supplied","and","`","dim","`","is","mismatched",".","tf.errors.InvalidArgumentError",":","If","`","normal_draws","`","is","supplied","and","`","num_time_steps","`","is","mismatched","."]
code: def sample_paths(
      self,
      times,
      num_samples=1,
      initial_state=None,
      random_type=None,
      seed=None,
      swap_memory=True,
      name=None,
      time_step=None,
      num_time_steps=None,
      skip=0,
      precompute_normal_draws=True,
      times_grid=None,
      normal_draws=None,
      watch_params=None,
      validate_args=False,
  ):
      """Returns a sample of paths from the process using Euler sampling.
  
      The default implementation uses the Euler scheme. However, for particular
      types of Ito processes more efficient schemes can be used.
  
      Args:
        times: Rank 1 `Tensor` of increasing positive real values. The times at
          which the path points are to be evaluated.
        num_samples: Positive scalar `int`. The number of paths to draw.
          Default value: 1.
        initial_state: `Tensor` of shape broadcastable
          `batch_shape + [num_samples, dim]`. The initial state of the process.
          `batch_shape` represents the shape of the independent batches of the
          stochastic process as in the `drift_fn` and `volatility_fn` of the
          underlying class. Note that the `batch_shape` is inferred from
          the `initial_state` and hence when sampling is requested for a batch of
          stochastic processes, the shape of `initial_state` should be as least
          `batch_shape + [1, 1]`.
          Default value: None which maps to a zero initial state.
        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.
        swap_memory: A Python bool. Whether GPU-CPU memory swap is enabled for
          this op. See an equivalent flag in `tf.while_loop` documentation for
          more details. Useful when computing a gradient of the op since
          `tf.while_loop` is used to propagate stochastic process in time.
          Default value: True.
        name: Python string. The name to give this op.
          Default value: `None` which maps to `sample_paths` is used.
        time_step: An optional scalar real `Tensor` - maximal distance between
          points in the time grid.
          Either this or `num_time_steps` should be supplied.
          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`.
        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`.
        precompute_normal_draws: Python bool. Indicates whether the noise
          increments in Euler scheme are precomputed upfront (see
          `models.euler_sampling.sample`). For `HALTON` and `SOBOL` random types
          the increments are always precomputed. While the resulting graph
          consumes more memory, the performance gains might be significant.
          Default value: `True`.
        times_grid: An optional rank 1 `Tensor` representing time discretization
          grid. If `times` are not on the grid, then the nearest points from the
          grid are used.
          Default value: `None`, which means that times grid is computed using
          `time_step` and `num_time_steps`.
        normal_draws: A `Tensor` of shape
          `batch_shape + [num_samples, num_time_points, dim]`
          and the same `dtype` as `times`. Represents random normal draws to
          compute increments `N(0, t_{n+1}) - N(0, t_n)`. `batch_shape` is the
          shape of the independent batches of the stochastic process. When
          supplied, `num_sample`, `time_step` and `num_time_steps` arguments are
          ignored and the first dimensions of `normal_draws` are used instead.
        watch_params: An optional list of zero-dimensional `Tensor`s of the same
          `dtype` as `initial_state`. If provided, specifies `Tensor`s with
          respect to which the differentiation of the sampling function will
          happen. A more efficient algorithm is used when `watch_params` are
          specified. Note the the function becomes differentiable onlhy wrt to
          these `Tensor`s and the `initial_state`. The gradient wrt any other
          `Tensor` is set to be zero.
        validate_args: Python `bool`. When `True` and `normal_draws` are supplied,
          checks that `tf.shape(normal_draws)[1]` is equal to `num_time_steps`
          that is either supplied as an argument or computed from `time_step`.
          When `False` invalid dimension may silently render incorrect outputs.
          Default value: `False`.
  
      Returns:
       A real `Tensor` of shape `batch_shape + [num_samples, k, n]` where `k`
       is the size of the `times`, and `n` is the dimension of the process.
  
      Raises:
        ValueError:
          (a) When `times_grid` is not supplied, and neither `num_time_steps` nor
            `time_step` are supplied or if both are supplied.
          (b) If `normal_draws` is supplied and `dim` is mismatched.
        tf.errors.InvalidArgumentError: If `normal_draws` is supplied and
          `num_time_steps` is mismatched.
      """
      name = name or (self._name + "_sample_path")
      with tf.name_scope(name):
          return euler_sampling.sample(
              dim=self._dim,
              drift_fn=self._drift_fn,
              volatility_fn=self._volatility_fn,
              times=times,
              num_samples=num_samples,
              initial_state=initial_state,
              random_type=random_type,
              time_step=time_step,
              num_time_steps=num_time_steps,
              seed=seed,
              swap_memory=swap_memory,
              skip=skip,
              precompute_normal_draws=precompute_normal_draws,
              times_grid=times_grid,
              normal_draws=normal_draws,
              watch_params=watch_params,
              dtype=self._dtype,
              name=name,
          )
  
file_path: tf-quant-finance/tf_quant_finance/models/generic_ito_process.py
imports: import tensorflow.compat.v2
  from tf_quant_finance.math.pde import fd_solvers
  from tf_quant_finance.models import euler_sampling
  from tf_quant_finance.models import ito_process
label_desc: Use image node_id 7 for calling the GenericItoProcess obj's underlying member method code with example usage: obj.sample_paths(times, num_samples, initial_state, random_type, seed, swap_memory, name, time_step, num_time_steps, skip, precompute_normal_draws, times_grid, normal_draws, watch_params, validate_args) and returns: euler_sampling