RFC: promote Drucker-Prager geomechanics assembler into TensorMesh public API

[kilickursat]

Hi,

Following the merged geomechanics examples, I would like to discuss whether it is now the right time to promote the example-local Drucker-Prager implementation into a small public API.

Motivation

The geomechanics examples now establish the main ingredients:

• Drucker-Prager triaxial compression as a constitutive driver,
• elastic strip footing as a geomechanics boundary-value problem,
• Drucker-Prager strip footing as a nonlinear geomechanics boundary-value problem.

The Drucker-Prager implementation has now been exercised in both constitutive-driver and boundary-value settings. A small public API would reduce duplication across future geomechanics examples and make it easier to add foundation, slope, excavation, and tunnel examples.

The current examples intentionally kept the implementation local. Now that the model surface has been tested in examples, I would like to ask whether it should be promoted into TensorMesh proper.

Proposed scope

I propose adding a small geomechanics assembler module inside the existing solid/assemble family:

tensormesh/assemble/geomechanics.py
    DruckerPragerPlasticity

and a lightweight material container, either in the existing material module or a small material submodule depending on maintainer preference:

tensormesh/material/
    FrictionalMaterial

I would not introduce a top-level tensormesh.geomechanics package.

Proposed material class

A first version could be:

FrictionalMaterial(
    name: str,
    E: float,
    nu: float,
    rho: float,
    cohesion: float,
    friction_angle: float,
    dilatancy_angle: float = 0.0,
    H: float = 0.0,
)

I am not attached to the exact name or file location. I would prefer to match TensorMesh’s existing material conventions.

For the first public version, I suggest keeping the implementation close to the examples: associated Drucker-Prager with linear isotropic hardening. The dilatancy_angle field could either be omitted initially or reserved for a future non-associated extension, depending on maintainer preference.

Proposed assembler

The public assembler would follow the existing J2-style lifecycle:

• per-quadrature history stored in self.history[etype],
• previous-step state passed through element_data,
• update_state(u) called after each converged load step under torch.no_grad(),
• internal stress convention remains tension-positive,
• geomechanics examples may report compression-positive pressure and settlement.

A possible user-facing pattern:

from tensormesh.assemble.geomechanics import DruckerPragerPlasticity
from tensormesh.material import FrictionalMaterial

soil = FrictionalMaterial(
    name="DenseSand",
    E=50.0e6,
    nu=0.30,
    rho=1900.0,
    cohesion=5.0e3,
    friction_angle=35.0,
    H=25.0e3,
)

model = DruckerPragerPlasticity.from_mesh(
    mesh,
    material=soil,
)

or, if maintainers prefer to keep the constructor style closer to J2Plasticity:

model = DruckerPragerPlasticity.from_mesh(
    mesh,
    E=50.0e6,
    nu=0.30,
    cohesion=5.0e3,
    friction_angle=35.0,
    H=25.0e3,
)

Validation plan

A public API PR would include:

• single-element elastic check below yield,
• triaxial compression yield check,
• pressure-dependent confinement check,
• monotonic committed plastic-history check,
• 2D plane-strain helper coverage under batching / vmap,
• regression of the existing Drucker-Prager triaxial example,
• regression of the Drucker-Prager footing example,
• CPU + float64 tests,
• clean docs build.

Migration plan

If accepted, I would update the existing geomechanics examples to use the public assembler rather than carrying duplicate local Drucker-Prager code:

examples/solid/geomechanics/drucker_prager_triaxial/
examples/solid/geomechanics/drucker_prager_footing/

The examples would remain in the gallery, but their constitutive implementation would come from the public API.

Questions

1. Is this the right time to promote Drucker-Prager into public API after the example-only triaxial and footing workflows?
2. Should the public assembler live in tensormesh/assemble/geomechanics.py, or beside the existing plasticity implementation?
3. Should FrictionalMaterial live in tensormesh/material/, or should the existing material module remain flat for now?
4. Should the first public API support associated Drucker-Prager only, or reserve room for non-associated flow through a future dilatancy_angle?
5. Should the examples be migrated to the public API in the same PR, or should the public API land first and the example migration follow separately?

[walkerchi]

Thanks for laying this out so concretely — a couple of thoughts from
the maintainer side, mapped to your questions:

Q1 + Q2 — promotion shape and location

Yes, the example-tested Drucker-Prager surface is mature enough to
promote. Two layers, kept separate:

(1) General API — the constitutive primitive. Expose the
Drucker-Prager return mapping / yield surface as a regular
function or class — pure math, no mesh, no ElementAssembler
subclass. This is the reusable piece anyone writing a custom
forward() (multi-field coupling, non-standard BCs, time
integration variants) composes into their own kernel. It matches
how the rest of the library exposes constitutive primitives and
is the "standard" API surface that should not be bypassed.

(2) Syntactic sugar — the one-line assembler.
DruckerPragerPlasticity.from_mesh(mesh, material=soil) that
wraps the primitive + standard plane-strain assembly is a built-in
convenience for the 90% case. Drop it into
tensormesh/assemble/builtin.py alongside J2Plasticity
(~200 lines), LinearElasticity, etc. — same drawer, same
discoverability from tensormesh.assemble.

builtin.py is currently ~815 lines and already houses 6
assemblers. If adding DP starts to feel cramped, a clean
follow-up is converting it to a builtin/ package with one
file per family (builtin/laplace.py, builtin/plasticity.py,
builtin/contact.py, ...) re-exported through
builtin/__init__.py so existing
from tensormesh.assemble import J2Plasticity keeps working.
That refactor can land separately — we don't want to gate the
DP promotion on it.

Note: applying this layering retroactively to J2Plasticity is
also on the table but out of scope for this RFC.

Q3 — material container

We'd lean toward a table-backed rather than constructor-per-soil
design. A canonical CSV (or TOML) of named presets — DenseSand,
LooseClay, WeatheredRock, ... — loaded by FrictionalMaterial
via a name lookup is easier to extend, easier to document, and lets
contributors add soils without touching code:

soil = FrictionalMaterial.from_preset("DenseSand")
# or, for one-off parameter sweeps:
soil = FrictionalMaterial(E=..., nu=..., cohesion=..., friction_angle=...)

The constructor stays for one-off sweeps; the preset table is the
publishable knowledge artifact.

Q4 — associated vs non-associated

The existing point_data / scalar_data channels on
ElementAssembler already cover this: dilatancy_angle is just
another constitutive parameter flowing through the same way every
other material coefficient does today. So associated vs
non-associated isn't a public-API decision — both fit on the same
primitive.

If you want a turnkey non-associated entrypoint for a specific
problem class, the natural move is to wrap a sugar class on top of
that primitive — same general / sugar layering as Q1+Q2 — instead
of pushing the distinction up to the public API. Let us know if
we're missing something.

Q5 — example migration

Same PR. The whole point of the promotion is removing the duplicate
local copy from the examples — landing the public API while leaving
the examples on their own implementation is a half move that
defers exactly the diff this RFC is trying to delete. Bundling them
also proves the API is genuinely usable on real call sites, not
just on the unit-test fixtures.

[kilickursat]

Thank you — this direction makes sense.

I’ll prepare the first public API PR using the two-layer structure you described:

1. a pure constitutive Drucker-Prager primitive for return mapping / yield-surface evaluation, independent of meshes and ElementAssembler;
2. a convenience DruckerPragerPlasticity.from_mesh(mesh, material=soil) assembler in tensormesh/assemble/builtin.py, following the existing built-in assembler style.

For the material side, I’ll add a table-backed FrictionalMaterial with from_preset(...) plus the constructor path for one-off parameter sweeps. I’ll keep the preset table as the publishable artifact and avoid introducing a top-level tensormesh.geomechanics package.

I’ll also migrate the existing Drucker-Prager triaxial and Drucker-Prager footing examples in the same PR so the new public API is exercised on real gallery examples, not only unit tests.

I’ll keep the scope focused and will not include the builtin/ package refactor, J2 refactoring, or tunnel-specific APIs in this PR.

Thanks again for the clear guidance.

[Shizheng-Wen]

Thanks to Mingyuan and Kursat. The PR is merged into the main.