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.

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.

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.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.VectorSpaceAtPoint — Type

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

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.CotangentSpaceAtPoint — Method

CotangentSpaceAtPoint(M::Manifold, p)

Return an object of type VectorSpaceAtPoint representing cotangent space at p.

Manifolds.TangentSpaceAtPoint — Method

TangentSpaceAtPoint(M::Manifold, p)

Return an object of type VectorSpaceAtPoint representing tangent space at p.

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_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.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.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.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.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 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 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$.

Manifolds.TensorProductType — Type

TensorProductType(spaces::VectorSpaceType...)

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

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