driven-pile 0.1.0__py3-none-any.whl

driven_pile/__init__.py

@@ -0,0 +1,28 @@
+"""driven-pile: long-term capacity of driven piles from the pile-driving log.
+
+Each logged foot of driving
+characterizes the soil at the toe once (friction angle, equivalent N1,60,
+cyclic resistance), the pore pressure generated by later hammer blows sets
+that foot's shaft resistance for the rest of the drive, and the end-of-drive
+characterization with pore pressure dissipated gives the long-term capacity.
+"""
+
+from .analysis import analyze
+from .capacity import long_term_capacity
+from .inputs import DriveLog, Hammer, Pile, SoilProfile, bpm_to_stroke, stroke_to_bpm
+from .march import run_drive
+from .montecarlo import monte_carlo
+from .options import ModelOptions, MonteCarloOptions
+from .preprocess import Target, prepare_target
+from .results import Analysis, DriveResult, MonteCarloResult, TopPhiBand
+from .top_segment import sweep_top_phi
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Analysis", "DriveLog", "DriveResult", "Hammer", "ModelOptions",
+    "MonteCarloOptions", "MonteCarloResult", "Pile", "SoilProfile", "Target",
+    "TopPhiBand", "analyze",
+    "bpm_to_stroke", "long_term_capacity", "monte_carlo", "prepare_target",
+    "run_drive", "stroke_to_bpm", "sweep_top_phi",
+]

driven_pile/analysis.py

@@ -0,0 +1,43 @@
+"""One-call analysis of a driving log."""
+
+from __future__ import annotations
+
+from .march import run_drive
+from .montecarlo import monte_carlo
+from .options import ModelOptions, MonteCarloOptions
+from .preprocess import prepare_target
+from .results import Analysis
+from .top_segment import sweep_top_phi
+
+
+def analyze(log, soil, options=None, mc_options=None, run_mc=False):
+    """Characterize the soil from a driving log and estimate long-term capacity.
+
+    Parameters
+    ----------
+    log : DriveLog
+        The driving record, with its pile and hammer.
+    soil : SoilProfile
+        Mudline, water table, unit weight and fines content.
+    options : ModelOptions, optional
+        Model parameters; defaults to the published values.
+    mc_options : MonteCarloOptions, optional
+        Monte Carlo settings, used when ``run_mc`` is True.
+    run_mc : bool, default False
+        Also run the Monte Carlo simulation.
+
+    Returns
+    -------
+    Analysis
+        The deterministic run uses the lowest admissible top-segment
+        friction angle.
+    """
+    options = options or ModelOptions()
+    target = prepare_target(log, soil, options)
+    band = sweep_top_phi(target, options)
+    drive = run_drive(target, options, top_phi=band.lo)
+    mc = None
+    if run_mc:
+        mc = monte_carlo(log, soil, options, mc_options or MonteCarloOptions(),
+                         target=target, top_band=band)
+    return Analysis(drive=drive, top_band=band, mc=mc)

driven_pile/bearing.py

@@ -0,0 +1,148 @@
+"""Toe bearing in sand: Vesic cavity expansion with a stress-dependent rigidity
+index, and its inversion for the friction angle."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import brentq
+
+from .constants import ABOVE_CEILING, BELOW_FLOOR, NONFINITE, OK, P_ATM
+
+_GRID_POINTS = 512
+
+
+def nq_vesic(phi, irr, k0=None):
+    """Vesic bearing capacity factor on vertical effective stress.
+
+    Parameters
+    ----------
+    phi : array_like
+        Friction angle, deg.
+    irr : array_like
+        Reduced rigidity index.
+    k0 : array_like, optional
+        At-rest earth pressure coefficient; ``1 - sin(phi)`` by default.
+
+    Returns
+    -------
+    ndarray
+        ``N_q* = N_sigma (1 + 2 K0) / 3`` with
+        ``N_sigma = 3 / (3 - sin phi) exp((pi/2 - phi) tan phi)
+        tan^2(45 + phi/2) Irr^(4 sin phi / (3 (1 + sin phi)))``.
+
+    References
+    ----------
+    Vesic (1977).
+    """
+    p = np.radians(np.asarray(phi, dtype=float))
+    sin_p = np.sin(p)
+    if k0 is None:
+        k0 = 1.0 - sin_p
+    n_sigma = (
+        (3.0 / (3.0 - sin_p))
+        * np.exp((np.pi / 2.0 - p) * np.tan(p))
+        * np.tan(np.pi / 4.0 + p / 2.0) ** 2
+        * np.asarray(irr, dtype=float) ** (4.0 * sin_p / (3.0 * (1.0 + sin_p)))
+    )
+    return n_sigma * (1.0 + 2.0 * k0) / 3.0
+
+
+def rigidity_index(phi, sigma_v, options):
+    """Rigidity index from a stress-dependent shear modulus.
+
+    Parameters
+    ----------
+    phi : array_like
+        Friction angle, deg.
+    sigma_v : array_like
+        Vertical effective stress, ksf.
+    options : ModelOptions
+        Supplies ``g_ratio``, ``k2_lo``, ``k2_hi``, ``phi_lo``, ``phi_hi``
+        and ``irr_bounds``.
+
+    Returns
+    -------
+    ndarray
+        ``I_r = g_ratio G_max / (sigma'_m tan phi)`` clamped to
+        ``irr_bounds``, with ``sigma'_m = (1 + 2 K0) / 3 sigma'_v`` and
+        ``G_max = 21.7 K2 Pa sqrt(sigma'_m / Pa)``.
+
+    References
+    ----------
+    Seed and Idriss (1970).
+    """
+    phi = np.asarray(phi, dtype=float)
+    p = np.radians(phi)
+    k0 = 1.0 - np.sin(p)
+    sig_m = np.maximum((1.0 + 2.0 * k0) / 3.0 * np.asarray(sigma_v, dtype=float), 1e-3)
+    k2 = np.interp(phi, [options.phi_lo, options.phi_hi], [options.k2_lo, options.k2_hi])
+    g_max = 21.7 * k2 * P_ATM * np.sqrt(sig_m / P_ATM)
+    ir = options.g_ratio * g_max / (sig_m * np.tan(p))
+    return np.clip(ir, *options.irr_bounds)
+
+
+def toe_bearing(sigma_v, phi, options):
+    """Unit toe resistance ``q_p = N_q*(phi, I_r) sigma'_v``, ksf."""
+    irr = rigidity_index(phi, sigma_v, options)
+    return np.asarray(sigma_v, dtype=float) * nq_vesic(phi, irr)
+
+
+def phi_from_toe_bearing(q_needed, sigma_v, options):
+    """Friction angle whose toe bearing on ``sigma_v`` equals ``q_needed``.
+
+    Parameters
+    ----------
+    q_needed : float
+        Required unit toe resistance, ksf.
+    sigma_v : float
+        Vertical effective stress at the toe, ksf.
+    options : ModelOptions
+        Supplies the friction angle bounds and rigidity parameters.
+
+    Returns
+    -------
+    phi : float
+        Friction angle, deg, held at a bound when the requirement lies
+        outside the attainable range; NaN when ``q_needed`` is not finite.
+    reason : str
+        One of the reason codes in `driven_pile.constants`.
+    """
+    lo, hi = options.phi_lo, options.phi_hi
+    if not np.isfinite(q_needed):
+        return np.nan, NONFINITE
+    if sigma_v <= 0:
+        return lo, BELOW_FLOOR
+    if q_needed <= toe_bearing(sigma_v, lo, options):
+        return lo, BELOW_FLOOR
+    if q_needed >= toe_bearing(sigma_v, hi, options):
+        return hi, ABOVE_CEILING
+    phi = brentq(lambda p: float(toe_bearing(sigma_v, p, options)) - q_needed, lo, hi)
+    return phi, OK
+
+
+def phi_from_toe_bearing_grid(q_needed, sigma_v, options):
+    """Friction angle from toe bearing by interpolation on a fixed grid.
+
+    Parameters
+    ----------
+    q_needed : float or array_like
+        Required unit toe resistance, ksf.
+    sigma_v : float or array_like
+        Vertical effective stress at the toe, ksf.
+    options : ModelOptions
+        Supplies the friction angle bounds and rigidity parameters.
+
+    Returns
+    -------
+    float or ndarray
+        Friction angle, deg, clamped to the bounds. Faster than
+        `phi_from_toe_bearing` when evaluated many times.
+    """
+    grid = np.linspace(options.phi_lo, options.phi_hi, _GRID_POINTS)
+    sig = np.atleast_1d(np.asarray(sigma_v, dtype=float))
+    q = np.broadcast_to(np.atleast_1d(np.asarray(q_needed, dtype=float)), sig.shape)
+    out = np.empty_like(sig)
+    for k, (s_k, q_k) in enumerate(zip(sig, q)):
+        qp = toe_bearing(max(s_k, 1e-9), grid, options)
+        out[k] = np.interp(q_k, qp, grid)
+    return out if np.ndim(sigma_v) else float(out[0])

driven_pile/capacity.py

@@ -0,0 +1,73 @@
+"""Long-term capacity from the end-of-drive characterization."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .bearing import toe_bearing
+from .constants import FOOT_INCREMENT
+
+
+def shaft_long_term(fs_ltc, pile):
+    """Long-term shaft resistance, kips.
+
+    Parameters
+    ----------
+    fs_ltc : array_like
+        Unit shaft resistance per foot after pore-pressure dissipation, ksf.
+    pile : Pile
+        Supplies the perimeter.
+    """
+    fs = np.asarray(fs_ltc, dtype=float)
+    return float(np.nansum(fs) * pile.perimeter * FOOT_INCREMENT)
+
+
+def toe_end_of_drive(phi, sigma_v0, ru_toe, residual, pile, options):
+    """Toe resistance at the end of the drive, kips.
+
+    Parameters
+    ----------
+    phi : float
+        Friction angle of the final foot, deg.
+    sigma_v0 : float
+        Static vertical effective stress at the toe, ksf.
+    ru_toe : float
+        Pore-pressure ratio applied to the toe stress.
+    residual : float
+        Modeled minus target capacity at the final reconciled foot, kips;
+        subtracted from the toe so the end-of-drive total matches the log.
+    pile : Pile
+        Supplies the toe area.
+    options : ModelOptions
+        Rigidity parameters.
+
+    Returns
+    -------
+    float
+        Vesic bearing on the reduced stress ``(1 - ru_toe) sigma'v0``, less
+        the residual, floored at zero. No toe setup is modeled.
+    """
+    if not np.isfinite(phi):
+        return 0.0
+    qp = float(toe_bearing(sigma_v0 * (1.0 - ru_toe), phi, options)) * pile.area
+    return max(qp - residual, 0.0)
+
+
+def long_term_capacity(result):
+    """Long-term shaft and toe resistance of a `DriveResult`.
+
+    Parameters
+    ----------
+    result : DriveResult
+
+    Returns
+    -------
+    shaft, toe : float
+        Kips. The toe is its end-of-drive value.
+    """
+    shaft = shaft_long_term(result.fs_ltc, result.pile)
+    m = np.isfinite(result.target) & np.isfinite(result.predicted)
+    residual = float(result.predicted[m][-1] - result.target[m][-1]) if m.any() else 0.0
+    toe = toe_end_of_drive(result.phi[-1], result.sigma_v0[-1], result.ru_toe[-1],
+                           residual, result.pile, result.options)
+    return shaft, toe

driven_pile/constants.py

@@ -0,0 +1,24 @@
+"""Physical constants and the per-foot reason codes shared across modules."""
+
+GAMMA_WATER = 0.0624
+"""Unit weight of water, ksf/ft."""
+
+P_ATM = 2.116
+"""Atmospheric pressure, ksf."""
+
+G_FT_S2 = 32.2
+"""Gravitational acceleration, ft/s^2."""
+
+FOOT_INCREMENT = 1.0
+"""Length of one analysis increment, ft."""
+
+OK = "ok"
+ABOVE_CEILING = "above_ceiling"
+BELOW_FLOOR = "below_floor"
+NONFINITE = "nonfinite"
+TOP_SEGMENT = "top_segment"
+
+LIQ_BEFORE = "before"
+LIQ_DURING = "during"
+LIQ_AFTER = "after"
+LIQ_NEVER = ""

driven_pile/formulas.py

@@ -0,0 +1,61 @@
+"""Dynamic capacity formula applied to the driving log."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def elastic_set(stroke, ram_weight, pile):
+    """Elastic compression term of the Danish formula.
+
+    Parameters
+    ----------
+    stroke : array_like
+        Hammer stroke, ft.
+    ram_weight : float
+        Ram weight, kips.
+    pile : Pile
+        Pile geometry and modulus.
+
+    Returns
+    -------
+    ndarray
+        ``s0 = sqrt(W h L / (2 A E))``, ft.
+    """
+    stroke = np.asarray(stroke, dtype=float)
+    return np.sqrt(ram_weight * stroke * pile.length / (2.0 * pile.area * pile.modulus))
+
+
+def danish_capacity(bpf, stroke, ram_weight, pile, c1=0.45, c2=0.0):
+    """Capacity at the time of driving from the recalibrated Danish formula.
+
+    Parameters
+    ----------
+    bpf : array_like
+        Blows per foot.
+    stroke : array_like
+        Hammer stroke, ft.
+    ram_weight : float
+        Ram weight, kips.
+    pile : Pile
+        Pile geometry and modulus.
+    c1, c2 : float
+        Multiplicative and additive (kips) recalibration coefficients.
+
+    Returns
+    -------
+    ndarray
+        ``c1 * W h / (s + s0) + c2``, kips, with the set per blow
+        ``s = 1 / bpf`` ft.
+
+    References
+    ----------
+    Sorensen and Hansen (1957); Reddy and Stuedlein (2013), Puget Sound
+    recalibration with unadjusted hammer energy.
+    """
+    bpf = np.asarray(bpf, dtype=float)
+    stroke = np.asarray(stroke, dtype=float)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        s = 1.0 / bpf
+        q = ram_weight * stroke / (s + elastic_set(stroke, ram_weight, pile))
+    return c1 * q + c2