Provenance inventory ==================== femorph-solver's correctness story depends on every non-trivial numerical kernel tracing to a published, open-source reference — a journal paper, textbook chapter, public technical report, or an explicit formula from one of the canonical FEM references (Bathe, Zienkiewicz, Hughes, Cook, Belytschko, Wriggers, Strang/Fix, Timoshenko, etc.). **Anything without a public corollary is flagged below for audit or removal** — the absence of a cite is itself a signal that either the algorithm is well known and we haven't written it down yet, or we have drifted toward reimplementing something that isn't in the public domain. This page is the tracking inventory. Each row points at the source file, summarises the published algorithm, and names the cite (full references live in each module's top-of-file ``References`` docstring block — the entries below are short-codes pointing there). How to read the status column ----------------------------- * **cited** — top-of-file ``References`` block in place; a reader can trace every non-trivial algorithm in the file back to a public source. * **audit** — file contains non-trivial numerical code but no authoritative citation yet. Slated for a follow-on PR. * **external** — wraps a third-party library whose provenance lives upstream; the wrapper cites the upstream paper but does not reimplement the algorithm. Solver internals (:mod:`femorph_solver.solvers`) ------------------------------------------------ .. list-table:: :header-rows: 1 :widths: 28 12 60 * - File - Status - Reference (short form) * - ``solvers/modal.py`` - cited - Bathe §11; Hughes §9; Wilkinson 1965. * - ``solvers/static.py`` - cited - Zienkiewicz/Taylor §1, §9; Cook §2; Bathe §3.4. * - ``solvers/transient.py`` - cited - Newmark 1959; Hughes §9.1-9.2; Bathe §9.2. * - ``solvers/cyclic.py`` - audit - Cyclic symmetry reduction (``P^H K P`` + 2N real augmentation) — deferred while the pyramid-kernel research is in flight; target cites are Petrolo / Zappino (cyclic symmetry) and Grimes / Lewis / Simon 1994 (the real augmentation identity). Eigen backends (:mod:`femorph_solver.solvers.eigen`) ---------------------------------------------------- .. list-table:: :header-rows: 1 :widths: 28 12 60 * - File - Status - Reference (short form) * - ``solvers/eigen/_arpack.py`` - external - Lehoucq/Sorensen 1996; Lehoucq/Sorensen/Yang 1998 (ARPACK Users' Guide); Ericsson/Ruhe 1980. * - ``solvers/eigen/_lobpcg.py`` - external - Knyazev 2001 (LOBPCG); Knyazev et al. 2007 (BLOPEX). * - ``solvers/eigen/_primme.py`` - external - Stathopoulos/McCombs 2010; Stathopoulos 2007; Davidson 1975. * - ``solvers/eigen/_lapack_dense.py`` - external - LAPACK Users' Guide 1999; Parlett 1998; Golub/Van Loan §8. Linear backends (:mod:`femorph_solver.solvers.linear`) ------------------------------------------------------ .. list-table:: :header-rows: 1 :widths: 28 12 60 * - File - Status - Reference (short form) * - ``solvers/linear/_superlu.py`` - external - Demmel/Eisenstat/Gilbert/Li/Liu 1999; Li 2005. * - ``solvers/linear/_cholmod.py`` - external - Chen/Davis/Hager/Rajamanickam 2008; Davis/Hager 2009. * - ``solvers/linear/_umfpack.py`` - external - Davis 2004 (Alg. 832); Davis/Duff 1997. * - ``solvers/linear/_pardiso.py`` - external - Schenk/Gärtner 2004, 2006; Intel oneMKL reference. * - ``solvers/linear/_mkl_pardiso.py`` - external - Schenk/Gärtner 2004, 2006; Intel oneMKL OOC user guide. * - ``solvers/linear/_mumps.py`` - external - Amestoy et al. 2001, 2006; Agullo/Guermouche/L'Excellent 2010. * - ``solvers/linear/_cg.py`` - external - Hestenes/Stiefel 1952; Saad 2003 §6. * - ``solvers/linear/_gmres.py`` - external - Saad/Schultz 1986; Saad 2003 §6.5. * - ``solvers/linear/_pyamg.py`` - external - Ruge/Stüben 1987; Vaněk/Mandel/Brezina 1996; Bell/Olson/Schroder 2023. Element kernels (:mod:`femorph_solver.elements`) ------------------------------------------------ **Status: audit in progress.** The Python-side element wrappers call into a C++ core under ``src/elements/``; provenance landing requires both sides cite. This is the scope of TA-9e-1 (see ``TODO-parity-perf.md``) — the audit here names the algorithms that must be cited in that follow-on PR. .. list-table:: :header-rows: 1 :widths: 30 12 58 * - File - Status - Algorithm + target citation * - ``elements/hex8.py``, ``src/elements/hex8.cpp`` - audit - HEX8 with B̄ (Hughes §4.4) and Simo-Rifai EAS (Simo/Rifai 1990) formulations. * - ``elements/hex20.py``, ``src/elements/hex20.cpp`` - audit - HEX20 Serendipity family; 2×2×2 reduced integration for K; 14-point Irons rule for M (Irons 1971). * - ``elements/_wedge15_pyr13.py``, ``src/elements/pyramid.cpp`` - audit - PYR13 / WEDGE15 Bedrosian apex-singular shape functions (Bedrosian 1992). Parity research in flight. * - ``elements/tet10.py``, ``src/elements/tet10.cpp`` - audit - TET10 quadratic with 4-point Keast Gauss rule (Keast 1986). * - ``elements/beam2.py`` - audit - Timoshenko 2-node beam with assumed linear strain; citation target is Bathe §5.4. * - ``elements/quad4_shell.py`` - audit - MITC4 shell (Bathe/Dvorkin 1985); citation + provenance deferred to a follow-up PR. * - ``elements/quad4_plane.py`` - audit - QUAD4 plane-stress / plane-strain / axisymmetric; Zienkiewicz/Taylor §6 reference. * - ``elements/truss2.py`` - audit - 2-node truss with axial-only formulation; Cook §3.2 reference. * - ``elements/spring.py`` - audit - 3-DOF linear spring/damper — elementary; citation target is Cook §3. * - ``elements/point_mass.py`` - audit - Point-mass + rotary-inertia contribution; elementary. Assembly + C++ core (:mod:`femorph_solver._core`) ------------------------------------------------- .. list-table:: :header-rows: 1 :widths: 30 12 58 * - File - Status - Notes * - ``src/core/csr_assembly.cpp`` - audit - CSR scatter/gather + parallel matvec. The algorithms (pattern-compile pass + parallel row-wise scatter) are standard; citation target is Saad 2003 §3.3 and Liu/Sherman 1975 for the CSR layout. Minor — flagged for TA-9e-4 follow-on if a reviewer asks for it. Materials library (:mod:`femorph_solver.materials`) --------------------------------------------------- Every built-in alloy in ``materials/_library.py`` cites a specific authoritative source in its ``provenance`` field. The master list of source short-codes (``MMPDS``, ``ASM-1``, ``ASM-2``, ``AA-SD``, ``SM-IN718``, ``SM-IN625``, ``ASTM-A36``) is in that module's top-of-file docstring. .. list-table:: :header-rows: 1 :widths: 30 70 * - Alloy - Source (short-code) * - Ti-6Al-4V (Grade 5) - MMPDS Chapter 5 (Titanium) * - CP Ti Grade 2 - ASM-2 (Nonferrous) * - Inconel 718 - SM-IN718 (Special Metals SMC-045) * - Inconel 625 - SM-IN625 (Special Metals SMC-063) * - SS 304 / SS 316 - ASM-1 (Irons/Steels/HPAs) * - AISI 1018 carbon steel - ASM-1 (Irons/Steels/HPAs) * - A36 structural steel - ASTM-A36 + ASM-1 cross-check * - 6061-T6 / 7075-T6 - AA-SD (Aluminum Standards and Data) + ASM-2 * - Pure copper (C10200) - ASM-2 (Nonferrous) * - Brass C26000 (70/30) - ASM-2 (Nonferrous) Ground rule going forward ------------------------- **No new algorithm, kernel, or material value lands without a citation.** PR reviewers should bounce any PR that adds > ~30 lines of maths-dense code without a ``References`` block in the target module (or an equivalent inline cite for a sufficiently self-contained snippet). Similarly, every new alloy added to :mod:`.materials._library` or via a plug-in must declare a verifiable source in its :attr:`MaterialProps.provenance`. Remaining audit scope --------------------- The ``audit`` rows above are the TA-9e-1 follow-on scope — the element-kernel Python / C++ pairs. Once those land, this page flips the matching rows to ``cited`` and the inventory is complete for structural-mechanics codepaths.