Skip to content

Quick start

A complete end-to-end screen of a multi-layer site, in fifteen lines. You will build a profile, compute stress, check a footing, predict settlement, and run a liquefaction triggering check.

The full example

Python
import geoeq as ge

# 1. Define a layered profile with a 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 of 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. Primary consolidation settlement under 15 kPa increase -----------------
S = ge.settlement_primary(Cc=0.27, e0=0.92, H=3.66,
                          sigma0=80, delta_sigma=15)
print(f"S = {S*1000:.1f} mm")
# S = 38.4 mm

# 4. Liquefaction triggering at the sand (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, 'MSF': 1.19, 'K_sigma': 1.0, 'K_alpha': 1.0}

That is four lines of imports plus four short blocks — a complete geotechnical screen of a multi-layer site, ready for a report.

Step-by-step

1. Build the profile

A SoilProfile is a list of (top, bottom, Soil) tuples with an optional water-table depth. Layers must be contiguous (no gaps, no overlaps) and ordered top-to-bottom. Positive z is downward.

Python
clay = ge.Soil("Soft Clay", gamma=17, gamma_sat=18.5,
               phi=0, c=25, Cc=0.27, e=0.92)
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=2.0)

Soil is a plain dataclass — only name is required, everything else has sensible defaults. The fields you do not provide simply will not be available downstream.

2. Compute stress at any depth

The profile integrates unit weights downward, applying \(\gamma\) above the water table and \(\gamma_{\text{sat}}\) below it. Pore pressure is hydrostatic from the water table down.

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

p.total_stress([2, 5, 10])         # vectorised — accepts arrays
p.layer_at(5).name                  # 'Soft Clay'

You can also plot the full \(\sigma\)–\(u\)–\(\sigma'\) vs depth profile:

Python
p.plot(dz=0.1, save_as="profile.pdf")

Stress profile

Total, pore, and effective vertical stress vs depth. Generated by SoilProfile.plot().

3. Check the footing — bearing capacity

bearing_capacity() implements the full Meyerhof / Hansen / Vesic equation with shape, depth, and inclination factors selectable per call.

Python
bc = ge.bearing_capacity(
    c=25, gamma=18.5 - 9.81,   # effective unit weight under water
    Df=2, B=3, L=3, phi=0,
    method="meyerhof",
)
print(bc["q_u"])               # 192 kPa

Try all four methods to see how they compare on this footing:

Python
for m in ("terzaghi", "meyerhof", "hansen", "vesic"):
    q = ge.bearing_capacity(c=25, gamma=8.7, Df=2, B=3, L=3,
                             phi=0, method=m)["q_u"]
    print(f"{m:9s} -> {q:.0f} kPa")

4. Predict settlement

For a saturated clay, primary consolidation:

Python
S = ge.settlement_primary(Cc=0.27, e0=0.92, H=3.66,
                          sigma0=80, delta_sigma=15)
print(f"S = {S*1000:.1f} mm")    # 38.4 mm

The function handles NC / OC-below-pc / OC-crossing-pc automatically via kind="auto". See the Settlement page for full details including Schmertmann strain-influence for sand.

5. Liquefaction triggering

The complete simplified procedure (Seed & Idriss 1971, NCEER):

Python
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, 'MSF': 1.19, ...}

FS_L < 1 indicates liquefaction is predicted under the design earthquake. See the Soil dynamics page for the full triggering workflow and chart helpers.

Where to go next

  • Tutorials: 25 chapter-by-chapter notebooks at Tutorials.
  • API reference: every function with full docstring at API reference.
  • Per-module guides: focused walkthroughs of each module's intent and methods at User guide.