Skip to content
GeoEQ · Geotechnical software research lab · University of Utah

Solutions · Automation with Python

Geotechnical calculations in Python: scripted, batched and reproducible.

Turn the calculations you repeat on every project into code you can rerun, check and share.

The short answer

Write the calculation once, run it on every borehole.

You can automate geotechnical calculations in Python by scripting each step, such as SPT corrections, soil classification, bearing capacity and liquefaction triggering, with the open-source geoeq library (pip install geoeq), so every result is reproducible from the inputs.

Spreadsheets are fine for one footing. They get fragile when the same procedure must run over fifty boreholes, a dozen trial designs, or a parametric study. Scripting those steps in Python keeps inputs, method and output together.

The workflow

Where Python fits in a geotechnical workflow.

Each step below shows which GeoEQ tool covers it. Steps marked as your own tools are not covered by GeoEQ.

  1. Step 01

    Field data and borehole logs

    Blow counts, strata, samples and groundwater are recorded and drawn as logs.

    GeoEQ SPT Logs AvailableFree

    GeoEQ SPT Logs produces the log sheets. Scripted calculations start from the values on those logs, typed or loaded into your script.

  2. Step 02

    Corrections and classification

    N60 and (N1)60 from field N, USCS and AASHTO group symbols, Atterberg indices.

    geoeq for Python AvailableOpen source

    geoeq functions spt_n60, spt_n160, spt_n160cs, classify_uscs, classify_aashto and atterberg run these over a whole borehole in a loop or array.

  3. Step 03

    Parameters and stresses

    Total and effective stress, correlations from SPT and CPT, layered profiles.

    geoeq for Python AvailableOpen source

    geoeq includes stress, pore pressure and SPT and CPT correlation functions.

  4. Step 04

    Design checks

    Shallow foundation bearing capacity, settlement, earth pressure and liquefaction triggering.

    geoeq for Python AvailableOpen source

    geoeq functions such as bearing_capacity, liquefaction_csr, liquefaction_crr and liquefaction_fos, each callable with the inputs you choose.

  5. Step 05

    Checking, reviewing and sign-off

    The engineer reviews inputs, judges whether each method applies and signs the result.

    Your own tools

    Done by you. A script records the calculation, it does not replace judgement.

  6. Step 06

    Report and drawings

    Tables, figures, calculation sheets and the report text.

    Your own tools

    Outside GeoEQ for Python: done in your own tools (a notebook, Word, a CAD or reporting package).

Worked examples

Four calculations, scripted.

Each snippet was run with geoeq and the output shown is what it printed. The input values are illustrative, not from a real site.

Batch SPT corrections for one borehole

Field blow counts become N60 (energy and rod-length corrections) and then (N1)60 (overburden correction). Here the rod-length factor Cr is 0.85 and the effective stresses are typed in; a real script would read them from your profile.

import geoeq as ge

# Field SPT blow counts (N) at depth, for one borehole
depths = [1.5, 3.0, 4.5, 6.0]      # m
N      = [8, 11, 14, 18]
sigma_v_eff = [24, 42, 58, 73]      # kPa, effective vertical stress

for z, n, s in zip(depths, N, sigma_v_eff):
    n60  = ge.spt_n60(n, ER=60, Cb=1.0, Cs=1.0, Cr=0.85)
    n160 = ge.spt_n160(n60, s)
    print(f"{z:>4} m  N={n:>2}  N60={n60:5.1f}  (N1)60={n160:5.1f}")

Output

 1.5 m  N= 8  N60=  6.8  (N1)60= 13.6
 3.0 m  N=11  N60=  9.3  (N1)60= 14.4
 4.5 m  N=14  N60= 11.9  (N1)60= 15.6
 6.0 m  N=18  N60= 15.3  (N1)60= 17.9

Classify a soil from index properties

USCS classification from liquid limit, plastic limit and gradation, following the ASTM D2487 flowchart, plus the plasticity index.

import geoeq as ge

soil = ge.classify_uscs(LL=48, PL=22, gravel=2, sand=18, fines=80)
print(soil)
print("PI =", ge.atterberg(LL=48, PL=22))

Output

{'symbol': 'CL', 'name': 'Lean clay'}
PI = 26.0

Bearing capacity and a parameter sweep

The documented example from the package, followed by a loop over embedment depth. The Meyerhof option is used here; a hand check of the method you choose remains good practice.

import geoeq as ge

res = ge.bearing_capacity(c=25, gamma=18, Df=1.5, B=2, phi=30, method="meyerhof")
print(round(res["q_u"], 1), "kPa")

# Parameter sweep: embedment depth
for Df in (0.5, 1.0, 1.5, 2.0):
    q = ge.bearing_capacity(c=25, gamma=18, Df=Df, B=2, phi=30, method="meyerhof")["q_u"]
    print(f"Df = {Df} m  q_u = {q:7.1f} kPa")

Output

1829.3 kPa
Df = 0.5 m  q_u =  1285.8 kPa
Df = 1.0 m  q_u =  1550.4 kPa
Df = 1.5 m  q_u =  1829.3 kPa
Df = 2.0 m  q_u =  2122.6 kPa

A liquefaction triggering check at one depth

Cyclic stress ratio from the design motion, cyclic resistance ratio from (N1)60cs by the NCEER (Youd et al. 2001) equation, and the factor of safety. FS below 1.0 means liquefaction is predicted at that depth.

import geoeq as ge

csr = ge.liquefaction_csr(amax=0.25, sigma_v=110, sigma_v_eff=73, Mw=7.5, z=6.0)
crr = ge.liquefaction_crr(N160cs=18, method="youd_2001")
fos = ge.liquefaction_fos(csr["CSR"], crr["CRR"], Mw=7.5)
print(csr); print(crr); print(fos)

Output

{'CSR': 0.2324061781360049, 'rd': 0.9491273288910969, 'amax_g': 0.25}
{'CRR': 0.19182098765432098, 'method': 'youd_2001'}
{'FS': 0.825492775397813, 'MSF': 1.0001492712300064, 'K_sigma': 1.0, 'K_alpha': 1.0, 'liquefies': True}

Why script it

What scripting gives you.

Reproducible
The inputs, the method and the result live in one file. Rerun it next year, or hand it to a reviewer, and get the same numbers.
Batch work
Apply the same correction to every depth, every borehole, or every trial footing, instead of copying a spreadsheet formula down a column.
Parameter studies
Sweep a footing width, an acceleration or a water table depth in a loop and plot the result with matplotlib.
Version control
Calculation scripts are text. They can be reviewed, diffed and tested like any other code.

Common pitfalls

Where scripted calculations go wrong.

  • Mixed units. Check kPa against kN/m³, metres against millimetres, and fractions of g against percent, before you loop over a hundred rows.
  • Correction factors typed in by habit. Energy ratio, borehole, sampler and rod-length factors depend on the equipment used on that job.
  • Applying a method outside its range. A function returning a number does not mean the method suits your soil, depth or site.
  • Unchecked output. Verify a script on a hand calculation you trust, then keep that case as a test.
  • Hidden state in notebooks. Run the notebook from top to bottom before you trust a result.

Read how the corrections work in SPT N-value corrections: N60 and N1(60) explained.

Tools for this work

GeoEQ tools for scripted calculations.

geoeq for Python

AvailableOpen source

170+ geotechnical functions, and the engine behind the desktop programs.

GeoEQ SPT Logs

AvailableFree

Log boreholes from soil to rock and export finished log sheets.

More: the open-source package, all GeoEQ software, geotechnical applications, reading the plasticity chart and all solutions.

Direct answers

Questions about Python for geotechnical work.

Can I automate geotechnical calculations with Python?

Yes. Python lets you script repeated calculations such as SPT corrections, soil classification, bearing capacity and liquefaction checks, and run them over many depths, boreholes or design cases in one pass. The open-source geoeq library provides these functions ready to call.

What is a Python library for geotechnical calculations?

It is a package of ready-made engineering functions you import into your own scripts or notebooks. geoeq is one such open-source library, with more than 170 functions covering soil classification, laboratory tests, site investigation, foundation design and liquefaction. Other open-source Python packages for geotechnical work exist, so compare their scope before you choose.

How do I install the geoeq library?

Run pip install geoeq. It supports Python 3.9 to 3.13 and depends only on numpy, scipy and matplotlib. The documentation is at docs.geoeq.org.

Which calculations can I script with geoeq?

Soil properties and classification, laboratory test reduction, SPT and CPT corrections and correlations, bearing capacity, settlement, earth pressure and liquefaction triggering, among others. The page on the open-source package lists the domains in full.

How do I correct SPT N-values for many depths at once?

Pass the field N values and correction factors to spt_n60, then pass the result and the effective vertical stress to spt_n160, inside a loop or with numpy arrays. The functions accept a single number or an array.

Is geoeq free to use?

Yes. geoeq is open source under the Apache 2.0 licence, so you can use it, read the source and cite it in your work.

Can I use geoeq in a Jupyter notebook?

Yes. It is an ordinary Python package, so it imports in a notebook like numpy or matplotlib, and results are plain numbers and dictionaries you can tabulate or plot.

Does a script replace checking calculations by hand?

No. A script makes a calculation repeatable, not correct. Check the method suits the ground and the project, and verify the script against a hand calculation you trust before relying on it.

geoeq for Python · Available

Install it and run your first check.