Welcome to GroundHog Geotechnical Libraries documentation!

This Python package contains useful functionality for supporting automated geotechnical calculations.

groundhog is first and foremost aimed at education on geotechnical engineering automation with Python. It aims to support students and educators with well-developed examples of geotechnical analysis in Python.

Functionality for onshore and offshore geotechnical problems is included. This package is under constant development so any request for additional functionality can always be submitted to the package author.

The package is developed around four pilars:

• 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;

• Multiple outputs: Groundhog functions return a Python dictionary including intermediate results or derived quantities;

• Data standardisation: Possibility to read multiple input file formats (e.g. CPT data);

• Soil profiles: Easy encoding and manipulation of soil profiles.

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 this repetitiveness from your day-to-day geotechnical engineering work.

Installation requirements

groundhog is written for Python 3.7+. Downloading Anaconda3 is recommended for users not familiar with Python development. Plotting functionality included in the package is built on plotly. The plotly package also needs to be installed and is not included in the default Anaconda installation.

Installation is easily done using pip:

pip install groundhog

A more comprehensive Getting Started section with detailed installation instructions is included in the documentation.

• Getting started with groundhog
  • 1. Installation
    • 1.1. Installing Python
    • 1.2. Installing groundhog
    • 1.3. Installing dependencies
    • 1.4. Installing from source (advanced)
  • 2. Learning Python
    • 2.1. Jupyter notebooks
    • 2.2. Online resources
  • 3. First steps with groundhog

Support groundhog

A lot of time and effort has gone into the creation and maintenance of groundhog. You can support the development of groundhog by buying me a coffee.

Training, writing of non-shared company-specific software built on groundhog and consultancy are additional revenue streams for the package. Get in touch if you are interested in these services.

Tutorials

Tutorials are provided in the notebooks folder of the project. Jupyter notebooks are provided for the following examples:

• Basic use of groundhog functions

• Soil profile definition, manipulation and plotting

• PCPT data loading

• PCPT data processing

• Loading AGS data

• Axial pile capacity calculation according to Belgian practice

• …

Function documentation

Detailed documentation is available on the functions and classes of the package. This documentation is essential for using the functions in groundhog correctly as the documentation specifies the physical meaning and the units of input and output variables.

• General and utility functions
  • Soil profiles and gridscd
  • Plotting
  • Validation
  • AGS to Pandas converter reference
  • Parameter mapping
• Site investigation
  • Soil classification
  • Soil parameter correlations
  • In-situ tests
  • Laboratory testing
• Pile calculations
  • Unit skin friction
  • Unit end bearing
  • Axial capacity calculations
  • De Beer and Eurocode 7 calculations
  • Koppejan pile resistance calculations
  • Pile settlement
  • Cavity expansion methods for cast in-situ piles
  • Negative skin friction
• Shallow foundations
  • Stress distributions
  • Shallow foundation capacity
  • Settlement
• Consolidation functions
  • Groundwater flow
  • Pore pressure dissipation analysis
• Excavations
  • Earth pressure coefficients
• Soil dynamics
  • Liquefaction
  • Cyclic behaviour
  • Dynamic soil property correlations
• Standards
  • Eurocode 7
• Constitutive models
  • General
  • Cohesionless materials
  • Cohesive
  • Rock

Acknowledgements

The code for the validation of function input has been adopted from the python-engineering library and was integrated in the package to reduce the amount of dependencies.

License and usage restrictions

groundhog. A general-purpose Python library for geotechnical engineering.

Copyright (C) 2020 Bruno Stuyts

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

Indices and tables

• Index

• Module Index

• Search Page