class_docstr: The multi dimensional Brownian Motion.
class_docstr_tok: ["The","multi","dimensional","Brownian","Motion","."]
docstr: Initializes the Brownian motion class.
  
  Represents the Ito process:
  
  ```None
    dX_i = a_i(t) dt + Sum(S_{ij}(t) dW_j for j in [1 ... n]), 1 <= i <= n
  
  ```
  
  `a_i(t)` is the drift rate of this process and the `S_{ij}(t)` is the
  volatility matrix. Associated to these parameters are the integrated
  drift and covariance functions. These are defined as:
  
  ```None
    total_drift_{i}(t1, t2) = Integrate(a_{i}(t), t1 <= t <= t2)
    total_covariance_{ij}(t1, t2) = Integrate(inst_covariance_{ij}(t),
                                                   t1 <= t <= t2)
    inst_covariance_{ij}(t) = (S.S^T)_{ij}(t)
  ```
  
  Sampling from the Brownian motion process with time dependent parameters
  can be done efficiently if the total drift and total covariance functions
  are supplied. If the parameters are constant, the total parameters can be
  automatically inferred and it is not worth supplying then explicitly.
  
  Currently, it is not possible to infer the total drift and covariance from
  the instantaneous values if the latter are functions of time. In this case,
  we use a generic sampling method (Euler-Maruyama) which may be
  inefficient. It is advisable to supply the total covariance and total drift
  in the time dependent case where possible.
  
  #### Example
  The following is an example of a 1 dimensional brownian motion using default
  arguments of zero drift and unit volatility.
  
  ```python
  process = bm.BrownianMotion()
  times = np.array([0.2, 0.33, 0.7, 0.9, 1.88])
  num_samples = 10000
  with tf.Session() as sess:
    paths = sess.run(process.sample_paths(
        times,
        num_samples=num_samples,
        initial_state=np.array(0.1),
        seed=1234))
  
  # Compute the means at the specified times.
  means = np.mean(paths, axis=0)
  print (means)  # Mean values will be near 0.1 for each time
  
  # Compute the covariances at the given times
  covars = np.cov(paths.reshape([num_samples, 5]), rowvar=False)
  
  # covars is a 5 x 5 covariance matrix.
  # Expected result is that Covar(X(t), X(t')) = min(t, t')
  expected = np.minimum(times.reshape([-1, 1]), times.reshape([1, -1]))
  print ("Computed Covars: {}, True Covars: {}".format(covars, expected))
  ```
  
  Args:
    dim: Python int greater than or equal to 1. The dimension of the Brownian
      motion.
      Default value: 1 (i.e. a one dimensional brownian process).
    drift: The drift of the process. The type and shape of the value must be
      one of the following (in increasing order of generality) (a) A real
      scalar `Tensor`. This corresponds to a time and component independent
      drift. Every component of the Brownian motion has the same drift rate
      equal to this value. (b) A real `Tensor` of shape `[dim]`. This
      corresponds to a time independent drift with the `i`th component as the
      drift rate of the `i`th component of the Brownian motion. (c) A Python
      callable accepting a single positive `Tensor` of general shape (referred
      to as `times_shape`) and returning a `Tensor` of shape `times_shape +
      [dim]`. The input argument is the times at which the drift needs to be
      evaluated. This case corresponds to a general time and direction
      dependent drift rate.
      Default value: None which maps to zero drift.
    volatility: The volatility of the process. The type and shape of the
      supplied value must be one of the following (in increasing order of
      generality) (a) A positive real scalar `Tensor`. This corresponds to a
      time independent, diagonal volatility matrix. The `(i, j)` component of
      the full volatility matrix is equal to zero if `i != j` and equal to the
      supplied value otherwise. (b) A positive real `Tensor` of shape `[dim]`.
      This corresponds to a time independent volatility matrix with zero
      correlation. The `(i, j)` component of the full volatility matrix is
      equal to zero `i != j` and equal to the `i`th component of the supplied
      value otherwise. (c) A positive definite real `Tensor` of shape `[dim,
      dim]`. The full time independent volatility matrix. (d) A Python
      callable accepting a single positive `Tensor` of general shape (referred
      to as `times_shape`) and returning a `Tensor` of shape `times_shape +
      [dim, dim]`. The input argument are the times at which the volatility
      needs to be evaluated. This case corresponds to a general time and axis
      dependent volatility matrix.
      Default value: None which maps to a volatility matrix equal to identity.
    total_drift_fn: Optional Python callable to compute the integrated drift
      rate between two times. The callable should accept two real `Tensor`
      arguments. The first argument contains the start times and the second,
      the end times of the time intervals for which the total drift is to be
      computed. Both the `Tensor` arguments are of the same dtype and shape.
      The return value of the callable should be a real `Tensor` of the same
      dtype as the input arguments and of shape `times_shape + [dim]` where
      `times_shape` is the shape of the times `Tensor`. Note that it is an
      error to supply this parameter if the `drift` is not supplied.
      Default value: None.
    total_covariance_fn: A Python callable returning the integrated covariance
      rate between two times. The callable should accept two real `Tensor`
      arguments. The first argument is the start times and the second is the
      end times of the time intervals for which the total covariance is
      needed. Both the `Tensor` arguments are of the same dtype and shape. The
      return value of the callable is a real `Tensor` of the same dtype as the
      input arguments and of shape `times_shape + [dim, dim]` where
      `times_shape` is the shape of the times `Tensor`. Note that it is an
      error to supply this argument if the `volatility` is not supplied.
      Default value: None.
    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.
    name: str. The name scope under which ops created by the methods of this
      class are nested.
      Default value: None which maps to the default name `brownian_motion`.
  
  Raises:
    ValueError if the dimension is less than 1 or if total drift is supplied
      but drift is not supplied or if the total covariance is supplied but
      but volatility is not supplied.
docstr_tok: ["Initializes","the","Brownian","motion","class",".","Represents","the","Ito","process",":","``","`","None","dX_i","=","a_i","(","t",")","dt","+","Sum","(","S_","{","ij","}","(","t",")","dW_j","for","j","in","[","1","...","n","]",")",",","1","<","=","i","<","=","n","``","`","`","a_i","(","t",")","`","is","the","drift","rate","of","this","process","and","the","`","S_","{","ij","}","(","t",")","`","is","the","volatility","matrix",".","Associated","to","these","parameters","are","the","integrated","drift","and","covariance","functions",".","These","are","defined","as",":","``","`","None","total_drift_","{","i","}","(","t1",",","t2",")","=","Integrate","(","a_","{","i","}","(","t",")",",","t1","<","=","t","<","=","t2",")","total_covariance_","{","ij","}","(","t1",",","t2",")","=","Integrate","(","inst_covariance_","{","ij","}","(","t",")",",","t1","<","=","t","<","=","t2",")","inst_covariance_","{","ij","}","(","t",")","=","(","S.S^T",")","_","{","ij","}","(","t",")","``","`","Sampling","from","the","Brownian","motion","process","with","time","dependent","parameters","can","be","done","efficiently","if","the","total","drift","and","total","covariance","functions","are","supplied",".","If","the","parameters","are","constant",",","the","total","parameters","can","be","automatically","inferred","and","it","is","not","worth","supplying","then","explicitly",".","Currently",",","it","is","not","possible","to","infer","the","total","drift","and","covariance","from","the","instantaneous","values","if","the","latter","are","functions","of","time",".","In","this","case",",","we","use","a","generic","sampling","method","(","Euler-Maruyama",")","which","may","be","inefficient",".","It","is","advisable","to","supply","the","total","covariance","and","total","drift","in","the","time","dependent","case","where","possible",".","#","#","#","#","Example","The","following","is","an","example","of","a","1","dimensional","brownian","motion","using","default","arguments","of","zero","drift","and","unit","volatility",".","``","`","python","process","=","bm.BrownianMotion","(",")","times","=","np.array","(","[","0.2",",","0.33",",","0.7",",","0.9",",","1.88","]",")","num_samples","=","10000","with","tf.Session","(",")","as","sess",":","paths","=","sess.run","(","process.sample_paths","(","times",",","num_samples=num_samples",",","initial_state=np.array","(","0.1",")",",","seed=1234",")",")","#","Compute","the","means","at","the","specified","times",".","means","=","np.mean","(","paths",",","axis=0",")","print","(","means",")","#","Mean","values","will","be","near","0.1","for","each","time","#","Compute","the","covariances","at","the","given","times","covars","=","np.cov","(","paths.reshape","(","[","num_samples",",","5","]",")",",","rowvar=False",")","#","covars","is","a","5","x","5","covariance","matrix",".","#","Expected","result","is","that","Covar","(","X","(","t",")",",","X","(","t","'",")",")","=","min","(","t",",","t","'",")","expected","=","np.minimum","(","times.reshape","(","[","-1",",","1","]",")",",","times.reshape","(","[","1",",","-1","]",")",")","print","(","``","Computed","Covars",":","{","}",",","True","Covars",":","{","}","''",".format","(","covars",",","expected",")",")","``","`","Args",":","dim",":","Python","int","greater","than","or","equal","to","1",".","The","dimension","of","the","Brownian","motion",".","Default","value",":","1","(","i.e",".","a","one","dimensional","brownian","process",")",".","drift",":","The","drift","of","the","process",".","The","type","and","shape","of","the","value","must","be","one","of","the","following","(","in","increasing","order","of","generality",")","(","a",")","A","real","scalar","`","Tensor","`",".","This","corresponds","to","a","time","and","component","independent","drift",".","Every","component","of","the","Brownian","motion","has","the","same","drift","rate","equal","to","this","value",".","(","b",")","A","real","`","Tensor","`","of","shape","`","[","dim","]","`",".","This","corresponds","to","a","time","independent","drift","with","the","`","i","`","th","component","as","the","drift","rate","of","the","`","i","`","th","component","of","the","Brownian","motion",".","(","c",")","A","Python","callable","accepting","a","single","positive","`","Tensor","`","of","general","shape","(","referred","to","as","`","times_shape","`",")","and","returning","a","`","Tensor","`","of","shape","`","times_shape","+","[","dim","]","`",".","The","input","argument","is","the","times","at","which","the","drift","needs","to","be","evaluated",".","This","case","corresponds","to","a","general","time","and","direction","dependent","drift","rate",".","Default","value",":","None","which","maps","to","zero","drift",".","volatility",":","The","volatility","of","the","process",".","The","type","and","shape","of","the","supplied","value","must","be","one","of","the","following","(","in","increasing","order","of","generality",")","(","a",")","A","positive","real","scalar","`","Tensor","`",".","This","corresponds","to","a","time","independent",",","diagonal","volatility","matrix",".","The","`","(","i",",","j",")","`","component","of","the","full","volatility","matrix","is","equal","to","zero","if","`","i","!","=","j","`","and","equal","to","the","supplied","value","otherwise",".","(","b",")","A","positive","real","`","Tensor","`","of","shape","`","[","dim","]","`",".","This","corresponds","to","a","time","independent","volatility","matrix","with","zero","correlation",".","The","`","(","i",",","j",")","`","component","of","the","full","volatility","matrix","is","equal","to","zero","`","i","!","=","j","`","and","equal","to","the","`","i","`","th","component","of","the","supplied","value","otherwise",".","(","c",")","A","positive","definite","real","`","Tensor","`","of","shape","`","[","dim",",","dim","]","`",".","The","full","time","independent","volatility","matrix",".","(","d",")","A","Python","callable","accepting","a","single","positive","`","Tensor","`","of","general","shape","(","referred","to","as","`","times_shape","`",")","and","returning","a","`","Tensor","`","of","shape","`","times_shape","+","[","dim",",","dim","]","`",".","The","input","argument","are","the","times","at","which","the","volatility","needs","to","be","evaluated",".","This","case","corresponds","to","a","general","time","and","axis","dependent","volatility","matrix",".","Default","value",":","None","which","maps","to","a","volatility","matrix","equal","to","identity",".","total_drift_fn",":","Optional","Python","callable","to","compute","the","integrated","drift","rate","between","two","times",".","The","callable","should","accept","two","real","`","Tensor","`","arguments",".","The","first","argument","contains","the","start","times","and","the","second",",","the","end","times","of","the","time","intervals","for","which","the","total","drift","is","to","be","computed",".","Both","the","`","Tensor","`","arguments","are","of","the","same","dtype","and","shape",".","The","return","value","of","the","callable","should","be","a","real","`","Tensor","`","of","the","same","dtype","as","the","input","arguments","and","of","shape","`","times_shape","+","[","dim","]","`","where","`","times_shape","`","is","the","shape","of","the","times","`","Tensor","`",".","Note","that","it","is","an","error","to","supply","this","parameter","if","the","`","drift","`","is","not","supplied",".","Default","value",":","None",".","total_covariance_fn",":","A","Python","callable","returning","the","integrated","covariance","rate","between","two","times",".","The","callable","should","accept","two","real","`","Tensor","`","arguments",".","The","first","argument","is","the","start","times","and","the","second","is","the","end","times","of","the","time","intervals","for","which","the","total","covariance","is","needed",".","Both","the","`","Tensor","`","arguments","are","of","the","same","dtype","and","shape",".","The","return","value","of","the","callable","is","a","real","`","Tensor","`","of","the","same","dtype","as","the","input","arguments","and","of","shape","`","times_shape","+","[","dim",",","dim","]","`","where","`","times_shape","`","is","the","shape","of","the","times","`","Tensor","`",".","Note","that","it","is","an","error","to","supply","this","argument","if","the","`","volatility","`","is","not","supplied",".","Default","value",":","None",".","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",".","name",":","str",".","The","name","scope","under","which","ops","created","by","the","methods","of","this","class","are","nested",".","Default","value",":","None","which","maps","to","the","default","name","`","brownian_motion","`",".","Raises",":","ValueError","if","the","dimension","is","less","than","1","or","if","total","drift","is","supplied","but","drift","is","not","supplied","or","if","the","total","covariance","is","supplied","but","but","volatility","is","not","supplied","."]
code: def __init__(
      self,
      dim=1,
      drift=None,
      volatility=None,
      total_drift_fn=None,
      total_covariance_fn=None,
      dtype=None,
      name=None,
  ):
      """Initializes the Brownian motion class.
  
      Represents the Ito process:
  
      ```None
        dX_i = a_i(t) dt + Sum(S_{ij}(t) dW_j for j in [1 ... n]), 1 <= i <= n
  
      ```
  
      `a_i(t)` is the drift rate of this process and the `S_{ij}(t)` is the
      volatility matrix. Associated to these parameters are the integrated
      drift and covariance functions. These are defined as:
  
      ```None
        total_drift_{i}(t1, t2) = Integrate(a_{i}(t), t1 <= t <= t2)
        total_covariance_{ij}(t1, t2) = Integrate(inst_covariance_{ij}(t),
                                                       t1 <= t <= t2)
        inst_covariance_{ij}(t) = (S.S^T)_{ij}(t)
      ```
  
      Sampling from the Brownian motion process with time dependent parameters
      can be done efficiently if the total drift and total covariance functions
      are supplied. If the parameters are constant, the total parameters can be
      automatically inferred and it is not worth supplying then explicitly.
  
      Currently, it is not possible to infer the total drift and covariance from
      the instantaneous values if the latter are functions of time. In this case,
      we use a generic sampling method (Euler-Maruyama) which may be
      inefficient. It is advisable to supply the total covariance and total drift
      in the time dependent case where possible.
  
      #### Example
      The following is an example of a 1 dimensional brownian motion using default
      arguments of zero drift and unit volatility.
  
      ```python
      process = bm.BrownianMotion()
      times = np.array([0.2, 0.33, 0.7, 0.9, 1.88])
      num_samples = 10000
      with tf.Session() as sess:
        paths = sess.run(process.sample_paths(
            times,
            num_samples=num_samples,
            initial_state=np.array(0.1),
            seed=1234))
  
      # Compute the means at the specified times.
      means = np.mean(paths, axis=0)
      print (means)  # Mean values will be near 0.1 for each time
  
      # Compute the covariances at the given times
      covars = np.cov(paths.reshape([num_samples, 5]), rowvar=False)
  
      # covars is a 5 x 5 covariance matrix.
      # Expected result is that Covar(X(t), X(t')) = min(t, t')
      expected = np.minimum(times.reshape([-1, 1]), times.reshape([1, -1]))
      print ("Computed Covars: {}, True Covars: {}".format(covars, expected))
      ```
  
      Args:
        dim: Python int greater than or equal to 1. The dimension of the Brownian
          motion.
          Default value: 1 (i.e. a one dimensional brownian process).
        drift: The drift of the process. The type and shape of the value must be
          one of the following (in increasing order of generality) (a) A real
          scalar `Tensor`. This corresponds to a time and component independent
          drift. Every component of the Brownian motion has the same drift rate
          equal to this value. (b) A real `Tensor` of shape `[dim]`. This
          corresponds to a time independent drift with the `i`th component as the
          drift rate of the `i`th component of the Brownian motion. (c) A Python
          callable accepting a single positive `Tensor` of general shape (referred
          to as `times_shape`) and returning a `Tensor` of shape `times_shape +
          [dim]`. The input argument is the times at which the drift needs to be
          evaluated. This case corresponds to a general time and direction
          dependent drift rate.
          Default value: None which maps to zero drift.
        volatility: The volatility of the process. The type and shape of the
          supplied value must be one of the following (in increasing order of
          generality) (a) A positive real scalar `Tensor`. This corresponds to a
          time independent, diagonal volatility matrix. The `(i, j)` component of
          the full volatility matrix is equal to zero if `i != j` and equal to the
          supplied value otherwise. (b) A positive real `Tensor` of shape `[dim]`.
          This corresponds to a time independent volatility matrix with zero
          correlation. The `(i, j)` component of the full volatility matrix is
          equal to zero `i != j` and equal to the `i`th component of the supplied
          value otherwise. (c) A positive definite real `Tensor` of shape `[dim,
          dim]`. The full time independent volatility matrix. (d) A Python
          callable accepting a single positive `Tensor` of general shape (referred
          to as `times_shape`) and returning a `Tensor` of shape `times_shape +
          [dim, dim]`. The input argument are the times at which the volatility
          needs to be evaluated. This case corresponds to a general time and axis
          dependent volatility matrix.
          Default value: None which maps to a volatility matrix equal to identity.
        total_drift_fn: Optional Python callable to compute the integrated drift
          rate between two times. The callable should accept two real `Tensor`
          arguments. The first argument contains the start times and the second,
          the end times of the time intervals for which the total drift is to be
          computed. Both the `Tensor` arguments are of the same dtype and shape.
          The return value of the callable should be a real `Tensor` of the same
          dtype as the input arguments and of shape `times_shape + [dim]` where
          `times_shape` is the shape of the times `Tensor`. Note that it is an
          error to supply this parameter if the `drift` is not supplied.
          Default value: None.
        total_covariance_fn: A Python callable returning the integrated covariance
          rate between two times. The callable should accept two real `Tensor`
          arguments. The first argument is the start times and the second is the
          end times of the time intervals for which the total covariance is
          needed. Both the `Tensor` arguments are of the same dtype and shape. The
          return value of the callable is a real `Tensor` of the same dtype as the
          input arguments and of shape `times_shape + [dim, dim]` where
          `times_shape` is the shape of the times `Tensor`. Note that it is an
          error to supply this argument if the `volatility` is not supplied.
          Default value: None.
        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.
        name: str. The name scope under which ops created by the methods of this
          class are nested.
          Default value: None which maps to the default name `brownian_motion`.
  
      Raises:
        ValueError if the dimension is less than 1 or if total drift is supplied
          but drift is not supplied or if the total covariance is supplied but
          but volatility is not supplied.
      """
      super(BrownianMotion, self).__init__()
  
      if dim < 1:
          raise ValueError("Dimension must be 1 or greater.")
      if drift is None and total_drift_fn is not None:
          raise ValueError(
              "total_drift_fn must not be supplied if drift"
              " is not supplied."
          )
      if volatility is None and total_covariance_fn is not None:
          raise ValueError(
              "total_covariance_fn must not be supplied if drift"
              " is not supplied."
          )
      self._dim = dim
      self._dtype = dtype
      self._name = name or "brownian_motion"
  
      drift_fn, total_drift_fn = bmu.construct_drift_data(
          drift, total_drift_fn, dim, dtype
      )
      self._drift_fn = drift_fn
      self._total_drift_fn = total_drift_fn
  
      vol_fn, total_covar_fn = bmu.construct_vol_data(
          volatility, total_covariance_fn, dim, dtype
      )
      self._volatility_fn = vol_fn
      self._total_covariance_fn = total_covar_fn
  
file_path: tf-quant-finance/tf_quant_finance/models/legacy/brownian_motion.py
imports: import tensorflow.compat.v2
  from tf_quant_finance.math.random_ops import multivariate_normal
  from tf_quant_finance.models.legacy import brownian_motion_utils
  from tf_quant_finance.models.legacy import ito_process
label_desc: Use image node_id 1 to create a new BrownianMotion object from inherited base classes: ito_process with example: obj = BrownianMotion(dim, drift, volatility, total_drift_fn, total_covariance_fn, dtype, name)