Developer documentation#

Note

Internal scope. This section is the developer / contributor handbook for femorph-solver. The intended audience is people building the solver — authoring kernels, adding interop cards, extending the verification corpus, profiling performance. An end-user reading the regular user guide should not need to open these pages.

A future build step will hide this section from the public docs deployment (the section is currently published; planned to gate behind the FEMORPH_DEV_DOCS build flag — tracked separately).

The user-facing documentation lives under Getting started, User guide, and Reference; this section is for the people landing the code.

Best-practice handbook#

The pages below are the canonical “how we do it here” rules. Each is written so a new contributor can read it once and start authoring code that matches the rest of the corpus.

Documentation craft

Architecture

Verification corpus

Tests + provenance

Reader + kernel authoring

Operations

What’s here, what’s coming#

Already documented:

  • Documentation style guide — single source of truth for docstring, RST, and tutorial style. Read before writing or editing any user-facing prose.

  • Documentation CI gates — the docs CI gates (numpydoc per-symbol, doctest, linkcheck) and the rules they enforce.

  • Architecture and design philosophy — design principles, the layer-by-layer structure, why pyvista / scipy.sparse / pluggable solvers, and where to look when something’s wrong.

  • Verification-manual spec — how to add a Verification Manual example to the corpus. Single source of truth for the spec types, the fixture / registry / harness layout, the multi-formulation pattern, and the reader-pending fallback.

  • Verification methodology — resolving discrepancies — the philosophy of resolving discrepancies once a benchmark fails. Walk-through of branches (a) deck mis-author, (b) reader gap, (c) tolerance mis-set, (d) kernel / analysis-feature gap.

  • Fixtures and decks — the immutable-input-deck rule, vendor provenance preservation, when to re-author vs. when to vendor a vendor-shipped deck, common pitfalls.

  • Validation data store — architecture + rationale for the Cloudflare R2 store that holds vendor-solver output binaries (.rst / .full / .emat / .mode) outside the main repo. Operational rules in the validation-data Claude skill.

  • Test-suite layout — test-suite layout, the four test categories, fixture conventions, parametrisation patterns, what to assert and what not to, pre-commit + CI overview.

  • Provenance inventory — running inventory of every published reference cited by the source. Each non-trivial numerical kernel must trace to a paper / textbook / public report.

  • Interop reader authoring — adding a new card to from_bdf / from_inp / from_dat: parser hooks, materialisation contract (real constants, materials, BCs, loads), unit-test pattern, coordinated card+kernel landings, common pitfalls.

  • Element-kernel authoring — adding a new element kernel: the ElementBase contract, neutral-name convention, real-constant layout, DOF ordering, six-step walkthrough, patterns by element family, common pitfalls.

  • Solver-backend authoring — adding a new linear or eigen backend: the pluggable solver protocols, dispatch rules, shift-invert path, lazy-import discipline, common pitfalls.

  • Performance — profiling, snapshots, the perf tracker — profiling tooling, the two benchmark harnesses (micro / pipeline), when to commit a snapshot, how PERFORMANCE.md works, the release-readiness gate.

  • CI workflows + merge queue — the eight CI workflows, the label-driven merge queue (automerge opt-in, rebase + serial-merge passes), the active-PR cap, pre-commit hooks, failure tracking.

  • Release process — version bumps via setuptools-scm, changelog conventions, the sphinx-multiversion story for old-tag galleries, yanking, the release-readiness gate.

The dev-handbook backlog is now empty; new pages get added when a recurring review comment surfaces (write the rule once in a page, link it from review, never write it again).

If you find yourself writing the same review comment more than once, that comment belongs as a section in one of the pages above. Open a docs PR.

Companion non-docs files#

Some developer material lives outside the Sphinx tree because it is heavily updated, machine-readable, or both. Keep it cross-referenced from the pages above, not duplicated here:

  • SOURCES.md (repo root) — third-party sourcing policy.

  • PERFORMANCE.md (repo root) — running performance tracker.

  • tests/cross_solver/_verification_registry.py — the live VM registry; pages here describe its conventions but do not enumerate the rows.

  • mpdl/docs/cyclic_expansion/ — cyclic-symmetry expansion notes.

  • perf/ (repo root) — perf snapshots / trends / latest runs.