class_docstr: Quotient metric.
  
  Given a (principal) fiber bundle, or more generally a manifold with a
  Lie group acting on it by the right, the quotient space is the space of
  orbits under this action. The quotient metric is defined such that the
  canonical projection is a Riemannian submersion, i.e. it is isometric to
  the restriction of the metric of the total space to horizontal subspaces.
  
  Parameters
  ----------
  space : Manifold
      Base.
  fiber_bundle : FiberBundle
      Bundle structure to define the quotient.
class_docstr_tok: ["Quotient","metric",".","Given","a","(","principal",")","fiber","bundle",",","or","more","generally","a","manifold","with","a","Lie","group","acting","on","it","by","the","right",",","the","quotient","space","is","the","space","of","orbits","under","this","action",".","The","quotient","metric","is","defined","such","that","the","canonical","projection","is","a","Riemannian","submersion",",","i.e",".","it","is","isometric","to","the","restriction","of","the","metric","of","the","total","space","to","horizontal","subspaces",".","Parameters","--","--","--","--","--","space",":","Manifold","Base",".","fiber_bundle",":","FiberBundle","Bundle","structure","to","define","the","quotient","."]
docstr: Compute the covariant derivative of the directional curvature.
  
  For two vectors fields :math:`X|_P =` `tangent_vec_a`,
  :math:`Y|_P =` `tangent_vec_b` with tangent vector value specified in
  argument at the `base_point` :math:`P`,
  the covariant derivative (in the direction :math:`X`)
  :math:`(\nabla_X R_Y)(X) |_P = (\nabla_X R)(Y, X) Y |_P` of the
  directional curvature (in the direction :math:`Y`)
  :math:`R_Y(X) = R(Y, X) Y` is a quadratic tensor in :math:`X` and :math:`Y`
  that plays an important role in the computation of the moments of the
  empirical Fréchet mean.
  
  This tensor can be computed from the covariant derivative of the
  curvature tensor as in done generically the Connection class.
  However, in the case of quotient metrics, a simplified expression can
  be implemented based on the directional curvature of the total space T
  and its covariant derivative with additional correction terms
  involving the integrability tensor A and its covariant derivatives
  [Pennec]_.
  
  In more details, let :math:`X, Y` be the horizontal lift of parallel
  vector fields extending the tangent vectors given in argument by
  parallel transport in a neighborhood of the `base_point` :math:`P` in the
  base-space. Such vector fields verify :math:`\nabla^T_X X=0` and
  :math:`\nabla^T_X^Y = A_X Y` using the connection :math:`\nabla^T`
  of the total space. Then the covariant derivative of the
  directional curvature tensor is given by
  
  .. math::
      \nabla_X (R_Y(X)) = hor \nabla^T_X (R^T_Y(X)) - A_X( ver R^T_Y(X))
      + 3 A_X A_Y A_X Y - 3 \nabla_X^T A_Y A_X Y
  
  where :math:`R^T_Y(X)` is the directional curvature tensor of the total space.
  
  Parameters
  ----------
  tangent_vec_a : array-like, shape=[..., n, n]
      Tangent vector at `base_point`.
  tangent_vec_b : array-like, shape=[..., n, n]
      Tangent vector at `base_point`.
  base_point : array-like, shape=[..., n, n]
      Point on the base manifold.
  
  Returns
  -------
  curvature_derivative : array-like, shape=[..., n, n]
      Tangent vector at `base_point`.
  
  References
  ----------
  .. [Pennec] Pennec, Xavier. Computing the curvature and its gradient
      in Kendall shape spaces. Unpublished.
docstr_tok: ["Compute","the","covariant","derivative","of","the","directional","curvature",".","For","two","vectors","fields",":","math",":","`","X|_P","=","`","`","tangent_vec_a","`",",",":","math",":","`","Y|_P","=","`","`","tangent_vec_b","`","with","tangent","vector","value","specified","in","argument","at","the","`","base_point","`",":","math",":","`","P","`",",","the","covariant","derivative","(","in","the","direction",":","math",":","`","X","`",")",":","math",":","`","(","\\nabla_X","R_Y",")","(","X",")","|_P","=","(","\\nabla_X","R",")","(","Y",",","X",")","Y","|_P","`","of","the","directional","curvature","(","in","the","direction",":","math",":","`","Y","`",")",":","math",":","`","R_Y","(","X",")","=","R","(","Y",",","X",")","Y","`","is","a","quadratic","tensor","in",":","math",":","`","X","`","and",":","math",":","`","Y","`","that","plays","an","important","role","in","the","computation","of","the","moments","of","the","empirical","Fr\u00e9chet","mean",".","This","tensor","can","be","computed","from","the","covariant","derivative","of","the","curvature","tensor","as","in","done","generically","the","Connection","class",".","However",",","in","the","case","of","quotient","metrics",",","a","simplified","expression","can","be","implemented","based","on","the","directional","curvature","of","the","total","space","T","and","its","covariant","derivative","with","additional","correction","terms","involving","the","integrability","tensor","A","and","its","covariant","derivatives","[","Pennec","]","_",".","In","more","details",",","let",":","math",":","`","X",",","Y","`","be","the","horizontal","lift","of","parallel","vector","fields","extending","the","tangent","vectors","given","in","argument","by","parallel","transport","in","a","neighborhood","of","the","`","base_point","`",":","math",":","`","P","`","in","the","base-space",".","Such","vector","fields","verify",":","math",":","`","\\nabla^T_X","X=0","`","and",":","math",":","`","\\nabla^T_X^Y","=","A_X","Y","`","using","the","connection",":","math",":","`","\\nabla^T","`","of","the","total","space",".","Then","the","covariant","derivative","of","the","directional","curvature","tensor","is","given","by","..","math",":",":","\\nabla_X","(","R_Y","(","X",")",")","=","hor","\\nabla^T_X","(","R^T_Y","(","X",")",")","-","A_X","(","ver","R^T_Y","(","X",")",")","+","3","A_X","A_Y","A_X","Y","-","3","\\nabla_X^T","A_Y","A_X","Y","where",":","math",":","`","R^T_Y","(","X",")","`","is","the","directional","curvature","tensor","of","the","total","space",".","Parameters","--","--","--","--","--","tangent_vec_a",":","array-like",",","shape=","[","...",",","n",",","n","]","Tangent","vector","at","`","base_point","`",".","tangent_vec_b",":","array-like",",","shape=","[","...",",","n",",","n","]","Tangent","vector","at","`","base_point","`",".","base_point",":","array-like",",","shape=","[","...",",","n",",","n","]","Point","on","the","base","manifold",".","Returns","--","--","--","-","curvature_derivative",":","array-like",",","shape=","[","...",",","n",",","n","]","Tangent","vector","at","`","base_point","`",".","References","--","--","--","--","--","..","[","Pennec","]","Pennec",",","Xavier",".","Computing","the","curvature","and","its","gradient","in","Kendall","shape","spaces",".","Unpublished","."]
code: def directional_curvature_derivative(
      self, tangent_vec_a, tangent_vec_b, base_point=None
  ):
      r"""Compute the covariant derivative of the directional curvature.
  
      For two vectors fields :math:`X|_P =` `tangent_vec_a`,
      :math:`Y|_P =` `tangent_vec_b` with tangent vector value specified in
      argument at the `base_point` :math:`P`,
      the covariant derivative (in the direction :math:`X`)
      :math:`(\nabla_X R_Y)(X) |_P = (\nabla_X R)(Y, X) Y |_P` of the
      directional curvature (in the direction :math:`Y`)
      :math:`R_Y(X) = R(Y, X) Y` is a quadratic tensor in :math:`X` and :math:`Y`
      that plays an important role in the computation of the moments of the
      empirical Fréchet mean.
  
      This tensor can be computed from the covariant derivative of the
      curvature tensor as in done generically the Connection class.
      However, in the case of quotient metrics, a simplified expression can
      be implemented based on the directional curvature of the total space T
      and its covariant derivative with additional correction terms
      involving the integrability tensor A and its covariant derivatives
      [Pennec]_.
  
      In more details, let :math:`X, Y` be the horizontal lift of parallel
      vector fields extending the tangent vectors given in argument by
      parallel transport in a neighborhood of the `base_point` :math:`P` in the
      base-space. Such vector fields verify :math:`\nabla^T_X X=0` and
      :math:`\nabla^T_X^Y = A_X Y` using the connection :math:`\nabla^T`
      of the total space. Then the covariant derivative of the
      directional curvature tensor is given by
  
      .. math::
          \nabla_X (R_Y(X)) = hor \nabla^T_X (R^T_Y(X)) - A_X( ver R^T_Y(X))
          + 3 A_X A_Y A_X Y - 3 \nabla_X^T A_Y A_X Y
  
      where :math:`R^T_Y(X)` is the directional curvature tensor of the total space.
  
      Parameters
      ----------
      tangent_vec_a : array-like, shape=[..., n, n]
          Tangent vector at `base_point`.
      tangent_vec_b : array-like, shape=[..., n, n]
          Tangent vector at `base_point`.
      base_point : array-like, shape=[..., n, n]
          Point on the base manifold.
  
      Returns
      -------
      curvature_derivative : array-like, shape=[..., n, n]
          Tangent vector at `base_point`.
  
      References
      ----------
      .. [Pennec] Pennec, Xavier. Computing the curvature and its gradient
          in Kendall shape spaces. Unpublished.
      """
      bundle = self.fiber_bundle
      point_fiber = bundle.lift(base_point)
      hor_x = bundle.horizontal_lift(tangent_vec_a, point_fiber)
      hor_y = bundle.horizontal_lift(tangent_vec_b, point_fiber)
  
      nabla_x_x = gs.zeros_like(hor_x)
      nabla_x_y = bundle.integrability_tensor(hor_x, hor_y, point_fiber)
  
      nabla_curvature_top = (
          bundle.total_space.metric.curvature_derivative(
              hor_x, hor_x, hor_y, hor_y, point_fiber
          )
      )
  
      hor_nabla_curvature_top = bundle.horizontal_projection(
          nabla_curvature_top, point_fiber
      )
      ver_nabla_curvature_top = (
          nabla_curvature_top - hor_nabla_curvature_top
      )
  
      a_x_ver_nabla_curvature_top = bundle.integrability_tensor(
          hor_x, ver_nabla_curvature_top, point_fiber
      )
  
      # A_X A_Y A_X Y and \nabla_X A_Y A_X Y
      nabla_x_a_x_y, a_x_y = bundle.integrability_tensor_derivative(
          hor_x, hor_x, nabla_x_x, hor_y, nabla_x_y, point_fiber
      )
      (
          nabla_x_a_y_a_x_y,
          a_y_a_x_y,
      ) = bundle.integrability_tensor_derivative(
          hor_x, hor_y, nabla_x_y, a_x_y, nabla_x_a_x_y, point_fiber
      )
      a_x_a_y_a_x_y = bundle.integrability_tensor(
          hor_x, a_y_a_x_y, point_fiber
      )
  
      return (
          hor_nabla_curvature_top
          - a_x_ver_nabla_curvature_top
          + 3.0 * (nabla_x_a_y_a_x_y - a_x_a_y_a_x_y)
      )
  
file_path: geomstats/geomstats/geometry/quotient_metric.py
imports: import geomstats.backend
  from geomstats.geometry.riemannian_metric import RiemannianMetric
label_desc: Use image node_id 9 for calling the QuotientMetric obj's underlying member method code with example usage: obj.directional_curvature_derivative(tangent_vec_a, tangent_vec_b, base_point) and returns: unknown