#API reference

Generated by npm run docs from the declaration files (.d.ts) of the public entry points, so it lists what a consumer can import and nothing else. For which operator to use, see Choosing an operator.

Import path	Exports
`traceprojector`	`Projector`, `Mesh`, `validateMeshInput`, `parseGmsh`, `Whitney`, `Locator`, `Refinement`, `Weight`, `Bubble`, `Solver`, `ValidateError`, `ProjectError`, `SingularError`, `H1`, `Hcurl`, `Hdiv`, `L2`, `ZeroTraceProjector`, `BoundedCommutingProjector`, `StableProjector`, `refineTetrahedra`, `CanonicalProjector`, `HigherOrderProjector`, `TracePreservingProjector`
`traceprojector/mesh`	`validateMeshInput`, `Mesh`
`traceprojector/whitney`	`Whitney`
`traceprojector/quadrature`	`triangleQuadrature`, `tetrahedronQuadrature`, `integrateTriangle`, `barycentricToCartesian`, `lineQuadrature`, `compositeTetrahedronQuadrature`, `integrateTetrahedron`
`traceprojector/utils`	`dot`, `cross`, `subtract`, `norm`, `subtractInto`, `crossInto`, `triangleArea`, `zeros`, `infinityNorm`, `luSolve`, `inverse3x3`, `solve3x3`, `MAX_SAFE_FACTORIAL`, `tetDeterminant`, `tetVolume`, `MIN_RELATIVE_VOLUME`, `longestEdge`, `relativeVolume`, `factorial`, `numericalGradient`
`traceprojector/locator`	`Locator`
`traceprojector/generator`	`generateUnitCubeMesh`, `generateSingleTetMesh`
`traceprojector/parallel`	`projectInParallel`, `CoefficientPool`

#`traceprojector`

#`Projector`

export class Projector

TRACEPROJECTOR: Commuting, Discrete-trace Preserving Projections.

Implements the de Rham projection operators Pi^l for l = 0,1,2,3 on tetrahedral meshes with boundary-aware trace preservation.

#`mesh` (property)

mesh: Mesh

#`whitney` (property)

whitney: Whitney

#`constructor`

constructor(
    mesh: Mesh,
    whitney: Whitney,
    options?: {
      quadratureOrder?: number;
      onWarning?: (ctx: {code: string; severity: 'warn' | 'error'; message: string}) => void;
    },
  )

#`buildLocator`

buildLocator(): void

Builds the AABB tree for point location. Must be called before projectAtPoint if the tree was not built automatically.

#`computeBoundaryWeights`

computeBoundaryWeights(): void

Section 6.3.1: Construction of lowest-order vertex weights. Computes boundary-aware weights for trace-preserving projections.

#`verifyBoundaryWeights`

verifyBoundaryWeights(tol?: number): {
    ok: boolean;
    passed: number;
    failing: number;
    checks: Array<{
      l: number;
      idx: number;
      edge?: number;
      expected: number;
      got: number;
    }>;
  }

Cross-checks the projected (exact) boundary degrees of freedom against the Section 6.3 boundary weights. Applies each wired weight functional to its boundary simplex's canonical exact trace basis field and verifies it recovers the normalized DoF (1), without altering how DoFs are computed. Call computeBoundaryWeights() first.

Parameters

tol: Absolute tolerance (default 1e-6).

Returns Result object with ok, passed, failing, and the per-simplex checks.

#`projectH1`

projectH1(u: (point: number[]) => number, point: number[], tIdx: number): number

H1 projection (l=0) of a scalar field.

Parameters

u: Scalar function.
point: Cartesian point [x, y, z].
tIdx: Tetrahedron index.

Returns Projected scalar value.

#`projectHcurl`

projectHcurl(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
  ): number[]

H(curl) projection (l=1). Boundary edges use exact trace DoFs ∫_e u·t ds. Interior edges use midpoint evaluation.

Parameters

u: Scalar or vector function.
point: Cartesian point [x, y, z].
tIdx: Tetrahedron index.

Returns Projected vector [vx, vy, vz].

#`projectHdiv`

projectHdiv(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
  ): number[]

H(div) projection (l=2). Boundary faces use exact trace DoFs ∫_f u·n dA. Interior faces use barycenter evaluation.

Parameters

u: Scalar or vector function.
point: Cartesian point [x, y, z].
tIdx: Tetrahedron index.

Returns Projected vector [vx, vy, vz].

#`projectL2`

projectL2(u: (point: number[]) => number, tIdx: number): number

L2 projection (l=3).

Parameters

u: Scalar function.
tIdx: Tetrahedron index.

Returns Projected scalar value (average over tet).

#`projectHp`

projectHp(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
    l: number,
    p: number,
  ): number | number[]

Higher-order projection.

Parameters

u: Scalar or vector function.
point: Cartesian point [x, y, z].
tIdx: Tetrahedron index.
l: Form degree (0=H1 scalar, 1=Hcurl vector, 2=Hdiv vector, 3=L2 scalar).
p: Polynomial degree (0 returns lowest-order projection).

Returns Projected value (number for l=0 or l=3, 3-vector for l=1 or l=2).

#`extractBoundaryDofs`

extractBoundaryDofs(
    u: (point: number[]) => number | number[],
    l: number,
  ): Map<number, number>

Extracts the boundary degrees of freedom for a given function.

Parameters

u: Scalar or vector function.
l: Form degree (0,1,2,3).

Returns Map from boundary entity index to DoF value.

#`projectRing`

projectRing(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
    l: number,
  ): number | number[]

Pi_ring^l: interior projector with zero boundary trace.

Parameters

u: Scalar or vector function.
point: Cartesian point [x, y, z].
tIdx: Tetrahedron index.
l: Form degree (0,1,2,3).

Returns Projected value (number for l=0 or l=3, 3-vector for l=1 or l=2).

#`extendBoundary`

extendBoundary(
    boundaryData: Map<number, number>,
    point: number[],
    tIdx: number,
    l: number,
  ): number | number[]

E^l: discrete extension operator. Takes boundary DoFs and produces a Whitney form whose trace on the boundary equals the given data.

Parameters

boundaryData: Map from boundary entity index to DoF.
point: Cartesian point [x, y, z].
tIdx: Tetrahedron index.
l: Form degree (0,1,2).

Returns Extended value.

#`projectPartial`

projectPartial(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
    l: number,
  ): number | number[]

Pi_partial^l: boundary correction part of the projection. Computes the discrete extension of the boundary trace of u.

Parameters

u: Scalar or vector function.
point: Cartesian point [x, y, z].
tIdx: Tetrahedron index.
l: Form degree (0,1,2,3).

Returns Boundary correction value.

#`projectAtPoint`

projectAtPoint(
    u: (point: number[]) => number | number[],
    point: number[],
    l?: number,
    p?: number,
  ): {
    value: number | number[];
    tIdx: number;
    bary: number[];
  }

Finds the tetrahedron containing the point and projects.

Parameters

u: Scalar or vector function.
point: Cartesian point [x, y, z].
l: Form degree (default 0).
p: Polynomial degree (default 0).

Returns Object with projected value, tetrahedron index, and barycentric coordinates.

#`sampler`

sampler(
    points: number[][],
    l?: number,
    p?: number,
  ): (u: (point: number[]) => number | number[]) => Array<number | number[]>

Locates the points once and returns a function that projects successive fields at them, for fields that evolve between time steps.

Parameters

points: Points inside the mesh.
l: Form degree (default 0).
p: Polynomial degree (default 0).

#`refine`

refine(marked: number[]): { projector: Projector; parent: number[] }

A projector on the mesh obtained by bisecting the marked cells; the boundary weights are recomputed for the new mesh.

Parameters

marked: Cells to bisect.

Returns The projector on the refined mesh, and the coarse cell each new cell came from.

#`Mesh`

export class Mesh

Tetrahedral mesh data structure with topological connectivity and boundary extraction.

#`vertices` (property)

vertices: number[][]

Vertex coordinates.

#`tetrahedra` (property)

tetrahedra: number[][]

Tetrahedron vertex indices.

#`originalVertexCount` (property)

readonly originalVertexCount: number

Number of vertices in the original (unrefined) mesh.

#`vertexCount` (property)

vertexCount: number

Current total number of vertices (includes refinements).

#`tetrahedronCount` (property)

readonly tetrahedronCount: number

Number of tetrahedra.

#`faces` (property)

faces: number[][]

Global faces as vertex index triples.

#`edges` (property)

edges: number[][]

Global edges as vertex index pairs.

#`boundaryFaces` (property)

boundaryFaces: number[]

Global indices of boundary faces.

#`boundaryEdges` (property)

boundaryEdges: number[]

Global indices of boundary edges.

#`boundaryNodes` (property)

boundaryNodes: Set<number>

Global vertex indices on the boundary.

#`faceToTets` (property)

faceToTets: number[][]

Maps each face index to the tetrahedra that contain it.

#`edgeToFaces` (property)

edgeToFaces: number[][]

Maps each edge index to the faces that contain it.

#`vertexToTets` (property)

vertexToTets: number[][]

Maps each vertex to the tetrahedra that contain it.

#`vertexToBoundaryFaces` (property)

vertexToBoundaryFaces: number[][]

Maps each vertex to the boundary faces that contain it.

#`vertexToEdges` (property)

vertexToEdges: number[][]

Maps each vertex to the edges that contain it.

#`constructor`

constructor(vertices: number[][], tetrahedra: number[][])

Parameters

vertices: Vertex coordinates.
tetrahedra: Tetrahedron vertex indices.

#`getFaceArea`

getFaceArea(fIdx: number): number

Returns the geometric area of a face.

#`getEdgeIndex`

getEdgeIndex(edgeKey: number): number | undefined

Looks up the global edge index for an edge key.

#`getFaceIndex`

getFaceIndex(faceKey: number): number | undefined

Looks up the global face index for a face key.

#`getTetEdgeSign`

getTetEdgeSign(tIdx: number, e: number): number

Returns the edge orientation sign for a local edge within a tetrahedron.

#`getTetFaceSign`

getTetFaceSign(tIdx: number, f: number): number

Returns the face orientation sign for a local face within a tetrahedron.

#`getVertices`

getVertices(): number[][]

Returns all vertex coordinates.

#`getTetrahedra`

getTetrahedra(): number[][]

Returns all tetrahedra as vertex index arrays.

#`getFaces`

getFaces(): number[][]

Returns all faces as vertex index triples.

#`getEdges`

getEdges(): number[][]

Returns all edges as vertex index pairs.

#`getBoundaryNodes`

getBoundaryNodes(): Set<number>

Returns the set of boundary node indices.

#`getBoundaryFaces`

getBoundaryFaces(): number[]

Returns the array of boundary face indices.

#`getBoundaryEdges`

getBoundaryEdges(): number[]

Returns the array of boundary edge indices.

#`getOriginalVertexCount`

getOriginalVertexCount(): number

Returns the original vertex count before refinement.

#`getFaceBarycenter`

getFaceBarycenter(fIdx: number): number[]

Returns the barycenter of a face.

#`getTetrahedronBarycenter`

getTetrahedronBarycenter(tIdx: number): number[]

Returns the barycenter of a tetrahedron.

#`getStar`

getStar(vIdx: number): number[]

Returns the star (incident tets) of a vertex.

#`getBoundaryStar`

getBoundaryStar(vIdx: number): number[]

Returns the boundary faces incident to a vertex.

#`getEdgeStar`

getEdgeStar(vIdx: number): number[]

Returns the edges incident to a vertex.

#`getVolume`

getVolume(tIdx: number): number

Returns the volume of a tetrahedron.

#`getTetrahedronFaces`

getTetrahedronFaces(tIdx: number): number[]

Returns the global face indices of a tetrahedron's four faces.

#`getFaceOutwardNormal`

getFaceOutwardNormal(fIdx: number): number[]

Computes the outward-pointing unit normal for a boundary face. For interior faces the orientation is arbitrary.

#`validateMeshInput`

function validateMeshInput(
  vertices: number[][],
  tetrahedra: number[][],
  options?: { allowFlipped?: boolean },
): void

Checks vertices and tetrahedra and throws a ValidateError naming the first problem: a malformed or non-finite coordinate, an index that is not an integer or does not name a vertex, a repeated vertex, or a tetrahedron with degenerate volume. By default a tetrahedron must also be positively oriented, as Mesh and Projector require. The operators that take vertices and tetrahedra call it with allowFlipped because they give the same answer for either orientation.

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
options.allowFlipped: Accept negatively oriented tetrahedra (default false).

#`parseGmsh`

function parseGmsh(
  text: string,
  options?: { orient?: boolean },
): {
  vertices: number[][];
  tetrahedra: number[][];
  skipped: Record<string, number>;
}

Reads a Gmsh mesh file (ASCII formats 2.x and 4.1) into the two arrays every operator takes. Only first-order tetrahedra (element type 4) become cells; points, lines and triangles are counted in skipped. Binary files, other versions, hexahedra, prisms, pyramids and second-order tetrahedra raise a ValidateError, as does any file whose tetrahedra do not make a valid mesh.

Parameters

text: The contents of the .msh file.
options.orient: Reorder the vertices of negatively oriented tetrahedra so that all are positively oriented, as Mesh and Projector require (default true).

Returns The mesh and how many elements of each ignored kind the file held.

#`Whitney`

export class Whitney

Whitney forms and barycentric coordinate utilities on a tetrahedral mesh.

#`constructor`

constructor(mesh: Mesh)

#`getBarycentric`

getBarycentric(tIdx: number, point: number[]): number[]

Computes barycentric coordinates of a point with respect to a tetrahedron.

Parameters

tIdx: Tetrahedron index.
point: Cartesian point [x, y, z].

Returns Barycentric coordinates [lambda0, lambda1, lambda2, lambda3].

#`getGradBarycentric`

getGradBarycentric(tIdx: number): number[][]

Computes gradients of the barycentric coordinate functions.

Parameters

tIdx: Tetrahedron index.

Returns Four gradient vectors, one per vertex.

#`getEdgeBasis`

getEdgeBasis(tIdx: number, bary: number[]): number[][]

Edge-based Whitney 1-form (Nedelec) basis functions.

For edge e = (i, j): phi_e = lambda_i * grad(lambda_j) - lambda_j * grad(lambda_i)

Parameters

tIdx: Tetrahedron index.
bary: Barycentric coordinates at which to evaluate.

Returns Six edge basis vectors in order [0,1], [0,2], [0,3], [1,2], [1,3], [2,3].

#`getFaceBasis`

getFaceBasis(tIdx: number, bary: number[]): number[][]

Face-based Raviart-Thomas (Whitney 2-form) basis functions.

Parameters

tIdx: Tetrahedron index.
bary: Barycentric coordinates at which to evaluate.

Returns Four face basis vectors indexed by opposite vertex: 0, 1, 2, 3.

#`Locator`

export class Locator

Axis-aligned bounding box (AABB) tree for fast point-in-tetrahedron queries.

Recursively partitions the mesh bounding box to achieve O(log N) search.

#`constructor`

constructor(mesh: Mesh, maxLeafSize?: number)

Parameters

mesh: The mesh to index.
maxLeafSize: Maximum tets per leaf node (default 8).

#`findTetrahedron`

findTetrahedron(point: number[]): {
    tIdx: number;
    bary: number[];
  } | null

Finds the tetrahedron containing the given point.

Parameters

point: Cartesian point [x, y, z].

Returns Object with tetrahedron index and barycentric coordinates, or null if not found.

#`Refinement`

export class Refinement

Mesh refinement operators: Alfeld face splitting and Worsey-Farin tetrahedron splitting.

This class mutates the underlying Mesh by appending barycenter vertices. It stores the refinement data (sub-triangles, sub-tetrahedra) separately so that Mesh remains a pure data structure.

#`constructor`

constructor(mesh: Mesh)

#`faceBarycenters` (property)

faceBarycenters: number[]

Face barycenter vertex indices (mutated during split).

#`tetBarycenters` (property)

tetBarycenters: number[]

Tetrahedron barycenter vertex indices (mutated during split).

#`alfeldTriangles` (property)

alfeldTriangles: Array<{
    parentFaceIdx: number;
    triangles: number[][];
  }>

Alfeld-split triangles for each boundary face.

#`faceToAlfeld` (property)

faceToAlfeld: Map<number, {parentFaceIdx: number; triangles: number[][]}>

Maps parent face index to its Alfeld split data.

#`worseyFarinTetrahedra` (property)

worseyFarinTetrahedra: Array<{
    parentTetIdx: number;
    tetrahedra: number[][];
  }>

Worsey-Farin sub-tetrahedra for each parent tet.

#`computeAlfeldSplit`

computeAlfeldSplit(): void

Section 6.1.3: Alfeld split of boundary faces.

Mutates mesh.vertices by appending face barycenters.

#`computeWorseyFarinSplit`

computeWorseyFarinSplit(): void

Section 6.1.4: Worsey-Farin split of tetrahedra.

Mutates mesh.vertices by appending face and tetrahedron barycenters. Calls computeAlfeldSplit() if not already done.

#`Weight`

export class Weight

Boundary weight computation for Projector projections.

Computes the Section 6.3 vertex/edge/face duality functionals plus edge tangents/lengths and face normals/areas used by trace-preserving DoFs.

#`constructor`

constructor(
    mesh: Mesh,
    onWarning?: (ctx: {code: string; severity: 'warn' | 'error'; message: string}) => void,
  )

Parameters

mesh: The mesh.
onWarning: Optional warning callback.

#`compute`

compute(): {
    edgeBoundaryData: Map<
      number,
      {v0: number; v1: number; tangent: number[]; length: number}
    >;
    faceBoundaryData: Map<number, {normal: number[]; area: number}>;
    vertexBoundaryWeights: Map<
      number,
      {
        pair: (u: (point: number[]) => number[]) => number;
        integral: number;
        psi: number[];
        faces: number[][];
      }
    >;
    edgeBoundaryWeights: Map<
      number,
      {
        ePair: number[];
        pair: (u: (point: number[]) => number[]) => number;
        edges: number[][];
        eta: number[];
      }
    >;
    faceBoundaryWeights: Map<
      number,
      {
        face: number[];
        pair: (u: (point: number[]) => number[]) => number;
        nBasis: number;
      }
    >;
  }

Computes all boundary weights.

Returns Object containing edgeBoundaryData, faceBoundaryData, and the Section 6.3 vertex/edge/face duality-functional maps.

#`Bubble`

export class Bubble

Higher-Order Projection Framework (Section 7).

For p >= 1, the projection Pi^l_p is built recursively from the lowest-order projection Pi^l_0 by adding bubble corrections on Alfeld-split patches.

#`constructor`

constructor(
    mesh: Mesh,
    whitney: Whitney,
    quadratureOrder?: number,
    onWarning?: (ctx: {code: string; severity: 'warn' | 'error'; message: string}) => void,
  )

Parameters

mesh: The mesh.
whitney: Whitney form utilities.
quadratureOrder: Quadrature order (default 3).
onWarning: Optional warning callback.

#`evaluateBubbleBasis`

evaluateBubbleBasis(bary: number[], p: number): number[]

Evaluates the scalar bubble basis at a point given in barycentric coords.

Parameters

bary: Barycentric coordinates [lambda0, lambda1, lambda2, lambda3].
p: Polynomial degree.

Returns Bubble basis values.

#`assembleBubbleMass`

assembleBubbleMass(tIdx: number, p: number): number[][]

Assembles the local mass matrix for the bubble space.

Parameters

tIdx: Tetrahedron index.
p: Polynomial degree.

Returns Mass matrix.

#`assembleBubbleRhs`

assembleBubbleRhs(
    tIdx: number,
    p: number,
    residualFn: (point: number[]) => number,
  ): number[]

Assembles the RHS for bubble projection.

Parameters

tIdx: Tetrahedron index.
p: Polynomial degree.
residualFn: Residual function.

Returns RHS vector.

#`solveBubbleProjection`

solveBubbleProjection(
    tIdx: number,
    p: number,
    residualFn: (point: number[]) => number,
  ): number[] | null

Solves for bubble coefficients.

Parameters

tIdx: Tetrahedron index.
p: Polynomial degree.
residualFn: Residual function.

Returns Bubble coefficients, or null if p < 4 or solve fails.

#`evaluateBubble`

evaluateBubble(
    tIdx: number,
    p: number,
    coeffs: number[],
    point: number[],
  ): number

Evaluates the bubble correction at a point.

Parameters

tIdx: Tetrahedron index.
p: Polynomial degree.
coeffs: Bubble coefficients.
point: Cartesian point [x, y, z].

Returns Bubble correction value.

#`evaluateBernsteinBasis`

evaluateBernsteinBasis(bary: number[], p: number): number[]

Evaluates the P^p Bernstein basis at barycentric coordinates.

Parameters

bary: Barycentric coordinates.
p: Polynomial degree.

Returns Bernstein basis values.

#`solveL2Projection`

solveL2Projection(
    tIdx: number,
    p: number,
    u: (point: number[]) => number,
  ): number[]

Solves the L2 projection of u onto P^p(T) using the Bernstein basis.

Parameters

tIdx: Tetrahedron index.
p: Polynomial degree.
u: Scalar function to project.

Returns Coefficients of the Bernstein basis.

#`evaluateL2Projection`

evaluateL2Projection(coeffs: number[], bary: number[], p: number): number

Evaluates the L2 projection at a point.

Parameters

coeffs: Bernstein coefficients.
bary: Barycentric coordinates.
p: Polynomial degree.

Returns Projected value.

#`Solver`

export class Solver

Local patch stiffness assembly and constrained solves for boundary weight computation.

#`assembleSurfaceStiffness`

static assembleSurfaceStiffness(
    vertices: number[][],
    triangles: number[][],
  ): number[][]

Assembles the surface stiffness matrix for -Delta_Gamma.

Parameters

vertices: Patch vertex coordinates.
triangles: Patch triangles as local vertex indices.

Returns Dense stiffness matrix.

#`solveWithConstraint`

static solveWithConstraint(
    K: number[][],
    b: number[],
    onWarning?: (ctx: {code: string; severity: 'warn' | 'error'; message: string}) => void,
  ): number[]

Solves K x = b with a mean-zero constraint sum(x) = 0.

Parameters

K: Stiffness matrix.
b: Right-hand side vector.
onWarning: Optional warning callback.

Returns Solution vector.

#`ValidateError`

export class ValidateError extends Error

Thrown when mesh input data fails validation.

#`constructor`

constructor(message: string, index?: number)

Parameters

message: Error message.
index: The offending element index, if applicable.

#`name` (property)

name: 'ValidateError'

#`index` (property)

index?: number

The offending element index, if applicable.

#`ProjectError`

export class ProjectError extends Error

Thrown when a projection cannot be computed.

#`constructor`

constructor(message: string)

#`name` (property)

name: 'ProjectError'

#`SingularError`

export class SingularError extends Error

Thrown when a linear system is singular or numerically ill-conditioned.

#`constructor`

constructor(message: string)

#`name` (property)

name: 'SingularError'

#`H1`

export class H1

#`constructor`

constructor(mesh: Mesh, whitney: Whitney)

#`project`

project(u: (point: number[]) => number, point: number[], tIdx: number): number

#`computeBoundaryIntegralH1`

computeBoundaryIntegralH1(
    vIdx: number,
    u: (point: number[]) => number,
  ): number

#`projectRing`

projectRing(
    u: (point: number[]) => number,
    point: number[],
    tIdx: number,
  ): number

#`extendBoundary`

extendBoundary(
    boundaryData: Map<number, number>,
    point: number[],
    tIdx: number,
  ): number

#`Hcurl`

export class Hcurl

#`constructor`

constructor(mesh: Mesh, whitney: Whitney, quadratureOrder: number)

#`project`

project(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
    boundaryEdgeSet: Set<number>,
  ): number[]

#`computeEdgeDof`

computeEdgeDof(
    u: (point: number[]) => number | number[],
    eIdx: number,
  ): number

#`projectRing`

projectRing(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
    boundaryEdgeSet: Set<number>,
  ): number[]

#`extendBoundary`

extendBoundary(
    boundaryData: Map<number, number>,
    point: number[],
    tIdx: number,
    boundaryEdgeSet: Set<number>,
  ): number[]

#`Hdiv`

export class Hdiv

#`constructor`

constructor(mesh: Mesh, whitney: Whitney, quadratureOrder: number)

#`project`

project(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
    boundaryFaceSet: Set<number>,
  ): number[]

#`computeFaceDof`

computeFaceDof(
    u: (point: number[]) => number | number[],
    fIdx: number,
  ): number

#`projectRing`

projectRing(
    u: (point: number[]) => number | number[],
    point: number[],
    tIdx: number,
    boundaryFaceSet: Set<number>,
  ): number[]

#`extendBoundary`

extendBoundary(
    boundaryData: Map<number, number>,
    point: number[],
    tIdx: number,
    boundaryFaceSet: Set<number>,
  ): number[]

#`L2`

export class L2

#`constructor`

constructor(mesh: Mesh, whitney: Whitney, quadratureOrder: number)

#`project`

project(u: (point: number[]) => number, tIdx: number): number

#`ZeroTraceProjector`

export class ZeroTraceProjector

Locally L2-bounded commuting projections onto the lowest-order Whitney spaces with zero trace on the whole boundary (arXiv:2502.03601, Thm 6.1, p = 0). The coefficients are integrals of the input against local weight functions, so the input needs only to be in L2.

#`constructor`

constructor(
    vertices: number[][],
    tetrahedra: number[][],
    options?: { quadratureOrder?: number; boundaryConditions?: boolean },
  )

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
options.quadratureOrder: Gauss points per direction for the weight integrals (default 4).

#`coefficient`

coefficient(u: (point: number[]) => number | number[], l: number, index: number): number

Coefficient of the Whitney form of an entity: the integral of the input against the entity's weight.

Parameters

u: Scalar (l = 0, 3) or vector (l = 1, 2) field.
l: Form degree.
index: Entity number in the projector's complex.

#`project`

project(
    u: (point: number[]) => number | number[],
    point: number[],
    cell: number,
    l: number,
  ): number | number[]

Value of the projection at a point of a cell.

Parameters

u: Scalar (l = 0, 3) or vector (l = 1, 2) field.
point: Cartesian point inside the cell.
cell: Cell number.
l: Form degree.

#`count`

count(l: number): number

Number of entities of form degree l in the projector's numbering: the vertices (0), edges (1), faces (2) or cells (3). The entity numbers that coefficient takes run from 0 to this count minus one.

Parameters

l: Form degree, 0 to 3.

#`edge`

edge(index: number): [number, number]

The two vertices of an edge, in the numbering of the input mesh.

Parameters

index: Edge number, from 0 to count(1) - 1.

#`BoundedCommutingProjector`

export class BoundedCommutingProjector extends ZeroTraceProjector

Locally L2-bounded projections onto the lowest-order Whitney spaces that commute with the exterior derivative for every input, without boundary conditions (arXiv:2502.03601, Thm 5.1, p = 0). The input needs only to be in L2, on the boundary as well. Traces are not preserved.

#`constructor`

constructor(
    vertices: number[][],
    tetrahedra: number[][],
    options?: { quadratureOrder?: number },
  )

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
options.quadratureOrder: Gauss points per direction (default 4).

#`StableProjector`

export class StableProjector

Commuting, discrete-trace preserving projection with a stable interior part: Pi u = Pi_boundary u + Pi_zero (u - Pi_boundary u).

The interior part is the locally L2-bounded zero-trace projection of ZeroTraceProjector, so inputs that are unbounded at an interior mesh vertex are projected stably. The boundary part uses canonical degrees of freedom (point values, edge integrals, face fluxes), so the input must have finite such values on the boundary; the paper's weight-based boundary operator, which tolerates rough boundary data, is not implemented. The projection commutes with the exterior derivative for fields with a piecewise polynomial trace.

#`constructor`

constructor(
    vertices: number[][],
    tetrahedra: number[][],
    options?: { quadratureOrder?: number; interior?: ZeroTraceProjector },
  )

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
options.quadratureOrder: Gauss points per direction (default 4).
options.interior: An existing zero-trace projector on the same mesh, to share its weights.

#`coefficient`

coefficient(u: (point: number[]) => number | number[], l: number, entity: number): number

Coefficient of the Whitney form of an entity in the projection of u.

#`project`

project(
    u: (point: number[]) => number | number[],
    point: number[],
    cell: number,
    l: number,
  ): number | number[]

Value of the projection at a point of a cell.

Parameters

u: Scalar (l = 0, 3) or vector (l = 1, 2) field.
point: Cartesian point inside the cell.
cell: Cell number.
l: Form degree.

#`count`

count(l: number): number

Number of entities of form degree l in the projector's numbering: the vertices (0), edges (1), faces (2) or cells (3). The entity numbers that coefficient takes run from 0 to this count minus one.

Parameters

l: Form degree, 0 to 3.

#`edge`

edge(index: number): [number, number]

The two vertices of an edge, in the numbering of the input mesh.

Parameters

index: Edge number, from 0 to count(1) - 1.

#`refineTetrahedra`

function refineTetrahedra(
  vertices: number[][],
  tetrahedra: number[][],
  marked: number[],
): { vertices: number[][]; tetrahedra: number[][]; parent: number[] }

Conforming adaptive refinement by longest-edge bisection (Rivara): bisects the marked cells, first bisecting any neighbour around the longest edge that has a different longest edge, so no hanging node is created.

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
marked: Cells to bisect.

Returns The refined mesh (original vertices first) and, for every new cell, the cell of the input it came from.

#`CanonicalProjector`

export class CanonicalProjector

Canonical (Arnold-Falk-Winther) interpolation onto the polynomial spaces P_r^- Lambda^k of any degree r = p + 1: Lagrange (l = 0), Nedelec of the first kind (l = 1), Raviart-Thomas (l = 2) and discontinuous (l = 3) elements. It is a projection, preserves the boundary trace and commutes with the exterior derivative; the degrees of freedom are moments of the pull-back of the input to each edge, face and cell, so the input must be regular enough for them to exist and the operator is not L2-stable.

#`constructor`

constructor(
    vertices: number[][],
    tetrahedra: number[][],
    options?: { degree?: number; quadratureOrder?: number },
  )

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
options.degree: Polynomial degree p of the library's convention (default 0, the Whitney space).
options.quadratureOrder: Gauss points per direction.

#`size`

size(l: number): number

Number of degrees of freedom in form degree l.

#`coefficients`

coefficients(u: (point: number[]) => number | number[], l: number): Float64Array

All canonical degrees of freedom of the input.

Parameters

u: Scalar field for l = 0, 3 and vector field for l = 1, 2.
l: Form degree.

#`evaluate`

evaluate(coefficients: Float64Array, point: number[], cell: number, l: number): number | number[]

Value of the interpolant with the given coefficients at a point of a cell.

Parameters

coefficients: From coefficients.

#`derivative`

derivative(coefficients: Float64Array, point: number[], cell: number, l: number): number | number[]

Value of the exterior derivative of the interpolant: the gradient (l = 0), the curl (l = 1) or the divergence (l = 2).

#`project`

project(u: (point: number[]) => number | number[], point: number[], cell: number, l: number): number | number[]

Value of the interpolant of u at a point of a cell.

#`HigherOrderProjector`

export class HigherOrderProjector

Locally L2-bounded commuting projections onto the finite element spaces of degree p + 1 (Lagrange, Nedelec, Raviart-Thomas, discontinuous), after Arnold and Guzman (ESAIM M2AN 55, 2021): pi = P + Q (I - P), with P the lowest-order projection built from local weight functions and Q the correction onto the forms without lowest-order degrees of freedom. It is a projection, commutes with the exterior derivative for every L2 input with an L2 derivative, and each coefficient depends only on the input near its entity. The weights are sparse local solves (a few seconds each at p = 1), and the mesh must be fine enough that its extended stars are balls. It does not preserve nonzero boundary traces; with boundaryConditions it maps into the forms with zero trace.

#`constructor`

constructor(
    vertices: number[][],
    tetrahedra: number[][],
    options?: {
      degree?: number;
      quadratureOrder?: number;
      boundaryConditions?: boolean;
    },
  )

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
options.degree: Polynomial degree p (default 0; the spaces have degree p + 1).
options.quadratureOrder: Gauss points per direction.
options.boundaryConditions: Zero trace on the boundary of the domain: the weights of boundary entities vanish (default false).

#`local`

local(
    u: (point: number[]) => number | number[],
    l: number,
  ): {
    value: (point: number[], cell: number) => number | number[];
    derivative: (point: number[], cell: number) => number | number[];
  }

Lazy evaluation of the projection of a field: only the coefficients that a cell needs are computed.

Parameters

u: Scalar field for l = 0, 3 and vector field for l = 1, 2.
l: Form degree.

Returns Functions giving the value of the projection, and of its exterior derivative (gradient, curl or divergence), at a point of a cell.

#`coefficients`

coefficients(
    u: (point: number[]) => number | number[],
    l: number,
  ): { lowest: Float64Array; correction: Float64Array }

All coefficients of the projection: those on the Whitney forms and those of the correction on the basis of the space of degree l.

#`evaluate`

evaluate(
    coefficients: { lowest: Float64Array; correction: Float64Array },
    point: number[],
    cell: number,
    l: number,
  ): number | number[]

Value of the projection with the given coefficients at a point of a cell.

#`TracePreservingProjector`

export class TracePreservingProjector

The full trace-preserving projection of Ern, Guzman, Potu and Vohralik: Pi = mPi (I - Pi_boundary) + Pi_boundary. It is a projection onto the finite element spaces of degree p + 1, preserves the discrete trace on the boundary and commutes with the exterior derivative for fields whose trace is a discrete trace; each value depends on a patch of cells around its point. It needs a mesh fine enough that the extended stars are balls.

At degree: 0 (the default) the spaces are the Whitney forms and the projection has coefficients on their basis. At degree >= 1 the projection is evaluated field by field with local.

#`constructor`

constructor(
    vertices: number[][],
    tetrahedra: number[][],
    options?: { quadratureOrder?: number; degree?: number },
  )

Parameters

vertices: Vertex coordinates.
tetrahedra: Four vertex numbers per tetrahedron.
options.quadratureOrder: Gauss points per direction (default 4). The commuting identities hold up to the quadrature error of the field: raise it for fields of high polynomial degree.
options.degree: Polynomial degree p (default 0, the Whitney forms; the spaces have degree p + 1).

#`local`

local(
    u: (point: number[]) => number | number[],
    du: ((point: number[]) => number | number[]) | null,
    l: number,
  ): {
    value: (point: number[], cell: number) => number | number[];
    derivative: (point: number[], cell: number) => number | number[];
  }

Pi u as a lazy field: its value and its exterior derivative at a point of a cell. At degree > 0 this is how the operator is evaluated.

#`coefficients`

coefficients(
    u: (point: number[]) => number | number[],
    du: ((point: number[]) => number | number[]) | null,
    l: number,
  ): Float64Array

All Whitney coefficients of the projection in degree l.

Parameters

u: Scalar (l = 0, 3) or vector (l = 1, 2) field.
du: Its derivative: the gradient (l = 0), the curl (l = 1) or the divergence (l = 2); unused for l = 3.
l: Form degree.

#`coefficient`

coefficient(
    u: (point: number[]) => number | number[],
    du: ((point: number[]) => number | number[]) | null,
    l: number,
    entity: number,
  ): number

One Whitney coefficient of the projection, computed without the others.

Parameters

entity: Entity number in the projector's complex.

#`project`

project(
    u: (point: number[]) => number | number[],
    du: ((point: number[]) => number | number[]) | null,
    point: number[],
    cell: number,
    l: number,
  ): number | number[]

Value of the projection at a point of a cell.

Parameters

cell: Cell number.
l: Form degree.

#`traceprojector/mesh`

#`validateMeshInput`

The same as validateMeshInput above.

#`Mesh`

The same as Mesh above.

#`traceprojector/whitney`

#`Whitney`

The same as Whitney above.

#`traceprojector/quadrature`

#`triangleQuadrature`

function triangleQuadrature(order: number): {
  bary: number[][];
  weights: number[];
}

Returns quadrature points and weights on the reference triangle. Weights are normalized so that sum(w_i) = 1.

Parameters

order: Target polynomial exactness (1, 2, or 3).

#`tetrahedronQuadrature`

function tetrahedronQuadrature(order: number): {
  bary: number[][];
  weights: number[];
}

Returns quadrature points and weights on the reference tetrahedron. Weights are normalized so that sum(w_i) = 1.

Parameters

order: Target polynomial exactness (1, 2, or 3).

#`integrateTriangle`

function integrateTriangle(
  vertices: number[][],
  fn: (point: number[]) => number,
  order?: number,
): number

Integrates a scalar function over a triangle using quadrature.

Parameters

vertices: Triangle vertices.
fn: Scalar function.
order: Quadrature order (default 2).

#`barycentricToCartesian`

function barycentricToCartesian(
  vertices: number[][],
  bary: number[],
): number[]

Maps barycentric coordinates to a Cartesian point.

Parameters

vertices: Vertices of the element.
bary: Barycentric coordinates.

#`lineQuadrature`

function lineQuadrature(order: number): {
  points: number[];
  weights: number[];
}

Returns quadrature points and weights on the reference interval [0, 1].

Parameters

order: Target polynomial exactness (1, 2, or 3).

#`compositeTetrahedronQuadrature`

function compositeTetrahedronQuadrature(order?: number): {
  bary: number[][];
  weights: number[];
}

Returns a composite quadrature rule by subdividing the reference tetrahedron into 4 sub-tetrahedra via the centroid and applying the base rule on each.

Parameters

order: Base quadrature order.

#`integrateTetrahedron`

function integrateTetrahedron(
  vertices: number[][],
  fn: (point: number[]) => number,
  order?: number,
): number

Integrates a scalar function over a tetrahedron using quadrature.

Parameters

vertices: Tetrahedron vertices.
fn: Scalar function.
order: Quadrature order (default 2).

#`traceprojector/utils`

#`dot`

function dot(a: number[], b: number[]): number

Computes the dot product of two 3D vectors.

#`cross`

function cross(a: number[], b: number[]): number[]

Computes the cross product of two 3D vectors.

#`subtract`

function subtract(a: number[], b: number[]): number[]

Subtracts vector b from vector a.

#`norm`

function norm(v: number[]): number

Computes the Euclidean norm of a vector.

#`subtractInto`

function subtractInto(a: number[], b: number[], out: number[]): number[]

In-place vector subtraction: out = a - b.

#`crossInto`

function crossInto(a: number[], b: number[], out: number[]): number[]

In-place cross product: out = a x b.

#`triangleArea`

function triangleArea(p1: number[], p2: number[], p3: number[]): number

Computes the area of a triangle given its three vertices.

#`zeros`

function zeros(rows: number, cols: number): number[][]

Creates a zero-initialized dense matrix.

#`infinityNorm`

function infinityNorm(a: number[][]): number

Computes the infinity norm (maximum absolute row sum) of a matrix.

#`luSolve`

function luSolve(a: number[][], b: number[]): number[]

Solves Ax = b using Gaussian elimination with partial pivoting and row equilibration (pivot scaling).

Parameters

a: Dense square matrix (not modified).
b: Right-hand side vector.

Returns Solution vector x.

#`inverse3x3`

function inverse3x3(m: number[][]): number[][]

Computes the inverse of a 3x3 matrix.

#`solve3x3`

function solve3x3(a: number[][], b: number[]): number[]

Solves a 3x3 linear system Ax = b using Cramer's rule.

#`MAX_SAFE_FACTORIAL`

const MAX_SAFE_FACTORIAL: number

Maximum n for which n! fits in a JavaScript Number without overflowing.

#`tetDeterminant`

function tetDeterminant(v0: number[], v1: number[], v2: number[], v3: number[]): number

Computes the determinant (scalar triple product) of a tetrahedron.

#`tetVolume`

function tetVolume(v0: number[], v1: number[], v2: number[], v3: number[]): number

Computes the geometric volume of a tetrahedron.

#`MIN_RELATIVE_VOLUME`

const MIN_RELATIVE_VOLUME: number

Smallest accepted ratio of a tetrahedron's volume determinant to the cube of its longest edge. Independent of the unit system.

#`longestEdge`

function longestEdge(vertices: number[][]): number

Length of the longest edge of a tetrahedron.

Parameters

vertices: The four vertices.

#`relativeVolume`

function relativeVolume(vertices: number[][]): number

Signed volume determinant divided by the cube of the longest edge: a dimensionless measure of how far a tetrahedron is from flat.

Parameters

vertices: The four vertices.

#`factorial`

function factorial(n: number): number

Computes the factorial n!.

#`numericalGradient`

function numericalGradient(u: (pt: number[]) => number, pt: number[], h?: number): number[]

Numerical gradient of a scalar function using central differences.

#`traceprojector/locator`

#`Locator`

The same as Locator above.

#`traceprojector/generator`

#`generateUnitCubeMesh`

function generateUnitCubeMesh(n: number): Mesh

A mesh of the unit cube [0, 1]^3 with n cubes per side, each cut into six tetrahedra (6 n^3 in all), for tests, examples and convergence studies.

Parameters

n: Cubes per side (an integer of at least 1).

#`generateSingleTetMesh`

function generateSingleTetMesh(): Mesh

A mesh with the single reference tetrahedron.

#`traceprojector/parallel`

#`projectInParallel`

function projectInParallel(job: {
  vertices: number[][];
  tetrahedra: number[][];
  /** The `file:` URL (or absolute path) of an ES module whose default export is the field. */
  field: string;
  points: number[][];
  l?: number;
  p?: number;
  /** Number of workers (default: the number of cores). */
  workers?: number;
  options?: { quadratureOrder?: number };
}): Promise<Array<number | number[]>>

Projection of one field at many points on worker threads (Node.js only).

#`CoefficientPool`

export class CoefficientPool

A pool of worker threads that computes the coefficients of the bounded operators. Each worker owns a complete operator and shares no state, so the result is bitwise the same for any number of workers.

#`constructor`

constructor(job: {
    vertices: number[][];
    tetrahedra: number[][];
    /** `bounded-commuting` (default), `zero-trace` or `higher-order` (the lowest-order weights of degree `degree`). */
    operator?: 'bounded-commuting' | 'zero-trace' | 'higher-order';
    degree?: number;
    /** Number of workers (default: the number of cores). */
    workers?: number;
    options?: { quadratureOrder?: number };
    /** Limits of each worker thread (see worker_threads). */
    resourceLimits?: { maxOldGenerationSizeMb?: number; maxYoungGenerationSizeMb?: number };
  })

#`size` (property)

readonly size: number

Number of workers.

#`coefficients`

coefficients(job: {
    /** The `file:` URL (or absolute path) of an ES module whose default export is the field. */
    field: string;
    l: number;
    entities: number[];
  }): Promise<Float64Array>

The coefficient of every listed entity of form degree l, in order.

#`close`

close(): Promise<void>

Stops the workers.

#API reference

#traceprojector

#Projector

#mesh (property)

#whitney (property)

#constructor

#buildLocator

#computeBoundaryWeights

#verifyBoundaryWeights

#projectH1

#projectHcurl

#projectHdiv

#projectL2

#projectHp

#extractBoundaryDofs

#projectRing

#extendBoundary

#projectPartial

#projectAtPoint

#sampler

#refine

#Mesh

#vertices (property)

#tetrahedra (property)

#originalVertexCount (property)

#vertexCount (property)

#tetrahedronCount (property)

#faces (property)

#edges (property)

#boundaryFaces (property)

#boundaryEdges (property)

#boundaryNodes (property)

#faceToTets (property)

#edgeToFaces (property)

#vertexToTets (property)

#vertexToBoundaryFaces (property)

#vertexToEdges (property)

#constructor

#getFaceArea

#getEdgeIndex

#getFaceIndex

#getTetEdgeSign

#getTetFaceSign

#getVertices

#getTetrahedra

#getFaces

#getEdges

#getBoundaryNodes

#getBoundaryFaces

#getBoundaryEdges

#getOriginalVertexCount

#getFaceBarycenter

#getTetrahedronBarycenter

#getStar

#getBoundaryStar

#getEdgeStar

#getVolume

#getTetrahedronFaces

#getFaceOutwardNormal

#validateMeshInput

#parseGmsh

#Whitney

#constructor

#getBarycentric

#getGradBarycentric

#getEdgeBasis

#getFaceBasis

#Locator

#constructor

#findTetrahedron

#Refinement

#constructor

#faceBarycenters (property)

#tetBarycenters (property)

#alfeldTriangles (property)

#faceToAlfeld (property)

#worseyFarinTetrahedra (property)

#computeAlfeldSplit

#computeWorseyFarinSplit

#Weight

#`traceprojector`

#`Projector`

#`mesh` (property)

#`whitney` (property)

#`constructor`

#`buildLocator`

#`computeBoundaryWeights`

#`verifyBoundaryWeights`

#`projectH1`

#`projectHcurl`

#`projectHdiv`

#`projectL2`

#`projectHp`

#`extractBoundaryDofs`

#`projectRing`

#`extendBoundary`

#`projectPartial`

#`projectAtPoint`

#`sampler`

#`refine`

#`Mesh`

#`vertices` (property)

#`tetrahedra` (property)

#`originalVertexCount` (property)

#`vertexCount` (property)

#`tetrahedronCount` (property)

#`faces` (property)

#`edges` (property)

#`boundaryFaces` (property)

#`boundaryEdges` (property)

#`boundaryNodes` (property)

#`faceToTets` (property)

#`edgeToFaces` (property)

#`vertexToTets` (property)

#`vertexToBoundaryFaces` (property)

#`vertexToEdges` (property)

#`constructor`

#`getFaceArea`

#`getEdgeIndex`

#`getFaceIndex`

#`getTetEdgeSign`

#`getTetFaceSign`

#`getVertices`

#`getTetrahedra`

#`getFaces`

#`getEdges`

#`getBoundaryNodes`

#`getBoundaryFaces`

#`getBoundaryEdges`

#`getOriginalVertexCount`

#`getFaceBarycenter`

#`getTetrahedronBarycenter`

#`getStar`

#`getBoundaryStar`

#`getEdgeStar`

#`getVolume`

#`getTetrahedronFaces`

#`getFaceOutwardNormal`

#`validateMeshInput`

#`parseGmsh`

#`Whitney`

#`constructor`

#`getBarycentric`

#`getGradBarycentric`

#`getEdgeBasis`

#`getFaceBasis`

#`Locator`

#`constructor`

#`findTetrahedron`

#`Refinement`

#`constructor`

#`faceBarycenters` (property)

#`tetBarycenters` (property)

#`alfeldTriangles` (property)

#`faceToAlfeld` (property)

#`worseyFarinTetrahedra` (property)

#`computeAlfeldSplit`

#`computeWorseyFarinSplit`

#`Weight`

#`constructor`