Equation Interface

#About

The Equation interface allows for mapping of FiniteVolumeFields to a system of equations (represented as a sparse matrices) and back again. Several useful functions are already defined for common finite volume operations (divergence, laplacian etc), as well as more specialized functions used for constructing more niche equations (immersed boundary equations, CICSAM/PLIC interface etc). Equation objects of the same type may be added or subtracted to each other. Optionally, an Equation object may contain a shared ownership pointer to a SparseMatrixSolver object, allowing the equation to be solved (this is optional, as an equation may only exist as a temporary object used to store the information of a particular operation).

#Usage

Equations may be constructed line by line if desired (most functions that perform a particular operation utilize this approach). To construct an Equation object, a reference to a FiniteVolumeField must be passed. For example, to construct a Scalar equation (where phi is a previously defined field, and cell is a Cell object from a FiniteVolumeGrid2D):

Equation<Scalar> eqn(phi);
phi.add(cell, cell, -2); //- Add a laplacian central coefficient
phi.addBoundary(cell, 1); //- If cell is a boundary cell, add a boundary value. Actual coefficient depends on the boundary type

Most of the time, numerical PDE's require the solution of several operators. For example, a laplacian, one can simply write

Equation<Scalar> phiEqn(input, comm);
phiEqn = (fv::laplacian(gamma, phi) == 0.);
Scalar error = phiEqn.solve();

Where fv::laplacian is a utility function for constructing the laplacian coefficients. Note that the boundary information for phiEqn would be passed through phi, and that all settings for solving sparse linear systems using any number of available preconditioners/solvers is passed through the input object (see examples). Currently, Phase contains wrappers for Eigen3, HYPRE, Petsc and Trilinos (recommended). It is also important to note that mapping between the FiniteVolumeField and Equation object is done automatically, and that if multiple solves are necessary (eg transient simulations), the Equation object automatically uses the most recent solution as an initial guess (this behaviour can be overridden if desired).