Physics is governed by Partial differential algebraic equations which involve derivatives of fields. The ability to differentiate and integrate tensor fields is thus a key feature in numerical codes. In general relativity or in non-cartesian coordinate systems, differentiation and integration takes place on manifolds with non-necessarily-Lorentzian metric.
Examples of tensor fields which are linked one-to-the-other by differentiations are:
Integration is used to compute global quantities from local ones, ie. the current flowing through a wire, the energy in a physical system, etc. The generalized Stokes theorem (discussed below) is of particular importance when computing the integral of a derivative:
\[ \int_{\delta\Omega} \omega = \int_\Omega d\omega \]
Please refer to the reference document Discrete Differential Forms for Computational Modeling for a way more detailled description of the theory presented in this section.
A whole zoo of differential operators has been developed over the centuries : gradient, rotational, divergency, 4-gradient, 4-divergency, directional derivative, material derivative, covariant derivative, Lie derivative, etc. During the 20th century, mathematicians proposed a refactoring of it known as Exterior calculus, which proved highly suitable for discretization (now known as Discrete exterior calculus). Only two fundamental operators are defined and can be used to build any possible differential operator on any-dimension manifold:
Those operators must be applied on differential forms, which can be assimilated to antisymmetric tensor fields. The exterior derivative transforms a \(k-\)form into a \(k+1-\)form. The Hodge star transforms a \(k-\)form into a \(n-k-\)form where \(n\) is the dimension of the manifold. The codifferential operator \(\delta = (-1)^{n(k+1)+1}\star d^\top \star\) transforms a \(k-\)form into a \(k-1-\)form.
The generic Laplacian is defined as \(\delta d + d \delta\).
An important relation is the Poincarré Lemma \(dd = 0\). It leads to the very deep physical concept of gauge invariance, which tells us potentials are defined up to a derivative (because \(d(A+d\alpha) = dA + dd\alpha = dA\)).
CovariantDerivative<SpatialIndex...> extends the discrete exterior derivative to cochains with values in a vector bundle. Spatial dimension, form degree and fibre rank are independent: a scalar, vector or flattened tensor may be the value of a face cochain.
For a cell \(c\), let \(b(c)\) denote its lower vertex. The discrete operation is
\[ (d^\nabla u)(c) = \sum_{f\subset\partial c} [c:f]\,P_{b(c)\leftarrow b(f)}u(f). \]
Here \([c:f]\) is the oriented incidence number and \(P\) transports a face value into the fibre at the cell's lower vertex. Values already in that fibre are used directly. transport(to, from) returns the matrix with output fibre components as rows and input components as columns.
The implementation converts the vertex masks accepted by cochain_value() into a SimiLie Simplex, obtains its oriented faces with boundary(), and integrates each transported component using Cochain::integrate(). These are the same boundary and pairing operations used by Coboundary::run(); there is no separate formula for incidence signs in the covariant derivative. It shares these algebraic primitives rather than dispatching to the global tensor coboundary() wrapper, whose evaluator also supplies a mesh boundary policy.
With IdentityTransport<Rank>, this construction is the ordinary coboundary component by component, and its square vanishes. General transports need not give a square-zero operator: compositions along different paths can differ, representing discrete curvature. No metric, material law or quadrature rule enters this incidence operation.
The 2D elasticity use of this derivative is described in the physics module.
A \(k-\)simplex is an oriented discrete element of dimension \(k\) belonging to the discrete manifold. Ie. a \(0\)-simplex is a node, a \(1\)-simplex is an edge, a \(2\)-simplex is a face and a \(3\)-simplex is a cell. It can be defined for any dimension \(n\) of the discrete manifold.
In SimiLie, a simplex derives from ddc::DiscreteElement, associated to a shift vector with \(k\) 1 and \(n-k\) 0, and a boolean flag negative giving the orientation.
A \(k-\)chain - at least in the sense it is used in SimiLie - is basically a set of \(k-\)simplices.
1, every simplex belonging to the chain thus has to be oriented accordingly to the chain purpose.The boundary operator associates to a \(k-\)simplex a \(k-1-\)chain containing the simplices which form the boundary of the simplex. It can also associate to a \(k-\)chain a \(k-1-\)chain forming the boundary of the chain.
A \(k-\)cosimplex is the association of a simplex and of a real (or complex) number.
A \(k-\)cochain is basically a set of cosimplices. This is a discrete differential \(k-\)form. It can be represented as a rank-k antisymmetric tensor field (there is a Cochain constructor which takes an antisymmetric tensor as argument).
The coboundary operator associates to a \(k-\)cochain a \(k+1-\)cosimplex or a \(k+1-\)cochain containing the cosimplices which form the coboundary of the cochain. Please refer to Discrete Differential Forms for Computational Modeling for more details. This is the discrete exterior derivative \(d\).
At the implementation level, Coboundary evaluates the integral of the input cochain on the boundary of each local \((k+1)\)-simplex. For a primal basis simplex \(\sigma^{k+1}\), the discrete exterior derivative is therefore:
\[ (d\omega)(\sigma^{k+1}) = \omega(\partial \sigma^{k+1}). \]
Equivalently, if \(\omega\) is a discrete \(k\)-cochain, then:
\[ \left(d\omega\right)(\sigma^{k+1}) = \sum_{\tau^k \subset \partial \sigma^{k+1}} \mathrm{sgn}(\tau^k,\sigma^{k+1})\,\omega(\tau^k), \]
where the sum runs over the oriented boundary \(k\)-simplices of \(\sigma^{k+1}\) and \(\mathrm{sgn}(\tau^k,\sigma^{k+1})\) is the induced orientation sign.
The transposed coboundary operator accumulates the contributions of incident higher-dimensional simplices onto the current simplex. It is the transpose of the incidence operator underlying the coboundary. Explicitly, if \(\eta\) is a discrete \((k+1)\)-cochain and \(\tau^k\) is a \(k\)-simplex, then:
\[ \left(d^\top \eta\right)(\tau^k) = \sum_{\sigma^{k+1} \supset \tau^k} \mathrm{sgn}(\tau^k,\sigma^{k+1})\,\eta(\sigma^{k+1}), \]
However this is not the adjoint of the coboundary operator, because the latter has to involve the metric in some way. The adjoint operator on forms is the codifferential, presented below.
Boundary sampling is configurable independently of incidence and metric. coboundary() and deriv() default to ClampExtrapolationRule, which reuses the nearest stored node outside the input domain. transposed_coboundary() and the dual stages of codifferential() and laplacian() default to ZeroExtrapolationRule, which omits exterior contributions. A single supplied rule applies to all faces; ExtrapolationRules can instead select a different rule on each lower and upper face. The Laplacian accepts independent primal and dual rules.
NaturalScalarExtrapolationRule continues the slope from the nearest two nodes, while PrescribedScalarExtrapolationRule returns a given exterior value. Supplying an exterior sampling rule does not itself constrain stored boundary unknowns; the multidomain scalar assembler also prescribes those nodal rows. Physical normal flux conditions are imposed on the dual flux, separately from continuation of the primal scalar field.
The pointwise Coboundary and Codifferential APIs accept evaluators, allowing both stored and lazy cochains. Their coefficient-producing value() overloads provide stencils that can be composed with the same sampling policies during matrix assembly. Tensor extrapolation rules likewise expose operator() for sampling and value() for affine coefficients. The multidomains documentation explains donor mappings, interface jumps, stencil coordinate conventions and global assembly.
In DEC, cochains are not only characterized by their degree, but also by the cell complex on which they live. There is the primal complex, made of the mesh simplices themselves, but the operators presented below make use of a dual cell complex which allows to introduce metric information. Indeed, the dual cell complex provides the complementary cells on which the metric-dependent "orthogonal counterparts" live. This is why the discrete Hodge star, which is the operator encoding the metric in DEC, naturally maps primal cochains to dual cochains.
However, a dual mesh has to be chosen according to some "dualization strategy". In SimiLie, this choice is represented explicitly by the CellComplex tag:
CellComplex::Primal (no dualization)CellComplex::CircumcentricDualCellComplex::BarycentricDualTo build a discrete operator able to encode the metric (the discrete Hodge star), we need a volume operator (in the sense of \(k-\)volume, ie. length, area...) to provide the ability to measure the "size" of a simplex. Given a \(k\)-simplex spanned by edge vectors \(e_1,\dots,e_k\), SimiLie builds the local Gram matrix:
\[ G_{\mu\nu} = g_{\rho\sigma} e_\mu^\rho e_\nu^\sigma \]
where \(g\) is the metric evaluated at the current mesh node. The \(k\)-volume is then obtained from
\[ |\sigma^k| = \sqrt{|\det G|} \]
This is exactly what SimplexVolume computes: it first extracts the local edge vectors from the position field, assembles the Gram matrix, and finally takes the square root of its determinant. DualSimplexVolume applies the same formula to the complementary \((n-k)\) directions. The associated dual cell complex is selected through the CellComplex tag, typically circumcentric or barycentric.
Reduction and reconstruction connect pointwise differential-form coefficients and geometric cochains. Reduction integrates a piecewise-constant coefficient form over mesh cells, absorbing their geometry into the cochain values. Primal reconstruction recovers the coefficients by inverting this cell-local map. The CellComplex tag selects the cells used for reduction:
\[ R_k(\omega, \sigma^k) = \int_{\sigma^k} \omega \]
Depending on the chosen CellComplex, \(\sigma^k\) is interpreted as:
CellComplex::Primal,CellComplex::CircumcentricDual,CellComplex::BarycentricDual.For a fixed cell, the reduction of a piecewise-constant form is a linear map between its coefficient basis and the cochain basis. Primal reconstruction inverts that local matrix:
\[ c_I = \sum_J R_{IJ}\,\omega_J,\qquad \omega_J = \sum_I (R^{-1})_{JI}\,c_I. \]
For orthogonal cells this can reduce to division by a cell measure, but a skew geometry can couple different coefficient components. Primal reduction and reconstruction use the position field without a metric. Circumcentric-dual reduction also uses the metric.
In the current implementation:
static_assert.The Hodge star operator is implemented both in continuous and discrete form.
The continuous Hodge star acts pointwise on coefficient forms. It is the exterior-calculus counterpart of the metric. In an \(n\)-dimensional manifold, for a \(k\)-form \(\omega\) with components \(\omega_{i_1 \dots i_k}\), it is defined as ( \(\varepsilon\) is the Levi-Civita symbol):
\[ (\star \omega)_{j_1 \dots j_{n-k}} = \frac{\sqrt{|g|}}{k!} \omega_{i_1 \dots i_k} g^{i_1 \ell_1} \dots g^{i_k \ell_k} \varepsilon_{\ell_1 \dots \ell_k j_1 \dots j_{n-k}}. \]
The discrete Hodge star acts on cochains. For a \(k\)-simplex \(\sigma\) in an \(n\)-dimensional mesh, it is the composition:
For an orthogonal primal and dual pair, this composition gives the usual diagonal DEC factor:
\[ \star_\sigma = \frac{|\star \sigma|}{|\sigma|} \]
This is the adjoint of the coboundary operator in the metric sense. It is built from the discrete Hodge star and the transposed coboundary operator:
\[ \delta = (-1)^{n(k+1)+1}\,\star^{-1}\, d^\top_\mathrm{dual}\, \star, \]
where the "right" Hodge star dualizes the primal \(k\)-cochain and the "left" one brings the result back to the primal side.
The reason this is the adjoint is that the Hodge star defines the inner product \(\langle \alpha,\beta\rangle = \int \alpha \wedge \star \beta\) on differential forms (with \(\wedge\) the exterior product). The codifferential is then characterized by:
\[ \langle d\omega,\eta\rangle = \int d(\omega \wedge \star \eta) - (-1)^k \int \omega \wedge d(\star \eta) = \int \omega \wedge \star\left( (-1)^{n(k+1)+1}\star^{-1} d \star \eta \right) = \langle \omega,\delta\eta\rangle. \]
up to the boundary term and the usual sign convention.
The generic DEC Laplacian combines the exterior derivative and the codifferential:
\[ \Delta = \delta d + d \delta \]