docs: verification and validation; published benchmarks; fixtures (#31)

* docs: verification and validation against theory, experiments and published benchmarks; fixtures

Owner decision 2026-10-13: test against experimental and theoretical data; results published by
vendors (e.g. Abaqus benchmark and verification manuals) may be used as cited reference values for
our own models of the same problems; once a case matches, its result becomes a fixture so fidelity
cannot regress. Commercial products are still never run and their files and text never copied.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

* docs: V&V policy in AGENTS.md, ADR 0001 and the roadmap

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01NmAttHhUZTokgPeEJia8sm

---------

Co-authored-by: jyviko <[email protected]>
Co-authored-by: Claude Opus 5.5 <[email protected]>
This commit is contained in:
authored and GitHub committed 2026-10-13 18:43:36 -04:00
1 parent aa68bbbcdf
commit de8c0e2700
4 files changed
+45 -8

No files matched your search

+10 -6
View File
@@ -48,12 +48,16 @@ People trust ModelCraft with their models; a crash loses their work. **This outr
HyperMesh, ANSA, Femap, Patran, ANSYS, …): no test data, measurements, decks, results or ids
produced with them. Deck formats come from the vendors' publicly available reference manuals;
we write our own descriptions and our own examples, never copy manual text or example decks.
- **Expected values are analytic.** Reference tests compare with closed-form solutions (patch
tests, beams, plates, Lamé cylinders, Kirsch plates, natural frequencies, wave and shock
solutions) and with mesh invariants (positive Jacobians, conserved volume, watertight
boundaries). A separate **benchmark** suite may compare with reference values published in
papers (lid-driven cavity, Schäfer–Turek, Turek–Hron, Taylor bar), each tagged with its source;
the analytic suite is the gate. Never values produced with a commercial product.
- **Verification and validation (docs/verification.md).** Every solver capability is checked
three ways, each case in `tests/oracle/` tagged with its source: **theory** (closed-form
solutions, patch tests, mesh invariants), **experiment** (measurements published in papers and
reports) and **published benchmarks** (reference results published by benchmark bodies and by
solver vendors' benchmark and verification manuals, e.g. NAFEMS, Abaqus). Owner decision
2026-10-13: published vendor results may be used as reference values, cited per case. We never
run a commercial product, never copy its input files, text or figures: each case is our own
model built from the published description, and only the published numbers are used. Once our
result matches its reference within the stated tolerance, it is frozen as a **fixture**
(`fixture.json`), so any later change that moves it fails CI (fidelity never drifts silently).
- **Algorithms come from papers.** Meshing and solver methods are implemented from published
papers and theses, cited in the module docs and in `docs/meshing/literature.md`.
- **Never read, copy or link GPL/LGPL/AGPL code**: TetGen, CGAL, Gmsh, Netgen, CalculiX,