Skip to content

docs: retire small_strain_plasticity.md, keeping what it alone had - #49

Merged
petlenz merged 1 commit into
mainfrom
docs/stale-refs
Sep 7, 2026
Merged

docs: retire small_strain_plasticity.md, keeping what it alone had#49
petlenz merged 1 commit into
mainfrom
docs/stale-refs

Conversation

@petlenz

@petlenz petlenz commented Sep 6, 2026

Copy link
Copy Markdown
Member

Every reference to small_strain_plasticity and rk_plasticity on main — a whole document named after a class that no longer exists, two header comments pointing readers at it, and four historical or cross-reference mentions.

The document

docs/small_strain_plasticity.md (1048 lines) is superseded by plasticity-theory.md, which covers the same nine sections plus kinematics, the elastic law, the flow rule, hardening, KKT, the multi-stage variant, and what the derivations assume — with the identities checked against the code rather than asserted. Its implementation-map tables pointed at small_strain_plasticity.h, which is gone.

One section was not superseded, so it is ported rather than deleted — now §15 of plasticity-theory.md, four ways an implementation of these equations runs while being wrong:

trap
15.1 η·I₁ paired with the η/3 yield normal, or the reverse — a factor of three in the volumetric coupling, where the residual still converges and only the tangent is wrong
15.2 reaching for the J2-shaped N⊗N in the DP derivative, when the volumetric term differentiates away
15.3 converged-state quantities in a tangent whose update used trial ones
15.4 the smooth tangent at q = 0, where it carries 1/q

15.1 is the one worth having written down: both expressions look right in isolation. This code uses q + η·p with s/(2q) + (η/3)I, and (6.7) is the check — M : C : N reproduces G + Kηβ to twelve digits only if the two agree. 15.2 also connects to §11.3: the spurious volumetric term is traceless in neither index pair, so it breaks the 4G² collapse as well.

The comments

Two headers sent readers to the deleted file for "the full consistency requirements" (yield_functions.h, drucker_prager_yield_function.h); they now point at plasticity-theory.md and, for the normalization traps specifically, at §15. The other four name the split class in historical or cross-reference statements — j2_plasticity's "split out of", j2_rk_plasticity's shared-code note, vector_newton's example of a caller that throws — and are reworded to describe what exists.

plasticity.md's opening said "after the split of j2_plasticity, drucker_prager_plasticity and j2_rk_plasticity", which reads backwards — the split produced those — and carried a "current as of PRs #39 and #40" line that is stale now everything is on main. It now says what it is and links to the theory document.

Checks

No reference to either deleted class remains anywhere outside build trees; both cross-links resolve; every anchor in the theory document's contents resolves; pandoc still converts all 387 of its math expressions to MathML with no fallback and nothing on stderr; 263/263 tests pass.

The class the document was named after does not exist: #42, #43 and #40 split
it into j2_plasticity, drucker_prager_plasticity and j2_rk_plasticity. Its
implementation-map tables pointed at small_strain_plasticity.h and its
derivations are superseded by plasticity-theory.md, which covers the same nine
sections plus kinematics, the elastic law, the flow rule, hardening, KKT, the
multi-stage variant, and what the derivations assume -- with the identities
checked against the code rather than asserted.

One section was NOT superseded and is ported rather than lost: "Common failure
modes", now section 15 of plasticity-theory.md. Four ways an implementation of
these equations runs while being wrong:

  15.1  eta*I1 with the eta/3 yield normal, or the reverse -- a factor of three
        in the volumetric coupling, where the residual still converges and only
        the tangent is wrong. This code uses q + eta*p with s/(2q) + (eta/3)I,
        and (6.7) is the check: M:C:N reproduces G + K*eta*beta to twelve
        digits only if the two agree.
  15.2  reaching for the J2-shaped N (x) N in the DP derivative, when the
        volumetric term differentiates away -- which also breaks the 4G^2
        collapse, since the extra term is traceless in neither index pair
  15.3  converged-state quantities in a tangent whose update used trial ones
  15.4  the smooth tangent at q = 0, where it carries 1/q

The stale references in the headers are updated too. Two pointed at the deleted
file for "the full consistency requirements"; they now point at
plasticity-theory.md and, for the normalization traps, at section 15. The rest
name the split class in historical or cross-reference statements
(j2_plasticity's "split out of", j2_rk_plasticity's shared-code note,
vector_newton's example of a caller that throws) and are reworded to describe
what exists.

plasticity.md's opening said "after the split of j2_plasticity,
drucker_prager_plasticity and j2_rk_plasticity", which reads backwards -- the
split produced them -- and carried a "current as of PRs #39 and #40" line that
is stale now everything is on main. It now says what it is and links to the
theory document.

Checked: no reference to either deleted class remains anywhere outside build
trees, both cross-links resolve, every anchor in the theory document's contents
resolves, pandoc still converts all of its math with no fallback, and 263/263
tests pass.
@petlenz
petlenz merged commit 9bb103f into main Sep 7, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant