Add electrostatic MMS verification with optional Enzyme support

[laylagi]

Adds the Method of Manufactured Solutions (MMS) for the electrostatic solver, with an optional Enzyme-AD (Automatic Differentiation) backend.

The tests exercise the production solve path and verify:

• Homogeneous and non-homogeneous Dirichlet conditions.
• Neumann flux and anisotropic permittivity.
• Potential and recovered electric-field errors.
• Polynomial exactness on affine hexahedra and tetrahedra.
• Optimal convergence on Cartesian and curved tetrahedral meshes.
• Serial and distributed-memory execution.

Enzyme support

Enzyme support is disabled by default with PALACE_WITH_ENZYME=OFF. When enabled, the build requires matching upstream Clang and LLVM versions and can either build Enzyme or use an existing installation through ENZYME_DIR.

Enzyme-specific sources are compiled separately so the compiler plugin is not applied to unrelated Palace sources. CI enables Enzyme in the Clang sanitizer configuration while the remaining configurations continue to test the default Enzyme-disabled path.

Building and testing with Enzyme

Enzyme requires upstream Clang and a matching LLVM development package. Apple Clang is not supported because it does not provide a matching upstream LLVM package.

On Linux, configure from the repository root with:

cmake -S . -B build-enzyme \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -DLLVM_DIR="$(llvm-config --cmakedir)" \
  -DPALACE_MFEM_USE_EXCEPTIONS=ON \
  -DPALACE_WITH_ENZYME=ON

cmake --build build-enzyme --target palace-tests --parallel

On macOS with Homebrew LLVM:

LLVM_PREFIX="$(brew --prefix llvm)"

cmake -S . -B build-enzyme \
  -DCMAKE_C_COMPILER="$LLVM_PREFIX/bin/clang" \
  -DCMAKE_CXX_COMPILER="$LLVM_PREFIX/bin/clang++" \
  -DLLVM_DIR="$("$LLVM_PREFIX/bin/llvm-config" --cmakedir)" \
  -DPALACE_MFEM_USE_EXCEPTIONS=ON \
  -DPALACE_WITH_ENZYME=ON

cmake --build build-enzyme --target palace-tests --parallel

The superbuild builds Enzyme automatically. To use an existing compatible installation, also pass -DENZYME_DIR=<path-to-EnzymeConfig.cmake-directory>.

Run the analytic and Enzyme-backed MMS tests with:

  ./build-enzyme/bin/palace-unit-tests "[electrostaticmms]" --skip-benchmarks
  mpirun -np 2 ./build-enzyme/bin/palace-unit-tests \
    "[electrostaticmms]" --skip-benchmarks

  ./build-enzyme/bin/palace-unit-tests "[enzyme]" --skip-benchmarks
  mpirun -np 2 ./build-enzyme/bin/palace-unit-tests \
    "[enzyme]" --skip-benchmarks

macOS build note

The Homebrew LLVM workflow also requires passing the macOS SDK sysroot to LIBXSMM. LIBXSMM is a libCEED backend, not an Enzyme dependency; this is a general Darwin/Homebrew-Clang superbuild fix encountered while validating the Enzyme workflow.

Documentation

Adds a numerical-verification guide, reproducible convergence data and plots, and make targets for regenerating the documentation artifacts.

[Sbozzolo]

Flyby comment: this PR should also add support for spack.

Here are some notes to develop with spack: https://awslabs.github.io/palace/dev/developer/spack/