Contributing

This page collects the conventions for working on PETGEM’s code and documentation.

Building

make builds all three binaries; see Installation for build options (USE_INTEL, USE_EXTRAE, V=1 for verbose command lines, NO_COLOR). After changing a header, rebuild from clean so stale object files do not cause ABI skew:

make clean && make

Useful Makefile targets (run make help for the full list):

  • make / make all - build fm.csem, im.csem, and petgem

  • make docs - build the documentation (Doxygen + Sphinx)

  • make clean / make clean_doc - remove build / documentation artifacts

Code conventions

  • Do not modify the shared forward assembly/solver code when adding inverse features. The forward kernel (fm.csem) must stay byte-for-byte unaffected; add new functions rather than changing shared paths.

  • Keep the file-header comment block consistent across .c/.h files.

  • The compiler is invoked with -Wall -Wextra (plus -Wpedantic on gcc); keep new code warning-clean.

Adding a Nédélec order

The high-order basis is dispatched through a per-order ops table (NedelecOps in include/hvfem.h). To add an order: implement the per-order static helpers in hvfem.c, build a NedelecOps instance for them, and register it in nedelecOpsForOrder(). The rest of the assembly calls through the table, so no hot-path switch (nord) is needed.

Documentation

The documentation lives under docs/source and is built with Sphinx; the C API reference is generated from the headers with Doxygen + Breathe, and the Python API with autodoc. Build it locally with:

make docs        # output: docs/build/html/index.html

The clean + Doxygen + API-stub generation is shared with Read the Docs via scripts/auto_doc/prepare_docs.sh (single source of truth, so the local and hosted builds stay in lockstep). Aim for a warning-free build.

Continuous integration

The GitHub Actions workflow builds the binaries (with and without Extrae), runs the pytest suite, exercises a forward smoke pipeline and one Extrae profiling run at nord=1, and builds the documentation. The integration tests run inside the project Docker image, which provides PETSc (complex scalars), HDF5, and the Python stack.

Testing

Run the suite before submitting changes - see Testing. New behavior should come with a unit or integration test; numerical changes to the forward kernel must keep the reference NRMSD within tolerance.