Skip to contents

Abstract Class for Connections

Source: R/connection.R
Connection.Rd

An R6::R6Class object implementing the base Connection class for affine connections.

Author

Nicolas Guigui

Super class

rgeomstats::PythonClass -> Connection

Public fields

dim

An integer value specifying the dimension of the underlying manifold.

shape

An integer vector specifying the shape of one element of the manifold. Defaults to NULL.

default_coords_type

A string specifying the coordinate type. Choices are extrensic or intrinsic. Dedaults to intrinsic.

default_point_type

A string specifying the point type. Choices are vector or matrix. It is automatically determined depending on the manifold.

Methods

Public methods

Inherited methods

Method new()

The Connection class constructor.

Usage

Connection$new(
  dim,
  shape = NULL,
  default_coords_type = "intrinsic",
  py_cls = NULL
)

Arguments

dim

An integer value specifying the dimension of the manifold.

shape

An integer vector specifying the shape of one element of the manifold. Defaults to NULL.

default_coords_type

A string specifying the coordinate type. Choices are extrensic or intrinsic. Defaults to intrinsic.

py_cls

A Python object of class Connection. Defaults to NULL in which case it is instantiated on the fly using the other input arguments.

metric

A RiemannianMetric object specifying the metric to use on the manifold. Defaults to NULL.

Returns

An object of class Connection.

Method christoffels()

Christoffel symbols associated with the connection.

Usage

Connection$christoffels(base_point)

Arguments

base_point

A numeric array of shape dim specifying a base point on the manifold.

Returns

A numeric array of shape c(dim, dim, dim) storing the Christoffel symbols, with the contravariant index on the first dimension.

Method geodesic_equation()

Computes the geodesic ODE associated with the connection.

Usage

Connection$geodesic_equation(state, .time)

Arguments

state

A numeric array of shape dim specifying a tangent vector to the manifold at the position specified by .time.

.time

A numeric array of shape dim specifying a point on the manifold at which to compute the geodesic ODE.

Returns

A numeric array of shape dim storing the value of the vector field to be integrated at position.

Method exp()

Exponential map associated to the affine connection.

Usage

Connection$exp(tangent_vec, base_point, n_steps = 100, step = "euler")

Arguments

tangent_vec

A numeric array of shape dim specifying a tangent vector at base_point.

base_point

A numeric array of shape dim specifying a base point on the manifold.

n_steps

An integer value specifying the number of discrete time steps to take in the integration. Defaults to 100L.

step

A string specifying which numerical scheme to use for integration. Choices are euler or rk4. Defaults to euler.

Details

Exponential map at base_point of tangent_vec computed by integration of the geodesic equation (initial value problem), using the christoffel symbols.

Returns

A numeric array of shape dim storing the exponential of the input tangent vector, which lies on on the manifold.

Method log()

Logarithm map associated to the affine connection.

Usage

Connection$log(
  point,
  base_point,
  n_steps = 100,
  step = "euler",
  max_iter = 25,
  verbose = FALSE,
  tol = gs$backend$atol
)

Arguments

point

A numeric array of shape dim specifying a point on the manifold.

base_point

A numeric array of shape dim specifying a base point on the manifold.

n_steps

An integer value specifying the number of discrete time steps to take in the integration. Defaults to 100L.

step

A string specifying which numerical scheme to use for integration. Choices are euler or rk4. Defaults to euler.

max_iter

An integer value specifying the number of iterations. Defaults to 25L.

verbose

A boolean specifying whether the optimizer should display intermediate messages pertaining to its convergence. Defaults to FALSE.

tol

A numeric value specifying the absolute tolerance for optimization convergence. Defaults to gs$backend$atol.

Details

Solves the boundary value problem associated to the geodesic equation using the Christoffel symbols and conjugate gradient descent.

Returns

A numeric array of shape dim storing the exponential of the input tangent vector, which lies on on the manifold.

Method ladder_parallel_transport()

Approximate parallel transport using the pole ladder scheme.

Usage

Connection$ladder_parallel_transport(
  tangent_vec,
  base_point,
  direction,
  n_rungs = 1,
  scheme = "pole",
  alpha = 1,
  ...
)

Arguments

tangent_vec

A numeric array of shape dim specifying a tangent vector at base_point.

base_point

A numeric array of shape dim specifying a base point on the manifold.

direction

Tangent vector at base point specifying the initial speed of the geodesic along which to transport.

n_rungs

A scalar integer specifying the Number of steps of the ladder. Defaults to 1L.

scheme

A string specifying the scheme to use for the construction of the ladder at each step. Choices are either pole or schild. Defaults to pole.

alpha

A numeric value specifying the exponent for the scaling of the vector to transport. Must be greater or equal to 1 and Guigui and Pennec (2022) proved that alpha = 2 is optimal. Defaults to 2.

...

Extra arguments to be passed to calls to $exp() and $log() in auxiliary single ladder step functions.

Details

Approximate parallel transport using either the pole ladder or the Schild's ladder scheme (Lorenzi and Pennec 2014) . Pole ladder is exact in symmetric spaces and of order two in general while Schild's ladder is a first order approximation (Guigui and Pennec 2022) . Both schemes are available on any affine connection manifolds whose exponential and logarithm maps are implemented. tangent_vec is transported along the geodesic starting at the base_point with initial tangent vector direction.

References

Guigui N, Pennec X (2022). “Numerical accuracy of ladder schemes for parallel transport on manifolds.” Foundations of Computational Mathematics, 22(3), 757--790.

Lorenzi M, Pennec X (2014). “Efficient parallel transport of deformations in time series of images: from Schild’s to pole ladder.” Journal of mathematical imaging and vision, 50(1), 5--17.

Returns

A named list with 3 components:

  • transported_tangent_vector: Approximation of the parallel transport of the input tangent vector.

  • trajectory : A list of length n_steps storing the geodesics of the construction, only if return_geodesics = TRUE in the step function. The geodesics are methods of the class connection.

  • end_point:

Method curvature()

Computes the curvature.

Usage

Connection$curvature(tangent_vec_a, tangent_vec_b, tangent_vec_c, base_point)

Arguments

tangent_vec_a

Tangent vector at base_point.

tangent_vec_b

Tangent vector at base_point.

tangent_vec_c

Tangent vector at base_point.

base_point

A numeric array of shape dim specifying a base point on the manifold.

Details

For three vector fields \(X|_P = \mathrm{tangent\_vec\_a}\), \(Y|_P = \mathrm{tangent\_vec\_b}\), \(Z|_P = \mathrm{tangent\_vec\_c}\) with tangent vector specified in argument at the base point \(P\), the curvature is defined by $$R(X,Y)Z = \nabla_{[X,Y]}Z - \nabla_X\nabla_Y Z + \nabla_Y\nabla_X Z.$$

Returns

Tangent vector at base_point.

Method directional_curvature()

Computes the directional curvature (tidal force operator).

Usage

Connection$directional_curvature(tangent_vec_a, tangent_vec_b, base_point)

Arguments

tangent_vec_a

Tangent vector at base_point.

tangent_vec_b

Tangent vector at base_point.

base_point

A numeric array of shape dim specifying a base point on the manifold.

Details

For two vector fields \(X|_P = \mathrm{tangent\_vec\_a}\) and \(Y|_P = \mathrm{tangent\_vec\_b}\) with tangent vector specified in argument at the base point \(P\), the directional curvature, better known in relativity as the tidal force operator, is defined by $$R_Y(X) = R(Y,X)Y.$$

Returns

Tangent vector at base_point.

Method curvature_derivative()

Computes the covariant derivative of the curvature.

Usage

Connection$curvature_derivative(
  tangent_vec_a,
  tangent_vec_b,
  tangent_vec_c,
  tangent_vec_d,
  base_point = NULL
)

Arguments

tangent_vec_a

Tangent vector at base_point.

tangent_vec_b

Tangent vector at base_point.

tangent_vec_c

Tangent vector at base_point.

tangent_vec_d

Tangent vector at base_point.

base_point

A numeric array of shape dim specifying a base point on the manifold.

Details

For four vector fields \(H|_P = \mathrm{tangent\_vec\_a}\), \(X|_P = \mathrm{tangent\_vec\_b}\), \(Y|_P = \mathrm{tangent\_vec\_c}\), \(Z|_P = \mathrm{tangent\_vec\_d}\) with tangent vector value specified in argument at the base point \(P\), the covariant derivative of the curvature \((\nabla_H R)(X, Y) Z |_P\) is computed at the base point \(P\).

Returns

Tangent vector at base_point.

Method directional_curvature_derivative()

Computes the covariant derivative of the directional curvature.

Usage

Connection$directional_curvature_derivative(
  tangent_vec_a,
  tangent_vec_b,
  base_point = NULL
)

Arguments

tangent_vec_a

Tangent vector at base_point.

tangent_vec_b

Tangent vector at base_point.

base_point

A numeric array of shape dim specifying a base point on the manifold.

Details

For two vector fields \(X|_P = \mathrm{tangent\_vec\_a}\), \(Y|_P = \mathrm{tangent\_vec\_b}\) with tangent vector value specified in argument at the base point \(P\), the covariant derivative (in the direction \(X\)) \((\nabla_X R_Y)(X) |_P = (\nabla_X R)(Y, X) Y |_P\) of the directional curvature (in the direction \(Y\)) \(R_Y(X) = R(Y, X) Y\) is a quadratic tensor in \(X\) and \(Y\) that plays an important role in the computation of the moments of the empirical Fréchet mean (Pennec 2019) .

References

Pennec X (2019). “Curvature effects on the empirical mean in Riemannian and affine Manifolds: a non-asymptotic high concentration expansion in the small-sample regime.” arXiv preprint arXiv:1906.07418.

Returns

Tangent vector at base_point.

Method geodesic()

Generates parametrized function for the geodesic curve.

Usage

Connection$geodesic(
  initial_point,
  end_point = NULL,
  initial_tangent_vec = NULL
)

Arguments

initial_point

Point on the manifold specifying the initial point of the geodesic.

end_point

Point on the manifold specifying the end point of the geodesic. Defaults to NULL, in which case an initial tangent vector must be given.

initial_tangent_vec

Tangent vector at base point specifying the initial speed of the geodesics. Defaults to NULL, in which case an end point must be given and a logarithm is computed.

Details

Geodesic curve defined by either:

  • an initial point and an initial tangent vector,

  • an initial point and an end point.

Returns

A function representing the time-parametrized geodesic curve. If a list of initial conditions is passed, the output list will contain, for each time point, a list with the geodesic values each initial condition.

Method parallel_transport()

Computes the parallel transport of a tangent vector.

Usage

Connection$parallel_transport(
  tangent_vec,
  base_point,
  direction = NULL,
  end_point = NULL
)

Arguments

tangent_vec

A numeric array of shape dim specifying a tangent vector at base_point.

base_point

A numeric array of shape dim specifying a base point on the manifold.

direction

Tangent vector at base point specifying the point along which the parallel transport is computed. Defaults to NULL.

end_point

Point on the manifold specifying the point to transport to. Defaults to NULL.

Details

Closed-form solution for the parallel transport of a tangent vector along the geodesic between two points base_point and end_point or alternatively defined by \(t \mapsto \exp_\mathrm{base_point} (t \mathrm{direction})\).

Returns

Tangent vector transported at \(t \mapsto \exp_\mathrm{base_point} (t \mathrm{direction})\).

Method injectivity_radius()

Computes the radius of the injectivity domain.

Usage

Connection$injectivity_radius(base_point)

Arguments

base_point

A numeric array of shape dim specifying a base point on the manifold.

Details

This is is the supremum of radii r for which the exponential map is a diffeomorphism from the open ball of radius r centered at the base point onto its image.

Returns

A numeric value representing the injectivity radius.

Method clone()

The objects of this class are cloneable with this method.

Usage

Connection$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.