Skip to content

Why GeoEq

The problem

Geotechnical analysis still runs on spreadsheets. One tab per soil layer, copy-pasted Boussinesq equations, magic-number unit conversions, =IF() ladders nobody else can read six months later. Reports are non-reproducible. Calculations get redone from scratch every project. New engineers re-derive Terzaghi every time they touch a footing.

The intent

geoeq makes the working set of textbook geotechnical formulas, ASTM/BS/IS test procedures, and standard correlations available as a flat, validated, MIT-licensed Python API. Every function does one thing. Every formula cites its source.

Design principles

Flat API

import geoeq as ge, then call functions. You never need to remember which submodule a function lives in:

Python
ge.void_ratio(n=0.42)            # ge.soil.properties
ge.bearing_capacity(...)         # ge.design.bearing
ge.liquefaction_fos(CSR, CRR)    # ge.dynamics.liquefaction
ge.read_gef("cpt.gef")           # ge.io.gef_reader

No deep imports. No class hierarchies. Functions are the unit of work.

Validated inputs

Every function checks the physical meaningfulness of its arguments and raises ValueError with an engineer-readable message:

Python
>>> ge.density(Gs=2.65, e=-0.5, kind="dry")
ValueError: e must be > 0, got -0.5

This catches typos and unit mistakes immediately instead of letting them propagate through a long calculation.

Traceable formulas

Every function's docstring cites the textbook section or original paper from which the equation is taken:

Python
>>> help(ge.bearing_capacity)
...
References
----------
* Terzaghi (1943); Meyerhof (1963); Hansen (1970); Vesic (1973);
  Das (2014) Ch. 4.

You can always re-derive the result by hand from the cited source.

No magic

Returns are plain dictionaries or NumPy arrays. There is nothing hidden in a custom class. Inspect, slice, feed into Pandas, do whatever you would do with NumPy output.

Python
res = ge.bearing_capacity(c=10, gamma=18, Df=1, B=2, phi=30)
# {'q_u': 612.5, 'Nc': 30.14, 'Nq': 18.40, 'Ngamma': 15.67,
#  'sc': ..., 'method': 'meyerhof'}

Test-backed

The package ships with 563 unit tests across 22 test files. Where possible, tests verify against published textbook values:

  • Fadum's \(I_5(m=1,n=1) = 0.1752\) (Das Table 6.5)
  • Meyerhof's \(N_c = 30.14\), \(N_q = 18.40\), \(N_\gamma = 15.67\) at \(\phi=30°\)
  • Hansen's \(N_\gamma = 14.39\) at \(\phi=30°\)
  • Vesic's \(N_\gamma = 22.40\) at \(\phi=30°\)
  • Westergaard at \(r=0\), \(\mu=0\) gives \(2P / (\pi z^2)\)
  • Rankine \(K_a \cdot K_p = 1\) for smooth walls
  • Terzaghi \(T_v = 0.196\) at \(U=50\%\), \(T_v = 0.848\) at \(U=90\%\)
  • Boussinesq circular at \(z=R\) gives \(\Delta\sigma/q = 0.6465\)
  • Hardin & Drnevich plasticity exponent \(k(PI)\) ramping 0 → 0.5
  • NCEER liquefaction \(CRR_{7.5}\) at \((N_1)_{60,cs}=10\) ≈ 0.11
  • Schmertmann strain-influence peak at \(z=0.5B\) (square) or \(z=1.0B\) (strip)

Continuous-integration runs the suite on every push.

Publication quality plots

The plotting helpers produce 300 DPI Matplotlib figures with semi-log axes, shaded ASTM particle zones, red-dashed \(D_x\) projection lines, and clean parameter boxes out of the box. Every plot function accepts an ax= argument so you can embed it in a multi-panel report figure.

MIT licence forever

Commercial consulting, in-house tools, research, teaching. No exceptions, no dual licensing.

What geoeq is not

  • Not a numerical solver. No PLAXIS-style finite element analysis here. geoeq is the working set of analytical and empirical formulas; for full FEA, use Plaxis, FLAC, or Abaqus.
  • Not opinionated about workflow. It does not enforce a ground-investigation methodology, a particular standard (ASTM vs Eurocode), or a report format. Use what your jurisdiction requires.
  • Not a replacement for engineering judgement. A factor of safety computed by geoeq is only as good as the soil properties you fed in. Validate against measured behaviour on every project.

Validation philosophy

Every release is built from a tagged commit that:

  1. Passes the full 563-test suite (pytest).
  2. Passes python -m twine check dist/*.
  3. Compares spot-check values against the published textbook tables in Das (2010), Das (2014), Bowles (1996), Holtz & Kovacs (1981), Budhu (2011), Kramer (1996).
  4. Has the version bumped in both pyproject.toml and src/geoeq/__init__.py's __version__.

If you find a discrepancy from a textbook value, open an issue with the citation.

Citation

If geoeq saved you spreadsheet-hours on a paper or thesis:

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