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 (femorph_solver.solvers)#

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 (femorph_solver.solvers.eigen)#

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 (femorph_solver.solvers.linear)#

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 (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.

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 (femorph_solver._core)#

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 (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.

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 materials._library or via a plug-in must declare a verifiable source in its 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.