# Discrete exterior calculus

## API docs

`CombinatorialSpaces.DiscreteExteriorCalculus`

— ModuleThe 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.AbstractDeltaDualComplex1D`

— TypeAbstract type for dual complex of a 1D delta set.

`CombinatorialSpaces.DiscreteExteriorCalculus.AbstractDeltaDualComplex2D`

— TypeAbstract type for dual complex of a 2D delta set.

`CombinatorialSpaces.DiscreteExteriorCalculus.Barycenter`

— TypeBarycenter, aka centroid, of a simplex.

`CombinatorialSpaces.DiscreteExteriorCalculus.Circumcenter`

— TypeCircumcenter, or center of circumscribed circle, of a simplex.

The circumcenter is calculated by inverting the Cayley-Menger matrix, as explained by Westdendorp. This method of calculation is also used in the package AlphaShapes.jl.

`CombinatorialSpaces.DiscreteExteriorCalculus.DeltaDualComplex1D`

— TypeDual complex of a one-dimensional delta set.

The data structure includes both the primal complex and the dual complex, as well as the mapping between them.

`CombinatorialSpaces.DiscreteExteriorCalculus.DeltaDualComplex2D`

— TypeDual complex of a two-dimensional delta set.

`CombinatorialSpaces.DiscreteExteriorCalculus.DualChain`

— TypeWrapper 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.

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.

`CombinatorialSpaces.DiscreteExteriorCalculus.DualE`

— TypeEdge in simplicial set: alias for `Simplex{1}`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.DualForm`

— TypeWrapper for form, aka cochain, on dual cells of dimension `n`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.DualSimplex`

— Type`CombinatorialSpaces.DiscreteExteriorCalculus.DualTri`

— TypeTriangle in simplicial set: alias for `Simplex{2}`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.DualV`

— TypeVertex in simplicial set: alias for `Simplex{0}`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.DualVectorField`

— TypeWrapper for vector field on dual vertices.

`CombinatorialSpaces.DiscreteExteriorCalculus.EmbeddedDeltaDualComplex1D`

— TypeEmbedded dual complex of an embedded 1D delta set.

Although they are redundant information, the lengths of the primal and dual edges are precomputed and stored.

`CombinatorialSpaces.DiscreteExteriorCalculus.EmbeddedDeltaDualComplex2D`

— TypeEmbedded dual complex of an embedded 2D delta set.

Although they are redundant information, the lengths and areas of the primal/dual edges and triangles are precomputed and stored.

`CombinatorialSpaces.DiscreteExteriorCalculus.Incenter`

— TypeIncenter, or center of inscribed circle, of a simplex.

`CombinatorialSpaces.DiscreteExteriorCalculus.OrientedDeltaDualComplex1D`

— TypeOriented dual complex of an oriented 1D delta set.

`CombinatorialSpaces.DiscreteExteriorCalculus.OrientedDeltaDualComplex2D`

— TypeOriented dual complex of an oriented 2D delta set.

`CombinatorialSpaces.DiscreteExteriorCalculus.PrimalVectorField`

— TypeWrapper for vector field on primal vertices.

`CombinatorialSpaces.DiscreteExteriorCalculus.SimplexCenter`

— TypeA notion of "geometric center" of a simplex.

See also: `geometric_center`

.

`Catlab.Theories.:∧`

— MethodWedge 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.Δ`

— MethodLaplace-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.:⋆`

— MethodHodge 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.:⋆`

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

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.codifferential`

— FunctionAlias for the codifferential operator `δ`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.dual_boundary`

— MethodBoundary of chain of dual cells.

Transpose of `dual_derivative`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.dual_derivative`

— MethodDiscrete exterior derivative of dual form.

Transpose of `dual_boundary`

. For more info, see (Desbrun, Kanso, Tong, 2008: Discrete differential forms for computational modeling, §4.5).

`CombinatorialSpaces.DiscreteExteriorCalculus.dual_point`

— MethodPoint associated with dual vertex of complex.

`CombinatorialSpaces.DiscreteExteriorCalculus.dual_triangle_vertices`

— MethodBoundary dual vertices of a dual triangle.

This accessor assumes that the simplicial identities for the dual hold.

`CombinatorialSpaces.DiscreteExteriorCalculus.edge_center`

— MethodDual vertex corresponding to center of primal edge.

`CombinatorialSpaces.DiscreteExteriorCalculus.elementary_duals`

— MethodList 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.flat`

— FunctionAlias for the flat operator `♭`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.flat_sharp`

— FunctionAlias for the flat-sharp dual-to-primal interpolation operator `♭♯`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.flat_sharp_mat`

— FunctionAlias for the flat-sharp dual-to-primal interpolation matrix `♭♯_mat`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.geometric_center`

— FunctionCalculate the center of simplex spanned by given points.

The first argument is a list of points and the second specifies the notion of "center", via an instance of `SimplexCenter`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.hodge_star`

— FunctionAlias for the Hodge star operator `⋆`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.interior_product`

— MethodInterior 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_flat`

— MethodInterior 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_star`

— MethodInverse 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.laplace_beltrami`

— FunctionAlias for the Laplace-Beltrami operator `∇²`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.laplace_de_rham`

— FunctionAlias for the Laplace-de Rham operator `Δ`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.lie_derivative`

— FunctionAlias for Lie derivative operator `ℒ`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.lie_derivative_flat`

— MethodLie derivative of $n$-form with respect to a 1-form.

Assumes that the flat operator `♭`

has already been applied to the vector field.

`CombinatorialSpaces.DiscreteExteriorCalculus.primal_vertex`

— MethodPrimal vertex associated with a dual simplex.

`CombinatorialSpaces.DiscreteExteriorCalculus.sharp`

— FunctionAlias for the sharp operator `♯`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.subdivide`

— MethodSubdivide a 1D delta set.

`CombinatorialSpaces.DiscreteExteriorCalculus.subdivide`

— MethodSubdivide an oriented 1D delta set.

Note that this function does NOT currently guarantee that if the input is oriented, then the output will be.

`CombinatorialSpaces.DiscreteExteriorCalculus.subdivide_duals!`

— MethodCompute geometric subdivision for embedded dual complex.

Supports different methods of subdivision through the choice of geometric center, as defined by `geometric_center`

. In particular, barycentric subdivision and circumcentric subdivision are supported.

`CombinatorialSpaces.DiscreteExteriorCalculus.subsimplices`

— MethodList 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.triangle_center`

— MethodDual vertex corresponding to center of primal triangle.

`CombinatorialSpaces.DiscreteExteriorCalculus.vertex_center`

— MethodDual vertex corresponding to center of primal vertex.

`CombinatorialSpaces.DiscreteExteriorCalculus.wedge_product`

— FunctionAlias for the wedge product operator `∧`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.δ`

— MethodCodifferential operator from primal $n$ forms to primal $n-1$-forms.

`CombinatorialSpaces.DiscreteExteriorCalculus.ℒ`

— MethodLie 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.∇²`

— MethodLaplace-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.

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.♭`

— MethodFlat 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`♭♯(s::HasDeltaSet, α::SimplexForm{1})`

Make a dual 1-form primal by chaining ♭ᵈᵖ♯ᵈᵈ.

This returns the given dual 1-form as a primal 1-form. See also `♭♯_mat`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.♭♯_mat`

— Method`♭♯_mat(s::HasDeltaSet)`

Make a dual 1-form primal by chaining ♭ᵈᵖ♯ᵈᵈ.

This returns a matrix which can be multiplied by a dual 1-form. See also `♭♯`

.

`CombinatorialSpaces.DiscreteExteriorCalculus.♯`

— MethodSharp 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.♯`

— MethodSharp 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.

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.♯_mat`

— Method`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.♯_mat`

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