Geomechanics examples and Drucker–Prager plasticity for soils and rock

[kilickursat]

Hi TensorMesh maintainers,

I would like to contribute geomechanics / rock-and-soil mechanics support to TensorMesh. I am opening this as an RFC before starting a pull request because this may affect examples, documentation, and possibly future constitutive-model APIs.

Motivation

TensorMesh already has a strong solid-mechanics base, including linear elasticity, hyperelasticity, contact, and J2 plasticity. That is a useful foundation for geotechnical and rock mechanics, but many soil and rock workflows need pressure-dependent frictional behavior rather than pressure-insensitive J2 plasticity.

The geomechanics use cases I would like to help support include:

• elastic ground deformation under gravity and surface loading,
• footing, tunnel, excavation, or slope examples in plane strain,
• pore-pressure diffusion or consolidation examples,
• frictional plasticity using cohesion, friction angle, and dilatancy,
• later, strength-reduction or slope-stability-style examples.

Proposed staged contribution

Stage 1: Add a small geomechanics example

I propose starting with one example that uses existing TensorMesh APIs and requires minimal new core code.

Possible first examples:

1. examples/geomechanics/elastic_footing/

   • 2D plane-strain elastic soil block,
   • gravity or surcharge loading,
   • displacement boundary conditions,
   • settlement plot and reaction-force sanity check.

2. examples/geomechanics/terzaghi_consolidation_1d/

   • transient pore-pressure diffusion / consolidation benchmark,
   • comparison against a known analytical solution,
   • useful as a validation-style geomechanics example.

3. examples/geomechanics/geostatic_stress/

   • initialize vertical stress under self-weight,
   • demonstrate body forces and lateral constraints,
   • serve as a base for later excavation, tunnel, or slope examples.

My preference for the first pull request would be a documentation/example-only contribution, so that the scope is small and easy to review.

Stage 2: Add Drucker–Prager frictional plasticity

For a constitutive model, I suggest adding Drucker–Prager plasticity before full Mohr–Coulomb plasticity.

Reasoning:

• Mohr–Coulomb is very important in geotechnical engineering, but it has a non-smooth yield surface.
• Drucker–Prager is a smooth pressure-dependent approximation, so it may fit TensorMesh’s PyTorch/autograd style better as a first frictional model.
• The existing J2 plasticity workflow appears to provide a useful template for per-quadrature history variables and load-step updates.

A possible API could look like this:

soil = FrictionalMaterial(
    name="DenseSand",
    E=50e6,
    nu=0.3,
    rho=1900.0,
    cohesion=5e3,
    friction_angle=35.0,
    dilatancy_angle=5.0,
)

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

I am not attached to this exact API. I would prefer to follow the existing TensorMesh style and maintainer preferences.

Possible file structure

Depending on maintainer preference, the contribution could use something like:

examples/geomechanics/
docs/source/example_gallery/geomechanics/
tests/assemble/test_drucker_prager.py
tensormesh/assemble/geomechanics.py
tensormesh/material/geomechanics.py

Alternatively, the first version could stay entirely as an example-only custom assembler before adding anything to the public API.

Validation ideas

For an example-only pull request:

• compare 1D consolidation / pore-pressure diffusion against an analytical solution,
• or compare elastic settlement / stress response against a simple closed-form or mesh-refinement sanity check.

For a Drucker–Prager pull request:

• CPU + float64 unit tests,
• no NumPy inside assembler forward() / energy kernels,
• one-element triaxial compression yield check,
• elastic response below yield compared with the existing linear-elastic assembler,
• pressure-dependent yield check under different confining stresses,
• documentation example showing the effects of friction angle, cohesion, and dilatancy.

Questions for maintainers

1. Would you prefer a new Geomechanics example-gallery section, or should the first examples live under Solid Mechanics?
2. Would a docs/example-only first pull request be welcome before adding a constitutive model?
3. For the constitutive model, would you prefer:
   • DruckerPragerPlasticity as a built-in assembler,
   • a separate tensormesh.geomechanics module,
   • or keeping it as an example-only custom assembler first?
4. Are there preferred sign conventions for stress/strain in pressure-dependent materials?
5. Are there existing design constraints I should follow for material history variables or load-step updates?

I am happy to start small with a single runnable example and tests, then follow up with Drucker–Prager plasticity if the direction looks useful.

[Shizheng-Wen]

Hi Kursat,

Sorry for the late reply — I was away last week. We'd of course be very happy to have you join us and contribute the geomechanics applications of TensorMesh. Here are my answers to your questions:

1. Solid mechanics, to start. Geomechanics rides on the same assembler stack as the classical solid-mechanics problems, so it belongs in that family rather than as a separate top-level area. That said, in the examples/ tree, please group the scripts under examples/solid/geomechanics//. It'll be our first example sub-grouping, but geomechanics is clearly a coherent and growing cluster.
2. Yes, strongly preferred. A single runnable example plus an analytical/sanity check is the ideal first PR, and it lets us settle conventions before any public API lands.
3. Start as an example-only custom assembler. Once the model has proven out and the API has settled, graduate it into the library under tensormesh/assemble/ (a geomechanics.py next to the other solid assemblers is fine — once we accumulate more examples down the line, we'll do a more thorough reorganization), with a lightweight FrictionalMaterial dataclass in tensormesh/material/. We'd rather not introduce a separate top-level tensormesh.geomechanics package. Drucker–Prager is an extension of the existing plasticity machinery, not a separate subsystem, and keeping it in the solid/assemble family matches how J2Plasticity lives today.
4. Keep the library core tension-positive. The existing isotropic_stress, J2Plasticity, and the Voigt helpers are all tension-positive, and a pressure-dependent model has to compose with them.
5. Follow J2Plasticity directly：

• per-quadrature state in self.history[etype], as tensors on self.device / self.dtype;
• read the previous step's state through the element_data dict you pass to energy(...);
• advance it in an update_state(u) method called after each converged load step, under torch.no_grad().

Finally, thank you for the constructive feedback and for contributing to the open-source community. Many of these interfaces are still open for us to negotiate and adjust together later on. Welcome aboard!

Best,
Shizheng

[kilickursat]

Hi Shizheng,

Thank you very much for the detailed guidance and for the warm welcome. This clarifies the direction perfectly.

I will start with a small, example-only PR under examples/solid/geomechanics/, keeping geomechanics within the solid-mechanics family as you suggested.

For the first PR, I propose the following example:

examples/solid/geomechanics/drucker_prager_triaxial/

The scope will be deliberately small:

• a single runnable Drucker-Prager triaxial compression example,
• a local/example-only custom assembler inside the example,
• no new public API in tensormesh/assemble/ yet,
• no new tensormesh.geomechanics top-level package,
• tension-positive stress convention internally,
• per-quadrature state 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(),
• a small analytical/sanity check for the elastic response and pressure-dependent yield behavior,
• documentation/README explaining the sign convention and the example assumptions.

I will follow the existing J2Plasticity pattern as closely as possible and keep all tensor operations in Torch inside the assembler path and avoid adding a FrictionalMaterial dataclass or moving anything into tensormesh/assemble/geomechanics.py in this first PR. Once the example has proven useful and the API direction is clearer, we can discuss graduating it into the library.

Thanks again — I’ll prepare the first branch around this scope and keep the PR focused.

Best,
Kursat

[kilickursat]

Hi Shizheng,

Just closing the loop here: the first geomechanics example has now been merged in #4.

Thank you again for the guidance in this RFC. I followed the direction we agreed on: keeping the example under examples/solid/geomechanics/, making it example-only, using a local custom Drucker-Prager assembler, keeping TensorMesh tension-positive internally, and following the J2-style self.history[etype] / element_data / update_state(u) pattern.

I’ll keep any follow-up contributions incremental. A natural next step could be a small boundary-value geomechanics example under examples/solid/geomechanics/, such as an elastic footing or geostatic-stress example, before discussing any promoted public API under tensormesh/assemble/.

Thanks again for the review and merge.

Best,
Kursat

[Shizheng-Wen]

Thanks for your contribution Kursat ~

Looking forward to seeing your further contributions!

Best,
Shizheng