# 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.

## Example

The following code defines two points on a tangent bundle of the sphere $S^2$ and calculates distance between them, distance between their base points and norm of one of these tangent vectors.

```
using Manifolds
M = Sphere(2)
TB = TangentBundle(M)
p = ProductRepr([1.0, 0.0, 0.0], [0.0, 1.0, 3.0])
q = ProductRepr([0.0, 1.0, 0.0], [2.0, 0.0, -1.0])
println("Distance between p and q: ", distance(TB, p, q))
println("Distance between base points of p and q: ", distance(M, p[TB, :point], q[TB, :point]))
println("Norm of p: ", norm(M, p[TB, :point], p[TB, :vector]))
```

Distance between p and q: 5.240935136048942 Distance between base points of p and q: 1.5707963267948966 Norm of p: 3.1622776601683795

`Manifolds.CotangentSpaceAtPoint`

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

Return an object of type `VectorSpaceAtPoint`

representing cotangent space at `p`

.

`Manifolds.FVector`

— Type`FVector(type::VectorSpaceType, data)`

Decorator indicating that the vector `data`

is from a fiber of a vector bundle of type `type`

.

`Manifolds.TangentSpaceAtPoint`

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

Return an object of type `VectorSpaceAtPoint`

representing tangent space at `p`

on the `Manifold`

`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<:Manifold{𝔽}} <: Manifold{𝔽}`

Vector bundle on a `Manifold`

`M`

of type `VectorSpaceType`

.

**Constructor**

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

`Manifolds.VectorBundleFibers`

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

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.VectorBundleVectorTransport`

— Type```
VectorBundleVectorTransport(
method_point::AbstractVectorTransportMethod,
method_vector::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

`Manifolds.VectorSpaceAtPoint`

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

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`

.

`Manifolds.VectorSpaceType`

— Type`VectorSpaceType`

Abstract type for tangent spaces, cotangent spaces, their tensor products, exterior products, etc.

Every vector space `fiber`

is supposed to provide:

- a method of constructing vectors,
- basic operations: addition, subtraction, multiplication by a scalar and negation (unary minus),
`zero_vector!(fiber, X, p)`

to construct zero vectors at point`p`

,`allocate(X)`

and`allocate(X, T)`

for vector`X`

and type`T`

,`copyto!(X, Y)`

for vectors`X`

and`Y`

,`number_eltype(v)`

for vector`v`

,`vector_space_dimension(::VectorBundleFibers{<:typeof(fiber)}) where fiber`

.

Optionally:

- inner product via
`inner`

(used to provide Riemannian metric on vector bundles), `flat`

and`sharp`

,`norm`

(by default uses`inner`

),`project`

(for embedded vector spaces),`representation_size`

(if support for`ProductArray`

is desired),- broadcasting for basic operations.

`Base.exp`

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

Exponential map of tangent vector $X$ at point $p$ from 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 $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 exponential map is calculated as

\[\exp_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$.

`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::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(B::VectorBundle, p, q)`

Logarithmic map of the point `y`

at point `p`

from 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$. Similarly, $q = (x_q, V_q)$.

The logarithmic map is calculated as

\[\log_p q = (\log_{x_p}(x_q), V_{\log} - V_p)\]

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

`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::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.flat`

— Method`flat(M::Manifold, p, X::FVector)`

Compute the flat isomorphism (one of the musical isomorphisms) of tangent vector `X`

from the vector space of type `M`

at point `p`

from the underlying `Manifold`

.

The function can be used for example to transform vectors from the tangent bundle to vectors from the cotangent bundle $♭ : T\mathcal M → T^{*}\mathcal M$

`Manifolds.sharp`

— Method`sharp(M::Manifold, p, ξ::FVector)`

Compute the sharp isomorphism (one of the musical isomorphisms) of vector `ξ`

from the vector space `M`

at point `p`

from the underlying `Manifold`

.

The function can be used for example to transform vectors from the cotangent bundle to vectors from the tangent bundle $♯ : T^{*}\mathcal M → T\mathcal M$

`Manifolds.vector_bundle_transport`

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

Determine the vector tranport used for `exp`

and `log`

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

and manifold `M`

.

`Manifolds.vector_space_dimension`

— Method`vector_space_dimension(B::VectorBundleFibers)`

Dimension of the vector space of type `B`

.

`Manifolds.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`

.

`Manifolds.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`

.

`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`

Returns 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(B::VectorBundle, p, q)`

Distance between points $x$ and $y$ 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$. Similarly, $q = (x_q, V_q)$.

The distance is calculated as

\[d_B(x, y) = \sqrt{d_M(x_p, x_q)^2 + d_F(V_p, V_{q←p})^2}\]

where $d_\mathcal M$ is the distance on manifold $\mathcal M$, $d_F$ is the distance between two vectors from the fiber $F$ and $V_{q←p}$ is the result of parallel transport of vector $V_q$ to point $x_p$. The default behavior of `vector_transport_to`

is used to compute the vector transport.

`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.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.injectivity_radius`

— Method`injectivity_radius(M::TangentSpaceAtPoint)`

Return the injectivity radius on the `TangentSpaceAtPoint`

`M`

, which is $∞$.

`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.inner`

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

Inner product of vectors `X`

and `Y`

from the tangent space at `M`

.

`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.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.vector_transport_to`

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

Compute the vector transport the tangent vector `X`

at `p`

to `q`

on the `VectorBundle`

`M`

using the `VectorBundleVectorTransport`

`m`

.

`ManifoldsBase.zero_tangent_vector`

— Method`zero_tangent_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_tangent_vector`

— Method`zero_tangent_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`

.