Introducing Groundhog, a high-quality general-purpose geotechnical Python package

Digitisation is rapidly transforming the geotechnical engineering profession and many students and practicing engineers are learning new skills to cope with the challenges that lie ahead. Python is the language of choice for many engineers due to its intuitive syntax, rich ecosystem of high-quality packages and interface to other engineering software such as Abaqus, PLAXIS and GIS. 

But with many geotechnical engineers using Python, a myriad of scripts, modules and notebooks is emerging which contain code of varying quality and which are not always shared widely. Moreover, geotechnical engineering is a (semi)empirical discipline by nature and users should have knowledge of the data supporting these empirical correlations. 

This is where Groundhog comes in (https://github.com/snakesonabrain/groundhog), a Python project packed with useful functionality for supporting automated geotechnical calculations . The package is developed around four pillars: 

• Flexible input parameter validation: Predefined parameter ranges are defined for most functions, based on the range of soil parameters for which the function was originally developed. This validation can be overridden by the user but requires explicit definition of the modified parameter ranges;
• Parametric functions with multiple outputs: Groundhog functions are fully parametric (calibration parameters can be tuned) and return a Python dictionary including intermediate results or derived quantities. Units are specified for each numerical output;
• Unit testing: All Groundhog functionality is thoroughly unit tested to ensure that the implementations return the correct values. Results of handcalcs or published solutions have been used to validate the functions;
• Documentation: Each Groundhog function is extensively documented (https://snakesonabrain.com/docs/groundhog/index.html) and reference is made to the original work to ensure that users are aware of the underlying datasets for correlations.

The package standardises routine tasks such as PCPT processing or soil profile selection. These tasks are essential tasks for any geotechnical problem and performing them swiftly can greatly improve the efficiency of engineering calculations. Techniques for efficiently visualising results are built into Groundhog. 

To get started with Groundhog, a number of tutorial notebooks are available online (navigate to https://mybinder.org/v2/gh/snakesonabrain/groundhog/v0.2.0/ and go to the notebooks folder):

• Basic use of groundhog functions
• Soil profile definition, manipulation and plotting
• PCPT data loading
• PCPT data processing
• Loading AGS data in Python
• Axial pile capacity calculation according to Belgian practice

The package is under constant development so further tutorials are soon to be released. Any request for additional functionality can always be submitted to the package author through GitHub.

The package was named after the groundhog, an animal that lives in underground burrows. Moreover, the movie Groundhog Day where a reporter relives the same day again and again. The Groundhog package aims to remove that repetitiveness from your day-to-day geotechnical engineering work.

The package is released under a Creative Commons CC BY-NC 4.0 license (https://creativecommons.org/licenses/by-nc/4.0/) and is free to use for non-commercial purposes. I use it in my geotechnical courses at UGent to allow students to focus on the true challenges of geotechnical engineering (careful parameter selection, sensitivity studies) rather than the tedious implementation of formulae.