Parametric surfaces

Manifolds.ParametricSurface — Type

ParametricSurface{TMP<:AbstractManifold{ℝ},TE<:Euclidean,TF,TIF,TDF} <: AbstractDecoratorManifold{ℝ}

Surface in ℝⁿ described by a parametric function f defined on a parameter space M_param. The embedding ℝⁿ is described by a Euclidean manifold M_embed. The metric is the restriction of the Euclidean metric to the surface.

More precisely, the surface is the image

\[\mathcal M = \bigl\{f(u) \mid u \in \mathcal M_{\mathrm{param}}\bigr\} \subseteq \mathbb R^n,\]

and its Riemannian metric is induced by the Euclidean inner product,

\[g_u(\xi, \eta) = \left\langle \mathrm Df(u)[\xi], \mathrm Df(u)[\eta]\right\rangle.\]

The functions f!, inverse_f!, and jacobian_f! should be defined in-place. They map parameters p to embedded points q, embedded points to parameters, and parameters to the Jacobian of f, respectively.

Note that inverse_f! is required to accept any point in the embedding space, not just points on the surface. It should return the parameters of the closest point on the surface to the input point, i.e. parameters satisfying

\[f\bigl(\operatorname{inverse\_f}(q)\bigr) \in \underset{x \in \mathcal M}{\arg\min}\ \lVert q - x \rVert.\]

Constructor

ParametricSurface(M_param, M_embed, f!, inverse_f!, jacobian_f!)

Manifolds.ParametricSurfaceAtlas — Type

ParametricSurfaceAtlas(A)

Atlas for a ParametricSurface obtained by forwarding the parameter-space atlas A.

Manifolds.affine_connection! — Method

affine_connection!(M::ParametricSurface, Zc, A::ParametricSurfaceAtlas, i, a, Xc, Yc)

Store the Levi-Civita affine connection in forwarded chart coordinates in Zc.

Manifolds.check_chart_switch — Method

check_chart_switch(M::ParametricSurface, A::ParametricSurfaceAtlas, i, a; kwargs...)

Delegate the chart-switch condition to the parameter-space atlas wrapped by A.

Manifolds.gaussian_curvature — Method

gaussian_curvature(M::ParametricSurface, p; kwargs...)

Return the Gaussian curvature of M at embedded point p, computed in its forwarded atlas.

For a surface, the Gaussian curvature is half of the Ricci scalar,

\[K(p) = \tfrac{1}{2}\operatorname{Ric}(p).\]

Manifolds.get_chart_index — Method

get_chart_index(M::ParametricSurface, A::ParametricSurfaceAtlas, i, a)

Return the chart index in A containing the point represented by local coordinates a in chart i.

Manifolds.get_chart_index — Method

get_chart_index(M::ParametricSurface, A::ParametricSurfaceAtlas, p)

Return the chart index in A containing embedded point p.

Manifolds.get_default_atlas — Method

get_default_atlas(M::ParametricSurface)

Return the ParametricSurfaceAtlas forwarding the default atlas of the parameter space of M.

Manifolds.get_parameters! — Method

get_parameters!(M::ParametricSurface, a, A::ParametricSurfaceAtlas, i, p)

Store in a the local parameters of embedded point p in chart i of ParametricSurfaceAtlas A.

Manifolds.get_point! — Method

get_point!(M::ParametricSurface, p, A::ParametricSurfaceAtlas, i, a)

Store in p the embedded point represented by local parameters a in chart i of ParametricSurfaceAtlas A.

ManifoldsBase.check_point — Method

check_point(M::ParametricSurface, q; kwargs...)

Check whether the embedded point q lies on M by applying the inverse parametrization and reconstructing it with f!.

The check verifies that $q \approx f(\operatorname{inverse\_f}(q))$.

ManifoldsBase.check_vector — Method

check_vector(M::ParametricSurface, p, X; atol::Real=sqrt(eps(float(number_eltype(p)))), kwargs...)

Check whether X is tangent to the parametric surface M at embedded point p. Computes Jacobian of the parametrization at the parameters corresponding to p and checks whether the difference between X and its projection onto the tangent space is smaller than atol.

At $p = f(u)$, the tangent space is

\[T_p\mathcal M = \operatorname{range}\bigl(\mathrm Df(u)\bigr).\]

ManifoldsBase.get_embedding — Method

get_embedding(M::ParametricSurface)

Return the Euclidean embedding manifold of M.

ManifoldsBase.inner — Method

inner(M::ParametricSurface, A::ParametricSurfaceAtlas, i, a, Xc, Yc)

Return the pullback Euclidean inner product of chart-coordinate vectors Xc and Yc.

Writing $u$ for the parameter point and $J = \mathrm Df(u)$, the metric is

\[g_u(X_c, Y_c) = \langle JX_c, JY_c \rangle.\]

ManifoldsBase.manifold_dimension — Method

manifold_dimension(M::ParametricSurface)

Return the dimension of the parameter space of M.

ManifoldsBase.project! — Method

project!(M::ParametricSurface, Y, p, X)

Project the ambient vector X orthogonally onto the tangent space of M at p and store it in Y.

For $p = f(u)$ and $J = \mathrm Df(u)$, this computes

\[Y = J\bigl(J \backslash X\bigr),\]

where $J \backslash X$ denotes the least-squares solution.

ManifoldsBase.project! — Method

project!(M::ParametricSurface, q, p)

Project p onto M by applying the inverse parametrization followed by f! and store the result in q. Thus, $q = f(\operatorname{inverse\_f}(p))$ is a closest point on the surface.

ManifoldsBase.representation_size — Method

representation_size(M::ParametricSurface)

Return the representation size of the Euclidean embedding of M.

Example

The Möbius band is parametrized by a strip coordinate $u \in [-w, w]$ and an angle $\theta \in \mathbb S^1$. Its parameter space is therefore the product of a Hyperrectangle and a Circle.

using Manifolds, Plots, RecursiveArrayTools, ForwardDiffhalf_width = 0.35M_param = ProductManifold(Hyperrectangle([-half_width], [half_width]), Circle())M_embed = Euclidean(3)function mobius!(v, p::ArrayPartition)    u, θ = p.x[1][1], p.x[2][]    v .= [        (1 + u * cos(θ / 2)) * cos(θ),        (1 + u * cos(θ / 2)) * sin(θ),        u * sin(θ / 2),    ]    return vendfunction inverse_mobius!(p::ArrayPartition, u)    θ = atan(u[2], u[1])    p.x[1][1] =        (u[1] - cos(θ)) * cos(θ / 2) * cos(θ) +        (u[2] - sin(θ)) * cos(θ / 2) * sin(θ) + u[3] * sin(θ / 2)    p.x[2][] = θ    return pendfunction jacobian_mobius!(J, p::ArrayPartition)    ForwardDiff.jacobian!(J, v -> mobius!(Vector{eltype(x)}(undef, manifold_dimension(M_embed)), v), p)    return JendM = ParametricSurface(M_param, M_embed, mobius!, inverse_mobius!, jacobian_mobius!)

ParametricSurface{ProductManifold{ℝ, Tuple{Hyperrectangle{Vector{Float64}}, Circle{ℝ}}}, Euclidean{ℝ, ManifoldsBase.TypeParameter{Tuple{3}}}, typeof(Main.var"Main".mobius!), typeof(Main.var"Main".inverse_mobius!), typeof(Main.var"Main".jacobian_mobius!)}(ProductManifold(Hyperrectangle([-0.35], [0.35]), Circle(ℝ)), Euclidean(3; field=ℝ), Main.var"Main".mobius!, Main.var"Main".inverse_mobius!, Main.var"Main".jacobian_mobius!)

Sampling its parametrization can be used to produce a three-dimensional view of the band.

strip_coordinates = range(-half_width, half_width; length = 41)angles = range(-π, π; length = 181)xyz = [mobius!(zeros(3), ArrayPartition([u], [θ])) for u in strip_coordinates, θ in angles]x = [p[1] for p in xyz]y = [p[2] for p in xyz]z = [p[3] for p in xyz]

41×181 Matrix{Float64}:
  0.35     0.349947   0.349787   0.34952   …  -0.349787  -0.349947  -0.35
  0.3325   0.332449   0.332297   0.332044     -0.332297  -0.332449  -0.3325
  0.315    0.314952   0.314808   0.314568     -0.314808  -0.314952  -0.315
  0.2975   0.297455   0.297319   0.297092     -0.297319  -0.297455  -0.2975
  0.28     0.279957   0.279829   0.279616     -0.279829  -0.279957  -0.28
  0.2625   0.26246    0.26234    0.26214   …  -0.26234   -0.26246   -0.2625
  0.245    0.244963   0.244851   0.244664     -0.244851  -0.244963  -0.245
  0.2275   0.227465   0.227361   0.227188     -0.227361  -0.227465  -0.2275
  0.21     0.209968   0.209872   0.209712     -0.209872  -0.209968  -0.21
  0.1925   0.192471   0.192383   0.192236     -0.192383  -0.192471  -0.1925
  ⋮                                        ⋱                         ⋮
 -0.21    -0.209968  -0.209872  -0.209712      0.209872   0.209968   0.21
 -0.2275  -0.227465  -0.227361  -0.227188      0.227361   0.227465   0.2275
 -0.245   -0.244963  -0.244851  -0.244664      0.244851   0.244963   0.245
 -0.2625  -0.26246   -0.26234   -0.26214   …   0.26234    0.26246    0.2625
 -0.28    -0.279957  -0.279829  -0.279616      0.279829   0.279957   0.28
 -0.2975  -0.297455  -0.297319  -0.297092      0.297319   0.297455   0.2975
 -0.315   -0.314952  -0.314808  -0.314568      0.314808   0.314952   0.315
 -0.3325  -0.332449  -0.332297  -0.332044      0.332297   0.332449   0.3325
 -0.35    -0.349947  -0.349787  -0.34952   …   0.349787   0.349947   0.35

Which can then be visualized using for example GLMakie.jl: GLMakie.surface(x, y, z).

All the usual tools still work as in the embedded torus example.

Internal docs

Manifolds.get_coordinates_induced_basis! — Method

get_coordinates_induced_basis!(
    M::ParametricSurface, cX, p, X,
    B::InducedBasis{ℝ, TangentSpaceType, <:ParametricSurfaceAtlas}
)

Store in cX the coordinates of embedded tangent vector X at p in the basis induced by forwarded atlas B.

Manifolds.get_vector_induced_basis! — Method

get_vector_induced_basis!(
    M::ParametricSurface,
    X,
    p,
    cX,
    B::InducedBasis{ℝ, TangentSpaceType, <:ParametricSurfaceAtlas},
)

Store in X the embedded tangent vector at p represented by coordinates cX in the basis induced by forwarded atlas B.

ManifoldsBase.get_embedding_type — Method

ManifoldsBase.get_embedding_type(::ParametricSurface)

Declare ParametricSurface as directly and isometrically embedded in its Euclidean embedding.

ParametricSurface{TMP<:AbstractManifold{ℝ},TE<:Euclidean,TF,TIF,TDF} <: AbstractDecoratorManifold{ℝ}

Surface in ℝⁿ described by a parametric function f defined on a parameter space M_param.

ParametricSurfaceAtlas(A)

Atlas for a ParametricSurface obtained by forwarding the parameter-space atlas A.

get_coordinates_induced_basis!(
    M::ParametricSurface, cX, p, X,
    B::InducedBasis{ℝ, TangentSpaceType, <:ParametricSurfaceAtlas}
)

Store in cX the coordinates of embedded tangent vector X at p in the basis induced by forwarded atlas B.

get_vector_induced_basis!(
    M::ParametricSurface,
    X,
    p,
    cX,
    B::InducedBasis{ℝ, TangentSpaceType, <:ParametricSurfaceAtlas},
)

Store in X the embedded tangent vector at p represented by coordinates cX in the basis induced by forwarded atlas B.

manifold_dimension(M::ParametricSurface)

Return the dimension of the parameter space of M.

InducedBasis(vs::VectorSpaceType, A::AbstractAtlas, i)

The basis induced by chart with index i from an AbstractAtlas A of vector space of type vs.

get_coordinates_induced_basis!(M::AbstractManifold, c, p, X, B::InducedBasis{ℝ, TangentSpaceType, <:AbstractAtlas};
    backend::AbstractADType = AutoForwardDiff())

Compute the coordinates of a tangent vector X at a point p on the manifold M in the induced basis B and store the result in c.

get_vector_induced_basis!(M::AbstractManifold, Y, p, Xc, B::InducedBasis{ℝ, TangentSpaceType, <:AbstractAtlas};
    backend::AbstractADType = AutoForwardDiff())

Compute the tangent vector Y at a point p on the manifold M corresponding to the coordinates Xc in the induced basis B and store the result in Y.

manifold_dimension(M::CenteredMatrices)

Return the manifold dimension of the CenteredMatrices m-by-n matrix M over the number system 𝔽, i.e.

manifold_dimension(M::CholeskySpace)

Return the manifold dimension for the CholeskySpace M, i.e.

Circle{𝔽} <: AbstractManifold{𝔽}

The circle is a manifold here represented by real-valued points in or complex-valued points of absolute value .

manifold_dimension(M::Circle)

Return the dimension of the Circle M, i.e. .

manifold_dimension(M::DeterminantOneMatrices{n,𝔽})

Return the dimension of the DeterminantOneMatrices matrix M over the number system 𝔽, which is one dimension less than its embedding, the Euclidean(n, n; field=𝔽).

manifold_dimension(M::Elliptope)

returns the dimension of Elliptope M , i.e.

manifold_dimension(M::EssentialManifold{is_signed, ℝ})

Return the manifold dimension of the EssentialManifold, which is 5[TD17].

Euclidean{T,𝔽} <: AbstractManifold{𝔽}

Euclidean vector space.

manifold_dimension(M::Euclidean)

Return the manifold dimension of the Euclidean M, i.e. the product of all array dimensions and the real_dimension of the underlying number system.

manifold_dimension(M::FixedRankMatrices)

Return the manifold dimension for the 𝔽-valued FixedRankMatrices M of dimension mxn of rank k, namely

manifold_dimension(M::Flag)

Return dimension of flag manifold .

manifold_dimension(M::GeneralizedGrassmann)

Return the dimension of the GeneralizedGrassmann(n,k,𝔽) manifold M, i.e.

manifold_dimension(M::GeneralizedStiefel)

Return the dimension of the GeneralizedStiefel manifold M=.

manifold_dimension(M::Rotations)
manifold_dimension(M::OrthogonalMatrices)

Return the dimension of the manifold orthogonal matrices and of the manifold of rotations

manifold_dimension(M::SpecialUnitaryMatrices)

Return the dimension of the manifold of special unitary matrices.

manifold_dimension(M::UnitaryMatrices{n,ℂ}) where {n}

Return the dimension of the manifold unitary matrices.

manifold_dimension(M::UnitaryMatrices{<:Any,ℍ})

Return the dimension of the manifold unitary matrices.

manifold_dimension(N::GraphManifold{G,𝔽,M,EdgeManifold})

returns the manifold dimension of the GraphManifold N on the edges of a graph , i.e.

manifold_dimension(N::GraphManifold{G,𝔽,M,VertexManifold})

returns the manifold dimension of the GraphManifold N on the vertices of a graph , i.e.

get_coordinates_induced_basis!(M::Grassmann, c, p, X, B::InducedBasis{<:Any, <:Any, <:GrassmannAtlas})

Store in c the coordinates of a tangent vector X at p with respect to the basis induced by the standard GrassmannAtlas.

get_vector_induced_basis!(M::Grassmann, X, p, c, B::InducedBasis{ℝ, TangentSpaceType, <:GrassmannAtlas})

Store in X the tangent vector at p represented by coordinates c with respect to the basis induced by the standard GrassmannAtlas.

manifold_dimension(M::Grassmann)

Return the dimension of the Grassmann(n,k,𝔽) manifold M, i.e.

manifold_dimension(M::HeisenbergMatrices)

Return the dimension of HeisenbergMatrices(n), which is equal to .

manifold_dimension(M::Hyperbolic)

Return the dimension of the hyperbolic space manifold , i.e. .

Hyperrectangle{T} <: AbstractManifold{ℝ}

Hyperrectangle, also known as orthotope or box.

manifold_dimension(M::Hyperrectangle)

Return the manifold dimension of the Hyperrectangle M, i.e. the product of all array dimensions.

manifold_dimension(M::InvertibleMatrices{n,𝔽})

Return the dimension of the InvertibleMatrices matrix M over the number system 𝔽, which is the same dimension as its embedding, the Euclidean(n, n; field=𝔽).

manifold_dimension(M::MultinomialDoubleStochastic)

returns the dimension of the MultinomialDoubleStochastic manifold namely

manifold_dimension(M::MultinomialSymmetric)

returns the dimension of the MultinomialSymmetric manifold namely

manifold_dimension(M::PositiveNumbers)

Return the dimension of the PositiveNumbers M, i.e. of the 1-dimensional hyperbolic space,

manifold_dimension(M::ProbabilitySimplex)

Returns the manifold dimension of the probability simplex in , i.e.

manifold_dimension(M::AbstractProjectiveSpace{𝔽}) where {𝔽}

Return the real dimension of the AbstractProjectiveSpace M, respectively i.e. the real dimension of the embedding minus the real dimension of the field 𝔽.

manifold_dimension(M::KendallsPreShapeSpace)

Return the dimension of the KendallsPreShapeSpace manifold M.

manifold_dimension(M::KendallsShapeSpace)

Return the dimension of the KendallsShapeSpace manifold M.

manifold_dimension(M::SkewHermitianMatrices)

Return the dimension of the SkewHermitianMatrices matrix M over the number system 𝔽, i.e.

manifold_dimension(M::Spectrahedron)

returns the dimension of Spectrahedron M, i.e.

get_coordinates_induced_basis!(M::Sphere, cX, p, X, B::InducedBasis{ℝ, TangentSpaceType, <:StereographicAtlas})

Store in cX the stereographic coordinate representation of the tangent vector X at p with respect to the induced basis B.

get_vector_induced_basis!(M::Sphere, X, p, cX, B::InducedBasis{ℝ, TangentSpaceType, <:StereographicAtlas})

Store in X the tangent vector at p represented by stereographic coordinates cX with respect to the induced basis B.

manifold_dimension(M::AbstractSphere)

Return the dimension of the AbstractSphere M, respectively i.e. the dimension of the embedding -1.

manifold_dimension(M::SphereSymmetricMatrices{<:Any,𝔽})

Return the manifold dimension of the SphereSymmetricMatrices n-by-n symmetric matrix M of unit Frobenius norm over the number system 𝔽, i.e.

manifold_dimension(M::Stiefel)

Return the dimension of the Stiefel manifold M=.

manifold_dimension(M::SymmetricMatrices{n,𝔽})

Return the dimension of the SymmetricMatrices matrix M over the number system 𝔽, i.e.

manifold_dimension(M::SymmetricPositiveDefinite)

returns the dimension of SymmetricPositiveDefinite M , i.e.

manifold_dimension(M::SymmetricPositiveSemidefiniteFixedRank)

Return the dimension of the SymmetricPositiveSemidefiniteFixedRank matrix M over the number system 𝔽, i.e.

manifold_dimension(::SymplecticMatrices)

Returns the dimension of the symplectic manifold embedded in , i.e.

manifold_dimension(::SymplecticGrassmann)

Return the dimension of the SymplecticGrassmann(2n,2k), which is

manifold_dimension(::SymplecticStiefel)

Returns the dimension of the symplectic Stiefel manifold embedded in , i.e. [BZ21]

manifold_dimension(M::EmbeddedTorus)

Return the dimension of the EmbeddedTorus M that is 2.

manifold_dimension(::Tucker)

The dimension of the manifold of tensors of multilinear rank , i.e.