class_docstr: Class for (principal) fiber bundles.
  
  This class implements abstract methods for fiber bundles, or more
  generally manifolds, with a submersion map, or a right Lie group action.
  
  Parameters
  ----------
  group : LieGroup
      Group that acts on the total space by the right.
      Optional. Default : None.
      Either the group or the group action must be given.
  group_action : callable
      Right group action. It must take as input a point of the total space
      and an element of the group, and return a point of the total space.
class_docstr_tok: ["Class","for","(","principal",")","fiber","bundles",".","This","class","implements","abstract","methods","for","fiber","bundles",",","or","more","generally","manifolds",",","with","a","submersion","map",",","or","a","right","Lie","group","action",".","Parameters","--","--","--","--","--","group",":","LieGroup","Group","that","acts","on","the","total","space","by","the","right",".","Optional",".","Default",":","None",".","Either","the","group","or","the","group","action","must","be","given",".","group_action",":","callable","Right","group","action",".","It","must","take","as","input","a","point","of","the","total","space","and","an","element","of","the","group",",","and","return","a","point","of","the","total","space","."]
docstr: Align point to base_point.
  
  Find the optimal group element g such that the base point and
  point.g are well positioned, meaning that the total space distance is
  minimized. This also means that the geodesic joining the base point
  and the aligned point is horizontal. By default, this is solved by a
  gradient descent in the Lie algebra.
  
  Parameters
  ----------
  point : array-like, shape=[..., {total_space.dim, [n, m]}]
      Point on the manifold.
  base_point : array-like, shape=[..., {total_space.dim, [n, m]}]
      Point on the manifold.
  max_iter : int
      Maximum number of gradient steps.
      Optional, default : 25.
  verbose : bool
      Verbosity level.
      Optional, default : False.
  tol : float
      Tolerance for the stopping criterion.
      Optional, default : backend atol
  
  Returns
  -------
  aligned : array-like, shape=[..., {total_space.dim, [n, m]}]
      Action of the optimal g on point.
docstr_tok: ["Align","point","to","base_point",".","Find","the","optimal","group","element","g","such","that","the","base","point","and","point.g","are","well","positioned",",","meaning","that","the","total","space","distance","is","minimized",".","This","also","means","that","the","geodesic","joining","the","base","point","and","the","aligned","point","is","horizontal",".","By","default",",","this","is","solved","by","a","gradient","descent","in","the","Lie","algebra",".","Parameters","--","--","--","--","--","point",":","array-like",",","shape=","[","...",",","{","total_space.dim",",","[","n",",","m","]","}","]","Point","on","the","manifold",".","base_point",":","array-like",",","shape=","[","...",",","{","total_space.dim",",","[","n",",","m","]","}","]","Point","on","the","manifold",".","max_iter",":","int","Maximum","number","of","gradient","steps",".","Optional",",","default",":","25.","verbose",":","bool","Verbosity","level",".","Optional",",","default",":","False",".","tol",":","float","Tolerance","for","the","stopping","criterion",".","Optional",",","default",":","backend","atol","Returns","--","--","--","-","aligned",":","array-like",",","shape=","[","...",",","{","total_space.dim",",","[","n",",","m","]","}","]","Action","of","the","optimal","g","on","point","."]
code: def align(
      self, point, base_point, max_iter=25, verbose=False, tol=gs.atol
  ):
      """Align point to base_point.
  
      Find the optimal group element g such that the base point and
      point.g are well positioned, meaning that the total space distance is
      minimized. This also means that the geodesic joining the base point
      and the aligned point is horizontal. By default, this is solved by a
      gradient descent in the Lie algebra.
  
      Parameters
      ----------
      point : array-like, shape=[..., {total_space.dim, [n, m]}]
          Point on the manifold.
      base_point : array-like, shape=[..., {total_space.dim, [n, m]}]
          Point on the manifold.
      max_iter : int
          Maximum number of gradient steps.
          Optional, default : 25.
      verbose : bool
          Verbosity level.
          Optional, default : False.
      tol : float
          Tolerance for the stopping criterion.
          Optional, default : backend atol
  
      Returns
      -------
      aligned : array-like, shape=[..., {total_space.dim, [n, m]}]
          Action of the optimal g on point.
      """
      group = self.group
      group_action = self.group_action
  
      batch_shape = get_batch_shape(
          self.total_space.point_ndim, point, base_point
      )
      max_shape = batch_shape + (self.group_dim,)
  
      if group is not None:
  
          def wrap(param):
              """Wrap a parameter vector to a group element."""
              algebra_elt = gs.reshape(
                  gs.cast(gs.array(param), dtype=base_point.dtype),
                  max_shape,
              )
              algebra_elt = group.lie_algebra.matrix_representation(
                  algebra_elt
              )
              group_elt = group.exp(algebra_elt)
              return self.group_action(point, group_elt)
  
      elif group_action is not None:
  
          def wrap(param):
              vector = gs.reshape(gs.array(param), max_shape)
              vector = gs.cast(vector, dtype=base_point.dtype)
              return group_action(vector, point)
  
      else:
          raise ValueError(
              "Either the group of its action must be known"
          )
  
      objective_with_grad = gs.autodiff.value_and_grad(
          lambda param: gs.sum(
              self.total_space.metric.squared_dist(
                  wrap(param), base_point
              )
          ),
          to_numpy=True,
      )
  
      tangent_vec = gs.flatten(gs.random.rand(*max_shape))
      res = minimize(
          objective_with_grad,
          tangent_vec,
          method="L-BFGS-B",
          jac=True,
          options={"disp": verbose, "maxiter": max_iter},
          tol=tol,
      )
  
      return wrap(res.x)
  
file_path: geomstats/geomstats/geometry/fiber_bundle.py
imports: import sys
  from abc import ABC
  from scipy.optimize import minimize
  import geomstats.backend
  from geomstats.vectorization import get_batch_shape
label_desc: Use image node_id 5 for calling the FiberBundle obj's underlying member method code with example usage: obj.align(point, base_point, max_iter, verbose, tol) and returns: wrap, self, group_action