evspy: A python library for elasto-viscoplastic modelling of soils.

TL;DR Modelling large strain consolidation with creep and swelling response after unloading, install with pip install evspy or through github.

For almost any problem within geotechnical engineering, we are trying to predict and understand the soil response. Arguably the most basic response we can think of is the (volumetric) compression of a piece of soil. It is emblematic for the complexity of soil and the emergent properties from interaction of very small particles, air and water. While we do have good physical understanding of some components of the behaviour, we have to rely on empirical and phenomenological assessments to complete our models. With the growth of open source and increasing amounts of data and (physics-informed) machine learning, soil mechanics is a prime application for the next wave of model improvements. Given the inherently probabilistic nature of the work, mapping of the uncertainty of any prediction should be a prime focus.

As part of my PhD work, I developed set of elasto-viscoplastic models to understand and predict the long-term (1D) unloading response of soils. The evspy module makes these models available to all, hopefully as a basis for further research and collaboration in the geotechnical community. The research was done in two main steps, one model was used to interpret laboratory test results with Bayesian updating of parameters stage-by-stage to infer the overall behaviour. These results are then used to create a more complete model that can be used for predictions. The major portions of the work are published in Géotechnique and Int. J. for Num. and Anal. methods in Geomechanics.

Structure of the package

The package is created to be modular, applies automated testing and can be recalibrated as all model parameters are exposed. There are two main components to the package, with different methods and goals in mind: a decoupled model focused specifically on unloading and a coupled model that can be used more generally and can be reduced to a “standard” fully coupled 1D isotache model.

What problem are we trying to solve?

There is a widespread shortage of sand that affects, among others, the construction industry, including land reclamations. In many areas, the lack of sand as a high quality reclamation material leads to very high costs and the wish to use alternative resources. This is both more environmentally friendly and will cut down the costs. The only catch is that the alternatives are typically softer and hard to treat soil which need to be improved to be stable platforms with very small long-term deformations.

While there are many technical challenges, one of the hardest is to simply predict how the treated soil will respond in the long term, which involves creating a model from very short to very long term with very high to very low deformations. A particularly challenging subset of this problem is the response after unloading, as a complex response of primary and secondary swelling, and reappearance of creep is observed.

Some examples

To validate the model, a number of experiments were carried out. As part of the evspy repository, some of this experimental data is included. One of the example notebooks compares the experimental results with the model and some older models:

Future plans

evspy is still in early release. Some additional features are planned. Most importantly, documentation and a fully worked example with Bayesian updating will be added.