Discrete exterior calculus

CombinatorialSpaces.jl provides discrete differential operators defined on simplicial sets via the Discrete Exterior Calculus (DEC).

There are two modules for these DEC operators. The first, CombinatorialSpaces.DiscreteExteriorCalculus, serves as our reference implementation. It is suitable for any manifold-like delta dual complex. The second, CombinatorialSpaces.FastDEC, offers more efficient operators, both in construction, and in execution time. The operators offered by both modules agree up to differences introduced by re-ordering floating-point operations.

Certain operators in FastDEC are made more efficient by assuming that the delta dual complex has not been altered in any way after it is created and volumes have been assigned with subdivide_duals!. So, such operators should not be called on such a complex if it has been manually edited.

API docs

CombinatorialSpaces.DiscreteExteriorCalculusModule

The discrete exterior calculus (DEC) for simplicial sets.

This module provides the dual complex associated with a delta set (the primal complex), which is a discrete incarnation of Hodge duality, as well as the many operators of the DEC that depend on it, such as the Hodge star, codifferential, wedge product, interior product, and Lie derivative. The main reference for this module is Hirani's 2003 PhD thesis.

CombinatorialSpaces.DiscreteExteriorCalculus.DualChainType

Wrapper for chain of dual cells of dimension n.

In an $N$-dimensional complex, the elementary dual simplices of each $n$-simplex together comprise the dual $(N-n)$-cell of the simplex. Using this correspondence, a basis for primal $n$-chains defines the basis for dual $(N-n)$-chains.

Note

In (Hirani 2003, Definition 3.4.1), the duality operator assigns a certain sign to each elementary dual simplex. For us, all of these signs should be regarded as positive because we have already incorporated them into the orientation of the dual simplices.

Catlab.Theories.:∧Method

Wedge product of discrete forms.

The wedge product of a $k$-form and an $l$-form is a $(k+l)$-form.

The DEC and related systems have several flavors of wedge product. This one is the discrete primal-primal wedge product introduced in (Hirani, 2003, Chapter 7) and (Desbrun et al 2005, Section 8). It depends on the geometric embedding and requires the dual complex. Note that we diverge from Hirani in that his formulation explicitly divides by (k+1)!. We do not do so in this computation.

Catlab.Theories.ΔMethod

Laplace-de Rham operator on discrete forms.

This linear operator on primal $n$-forms is defined by $Δ := δ d + d δ$. Restricted to 0-forms, it reduces to the negative of the Laplace-Beltrami operator ∇²: $Δ f = -∇² f$.

CombinatorialSpaces.DiscreteExteriorCalculus.:⋆Method

Hodge star operator from primal 1-forms to dual 1-forms.

This specific hodge star implementation is based on the hodge star presented in (Ayoub et al 2020), which generalizes the operator presented in (Hirani 2003). This reproduces the diagonal hodge for a dual mesh generated under circumcentric subdivision and provides off-diagonal correction factors for meshes generated under other subdivision schemes (e.g. barycentric).

CombinatorialSpaces.DiscreteExteriorCalculus.:⋆Method

Hodge star operator from primal $n$-forms to dual $N-n$-forms.

Note

Some authors, such as (Hirani 2003) and (Desbrun 2005), use the symbol $⋆$ for the duality operator on chains and the symbol $*$ for the Hodge star operator on cochains. We do not explicitly define the duality operator and we use the symbol $⋆$ for the Hodge star.

CombinatorialSpaces.DiscreteExteriorCalculus.elementary_dualsMethod

List of elementary dual simplices corresponding to primal simplex.

In general, in an $n$-dimensional complex, the elementary duals of primal $k$-simplices are dual $(n-k)$-simplices. Thus, in 1D dual complexes, the elementary duals of...

  • primal vertices are dual edges
  • primal edges are (single) dual vertices

In 2D dual complexes, the elementary duals of...

  • primal vertices are dual triangles
  • primal edges are dual edges
  • primal triangles are (single) dual vertices
CombinatorialSpaces.DiscreteExteriorCalculus.interior_productMethod

Interior product of a vector field (or 1-form) and a $n$-form.

Specifically, this operation is the primal-dual interior product defined in (Hirani 2003, Section 8.2) and (Desbrun et al 2005, Section 10). Thus it takes a primal vector field (or primal 1-form) and a dual $n$-forms and then returns a dual $(n-1)$-form.

CombinatorialSpaces.DiscreteExteriorCalculus.interior_product_flatMethod

Interior product of a 1-form and a $n$-form, yielding an $(n-1)$-form.

Usually, the interior product is defined for vector fields; this function assumes that the flat operator (not yet implemented for primal vector fields) has already been applied to yield a 1-form.

CombinatorialSpaces.DiscreteExteriorCalculus.inv_hodge_starMethod

Inverse Hodge star operator from dual $N-n$-forms to primal $n$-forms.

Confusingly, this is not the operator inverse of the Hodge star because it carries an extra global sign, in analogy to the smooth case (Gillette, 2009, Notes on the DEC, Definition 2.27).

CombinatorialSpaces.DiscreteExteriorCalculus.subsimplicesMethod

List of dual simplices comprising the subdivision of a primal simplex.

A primal $n$-simplex is always subdivided into $(n+1)!$ dual $n$-simplices, not be confused with the elementary_duals which have complementary dimension.

The returned list is ordered such that subsimplices with the same primal vertex appear consecutively.

CombinatorialSpaces.DiscreteExteriorCalculus.ℒMethod

Lie derivative of $n$-form with respect to a vector field (or 1-form).

Specifically, this is the primal-dual Lie derivative defined in (Hirani 2003, Section 8.4) and (Desbrun et al 2005, Section 10).

CombinatorialSpaces.DiscreteExteriorCalculus.∇²Method

Laplace-Beltrami operator on discrete forms.

This linear operator on primal $n$-forms defined by $∇² α := -δ d α$, where δ is the codifferential and d is the exterior derivative.

Note

For following texts such as Abraham-Marsden-Ratiu, we take the sign convention that makes the Laplace-Beltrami operator consistent with the Euclidean Laplace operator (the divergence of the gradient). Other authors, such as (Hirani 2003), take the opposite convention, which has the advantage of being consistent with the Laplace-de Rham operator Δ.

CombinatorialSpaces.DiscreteExteriorCalculus.♭Method

Flat operator converting vector fields to 1-forms.

A generic function for discrete flat operators. Currently only the DPP-flat from (Hirani 2003, Definition 5.5.2) and (Desbrun et al 2005, Definition 7.3) is implemented.

See also: the sharp operator .

CombinatorialSpaces.DiscreteExteriorCalculus.♯Method

Sharp operator for converting dual 1-forms to dual vector fields.

This dual-dual sharp uses a method of local linear least squares to provide a tangent vector field.

See also: ♯_mat, which returns a matrix that encodes this operator.

CombinatorialSpaces.DiscreteExteriorCalculus.♯Method

Sharp operator for converting primal 1-forms to primal vector fields.

This the primal-primal sharp from Hirani 2003, Definition 5.8.1 and Remark 2.7.2.

Note

A PP-flat is also defined in (Desbrun et al 2005, Definition 7.4) but differs in two ways: Desbrun et al's notation suggests a unit normal vector, whereas the gradient of Hirani's primal-primal interpolation function is not necessarily a unit vector. More importantly, Hirani's vector is a normal to a different face than Desbrun et al's, with further confusion created by the fact that Hirani's Figure 5.7 agrees with Desbrun et al's description rather than his own. That being said, to the best of our knowledge, our implementation is the correct one and agrees with Hirani's description, if not his figure.

See also: and ♯_mat, which returns a matrix that encodes this operator.

CombinatorialSpaces.DiscreteExteriorCalculus.♯_matMethod
function ♯_mat(s::AbstractDeltaDualComplex2D, DS::DiscreteSharp)

Sharpen a 1-form into a vector field.

3 primal-primal methods are supported. See ♯_denominator for the distinction between Hirani's method and and an "Alternative" method. Desbrun's definition is selected with DesbrunSharp, and is like Hirani's, save for dividing by the norm twice.

A dual-dual method which uses linear least squares to estimate a vector field is selected with LLSDDSharp.

CombinatorialSpaces.DiscreteExteriorCalculus.♯_matMethod
function ♯_mat(s::AbstractDeltaDualComplex2D, ::LLSDDSharp)

Sharpen a dual 1-form into a DualVectorField, using linear least squares.

Up to floating point error, this method perfectly produces fields which are constant over any triangle in the domain. Assume that the contribution of each half-edge to the value stored on the entire dual edge is proportional to their lengths. Since this least squares method does not perform pre-normalization, the contribution of each half-edge value is proportional to its length on the given triangle. Satisfying the continuous exterior calculus, sharpened vectors are constrained to lie on their triangle (i.e. they are indeed tangent).

It is not known whether this method has been exploited previously in the DEC literature, or defined in code elsewhere.

CombinatorialSpaces.FastDECModule

The discrete exterior calculus (DEC) with high performance in mind.

This module provides similar fuctionality to the DiscreteExteriorCalculus module but uses assumptions about the ACSet mesh structure to greatly improve performance. Some operators, like the exterior derivative are returned as sparse matrices while others, like the wedge product, are instead returned as functions that will compute the product.

Catlab.Theories.:∧Method
∧(s::HasDeltaSet, α::DualForm{1}, β::SimplexForm{1})

Wedge product of a dual 1-form and a primal 1-form.

Chain the musical isomorphisms to interpolate the dual 1-form to a primal 1-form. Then use the CombinatorialSpaces version of the Hirani primal-primal weddge (without explicitly dividing by 2.)

Catlab.Theories.:∧Method
∧(s::HasDeltaSet, α::SimplexForm{1}, β::DualForm{1})

Wedge product of a primal 1-form and a dual 1-form.

Chain the musical isomorphisms to interpolate the dual 1-form to a primal 1-form, using the linear least squares ♯. Then use the CombinatorialSpaces version of the Hirani primal-primal weddge.

CombinatorialSpaces.FastDEC.avg₀₁_matMethod

Averaging matrix from 0-forms to 1-forms.

Given a 0-form, this matrix computes a 1-form by taking the mean of value stored on the faces of each edge.

This matrix can be used to implement a wedge product: (avg₀₁(s)*X) .* Y where X is a 0-form and Y a 1-form, assuming the center of an edge is halfway between its endpoints.

See also avg₀₁.

CombinatorialSpaces.FastDEC.dec_c_wedge_product!Method
dec_c_wedge_product!(::Type{Tuple{0,1}}, wedge_terms, f, α, val_pack)

Computes the wedge product between a 0 and 1-form. Use the precomputational "p" varient for the wedge_terms parameter. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_c_wedge_product!Method
dec_c_wedge_product!(::Type{Tuple{0,2}}, wedge_terms, f, α, val_pack)

Computes the wedge product between a 0 and 2-form. Use the precomputational "p" varient for the wedge_terms parameter. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_c_wedge_product!Method
dec_c_wedge_product!(::Type{Tuple{1,1}}, wedge_terms, f, α, val_pack)

Computes the wedge product between a 1 and 1-form. Use the precomputational "p" varient for the wedge_terms parameter. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_c_wedge_productMethod
dec_c_wedge_product(::Type{Tuple{m,n}}, α, β, val_pack) where {m,n}

Computes the wedge product between two forms. Use the precomputational "p" varient for the wedge_terms parameter. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_p_wedge_productMethod
dec_p_wedge_product(::Type{Tuple{0,1}}, sd::EmbeddedDeltaDualComplex1D)

Precomputes values for the wedge product between a 0 and 1-form. The values are to be fed into the wedge_terms parameter for the computational "c" varient. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_p_wedge_productMethod
dec_p_wedge_product(::Type{Tuple{0,1}}, sd::EmbeddedDeltaDualComplex2D)

Precomputes values for the wedge product between a 0 and 1-form. The values are to be fed into the wedge_terms parameter for the computational "c" varient. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_p_wedge_productMethod
dec_p_wedge_product(::Type{Tuple{0,2}}, sd::EmbeddedDeltaDualComplex2D{Bool, float_type, _p} where _p) where float_type

Precomputes values for the wedge product between a 0 and 2-form. The values are to be fed into the wedge_terms parameter for the computational "c" varient. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_p_wedge_productMethod
dec_p_wedge_product(::Type{Tuple{1,1}}, sd::EmbeddedDeltaDualComplex2D{Bool, float_type, _p} where _p) where float_type

Precomputes values for the wedge product between a 1 and 1-form. The values are to be fed into the wedge_terms parameter for the computational "c" varient. This relies on the assumption of a well ordering of the dual space simplices. Do NOT modify the mesh once it's dual mesh has been computed else this method may not function properly.

CombinatorialSpaces.FastDEC.dec_wedge_product_dpMethod
dec_wedge_product_dp(::Type{Tuple{1,0}}, sd::HasDeltaSet)

Returns a cached function that computes the wedge product between a dual 1-form and a primal 0-form.

This function assumes barycentric means and performs bilinear interpolation. It is not known if this definition has appeared in the literature or any code.

CombinatorialSpaces.FastDEC.dec_wedge_product_pdMethod
function dec_wedge_product_pd(::Type{Tuple{0,1}}, sd::HasDeltaSet)

Returns a cached function that computes the wedge product between a primal 0-form and a dual 1-form.

This function assumes barycentric means and performs bilinear interpolation. It is not known if this definition has appeared in the literature or any code.

CombinatorialSpaces.FastDEC.ΔᵈMethod
function Δᵈ_mat(::Type{Val{0}}, s::SimplicialSets.HasDeltaSet)

Return a function matrix encoding the dual 0-form Laplacian.

CombinatorialSpaces.FastDEC.ΔᵈMethod
function Δᵈ_mat(::Type{Val{2}}, s::SimplicialSets.HasDeltaSet)

Return a function matrix encoding the dual 1-form Laplacian.

CombinatorialSpaces.FastDEC.ℒ_ddMethod
function ℒ_dd(::Type{Tuple{1,1}}, s::SimplicialSets.HasDeltaSet)

Given a dual 1-form and a dual 1-form, return their lie derivative as a dual 1-form.