#Architecture

The library has one job, projecting a field onto finite element forms, done in two different ways. Understanding which way a class uses explains what it guarantees and what it costs.

                    the input field u(x)
                           |
          +----------------+----------------+
          |                                 |
   canonical path                      bounded path
   (point values, edge                 (a weight function per mesh entity,
   integrals, face fluxes)              found by a local solve on its star)
          |                                 |
   Projector                          ZeroTraceProjector
   CanonicalProjector                 BoundedCommutingProjector
                                      StableProjector
                                      TracePreservingProjector
                                      HigherOrderProjector

#The canonical path

A coefficient of the projection is a functional of the input at one entity: the value at a vertex, the integral along an edge, the flux through a face, the integral over a cell. This is cheap and exact for smooth input, but a functional like a point value is not bounded in L², so the operator is not stable.

#The bounded path

A coefficient is an integral of the input against a weight function that is supported on the star of mesh entities around the entity. The weight is found by solving a small local problem: the minimum-norm field whose exterior derivative equals the weights of the entities on the boundary of the entity, plus a local potential problem. Integrals against such weights are bounded in L², which is where the stability comes from; the weights are built so that the commuting property holds by construction.

#Shared numerical code

#Design decisions

1. Pure ES modules, no runtime dependencies. All the linear algebra is in the repository; bundlers produce the ESM, CJS and UMD files in dist/.
2. Typed errors for bad input. Anything a caller can get wrong (a flipped tetrahedron, a NaN coordinate, a point outside the mesh, a field that returns Infinity) raises one of three error classes. The fuzz tests assert that no malformed mesh produces a wrong answer, a hang or a crash.
3. Lazy, cached weights. The bounded operators compute the weight of an entity the first time a coefficient needs it and cache it. Projecting at a few points therefore solves only the problems near them. The higher-order weights are also cached by a signature of the star's geometry, so stars that are translates of each other share one solve.
4. Local solves are minimum-norm. The weight of an entity is the field of least L² norm with the required exterior derivative. Minimality makes it unique, which is what lets cached weights be reused.
5. Warnings for local failures, errors for global ones. The canonical boundary weights warn (and can be made strict) so that one bad element does not hide the rest.
6. Determinism. The same input gives the same bits, which the determinism test checks.

#Encoding limits

Edge and face lookups use integer keys computed in Number arithmetic, so they are exact up to 2^53 − 1:

The face key is reached first; meshes beyond about 131,000 vertices are outside what the canonical path has been run on.