Numerical Verification

ManifoldsBase.check_geodesic — Function

check_geodesic(
    M::AbstractManifold,
    p=rand(M),
    X=rand(M; vector_at=p);
    #
    tol::Real = 1e-12,
    io::Union{IO,Nothing} = nothing,
    N::Int = 101,
    name::String = "geodesic",
    plot::Bool = false,
    error::Symbol = :none,
    inverse_retraction_method::AbstractInverseRetractionMethod = LogarithmicInverseRetraction(),
    vector_transport_method::AbstractVectorTransportMethod = ParallelTransport(),
)

Numerically check whether the geodesic implementation is correct. This check requires both the log and parallel_transport_to functions to be implemented in order to get an exact numerical verification. We further require the norm function to be implemented for the AbstractManifold M.

You can provide an inverse_retraction_method and vector_transport_method to be used, but the verification will then be less accurate.

The tests performed are the following based on sampling the geodesic $\gamma(t) =$geodesic(M, p, X) at N equidistant points $t_i = i/(N-1)$, i=0,...,N-1 we denote by $p_i = \gamma(t_i)$

Compute the norms of the tangent vectors $\dot\gamma(t_i) ≈ X_i = \log_{p_i}(p_{i+1})$, $i=0,...,N-2$ and check how far these norms deviate from their mean value.
Check how far this mean deviates from being $\frac{||X||}{N-1}$
Check that the parallel transport of each $X_{i+1}$ from $p_{i+1}$ to $p_i$ is close to $X_i$, both in norm and in the angle the two enclose.

Arguments

M: the manifold to check
p: point on the manifold to start the geodesic, a random point is used by default
X: tangent vector at p to start the geodesic, a random tangent vector is used by default

Keyword arguments

tol: if all errors are below this tolerance, the geodesic is considered to be exact
io: provide an IO to print the result to
N: number of points to sample the geodesic on $[0,1]$ (default: 101)
plot: whether to plot the result (see plot_check_geodesic)
error: specify how to report errors: :none, :info, :warn, or :error are available
inverse_retraction_method: method to use for the inverse retraction, it is recommended to use LogarithmicInverseRetraction
name: name to display in the plot and in the reported messages
vector_transport_method: method to use for the vector transport, it is recommended to use ParallelTransport

Note that since the plot yields more information than throwing an error, when both are specified, the plot is generated first and returned (to be shown/displayed), such that no error is thrown. You can switch to e.g. :warn to get a warning together with the plot.

source

ManifoldsBase.check_inverse_retraction — Function

check_inverse_retraction(
    M::AbstractManifold,
    inverse_retraction_method::AbstractInverseRetractionMethod,
    p=rand(M),
    X=rand(M; vector_at=p);
    #
    exactness_tol::Real = 1e-12,
    io::Union{IO,Nothing} = nothing,
    limits::Tuple = (-8.0, 0.0),
    log_range::AbstractVector = range(limits[1], limits[2]; length=N),
    N::Int = 101,
    name::String = second_order ? "second order inverse retraction" : "inverse retraction",
    plot::Bool = false,
    second_order::Bool = true,
    slope_tol::Real = 0.1,
    error::Symbol = :none,
    window = nothing,
)

Check numerically whether the inverse retraction inverse_retraction_method is correct. This requires the exp and norm functions to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated.

Keyword arguments

exactness_tol: if all errors are below this tolerance, the inverse retraction is considered to be exact
io: provide an IO to print the result to
limits: specify the limits in the log_range, that is the exponent for the range
log_range: specify the range of points (in log scale) to sample the length of the tangent vector X
N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
name: name to display in the plot
plot: whether to plot the result (see plot_slope) The plot is in log-log-scale. This is returned and can then also be saved.
second_order: check whether the inverse retraction is of second order. if set to false, first order is checked.
slope_tol: tolerance for the slope (global) of the approximation
error: specify how to report errors: :none, :info, :warn, or :error are available
window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:n, where n is the number of samples with error above exactness_tol.

source

ManifoldsBase.check_retraction — Function

check_retraction(
    M::AbstractManifold, retraction_method::AbstractRetractionMethod,
    p=rand(M), X=rand(M; vector_at=p);
    #
    exactness_tol::Real = 1e-12,
    io::Union{IO,Nothing} = nothing,
    limits::Tuple = (-8.0, 0.0),
    log_range::AbstractVector = range(limits[1], limits[2]; length=N),
    N::Int = 101,
    name::String = second_order ? "second order retraction" : "retraction",
    plot::Bool = false,
    second_order::Bool = true,
    slope_tol::Real = 0.1,
    error::Symbol = :none,
    window = nothing,
)

Check numerically whether the retraction is correct. This is done by comparing the points $\operatorname{retr}_p(t_i X)$ to $\exp_p(t_i X)$ in the distance on M, where $t_i$ takes all values from exp10.(log_range).

This requires the exp, retract, distance and norm functions to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated.

Keyword arguments

exactness_tol: if all errors are below this tolerance, the retraction is considered to be exact
io: provide an IO to print the result to
limits: specify the limits in the log_range, that is the exponent for the range
log_range: specify the range of points (in log scale) to sample the length of the tangent vector X
N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
name: name to display in the plot
plot: whether to plot the result (see plot_slope) The plot is in log-log-scale. This is returned and can then also be saved.
second_order: check whether the retraction is of second order. if set to false, first order is checked.
slope_tol: tolerance for the slope (global) of the approximation
error: specify how to report errors: :none, :info, :warn, or :error are available
window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:n, where n is the number of samples with error above exactness_tol.

source

ManifoldsBase.check_vector_transport — Function

check_vector_transport(
    M::AbstractManifold, vector_transport_method::AbstractVectorTransportMethod,
    p=rand(M), X=rand(M; vector_at=p), Y=rand(M; vector_at=p);
    #
    error::Symbol = :none,
    exactness_tol::Real = 1e-12,
    io::Union{IO,Nothing} = nothing,
    limits::Tuple = (-8.0, 0.0),
    log_range::AbstractVector = range(limits[1], limits[2]; length=N),
    N::Int = 101,
    name::String = second_order ? "second order vector transport" : "vector transport",
    plot::Bool = false,
    second_order::Bool = true,
    slope_tol::Real = 0.1,
    window = nothing,
)

Check numerically whether the vector transport is correct. This is done by selecting a set of points $q_i = \exp_p (t_i X)$ where $t$ takes all values from log_range, to then compare parallel_transport_to to the vector_transport_method applied to the vector Y.

This requires the exp, parallel_transport_to and norm function to be implemented for the AbstractManifold M.

This implements a method similar to [Bou23, Section 4.8 or Section 6.8].

Note that if the errors are below the given tolerance and the method is exact, no plot is generated.

Keyword arguments

exactness_tol: if all errors are below this tolerance, the vector transport is considered to be exact
io: provide an IO to print the result to
limits: specify the limits in the log_range, that is the exponent for the range
log_range: specify the range of points (in log scale) to sample the length of the tangent vector X
N: number of points to verify within the log_range default range $[10^{-8},10^{0}]$
name: name to display in the plot
plot: whether to plot the result (see plot_slope) The plot is in log-log-scale. This is returned and can then also be saved.
second_order: check whether the vector transport is of second order. if set to false, first order is checked.
slope_tol: tolerance for the slope (global) of the approximation
error: specify how to report errors: :none, :info, :warn, or :error are available
window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:n, where n is the number of samples with error above exactness_tol.

source

Internal functions

The following functions split the check into several parts, for example looking for the best fitting window and finding out the best slope, or plotting the slope.

ManifoldsBase.find_best_slope_window — Function

(a, b, i, j) = find_best_slope_window(X, Y, window=nothing; slope::Real=2.0, slope_tol::Real=0.1)

Check data X,Y for the largest contiguous interval (window) with a regression line fitting “best”. Among all intervals with a slope within slope_tol to slope the longest one is taken. If no such interval exists, the one with the slope closest to slope is taken.

If the window is set to nothing (default), all window sizes 2,...,length(X) are checked. You can also specify a window size or an array of window sizes.

For each window size, all its translates in the data is checked. For all these (shifted) windows the regression line is computed (with a,b in a + t*b) and the best line is computed.

From the best line the following data is returned

a, b specifying the regression line a + t*b
i, j determining the window, i.e the regression line stems from data X[i], ..., X[j]

Note

This function has to be implemented using some statistics package. loading Statistics.jl provides a default implementation.

source

ManifoldsBase.plot_check_geodesic — Function

plot_check_geodesic(T, N, e_norm, e_pt, e_alpha; name="")

Plot the three errors e_norm, e_pt, e_alpha as described in check_geodesic, where T are all time points used, N is their length, where

e_norm is of length N-1, since it is obtained from forward differences,
e_pt and e_alpha are of length N-2 since they are second order forward differences

The name is used as the title of the plot.

source

ManifoldsBase.plot_slope — Method

plot_slope(
    x, y; slope=2, line_base=0, a=0, b=2.0, i=1, j=length(x), name=""
)

Plot the result from the verification functions on data x,y with two comparison lines

line_base + tslope as the global slope(s) the plot could have
a + b*t on the interval [x[i], x[j]] for some (best fitting) comparison slope

The name is used as the title of the plot.

Note

This function has to be implemented for a certain plotting package. loading Plots.jl or a Makie.jl backend provides a default implementation.

source

ManifoldsBase.prepare_check_result — Method

prepare_check_result(
    log_range::AbstractVector, errors::AbstractVector, slope::Real;
    error::Symbol = :none, exactness_tol::Real = 1e3*eps(eltype(errors)),
    io::Union{IO,Nothing} = nothing, name::String = "estimated slope",
    plot::Bool = false, slope_tol::Real = 0.1, window = nothing,
)

Given a range of values log_range, with computed errors, verify whether this yields a slope of slope in log-scale

Note that if the errors are below the given tolerance and the method is exact, no plot is generated.

Keyword arguments

exactness_tol: if all errors are below this tolerance, the verification is considered exact. Errors below it are excluded from the slope estimation, since an error that small is round-off from evaluating the function rather than approximation error.
io: provide an IO to print the result to
name: name to display in the plot title and in the reported messages
plot: whether to plot the result, see plot_slope The plot is in log-log-scale. This is returned and can then also be saved.
slope_tol: tolerance for the slope (global) of the approximation
error: specify how to handle errors, :none, :info, :warn, :error
window: specify window sizes within the log_range that are used for the slope estimation. the default is, to use all window sizes 2:n, where n is the number of samples with error above exactness_tol.

source