# Vector bundles

Vector bundle $E$ is a manifold that is built on top of another manifold $\mathcal M$ (base space). It is characterized by a continuous function $Π : E → \mathcal M$, such that for each point $p ∈ \mathcal M$ the preimage of $p$ by $Π$, $Π^{-1}(\{p\})$, has a structure of a vector space. These vector spaces are called fibers. Bundle projection can be performed using function `bundle_projection`

.

Tangent bundle is a simple example of a vector bundle, where each fiber is the tangent space at the specified point $x$. An object representing a tangent bundle can be obtained using the constructor called `TangentBundle`

.

Fibers of a vector bundle are represented by the type `VectorBundleFibers`

. The important difference between functions operating on `VectorBundle`

and `VectorBundleFibers`

is that in the first case both a point on the underlying manifold and the vector are represented together (by a single argument) while in the second case only the vector part is present, while the point is supplied in a different argument where needed.

`VectorBundleFibers`

refers to the whole set of fibers of a vector bundle. There is also another type, `VectorSpaceAtPoint`

, that represents a specific fiber at a given point. This distinction is made to reduce the need to repeatedly construct objects of type `VectorSpaceAtPoint`

in certain usage scenarios. This is also considered a manifold.

## FVector

For cases where confusion between different types of vectors is possible, the type `FVector`

can be used to express which type of vector space the vector belongs to. It is used for example in musical isomorphisms (the `flat`

and `sharp`

functions) that are used to go from a tangent space to cotangent space and vice versa.

## Documentation

`ManifoldsBase.TangentSpace`

— Method`TangentSpace(M::AbstractManifold, p)`

Return a `TangentSpaceAtPoint`

representing tangent space at `p`

on the `AbstractManifold`

`M`

.

`Manifolds.CotangentSpaceAtPoint`

— Method`CotangentSpaceAtPoint(M::AbstractManifold, p)`

Return an object of type `VectorSpaceAtPoint`

representing cotangent space at `p`

.

`Manifolds.SasakiRetraction`

— Type`struct SasakiRetraction <: AbstractRetractionMethod end`

Exponential map on `TangentBundle`

computed via Euler integration as described in ^{[Muralidharan2012]}. The system of equations for $\gamma : ℝ \to T\mathcal M$ such that $\gamma(1) = \exp_{p,X}(X_M, X_F)$ and $\gamma(0)=(p, X)$ reads

\[\dot{\gamma}(t) = (\dot{p}(t), \dot{X}(t)) = (R(X(t), \dot{X}(t))\dot{p}(t), 0)\]

where $R$ is the Riemann curvature tensor (see `riemann_tensor`

).

**Constructor**

`SasakiRetraction(L::Int)`

In this constructor `L`

is the number of integration steps.

`Manifolds.TangentBundle`

— Type`TangentBundle{𝔽,M} = VectorBundle{𝔽,TangentSpaceType,M} where {𝔽,M<:AbstractManifold{𝔽}}`

Tangent bundle for manifold of type `M`

, as a manifold with the Sasaki metric ^{[Sasaki1958]}.

Exact retraction and inverse retraction can be approximated using `VectorBundleProductRetraction`

, `VectorBundleInverseProductRetraction`

and `SasakiRetraction`

. `VectorBundleProductVectorTransport`

can be used as a vector transport.

**Constructors**

```
TangentBundle(M::AbstractManifold)
TangentBundle(M::AbstractManifold, vtm::VectorBundleProductVectorTransport)
```

`Manifolds.TangentSpaceAtPoint`

— Type`TangentSpaceAtPoint{M}`

Alias for `VectorSpaceAtPoint`

for the tangent space at a point.

`Manifolds.TangentSpaceAtPoint`

— Method`TangentSpaceAtPoint(M::AbstractManifold, p)`

Return an object of type `VectorSpaceAtPoint`

representing tangent space at `p`

on the `AbstractManifold`

`M`

.

`Manifolds.TensorProductType`

— Type`TensorProductType(spaces::VectorSpaceType...)`

Vector space type corresponding to the tensor product of given vector space types.

`Manifolds.VectorBundle`

— Type`VectorBundle{𝔽,TVS<:VectorSpaceType,TM<:AbstractManifold{𝔽}} <: AbstractManifold{𝔽}`

Vector bundle on a `AbstractManifold`

`M`

of type `VectorSpaceType`

.

**Constructor**

`VectorBundle(M::AbstractManifold, type::VectorSpaceType)`

`Manifolds.VectorBundleFibers`

— Type`VectorBundleFibers(fiber::VectorSpaceType, M::AbstractManifold)`

Type representing a family of vector spaces (fibers) of a vector bundle over `M`

with vector spaces of type `fiber`

. In contrast with `VectorBundle`

, operations on `VectorBundleFibers`

expect point-like and vector-like parts to be passed separately instead of being bundled together. It can be thought of as a representation of vector spaces from a vector bundle but without storing the point at which a vector space is attached (which is specified separately in various functions).

`Manifolds.VectorBundleInverseProductRetraction`

— Type`struct VectorBundleInverseProductRetraction <: AbstractInverseRetractionMethod end`

Inverse retraction of the point `y`

at point `p`

from vector bundle `B`

over manifold `B.fiber`

(denoted $\mathcal M$). The inverse retraction is derived as a product manifold-style approximation to the logarithmic map in the Sasaki metric. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.

Notation:

- The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$. Similarly, $q = (x_q, V_q)$.

The inverse retraction is calculated as

\[\operatorname{retr}^{-1}_p q = (\operatorname{retr}^{-1}_{x_p}(x_q), V_{\operatorname{retr}^{-1}} - V_p)\]

where $V_{\operatorname{retr}^{-1}}$ is the result of vector transport of $V_q$ to the point $x_p$. The difference $V_{\operatorname{retr}^{-1}} - V_p$ corresponds to the logarithmic map in the vector space $F$.

See also `VectorBundleProductRetraction`

.

`Manifolds.VectorBundleProductRetraction`

— Type`struct VectorBundleProductRetraction <: AbstractRetractionMethod end`

Product retraction map of tangent vector $X$ at point $p$ from vector bundle `B`

over manifold `B.fiber`

(denoted $\mathcal M$). The retraction is derived as a product manifold-style approximation to the exponential map in the Sasaki metric. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.

Notation:

- The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
- The tangent vector $X = (V_{X,M}, V_{X,F}) ∈ T_pB$ where $V_{X,M}$ is a tangent vector from the tangent space $T_{x_p}\mathcal M$ and $V_{X,F}$ is a tangent vector from the tangent space $T_{V_p}F$ (isomorphic to $F$).

The retraction is calculated as

\[\operatorname{retr}_p(X) = (\exp_{x_p}(V_{X,M}), V_{\exp})\]

where $V_{\exp}$ is the result of vector transport of $V_p + V_{X,F}$ to the point $\exp_{x_p}(V_{X,M})$. The sum $V_p + V_{X,F}$ corresponds to the exponential map in the vector space $F$.

See also `VectorBundleInverseProductRetraction`

.

`Manifolds.VectorBundleProductVectorTransport`

— Type```
VectorBundleProductVectorTransport{
TMP<:AbstractVectorTransportMethod,
TMV<:AbstractVectorTransportMethod,
} <: AbstractVectorTransportMethod
```

Vector transport type on `VectorBundle`

. `method_point`

is used for vector transport of the point part and `method_vector`

is used for transport of the vector part.

The vector transport is derived as a product manifold-style vector transport. The considered product manifold is the product between the manifold $\mathcal M$ and the topological vector space isometric to the fiber.

**Constructor**

```
VectorBundleProductVectorTransport(
method_point::AbstractVectorTransportMethod,
method_vector::AbstractVectorTransportMethod,
)
VectorBundleProductVectorTransport()
```

By default both methods are set to `ParallelTransport`

.

`Manifolds.VectorBundleVectorTransport`

— Type`const VectorBundleVectorTransport = VectorBundleProductVectorTransport`

Deprecated: an alias for `VectorBundleProductVectorTransport`

.

`Manifolds.VectorSpaceAtPoint`

— Type```
VectorSpaceAtPoint{
𝔽,
TFiber<:VectorBundleFibers{<:VectorSpaceType,<:AbstractManifold{𝔽}},
TX,
} <: AbstractManifold{𝔽}
```

A vector space at a point `p`

on the manifold. This is modelled using `VectorBundleFibers`

with only a vector-like part and fixing the point-like part to be just `p`

.

This vector space itself is also a `manifold`

. Especially, it's flat and hence isometric to the `Euclidean`

manifold.

**Constructor**

`VectorSpaceAtPoint(fiber::VectorBundleFibers, p)`

A vector space (fiber type `fiber`

of a vector bundle) at point `p`

from the manifold `fiber.manifold`

.

`Base.exp`

— Method`exp(M::TangentSpaceAtPoint, p, X)`

Exponential map of tangent vectors `X`

and `p`

from the tangent space `M`

. It is calculated as their sum.

`Base.getindex`

— Method```
getindex(p::ArrayPartition, M::VectorBundle, s::Symbol)
p[M::VectorBundle, s]
```

Access the element(s) at index `s`

of a point `p`

on a `VectorBundle`

`M`

by using the symbols `:point`

and `:vector`

for the base and vector component, respectively.

`Base.getindex`

— Method```
getindex(p::ProductRepr, M::VectorBundle, s::Symbol)
p[M::VectorBundle, s]
```

Access the element(s) at index `s`

of a point `p`

on a `VectorBundle`

`M`

by using the symbols `:point`

and `:vector`

for the base and vector component, respectively.

`Base.log`

— Method`log(M::TangentSpaceAtPoint, p, q)`

Logarithmic map on the tangent space manifold `M`

, calculated as the difference of tangent vectors `q`

and `p`

from `M`

.

`Base.setindex!`

— Method```
setindex!(p::ArrayPartition, val, M::VectorBundle, s::Symbol)
p[M::VectorBundle, s] = val
```

Set the element(s) at index `s`

of a point `p`

on a `VectorBundle`

`M`

to `val`

by using the symbols `:point`

and `:vector`

for the base and vector component, respectively.

The *content* of element of `p`

is replaced, not the element itself.

`Base.setindex!`

— Method```
setindex!(p::ProductRepr, val, M::VectorBundle, s::Symbol)
p[M::VectorBundle, s] = val
```

Set the element(s) at index `s`

of a point `p`

on a `VectorBundle`

`M`

to `val`

by using the symbols `:point`

and `:vector`

for the base and vector component, respectively.

The *content* of element of `p`

is replaced, not the element itself.

`LinearAlgebra.norm`

— Method`norm(B::VectorBundleFibers, p, q)`

Norm of the vector `X`

from the vector space of type `B.fiber`

at point `p`

from manifold `B.manifold`

.

`Manifolds.bundle_projection`

— Method`bundle_projection(B::VectorBundle, x::ProductRepr)`

Projection of point `p`

from the bundle `M`

to the base manifold. Returns the point on the base manifold `B.manifold`

at which the vector part of `p`

is attached.

`Manifolds.inverse_retract_product`

— Method`inverse_retract_product(M::VectorBundle, p, q)`

Compute the allocating variant of the `VectorBundleInverseProductRetraction`

, which by default allocates and calls `inverse_retract_product!`

.

`Manifolds.retract_product`

— Method`retract_product(M::VectorBundle, p, q)`

Compute the allocating variant of the `VectorBundleProductRetraction`

, which by default allocates and calls `retract_product!`

.

`Manifolds.retract_sasaki`

— Method`retract_sasaki(M::AbstractManifold, p, q, m::SasakiRetraction)`

Compute the allocating variant of the `SasakiRetraction`

, which by default allocates and calls `retract_sasaki!`

.

`Manifolds.vector_bundle_transport`

— Method`vector_bundle_transport(fiber::VectorSpaceType, M::AbstractManifold)`

Determine the vector tranport used for `exp`

and `log`

maps on a vector bundle with vector space type `fiber`

and manifold `M`

.

`ManifoldsBase.allocate_result`

— Method`allocate_result(B::VectorBundleFibers, f, x...)`

Allocates an array for the result of function `f`

that is an element of the vector space of type `B.fiber`

on manifold `B.manifold`

and arguments `x...`

for implementing the non-modifying operation using the modifying operation.

`ManifoldsBase.allocate_result_type`

— Method`allocate_result_type(B::VectorBundleFibers, f, args::NTuple{N,Any}) where N`

Return type of element of the array that will represent the result of function `f`

for representing an operation with result in the vector space `fiber`

for manifold `M`

on given arguments (passed at a tuple).

`ManifoldsBase.distance`

— Method`distance(M::TangentSpaceAtPoint, p, q)`

Distance between vectors `p`

and `q`

from the vector space `M`

. It is calculated as the norm of their difference.

`ManifoldsBase.distance`

— Method`distance(B::VectorBundleFibers, p, X, Y)`

Distance between vectors `X`

and `Y`

from the vector space at point `p`

from the manifold `B.manifold`

, that is the base manifold of `M`

.

`ManifoldsBase.injectivity_radius`

— Method`injectivity_radius(M::TangentBundle)`

Injectivity radius of `TangentBundle`

manifold is infinite if the base manifold is flat and 0 otherwise. See https://mathoverflow.net/questions/94322/injectivity-radius-of-the-sasaki-metric.

`ManifoldsBase.injectivity_radius`

— Method`injectivity_radius(M::TangentSpaceAtPoint)`

Return the injectivity radius on the `TangentSpaceAtPoint`

`M`

, which is $∞$.

`ManifoldsBase.inner`

— Method`inner(M::TangentSpaceAtPoint, p, X, Y)`

Inner product of vectors `X`

and `Y`

from the tangent space at `M`

.

`ManifoldsBase.inner`

— Method`inner(B::VectorBundle, p, X, Y)`

Inner product of tangent vectors `X`

and `Y`

at point `p`

from the vector bundle `B`

over manifold `B.fiber`

(denoted $\mathcal M$).

Notation:

- The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
- The tangent vector $v = (V_{X,M}, V_{X,F}) ∈ T_{x}B$ where $V_{X,M}$ is a tangent vector from the tangent space $T_{x_p}\mathcal M$ and $V_{X,F}$ is a tangent vector from the tangent space $T_{V_p}F$ (isomorphic to $F$). Similarly for the other tangent vector $w = (V_{Y,M}, V_{Y,F}) ∈ T_{x}B$.

The inner product is calculated as

\[⟨X, Y⟩_p = ⟨V_{X,M}, V_{Y,M}⟩_{x_p} + ⟨V_{X,F}, V_{Y,F}⟩_{V_p}.\]

`ManifoldsBase.inner`

— Method`inner(B::VectorBundleFibers, p, X, Y)`

Inner product of vectors `X`

and `Y`

from the vector space of type `B.fiber`

at point `p`

from manifold `B.manifold`

.

`ManifoldsBase.is_flat`

— Method`is_flat(::TangentSpaceAtPoint)`

Return true. `TangentSpaceAtPoint`

is a flat manifold.

`ManifoldsBase.is_flat`

— Method`is_flat(::VectorBundle)`

Return true if the underlying manifold of `VectorBundle`

`M`

is flat.

`ManifoldsBase.project`

— Method`project(M::TangentSpaceAtPoint, p, X)`

Project the vector `X`

from the tangent space `M`

, that is project the vector `X`

tangent at `M.point`

.

`ManifoldsBase.project`

— Method`project(M::TangentSpaceAtPoint, p)`

Project the point `p`

from the tangent space `M`

, that is project the vector `p`

tangent at `M.point`

.

`ManifoldsBase.project`

— Method`project(B::VectorBundle, p, X)`

Project the element `X`

of the ambient space of the tangent space $T_p B$ to the tangent space $T_p B$.

Notation:

- The point $p = (x_p, V_p)$ where $x_p ∈ \mathcal M$ and $V_p$ belongs to the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.
- The vector $x = (V_{X,M}, V_{X,F})$ where $x_p$ belongs to the ambient space of $T_{x_p}\mathcal M$ and $V_{X,F}$ belongs to the ambient space of the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.

The projection is calculated by projecting $V_{X,M}$ to tangent space $T_{x_p}\mathcal M$ and then projecting the vector $V_{X,F}$ to the fiber $F$.

`ManifoldsBase.project`

— Method`project(B::VectorBundle, p)`

Project the point `p`

from the ambient space of the vector bundle `B`

over manifold `B.fiber`

(denoted $\mathcal M$) to the vector bundle.

Notation:

- The point $p = (x_p, V_p)$ where $x_p$ belongs to the ambient space of $\mathcal M$ and $V_p$ belongs to the ambient space of the fiber $F=π^{-1}(\{x_p\})$ of the vector bundle $B$ where $π$ is the canonical projection of that vector bundle $B$.

The projection is calculated by projecting the point $x_p$ to the manifold $\mathcal M$ and then projecting the vector $V_p$ to the tangent space $T_{x_p}\mathcal M$.

`ManifoldsBase.project`

— Method`project(B::VectorBundleFibers, p, X)`

Project vector `X`

from the vector space of type `B.fiber`

at point `p`

.

`ManifoldsBase.vector_transport_to`

— Method`vector_transport_to(M::VectorBundle, p, X, q, m::VectorBundleProductVectorTransport)`

Compute the vector transport the tangent vector `X`

at `p`

to `q`

on the `VectorBundle`

`M`

using the `VectorBundleProductVectorTransport`

`m`

.

`ManifoldsBase.zero_vector!`

— Method`zero_vector!(B::VectorBundleFibers, X, p)`

Save the zero vector from the vector space of type `B.fiber`

at point `p`

from manifold `B.manifold`

to `X`

.

`ManifoldsBase.zero_vector`

— Method`zero_vector(M::TangentSpaceAtPoint, p)`

Zero tangent vector at point `p`

from the tangent space `M`

, that is the zero tangent vector at point `M.point`

.

`ManifoldsBase.zero_vector`

— Method`zero_vector(B::VectorBundle, p)`

Zero tangent vector at point `p`

from the vector bundle `B`

over manifold `B.fiber`

(denoted $\mathcal M$). The zero vector belongs to the space $T_{p}B$

Notation:

The zero vector is calculated as

\[\mathbf{0}_{p} = (\mathbf{0}_{x_p}, \mathbf{0}_F)\]

where $\mathbf{0}_{x_p}$ is the zero tangent vector from $T_{x_p}\mathcal M$ and $\mathbf{0}_F$ is the zero element of the vector space $F$.

`ManifoldsBase.zero_vector`

— Method`zero_vector(B::VectorBundleFibers, p)`

Compute the zero vector from the vector space of type `B.fiber`

at point `p`

from manifold `B.manifold`

.

## Example

The following code defines a point on the tangent bundle of the sphere $S^2$ and a tangent vector to that point.

```
using Manifolds
M = Sphere(2)
TB = TangentBundle(M)
p = ProductRepr([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])
X = ProductRepr([0.0, 1.0, 0.0], [0.0, 0.0, -2.0])
```

```
ProductRepr with 2 submanifold components:
Component 1 =
3-element Vector{Float64}:
0.0
1.0
0.0
Component 2 =
3-element Vector{Float64}:
0.0
0.0
-2.0
```

An approximation of the exponential in the Sasaki metric using 1000 steps can be calculated as follows.

```
q = retract(TB, p, X, SasakiRetraction(1000))
println("Approximation of the exponential map: ", q)
```

`Approximation of the exponential map: ProductRepr{Tuple{Vector{Float64}, Vector{Float64}}}(([0.6759570857309881, 0.352414864043865, 0.6472138609849256], [-1.031826958326108, 0.6273324630574114, 0.7360618920075952]))`

- Muralidharan2012
P. Muralidharan and P. T. Fletcher, “Sasaki Metrics for Analysis of Longitudinal Data on Manifolds,” Proc IEEE Comput Soc Conf Comput Vis Pattern Recognit, vol. 2012, pp. 1027–1034, Jun. 2012, doi: 10.1109/CVPR.2012.6247780.

- Sasaki1958
S. Sasaki, “On the differential geometry of tangent bundles of Riemannian manifolds,” Tohoku Math. J. (2), vol. 10, no. 3, pp. 338–354, 1958, doi: 10.2748/tmj/1178244668.