Geotechnical engineering, solved in Python.

A clean, validated, Apache 2.0-licensed Python library for the complete onshore geotechnical workflow —
laboratory testing, site investigation, foundation design, soil dynamics, and data exchange —
under a single flat namespace.

Install · Quick Start · Capabilities · Documentation · User Guide · Tutorials

GeoEq is a free, open-source Python library for geotechnical engineering. It provides 170+ validated functions for soil mechanics, site investigation, and foundation design — soil classification (USCS, AASHTO, USDA), SPT and CPT interpretation, bearing capacity, settlement, consolidation, slope stability, earth pressure, pile design, and earthquake liquefaction analysis — all under a single flat namespace (import geoeq as ge). Every formula cites its textbook or published source, and every function is tested against reference values.

GeoEq is built for geotechnical engineers, civil engineers, students, and researchers who want reproducible calculations in Python instead of spreadsheets.

• Classify soils by USCS, AASHTO, or the USDA texture triangle from grain-size and Atterberg data
• Interpret SPT and CPT — N60/N1(60) corrections, friction angle, undrained shear strength, relative density, and soil modulus
• Calculate bearing capacity with Terzaghi, Meyerhof, Hansen, or Vesic methods, including shape, depth, and inclination factors
• Estimate settlement — immediate (elastic), primary consolidation, secondary, and Schmertmann strain-influence methods
• Assess earthquake liquefaction using the NCEER / Idriss-Boulanger simplified procedure (CSR, CRR, factor of safety)
• Analyze slope stability with infinite-slope, Culmann, Taylor, and Bishop methods
• Design retaining walls and piles — earth pressure coefficients, overturning/sliding checks, pile capacity (α/β/λ methods)
• Read field data from CSV, AGS4, and GEF-CPT formats

Geotechnical analysis still runs on spreadsheets — one tab per soil layer, copy-pasted Boussinesq equations, magic-number unit conversions, and =IF() ladders nobody else can read six months later. Reports are non-reproducible. Calculations get re-derived from scratch every project.

GeoEq replaces that entire workflow with one Python import.

import geoeq as ge

# Soil classification, bearing capacity, liquefaction — all in one namespace
ge.density(Gs=2.65, e=0.72, kind="saturated", unit="kN/m3")
ge.bearing_capacity(c=10, gamma=18, Df=1, B=2, phi=30, method="meyerhof")
ge.liquefaction_fos(CSR=0.20, CRR=0.18, Mw=7.0)

170+ validated functions. Plain dicts in, plain dicts out. Every formula cites its textbook source. Every function is tested against published values. No class hierarchies, no deep imports, no magic. Apache 2.0 licensed.

pip install geoeq

Python 3.9+ on any platform. Dependencies: numpy, matplotlib, scipy — nothing else.

import geoeq as ge
# Every function is a top-level attribute — no submodule imports needed

A complete site screening in fifteen lines — soil profiling, bearing capacity, and liquefaction check:

import geoeq as ge

# 1. Define a layered soil profile with water table
p = ge.SoilProfile([
    (0, 2,  ge.Soil("Fill",       gamma=18)),
    (2, 8,  ge.Soil("Soft Clay",  gamma=17, gamma_sat=18.5,
                                  phi=0, c=25, Cc=0.27, e=0.92)),
    (8, 20, ge.Soil("Dense Sand", gamma=19, gamma_sat=20.5, phi=35)),
], water_table=2.0)

print(p.stress_at(10))
# {'sigma': 188.0, 'u': 78.48, 'sigma_eff': 109.52}

# 2. Bearing capacity — Meyerhof method for a 3 m square footing
bc = ge.bearing_capacity(c=25, gamma=18.5 - 9.81, Df=2, B=3, L=3,
                         phi=0, method="meyerhof")
print(f"q_u = {bc['q_u']:.0f} kPa")    # q_u = 192 kPa

# 3. Liquefaction triggering (NCEER simplified procedure)
csr = ge.liquefaction_csr(amax=0.25, sigma_v=120, sigma_v_eff=70, z=6, Mw=7.0)
crr = ge.liquefaction_crr(N160cs=12, method="youd_2001")
fs  = ge.liquefaction_fos(csr["CSR"], crr["CRR"], Mw=7.0)
print(fs)   # {'FS': 0.58, 'liquefies': True, ...}

Full per-function reference at geoeq.org. Below is what ships in v0.1.3.

clay = ge.Soil("Soft Clay", gamma=17, gamma_sat=18.5, phi=0, c=25, e=0.9)

p = ge.SoilProfile([
    (0, 2,  ge.Soil("Fill",       gamma=18)),
    (2, 8,  clay),
    (8, 20, ge.Soil("Dense Sand", gamma=19, gamma_sat=20.5, phi=35)),
], water_table=1.5)

p.effective_stress(10)   # σ' at z = 10 m
p.plot()                 # publication-quality stress profile

27 Jupyter notebooks covering all 163+ functions with synthetic data, step-by-step explanations, and real-world geotechnical problems:

Browse notebooks: test_and_tutorial/

git clone https://github.com/geoeq/geoeq.git
cd geoeq
pip install -e ".[dev]"
pytest                       # → 563 passed

GeoEq is a purpose-built, open-source Python library covering the complete onshore geotechnical workflow — lab testing, site investigation, foundation design, and soil dynamics — in one flat API. Unlike general scientific libraries, every GeoEq function implements a specific, citable geotechnical method and is validated against textbook values.

Use ge.bearing_capacity(). It supports the Terzaghi, Meyerhof, Hansen, and Vesic methods with shape, depth, and inclination factors:

import geoeq as ge
result = ge.bearing_capacity(c=25, gamma=18, Df=1.5, B=2, phi=30, method="meyerhof")
print(result["q_u"])   # ultimate bearing capacity in kPa

GeoEq implements the NCEER / Idriss-Boulanger simplified procedure. Compute the cyclic stress ratio (CSR), the cyclic resistance ratio (CRR), and the factor of safety against liquefaction:

csr = ge.liquefaction_csr(amax=0.25, sigma_v=120, sigma_v_eff=70, z=6, Mw=7.0)
crr = ge.liquefaction_crr(N160cs=12, method="youd_2001")
fs  = ge.liquefaction_fos(csr["CSR"], crr["CRR"], Mw=7.0)

GeoEq supports three systems: ge.classify_uscs() (Unified Soil Classification System, ASTM D2487), ge.classify_aashto() (AASHTO M145), and ge.classify_usda() (USDA soil texture triangle).

Yes. GeoEq is licensed under Apache 2.0 — free for personal, academic, commercial, consulting, and enterprise use, with an explicit patent grant. No fees, no dual licensing.

Only numpy, matplotlib, and scipy. GeoEq runs on Python 3.9+ on Windows, macOS, and Linux.

Spreadsheets hide formulas in cells, break silently on edits, and are hard to review or reuse. GeoEq calculations are reproducible, version-controlled, unit-safe, textbook-cited, and test-backed — and produce publication-quality figures out of the box.

Pull requests are welcome once the project reaches v1.0; until then, please open an issue first.

• Formula bug or unit error? Open an issue with a textbook citation.
• Feature request? Open an issue tagged enhancement with the use case.
• Using GeoEq in research or teaching? Open an issue tagged usage — we'd love to hear about it.

@software{geoeq2026,
  author       = {Malo, Ripon Chandra},
  title        = {GeoEq: A Python Library for Geotechnical Engineering},
  year         = {2026},
  version      = {0.1.3},
  url          = {https://github.com/geoeq/geoeq},
  license      = {Apache-2.0}
}

Apache 2.0 — free for personal, commercial, consulting, and enterprise use forever, with explicit patent protection. See LICENSE.

Copyright © 2026 Ripon Chandra Malo · University of Utah

This package was built using projectmem — a local-first memory and judgment layer for AI coding agents that tracks decisions, prevents repeated mistakes, and maintains project context across sessions.