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 curvature.
  
  For four vectors fields :math:`H|_P =` `tangent_vec_a`,
  :math:`X|_P =` `tangent_vec_b`, :math:`Y|_P =` `tangent_vec_c`,
  :math:`Z|_P =` `tangent_vec_d` with
  tangent vector value specified in argument at the `base_point` :math:`P`,
  the covariant derivative of the curvature
  :math:`(\nabla_H R)(X, Y)Z |_P` is computed at the `base_point` :math:`P`.
  
  In the case of quotient metrics, the fundamental equations of a
  Riemannian submersion allow to compute this tensor on the base manifold
  from the one 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:`H, X, Y, Z` 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_H H=0`,
  :math:`\nabla^T_H X = A_H X` (and similarly for Y and Z) using the
  connection :math:`\nabla^T` of the total space. Then the covariant
  derivative of the curvature tensor is given by
  
  .. math::
      \nabla_H (R(X, Y) Z) =
      hor\nabla_H^T(R^T(X,Y)Z) - A_H(ver R^T(X,Y)Z )
      + (2 A_H A_Z A_X Y - A_H A_X A_Y Z + A_H A_Y A_X Z)
      - (2 \nabla_H^T A_Z A_X Y - \nabla_H^T A_X A_Y Z + \nabla_H^T A_Y A_X Z)
  
  where :math:`R^T(X,Y)Z` is the curvature tensor of the total space.
  
  Parameters
  ----------
  tangent_vec_a : array-like, shape=[..., n, n]
      Tangent vector at `base_point` (derivative direction).
  tangent_vec_b : array-like, shape=[..., n, n]
      Tangent vector at `base_point`.
  tangent_vec_c : array-like, shape=[..., n, n]
      Tangent vector at `base_point`.
  tangent_vec_d : 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","curvature",".","For","four","vectors","fields",":","math",":","`","H|_P","=","`","`","tangent_vec_a","`",",",":","math",":","`","X|_P","=","`","`","tangent_vec_b","`",",",":","math",":","`","Y|_P","=","`","`","tangent_vec_c","`",",",":","math",":","`","Z|_P","=","`","`","tangent_vec_d","`","with","tangent","vector","value","specified","in","argument","at","the","`","base_point","`",":","math",":","`","P","`",",","the","covariant","derivative","of","the","curvature",":","math",":","`","(","\\nabla_H","R",")","(","X",",","Y",")","Z","|_P","`","is","computed","at","the","`","base_point","`",":","math",":","`","P","`",".","In","the","case","of","quotient","metrics",",","the","fundamental","equations","of","a","Riemannian","submersion","allow","to","compute","this","tensor","on","the","base","manifold","from","the","one","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",":","`","H",",","X",",","Y",",","Z","`","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_H","H=0","`",",",":","math",":","`","\\nabla^T_H","X","=","A_H","X","`","(","and","similarly","for","Y","and","Z",")","using","the","connection",":","math",":","`","\\nabla^T","`","of","the","total","space",".","Then","the","covariant","derivative","of","the","curvature","tensor","is","given","by","..","math",":",":","\\nabla_H","(","R","(","X",",","Y",")","Z",")","=","hor\\nabla_H^T","(","R^T","(","X",",","Y",")","Z",")","-","A_H","(","ver","R^T","(","X",",","Y",")","Z",")","+","(","2","A_H","A_Z","A_X","Y","-","A_H","A_X","A_Y","Z","+","A_H","A_Y","A_X","Z",")","-","(","2","\\nabla_H^T","A_Z","A_X","Y","-","\\nabla_H^T","A_X","A_Y","Z","+","\\nabla_H^T","A_Y","A_X","Z",")","where",":","math",":","`","R^T","(","X",",","Y",")","Z","`","is","the","curvature","tensor","of","the","total","space",".","Parameters","--","--","--","--","--","tangent_vec_a",":","array-like",",","shape=","[","...",",","n",",","n","]","Tangent","vector","at","`","base_point","`","(","derivative","direction",")",".","tangent_vec_b",":","array-like",",","shape=","[","...",",","n",",","n","]","Tangent","vector","at","`","base_point","`",".","tangent_vec_c",":","array-like",",","shape=","[","...",",","n",",","n","]","Tangent","vector","at","`","base_point","`",".","tangent_vec_d",":","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 curvature_derivative(
      self,
      tangent_vec_a,
      tangent_vec_b,
      tangent_vec_c,
      tangent_vec_d,
      base_point=None,
  ):
      r"""Compute the covariant derivative of the curvature.
  
      For four vectors fields :math:`H|_P =` `tangent_vec_a`,
      :math:`X|_P =` `tangent_vec_b`, :math:`Y|_P =` `tangent_vec_c`,
      :math:`Z|_P =` `tangent_vec_d` with
      tangent vector value specified in argument at the `base_point` :math:`P`,
      the covariant derivative of the curvature
      :math:`(\nabla_H R)(X, Y)Z |_P` is computed at the `base_point` :math:`P`.
  
      In the case of quotient metrics, the fundamental equations of a
      Riemannian submersion allow to compute this tensor on the base manifold
      from the one 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:`H, X, Y, Z` 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_H H=0`,
      :math:`\nabla^T_H X = A_H X` (and similarly for Y and Z) using the
      connection :math:`\nabla^T` of the total space. Then the covariant
      derivative of the curvature tensor is given by
  
      .. math::
          \nabla_H (R(X, Y) Z) =
          hor\nabla_H^T(R^T(X,Y)Z) - A_H(ver R^T(X,Y)Z )
          + (2 A_H A_Z A_X Y - A_H A_X A_Y Z + A_H A_Y A_X Z)
          - (2 \nabla_H^T A_Z A_X Y - \nabla_H^T A_X A_Y Z + \nabla_H^T A_Y A_X Z)
  
      where :math:`R^T(X,Y)Z` is the curvature tensor of the total space.
  
      Parameters
      ----------
      tangent_vec_a : array-like, shape=[..., n, n]
          Tangent vector at `base_point` (derivative direction).
      tangent_vec_b : array-like, shape=[..., n, n]
          Tangent vector at `base_point`.
      tangent_vec_c : array-like, shape=[..., n, n]
          Tangent vector at `base_point`.
      tangent_vec_d : 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_h = bundle.horizontal_lift(tangent_vec_a, point_fiber)
      hor_x = bundle.horizontal_lift(tangent_vec_b, point_fiber)
      hor_y = bundle.horizontal_lift(tangent_vec_c, point_fiber)
      hor_z = bundle.horizontal_lift(tangent_vec_d, point_fiber)
  
      nabla_h_x = bundle.integrability_tensor(hor_h, hor_x, point_fiber)
      nabla_h_y = bundle.integrability_tensor(hor_h, hor_y, point_fiber)
      nabla_h_z = bundle.integrability_tensor(hor_h, hor_z, point_fiber)
  
      nabla_curvature_top = (
          bundle.total_space.metric.curvature_derivative(
              hor_h, hor_x, hor_y, hor_z, 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_h_ver_nabla_curvature_top = bundle.integrability_tensor(
          hor_h, ver_nabla_curvature_top, point_fiber
      )
  
      # A_H A_Z A_X Y and \nabla_H A_Z A_X Y
      nabla_h_a_x_y, a_x_y = bundle.integrability_tensor_derivative(
          hor_h, hor_x, nabla_h_x, hor_y, nabla_h_y, point_fiber
      )
      (
          nabla_h_a_z_a_x_y,
          a_z_a_x_y,
      ) = bundle.integrability_tensor_derivative(
          hor_h, hor_z, nabla_h_z, a_x_y, nabla_h_a_x_y, point_fiber
      )
      a_h_a_z_a_x_y = bundle.integrability_tensor(
          hor_h, a_z_a_x_y, point_fiber
      )
  
      # A_H A_X A_Y Z and \nabla_H A_X A_Y Z
      nabla_h_a_y_z, a_y_z = bundle.integrability_tensor_derivative(
          hor_h, hor_y, nabla_h_y, hor_z, nabla_h_z, point_fiber
      )
      (
          nabla_h_a_x_a_y_z,
          a_x_a_y_z,
      ) = bundle.integrability_tensor_derivative(
          hor_h, hor_x, nabla_h_x, a_y_z, nabla_h_a_y_z, point_fiber
      )
      a_h_a_x_a_y_z = bundle.integrability_tensor(
          hor_h, a_x_a_y_z, point_fiber
      )
  
      # A_H A_Y A_X Z and \nabla_H A_Y A_X Z
      nabla_h_a_x_z, a_x_z = bundle.integrability_tensor_derivative(
          hor_h, hor_x, nabla_h_x, hor_z, nabla_h_z, point_fiber
      )
      (
          nabla_h_a_y_a_x_z,
          a_y_a_x_z,
      ) = bundle.integrability_tensor_derivative(
          hor_h, hor_y, nabla_h_y, a_x_z, nabla_h_a_x_z, point_fiber
      )
      a_h_a_y_a_x_z = bundle.integrability_tensor(
          hor_h, a_y_a_x_z, point_fiber
      )
  
      return (
          hor_nabla_curvature_top
          - a_h_ver_nabla_curvature_top
          - 2.0 * (nabla_h_a_z_a_x_y - a_h_a_z_a_x_y)
          + (nabla_h_a_x_a_y_z - a_h_a_x_a_y_z)
          - (nabla_h_a_y_a_x_z - a_h_a_y_a_x_z)
      )
  
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 8 for calling the QuotientMetric obj's underlying member method code with example usage: obj.curvature_derivative(tangent_vec_a, tangent_vec_b, tangent_vec_c, tangent_vec_d, base_point) and returns: unknown