Internal documentation

eigen_safe(x)

Compute the eigendecomposition of x. If x is a StaticMatrix, it is converted to a Matrix before the decomposition.

estimated_sectional_curvature(M::AbstractManifold, p, X, Y; r::Real=1e-3, N::Int=10000)

Approximate sectional curvature of manifold M in the plane spanned by vectors X and Y from tangent space at p using a circle on M of radius r divided into N segments.

The approximation is derived from the Bertrand–Diguet–Puiseux theorem which states that

\[\kappa_p(X, Y) = \lim_{r \to 0^+} 3\frac{2\pi r-C(r)}{\pi r^3},\]

where $C(r)$ is the circumference of the circle of radius $r$ around p in submanifold of M spanned by X and Y. The circumference calculation method has a tendency to return curvature values larger than the exact ones.

estimated_sectional_curvature_matrix(M::AbstractManifold, p, B::AbstractBasis; r::Real=1e-3, N::Int=10000)

Estimate the matrix of sectional curvatures of manifold M at point p using estimated_sectional_curvature. Entry (i, j)corresponds to sectional curvature of the surface spanned by vectorsiandjfrom basisB`.

get_parameter_type(M::AbstractManifold)

Get parameter argument of the constructor of manifold M. Returns either :field or :type.

See also

get_parameter, TypeParameter

isnormal(x; kwargs...) -> Bool

Check if the matrix or number x is normal, that is, if it commutes with its adjoint:

\[x x^\mathrm{H} = x^\mathrm{H} x.\]

By default, this is an equality check. Provide kwargs for isapprox to perform an approximate check.

log_safe(x)

Compute the matrix logarithm of x. If x is a StaticMatrix, it is converted to a Matrix before computing the log.

log_safe!(y, x)

Compute the matrix logarithm of x. If the eltype of y is real, then the imaginary part of x is ignored, and a DomainError is raised if real(x) has no real logarithm.

mul!_safe(Y, A, B) -> Y

Call mul! safely, that is, A and/or B are permitted to alias with Y.

normal_tvector_distribution(M::AbstractManifold, p, σ)

Normal distribution in ambient space with standard deviation σ projected to tangent space at p.

nzsign(z[, absz])

Compute a modified sign(z) that is always nonzero, i.e. where

\[\operatorname(nzsign)(z) = \begin{cases} 1 & \text{if } z = 0\\ \frac{z}{|z|} & \text{otherwise} \end{cases}\]

Note that the condition absz == 0 would be incorrectly handled by ForwardDiff.jl.

projected_distribution(M::AbstractManifold, d, [p=rand(d)])

Wrap the standard distribution d into a manifold-valued distribution. Generated points will be of similar type to p. By default, the type is not changed.

realify(X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers) -> Y::AbstractMatrix{<:Real}

Given a matrix $X ∈ 𝔽^{n×n}$, compute $Y ∈ ℝ^{m×m}$, where $m = n \operatorname{dim}_𝔽$, and $\operatorname{dim}_𝔽$ is the real_dimension of the number field $𝔽$, using the map $ϕ \colon X ↦ Y$, that preserves the matrix product, so that for all $C,D ∈ 𝔽^{n×n}$,

\[ϕ(C) ϕ(D) = ϕ(CD).\]

See realify! for an in-place version, and unrealify! to compute the inverse of $ϕ$.

realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{T𝔽}, 𝔽::AbstractNumbers)

In-place version of realify.

realify!(Y::AbstractMatrix{<:Real}, X::AbstractMatrix{<:Complex}, ::typeof(ℂ))

Given a complex matrix $X = A + iB ∈ ℂ^{n×n}$, compute its realified matrix $Y ∈ ℝ^{2n×2n}$, written where

\[Y = \begin{pmatrix}A & -B \\ B & A \end{pmatrix}.\]

symmetrize(X)

Given a square matrix X compute 1/2 .* (X' + X).

symmetrize!(Y, X)

Given a square matrix X compute 1/2 .* (X' + X) in place of Y.

unrealify!(X::AbstractMatrix{T𝔽}, Y::AbstractMatrix{<:Real}, 𝔽::AbstractNumbers[, n])

Given a real matrix $Y ∈ ℝ^{m×m}$, where $m = n \operatorname{dim}_𝔽$, and $\operatorname{dim}_𝔽$ is the real_dimension of the number field $𝔽$, compute in-place its equivalent matrix $X ∈ 𝔽^{n×n}$. Note that this function does not check that $Y$ has a valid structure to be un-realified.

See realify! for the inverse of this function.

usinc(θ::Real)

Unnormalized version of sinc function, i.e. $\operatorname{usinc}(θ) = \frac{\sin(θ)}{θ}$. This is equivalent to sinc(θ/π).

Note that ForwardDiff.jl would return wrong answer at θ=0 if a simple equality was used.

usinc_from_cos(x::Real)

Unnormalized version of sinc function, i.e. $\operatorname{usinc}(θ) = \frac{\sin(θ)}{θ}$, computed from $x = cos(θ)$.

vec2skew!(X, v, k)

Create a skew symmetric matrix in-place in X of size $k×k$ from a vector v, for example for v=[1,2,3] and k=3 this yields

[  0  1  2;  -1  0  3;  -2 -3  0]

(int_term::IntegratorTerminatorNearChartBoundary)(u, t, integrator)

Terminate integration when integrator goes too closely to chart boundary. Closeness is determined by ϵ value of IntegratorTerminatorNearChartBoundary int_term.

Arguments:

• int_term: object containing keyword arguments for check_chart_switch, such as the desired maximum distance to boundary,
• u: parameters of a point at which the integrator is solving a differential equation.
• t: time parameter of the integrator
• integrator: state of the integrator. Internal parameters are expected to contained the manifold on which the equation is solved, the atlas and the current chart index.

StitchedChartSolution{Prob,TM<:AbstractManifold,TA<:AbstractAtlas,TChart}

Solution of an ODE on a manifold M in charts of an AbstractAtlas A.

When StitchedChartSolution{:Exp} is used as a function with a number t as an argument, a pair (p, X) is returned such that $p\in \mathcal{M}$ is the point at time t of the geodesic and $X \in T_p \mathcal{M}$ is the velocity of the geodesic at that point. Similarly, StitchedChartSolution{:PT} called with number t returns a triple (p, X, Y) where (p, X) corresponds to the geodesic along which the vector is transported and $Y\in T_p\mathcal{M}$ is the vector transported to p.

_adjoint_coordinate_map(M::AbstractManifold, A::AbstractAtlas,
    i_from, a_from, L, i_to, a_to, Yc)

Apply the Riemannian adjoint of a linear map represented in chart-induced bases. If L represents a map from the tangent space at the point with coordinates a_from in chart i_from to the tangent space at the point with coordinates a_to in chart i_to, this function returns the coordinates of its adjoint applied to Yc. The adjoint is computed using the local metric matrices as

\[L^* = G_{\mathrm{from}}^{-1}L^\mathsf{T}G_{\mathrm{to}}.\]

_jacobi_exp_matrix(M::AbstractManifold, a, Xc, A::AbstractAtlas, i0; kwargs...)

Solve the chart-coordinate geodesic and a matrix-valued Jacobi equation to compute the coordinate matrix of the differential of the exponential map with respect to either its argument (if wrt is set to :argument) or its basepoint (if wrt is set to :basepoint).

The geodesic coordinates satisfy

\[\dot a^k = X^k, \qquad \dot X^k = -\Gamma^k_{ij}(a)X^iX^j.\]

For the matrices $Y$ and $dY$, whose columns are Jacobi fields and their covariant derivatives, respectively, the system is

\[\begin{aligned} \dot Y^k{}_r &= dY^k{}_r - \Gamma^k_{ij}(a)X^iY^j{}_r, \\ \dot{dY}^k{}_r &= -\Gamma^k_{ij}(a)X^i dY^j{}_r - R^k_{\ell ij}(a)Y^\ell{}_rX^iX^j. \end{aligned}\]

The initial conditions are $a(0) = a$, $X(0)$ is set to Xc. If the keyword argument wrt is set to :basepoint, then $Y(0)$ is set to 0, and $dY(0) = I$. If the keyword argument wrt is set to :argument, then $Y(0) = I$, and $dY(0) = 0$. Thus, the returned matrix $Y(1)$ represents $D_X\exp_p(X)$ in the chart-induced bases if wrt is set to :argument and $D_p\exp_p(X)$ if wrt is set to :basepoint. The function also returns the final chart index and the final point coordinates.

solve_chart_adjoint_differential_exp_argument(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Compute the chart coordinates at the base point of the adjoint of $D_X\exp_p(X)$ applied to Yc. Here Yc contains coordinates in the induced basis of the final chart reached by the geodesic. p is the point with coordinates a in chart i0. X is the tangent vector with coordinates Xc in the induced basis of chart i0 at p.

solve_chart_adjoint_differential_exp_basepoint(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Compute the chart coordinates at the base point of the adjoint of $D_p\exp_p(X)$ applied to Yc. Here Yc contains coordinates in the induced basis of the final chart reached by the geodesic. p is the point with coordinates a in chart i0. X is the tangent vector with coordinates Xc in the induced basis of chart i0 at p.

solve_chart_adjoint_differential_log_argument(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Compute the chart coordinates at q = exp_p(X) of the adjoint of $D_q\log_p(q)$ applied to Yc. The input uses the induced basis of the initial chart; the output uses that of the final chart reached by the geodesic. p is the point with coordinates a in chart i0. X is the tangent vector with coordinates Xc in the induced basis of chart i0 at p.

solve_chart_adjoint_differential_log_basepoint(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Compute the chart coordinates at the base point of the adjoint of $D_p\log_p(q)$, where $q = \exp_p(X)$. Both the input and output use the induced basis of the initial chart. p is the point with coordinates a in chart i0. X is the tangent vector with coordinates Xc in the induced basis of chart i0 at p.

solve_chart_differential_exp_argument(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Solve the Jacobi equation for $D_X\exp_p(X)[Y]$. The coordinate vectors Xc and Yc are represented in the chart-induced basis at p.

solve_chart_differential_exp_basepoint(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Solve the Jacobi equation for $D_p\exp_p(X)[Y]$. The coordinate vectors Xc and Yc are represented in the chart-induced basis at p.

The ODE is solved by solve_chart_jacobi_field with dYc set to 0.

solve_chart_differential_log_argument(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Solve the Jacobi equation for $D_q\log_p(q)[Y]$, where $q = \exp_p(X)$. The coordinate vector Yc is represented in the chart-induced basis at q; the differential is the covariant derivative in solution(0)[4].

solve_chart_differential_log_basepoint(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc; kwargs...
)

Solve the Jacobi equation for $D_p\log_p(q)[Y]$, where $q = \exp_p(X)$. The coordinate vector Yc is represented in the chart-induced basis at p; the differential is the covariant derivative in solution(0)[4].

solve_chart_exp_ode(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0;
    solver=AutoVern9(Rodas5P()),
    final_time::Real=1.0,
    check_chart_switch_kwargs=NamedTuple(),
    kwargs...,
)

Solve geodesic ODE on a manifold M from point of coordinates a in chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis. The geodesic is solved up to time final_time (by default equal to 1).

Chart switching

If the solution exceeds the domain of chart i0 (which is detected using the check_chart_switch function with additional keyword arguments check_chart_switch_kwargs), a new chart is selected using get_chart_index on the final point in the old chart.

Returned value

The function returns an object of type StitchedChartSolution{:Exp} to represent the geodesic.

solve_chart_jacobi_field(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc, dYc;
    solver=AutoVern9(Rodas5P()), final_time::Real = 1.0,
    check_chart_switch_kwargs = NamedTuple(), kwargs...
)

Solve the Jacobi equation along the geodesic starting at parameters a in chart i0 with initial velocity coordinates Xc. Yc and dYc are, respectively, the coordinates of the initial Jacobi field and its initial covariant derivative in the induced basis of the chart.

In chart coordinates, this solves the system

\[\begin{aligned} \dot a^k &= X^k, & \dot X^k &= -\Gamma^k_{ij}(a)X^iX^j, \\ \dot Y^k &= dY^k - \Gamma^k_{ij}(a)X^iY^j, & \dot{dY}^k &= -\Gamma^k_{ij}(a)X^i dY^j - R^k_{\ell ij}(a)Y^\ell X^iX^j, \end{aligned}\]

with initial conditions $a(0) = a$, $X(0)$ is equal to Xc, $Y(0)$ is equal to Yc, and $dY(0) = dYc$. Here, dY represents the coordinates of $\nabla_{\dot\gamma}Y$. $\Gamma^k_{ij}$ are the Christoffel symbols of the affine connection calculated using the mutating variant of affine_connection and $R^k_{\ell ij}$ are the components of the Riemann curvature tensor calculated using the mutating variant of riemann_tensor.

The returned StitchedChartSolution{:Jacobi} returns (p, X, Y, dY) at time t, where p is the point on the geodesic, X its velocity, Y the Jacobi field, and dY its covariant derivative.

solve_chart_parallel_transport_ode(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0, Yc;
    solver=AutoVern9(Rodas5P()), check_chart_switch_kwargs=NamedTuple(), final_time::Real=1.0,
    kwargs...
)

Parallel transport vector with coordinates Yc along geodesic on a manifold M from point of coordinates a in a chart i0 from an AbstractAtlas A in direction of coordinates Xc in the induced basis.

solve_chart_volume_density(
    M::AbstractManifold, a, Xc, A::AbstractAtlas, i0; kwargs...
)

Compute the volume density of the exponential map in chart coordinates. The coordinates a and Xc are represented in the induced basis of chart i0 from atlas A.