Discrete exterior calculus

API docs


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.


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.


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.


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.


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$.


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).


Hodge 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.


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

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.


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.


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).


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.


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).


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.


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 Δ.


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 .


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.


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.


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.

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.

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.