----------------------------------------------------------------------
This is the API documentation for the driven_pile library.
----------------------------------------------------------------------


## Inputs

The driving record, the pile and hammer that produced it, and the ground it was driven through.


DriveLog(pile: 'Pile', hammer: 'Hammer', elevation: 'np.ndarray', bpm: 'np.ndarray', bpf: 'np.ndarray', pile_id: 'str | None' = None) -> None

A pile-driving record, one entry per logged foot.

Attributes
----------
pile : Pile
    The pile that was driven.
hammer : Hammer
    The hammer that drove it.
elevation : ndarray
    Toe elevation at the end of each logged foot, ft.
bpm : ndarray
    Hammer blows per minute.
bpf : ndarray
    Blows per foot.
pile_id : str, optional
    Identifier of the pile.

Pile(area: 'float', perimeter: 'float', width: 'float', length: 'float', modulus: 'float') -> None

Pile geometry and stiffness.

Attributes
----------
area : float
    Cross-sectional area, ft^2.
perimeter : float
    Perimeter, ft.
width : float
    Width across flats (or diameter), ft.
length : float
    Total pile length, ft.
modulus : float
    Elastic modulus of the pile material, ksf.

Hammer(ram_weight: 'float') -> None

Driving hammer.

Attributes
----------
ram_weight : float
    Weight of the ram, kips.

SoilProfile(mudline: 'float', fines: 'np.ndarray', elevation: 'np.ndarray | None' = None, water_elevation: 'float' = 0.0, gamma_total: 'float' = 0.122) -> None

Ground conditions at a pile location.

Attributes
----------
mudline : float
    Elevation of the soil surface the pile was driven through, ft.
fines : ndarray
    Fines content (percent passing the No. 200 sieve) at each row of
    ``elevation``. A single value gives a uniform profile.
elevation : ndarray or None
    Elevations of the fines rows, ft; None for a uniform profile.
water_elevation : float, default 0.0
    Elevation of the water table, ft.
gamma_total : float, default 0.122
    Total unit weight of the soil, ksf/ft.

bpm_to_stroke(bpm)

Hammer stroke from the blow rate of a free-falling ram.

Parameters
----------
bpm : array_like
    Hammer blows per minute.

Returns
-------
ndarray
    Stroke (drop height), ft.

Notes
-----
The ram is in free flight for the time between blows, rising for half of
it and falling for the other half, so ``h = g / 2 * (t / 2)**2`` with
``t = 60 / bpm`` seconds.

stroke_to_bpm(stroke)

Blow rate of a free-falling ram from its stroke; inverse of `bpm_to_stroke`.

Parameters
----------
stroke : array_like
    Stroke (drop height), ft.

Returns
-------
ndarray
    Hammer blows per minute.


## Options

Model parameters and Monte Carlo settings, with the published values as defaults.


ModelOptions(c1: 'float' = 0.45, c2: 'float' = 0.0, phi_lo: 'float' = 25.0, phi_hi: 'float' = 45.0, g_ratio: 'float' = 0.05, k2_lo: 'float' = 30.0, k2_hi: 'float' = 75.0, irr_bounds: 'tuple' = (10.0, 500.0), cc_delta_ratio: 'float' = 0.8, sr_psi_nc: 'float' = 0.22, zone_factor: 'float' = 1.5, b_exponent: 'float' = 0.34, ru_cap_toe: 'float' = 0.9, dphi: 'float' = 0.0, crr_multiplier: 'float' = 1.0, smoothing_window: 'int' = 13, smoothing_order: 'int' = 2, tip_anchor: 'bool' = True, top_sweep_step: 'float' = 1.0, top_sweep_tol_frac: 'float' = 0.05, top_sweep_tol_kips: 'float' = 1.0, max_iter: 'int' = 60, ru_tol: 'float' = 0.0001) -> None

Parameters of the drive model.

Attributes
----------
c1, c2 : float
    Multiplicative and additive (kips) recalibration coefficients of the
    Danish formula (Reddy and Stuedlein, 2013).
phi_lo, phi_hi : float
    Bounds on the friction angle, deg (WSDOT GDM correlation range).
g_ratio : float
    Ratio of the operative shear modulus to the small-strain modulus in
    the rigidity index.
k2_lo, k2_hi : float
    Seed and Idriss (1970) modulus coefficient K2,max at ``phi_lo`` and
    ``phi_hi``; interpolated linearly in friction angle.
irr_bounds : tuple of float
    Clamp on the rigidity index.
cc_delta_ratio : float
    Interface friction angle divided by the soil friction angle in the
    Coyle and Castello (1981) shaft resistance.
sr_psi_nc : float
    Normally consolidated strength ratio in the Randolph and Murphy (1985)
    interface factor applied to the residual strength.
zone_factor : float
    A foot starts accumulating blows when the toe is within
    ``zone_factor * width`` above it.
b_exponent : float
    Exponent of the cyclic strength curve.
ru_cap_toe : float
    Largest pore-pressure ratio applied to the toe stress.
dphi : float
    Shift of the friction angle correlation line, deg.
crr_multiplier : float
    Multiplier on the cyclic resistance ratio.
smoothing_window, smoothing_order : int
    Savitzky-Golay window (feet) and polynomial order for the capacity
    target.
tip_anchor : bool
    Replace the smoothed capacity at the final foot with the unsmoothed
    value.
top_sweep_step : float
    Step of the top-segment friction angle sweep, deg.
top_sweep_tol_frac, top_sweep_tol_kips : float
    A swept value is admissible when its log-fit RMS is within
    ``max(top_sweep_tol_frac * rms_min, top_sweep_tol_kips)`` of the
    minimum.
max_iter : int
    Iteration limit of the per-foot solves.
ru_tol : float
    Tolerance of the pore-pressure ratio fixed point.

MonteCarloOptions(bias_cov: 'float' = 0.35, crr_sigma_ln: 'float' = 0.2, dphi_bound: 'float' = 2.5, target_noise: 'bool' = True, ci_target: 'float' = 0.02, chunk: 'int' = 100, max_realizations: 'int' = 1200, seed: 'int | None' = None) -> None

Monte Carlo settings.

Attributes
----------
bias_cov : float
    Coefficient of variation of the lognormal capacity-formula bias
    (mean 1), drawn per realization.
crr_sigma_ln : float
    Log standard deviation of the lognormal multiplier on the cyclic
    resistance ratio (median 1), drawn per realization.
dphi_bound : float
    Half-width of the uniform shift of the friction angle correlation
    line, deg, drawn per realization.
target_noise : bool
    Add independent normal noise to each foot's capacity target with the
    robust standard deviation of the raw-minus-smoothed residuals.
ci_target : float
    Stop when the 95 percent confidence half-width of the mean long-term
    capacity is below this fraction of the mean.
chunk : int
    Realizations between convergence checks.
max_realizations : int
    Upper limit on realizations.
seed : int or None
    Seed of the random number generator.


## Pipeline

One function per stage of the method, and one call that runs them all.


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.

prepare_target(log, soil, options=None)

Build the capacity target from a driving log.

Parameters
----------
log : DriveLog
    The driving record, with its pile and hammer.
soil : SoilProfile
    Mudline, water table, unit weight and fines content.
options : ModelOptions, optional
    Formula coefficients and smoothing settings.

Returns
-------
Target

Raises
------
ValueError
    If the log has no valid feet.

sweep_top_phi(target, options=None)

Sweep a constant top-segment friction angle and find the admissible band.

Parameters
----------
target : Target
options : ModelOptions, optional
    Supplies the sweep range, step and tolerances.

Returns
-------
TopPhiBand
    The band is the contiguous set of swept values around the best fit
    whose log-fit RMS is within
    ``max(top_sweep_tol_frac * rms_min, top_sweep_tol_kips)`` of the
    minimum. Values with equal RMS tie in favor of the lower angle.

run_drive(target, options=None, top_phi=None)

Characterize every foot sequentially from the capacity target, top down.

Parameters
----------
target : Target
    Capacity target, pile and static soil state on the analysis grid.
options : ModelOptions, optional
top_phi : float, optional
    Friction angle assigned to the unlogged top segment, deg. Required
    when the target has a top segment.

Returns
-------
DriveResult

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.

monte_carlo(log, soil, options=None, mc_options=None, *, target=None, top_band=None)

Realizations of the long-term capacity under the five uncertainty sources.

Parameters
----------
log : DriveLog
soil : SoilProfile
options : ModelOptions, optional
mc_options : MonteCarloOptions, optional
target : Target, optional
    Precomputed capacity target; built from the log when omitted.
top_band : TopPhiBand, optional
    Precomputed admissible top-segment band; swept when omitted.

Returns
-------
MonteCarloResult

Notes
-----
Each realization draws a capacity-formula bias (lognormal), a multiplier
on the cyclic resistance ratio (lognormal), a shift of the friction angle
correlation line (uniform), independent normal noise on each foot's
capacity target, and a top-segment friction angle uniform over the
admissible band. Realizations are added in chunks until the 95 percent
confidence half-width of the mean long-term capacity is below
``mc_options.ci_target`` of the mean or ``mc_options.max_realizations``
is reached.


## Results

Dataclasses of plain NumPy arrays.


Analysis(drive: 'DriveResult', top_band: 'TopPhiBand', mc: 'MonteCarloResult | None' = None) -> None

Everything `analyze` produces.

Attributes
----------
drive : DriveResult
    Deterministic run at the lowest admissible top-segment friction angle.
top_band : TopPhiBand
    Admissible top-segment friction angles.
mc : MonteCarloResult or None
    Monte Carlo realizations, when requested.

Target(pile: 'Pile', elevation: 'np.ndarray', capacity: 'np.ndarray', raw_capacity: 'np.ndarray', bpf: 'np.ndarray', fines: 'np.ndarray', sigma_v0: 'np.ndarray', mudline: 'float', n_top: 'int', pile_id: 'str | None' = None) -> None

Per-foot capacity target and static soil state on the analysis grid.

The grid runs from one foot below the mudline to the final logged foot,
top down. The first ``n_top`` entries are the unlogged top segment.

Attributes
----------
pile : Pile
    The pile that was driven.
elevation : ndarray
    Elevation of each foot, ft, descending.
capacity : ndarray
    Smoothed capacity target, kips; NaN over the top segment.
raw_capacity : ndarray
    Unsmoothed formula capacity, kips; NaN over the top segment.
bpf : ndarray
    Blows per foot; 0 over the top segment.
fines : ndarray
    Fines content, percent.
sigma_v0 : ndarray
    Static vertical effective stress, ksf.
mudline : float
    Elevation of the soil surface, ft.
n_top : int
    Number of unlogged feet above the first logged foot.
pile_id : str, optional
    Identifier of the pile.

TopPhiBand(phi: 'np.ndarray', rms: 'np.ndarray', lo: 'float', hi: 'float') -> None

Admissible friction angles for the unlogged top segment.

Attributes
----------
phi : ndarray
    Swept friction angles, deg.
rms : ndarray
    Root-mean-square log-fit residual at each swept value, kips.
lo, hi : float
    Lowest and highest admissible friction angles, deg.

DriveResult(elevation: 'np.ndarray', depth: 'np.ndarray', sigma_v0: 'np.ndarray', bpf: 'np.ndarray', fines: 'np.ndarray', phi: 'np.ndarray', n160: 'np.ndarray', csr: 'np.ndarray', crr15: 'np.ndarray', cycles_to_liq: 'np.ndarray', felt_arrival: 'np.ndarray', felt: 'np.ndarray', ru: 'np.ndarray', ru_toe: 'np.ndarray', liquefied: 'np.ndarray', liq_when: 'np.ndarray', reason: 'np.ndarray', fs_eod: 'np.ndarray', fs_ltc: 'np.ndarray', target: 'np.ndarray', raw_capacity: 'np.ndarray', predicted: 'np.ndarray', top_phi: 'float', n_top: 'int', eod_capacity: 'float', ltc: 'float', ltc_shaft: 'float', toe_eod: 'float', rms_kips: 'float', pile: 'object', options: 'ModelOptions', pile_id: 'str | None' = None) -> None

Soil characterization and capacities from one drive-model run.

Per-foot arrays run over the analysis grid, top down, including the
unlogged top segment.

Attributes
----------
elevation : ndarray
    Elevation of each foot, ft.
depth : ndarray
    Depth of each foot below the ground surface, ft.
sigma_v0 : ndarray
    Static vertical effective stress, ksf.
bpf : ndarray
    Blows per foot.
fines : ndarray
    Fines content, percent.
phi : ndarray
    Friction angle, deg; NaN where the foot was not characterized.
n160 : ndarray
    Equivalent corrected blow count.
csr : ndarray
    Cyclic stress ratio of a hammer blow.
crr15 : ndarray
    Cyclic resistance ratio at 15 cycles.
cycles_to_liq : ndarray
    Blows to liquefaction.
felt_arrival : ndarray
    Blows felt before the toe reached the foot.
felt : ndarray
    Blows felt by the end of the drive.
ru : ndarray
    Pore-pressure ratio of each foot at the end of the drive.
ru_toe : ndarray
    Pore-pressure ratio applied to the toe stress when the foot was
    characterized.
liquefied : ndarray
    True where the foot liquefied.
liq_when : ndarray
    "before", "during" or "after" the toe's arrival, or "" if never.
reason : ndarray
    Outcome code of each foot's characterization.
fs_eod : ndarray
    Unit shaft resistance at the end of the drive, ksf.
fs_ltc : ndarray
    Unit shaft resistance after pore-pressure dissipation, ksf.
target : ndarray
    Capacity target, kips.
raw_capacity : ndarray
    Per-foot capacity from the dynamic formula before smoothing, kips;
    NaN on the top segment.
predicted : ndarray
    Modeled capacity at the time of driving, kips.
top_phi : float
    Friction angle assigned to the top segment, deg; NaN if there is no
    top segment.
n_top : int
    Number of feet in the top segment.
eod_capacity : float
    Modeled capacity at the final foot, kips.
ltc : float
    Long-term capacity, kips.
ltc_shaft : float
    Long-term shaft resistance, kips.
toe_eod : float
    Toe resistance at the end of the drive, kips.
rms_kips : float
    Root-mean-square of ``predicted - target`` over the logged feet.
pile : Pile
    Pile used for the run.
options : ModelOptions
    Options used for the run.
pile_id : str, optional
    Identifier of the pile.

MonteCarloResult(ltc: 'np.ndarray', shaft: 'np.ndarray', toe_eod: 'np.ndarray', bias: 'np.ndarray', dphi: 'np.ndarray', crr_multiplier: 'np.ndarray', top_phi: 'np.ndarray', elevation: 'np.ndarray', phi_quantiles: 'np.ndarray', converged: 'bool', percentiles: 'tuple' = (5, 25, 50, 75, 95)) -> None

Monte Carlo realizations of the long-term capacity.

Attributes
----------
ltc : ndarray
    Long-term capacity per realization, kips.
shaft : ndarray
    Long-term shaft resistance per realization, kips.
toe_eod : ndarray
    End-of-drive toe resistance per realization, kips.
bias : ndarray
    Capacity-formula bias drawn per realization.
dphi : ndarray
    Shift of the friction angle correlation line drawn per realization, deg.
crr_multiplier : ndarray
    Multiplier on the cyclic resistance ratio drawn per realization.
top_phi : ndarray
    Top-segment friction angle drawn per realization, deg.
elevation : ndarray
    Elevation of each foot of the analysis grid, ft.
phi_quantiles : ndarray
    Friction angle percentiles 5, 25, 50, 75 and 95 per foot, shape
    ``(n_feet, 5)``.
converged : bool
    True if the stopping criterion was met before the realization limit.


## DriveResult Methods

Methods for the DriveResult class


DriveResult.n_logged

Number of logged feet.

DriveResult.logged

Boolean mask of the logged feet.

reason_counts(self) -> 'dict'

Count of each outcome code over the logged feet.

fraction_liquefied(self) -> 'float'

Fraction of logged feet that liquefied during the drive.

plot_profile(self, ax=None)

Plot friction angle, blow count and pore-pressure ratio versus elevation.

plot_fit(self, ax=None)

Plot the capacity target and the modeled capacity versus elevation.


## Equation-level functions

The equations of the method, importable from the submodules for teaching and testing.


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.

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.

smooth_capacity(capacity, window, order)

Savitzky-Golay smoothing of a capacity sequence.

Parameters
----------
capacity : array_like
    Capacity per foot in grid order, kips.
window : int
    Window length in feet; reduced to an odd number no longer than the
    sequence when the sequence is shorter.
order : int
    Polynomial order of the local fit.

Returns
-------
ndarray
    Smoothed capacity; the input unchanged when the window does not
    exceed the polynomial order.

sigma_v0_profile(elevation, surface, gamma_total, water_elevation=0.0, gamma_water=0.0624)

Static vertical effective stress at each elevation.

Parameters
----------
elevation : array_like
    Elevations, ft.
surface : float
    Ground surface elevation, ft.
gamma_total : float
    Total unit weight of the soil, ksf/ft.
water_elevation : float
    Water table elevation, ft. Water standing above the surface adds to
    the total stress.
gamma_water : float
    Unit weight of water, ksf/ft.

Returns
-------
ndarray
    Effective stress, ksf, floored at zero.

extend_to_mudline(elevation, mudline)

Prepend the unlogged feet between the mudline and the first logged foot.

Parameters
----------
elevation : array_like
    Logged elevations, ft, descending.
mudline : float
    Soil surface elevation, ft.

Returns
-------
elevation : ndarray
    Grid elevations, one-foot steps from ``mudline - 1`` down to the
    first logged foot, followed by the logged elevations.
n_top : int
    Number of prepended feet.

residual_scale(target)

Robust standard deviation of the raw-minus-smoothed capacity residuals.

Parameters
----------
target : Target

Returns
-------
float
    ``1.4826 * median(|r - median(r)|)`` over the logged feet, kips.

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).

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).

toe_bearing(sigma_v, phi, options)

Unit toe resistance ``q_p = N_q*(phi, I_r) sigma'_v``, ksf.

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`.

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.

phi_from_n160(n160, cap=45.0)

Friction angle from the corrected SPT blow count.

Parameters
----------
n160 : array_like
    Overburden- and energy-corrected blow count N1,60.
cap : float, default 45.0
    Upper limit on the friction angle, deg.

Returns
-------
ndarray
    ``min(cap, 26 + 5.5 log10(N1,60 + 0.01) + 0.11 N1,60)``, deg.

References
----------
WSDOT Geotechnical Design Manual (2022), Table 5-1 band midpoints.

n160_from_phi(phi, bounds=(0.1, 100.0), cap=45.0)

Corrected blow count whose correlated friction angle equals ``phi``.

Parameters
----------
phi : array_like
    Friction angle, deg.
bounds : tuple of float
    Search bracket on N1,60. Values of ``phi`` at or beyond the
    correlation's range return the bracket edge.
cap : float
    Cap passed to `phi_from_n160`.

Returns
-------
float or ndarray
    N1,60, NaN where ``phi`` is not finite.

coyle_castello_k(phi, width)

Coyle and Castello earth pressure coefficient at the ground surface.

Parameters
----------
phi : array_like
    Friction angle, deg.
width : float
    Pile width, ft.

Returns
-------
ndarray
    K_t interpolated between the tabulated values at 30, 33 and 36 deg
    and extended above 36 deg in proportion to `nordlund_k_delta` at
    the pile's displaced volume.

References
----------
Coyle and Castello (1981).

nordlund_k_delta(phi, displaced_volume)

Nordlund lateral coefficient for a non-tapered displacement pile.

Parameters
----------
phi : array_like
    Friction angle, deg.
displaced_volume : float
    Soil volume displaced per unit length, m^3/m.

Returns
-------
ndarray
    K_delta, interpolated in log10 of the displaced volume and
    log-linearly in friction angle; the 35 to 40 deg slope is continued
    above 40 deg.

References
----------
Nordlund (1963, 1979) as tabulated in FHWA GEC-12 (Hannigan et al., 2016).

fs_coyle_castello(sigma_v0, phi, z, width, delta_ratio=0.8)

Unit shaft resistance of a driven pile in sand.

Parameters
----------
sigma_v0 : array_like
    Vertical effective stress, ksf.
phi : array_like
    Friction angle, deg.
z : array_like
    Depth below the ground surface, ft.
width : float
    Pile width, ft.
delta_ratio : float
    Interface friction angle divided by ``phi``.

Returns
-------
ndarray
    ``sigma'v0 K_t(phi) 10**(-0.017 z / B) tan(delta_ratio phi)``, ksf.

References
----------
Coyle and Castello (1981).

interface_alpha(sr, sigma_v0, psi_nc=0.22)

Interface factor on the residual strength of liquefied soil.

Parameters
----------
sr : float
    Residual strength, ksf.
sigma_v0 : float
    Vertical effective stress, ksf.
psi_nc : float
    Normally consolidated undrained strength ratio.

Returns
-------
float
    ``min(1, sqrt(psi_nc / psi))`` for ``psi = sr / sigma'v0 <= 1`` and
    ``sqrt(psi_nc) psi**-0.25`` above; 1 when the inputs are not positive.

References
----------
Randolph and Murphy (1985), as adopted in API RP 2A.

fs_partially_liquefied(fs_unliq, ru, sr, alpha)

Unit shaft resistance through soil at pore-pressure ratio ``ru``.

Parameters
----------
fs_unliq : float
    Unliquefied unit shaft resistance, ksf.
ru : float
    Pore-pressure ratio.
sr : float
    Residual strength of the liquefied soil, ksf.
alpha : float
    Interface factor on ``sr``.

Returns
-------
float
    ``max((1 - ru) fs_unliq, ru alpha sr)``.

References
----------
Boulanger and Brandenberg (2004).

delta_n_fines(fines)

Fines-content adjustment to the clean-sand equivalent blow count.

Parameters
----------
fines : array_like
    Fines content, percent.

Returns
-------
ndarray
    ``exp(1.63 + 9.7 / (FC + 0.01) - (15.7 / (FC + 0.01))**2)``.

References
----------
Boulanger and Idriss (2014), Eq. 2.23.

n160_clean_sand(n160, fines)

Clean-sand equivalent blow count ``N1,60cs = N1,60 + dN(FC)``.

crr_m75(n160cs)

Cyclic resistance ratio at the magnitude 7.5 reference and 1 atm.

Parameters
----------
n160cs : array_like
    Clean-sand equivalent blow count.

Returns
-------
ndarray
    ``exp(N/14.1 + (N/126)**2 - (N/23.6)**3 + (N/25.4)**4 - 2.8)``.

References
----------
Boulanger and Idriss (2014), Eq. 2.25.

k_sigma(n160cs, sigma_v0, pa=2.116)

Overburden correction factor on the cyclic resistance ratio.

Parameters
----------
n160cs : array_like
    Clean-sand equivalent blow count, clamped to 37.
sigma_v0 : array_like
    Vertical effective stress, ksf.
pa : float
    Atmospheric pressure, ksf.

Returns
-------
ndarray
    ``min(1 - C ln(sigma'v0 / pa), 1.1)`` with
    ``C = min(1 / (18.9 - 2.55 sqrt(N)), 0.3)``.

References
----------
Boulanger and Idriss (2014), Eqs. 2.16 and 2.16b.

crr_15(n160, fines, sigma_v0)

In-situ cyclic resistance ratio at the 15-cycle reference.

Parameters
----------
n160 : array_like
    Corrected blow count N1,60.
fines : array_like
    Fines content, percent.
sigma_v0 : array_like
    Vertical effective stress, ksf.

Returns
-------
ndarray
    ``CRR_M7.5(N1,60cs) * K_sigma``.

csr_driving(phi)

Cyclic stress ratio applied by a hammer blow that fails the soil.

Parameters
----------
phi : array_like
    Friction angle, deg.

Returns
-------
ndarray
    ``tau_max / sigma'v0 = (1 - sin phi) tan phi``.

cycles_to_liquefaction(csr, crr15, b=0.34, n_ref=15.0, nl_max=1000000000.0)

Uniform cycles at ``csr`` needed to trigger liquefaction.

Parameters
----------
csr : array_like
    Applied cyclic stress ratio.
crr15 : array_like
    Cyclic resistance ratio at ``n_ref`` cycles.
b : float
    Exponent of the cyclic strength curve.
n_ref : float
    Reference cycle count of ``crr15``.
nl_max : float
    Cap returned where the result is not finite or ``csr`` is not
    positive.

Returns
-------
ndarray
    ``n_ref * (crr15 / csr)**(1 / b)``, capped at ``nl_max``.

References
----------
Idriss and Boulanger (2008).

ru_linear(n_felt, nl)

Pore-pressure ratio growing linearly with the cycle ratio.

Parameters
----------
n_felt : array_like
    Cycles (blows) felt.
nl : array_like
    Cycles to liquefaction.

Returns
-------
ndarray
    ``min(n_felt / nl, 1)``.

residual_strength(n160, sigma_v0)

Residual strength of liquefied soil.

Parameters
----------
n160 : array_like
    Corrected blow count N1,60.
sigma_v0 : array_like
    Vertical effective stress, ksf.

Returns
-------
ndarray
    ``Pa exp(-8.444 + 0.109 N1,60 + 5.379 (sigma'v0 / Pa)**0.1)``, ksf.

References
----------
Kramer and Wang (2015).

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.

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.

triggering_state(phi, sigma_v0, fines, options)

Blow count, cyclic stress and resistance, and cycles to liquefaction.

Parameters
----------
phi : float or ndarray
    Friction angle, deg.
sigma_v0 : float
    Static vertical effective stress, ksf.
fines : float
    Fines content, percent.
options : ModelOptions

Returns
-------
n160, csr, crr15, nl
    Each a float or ndarray matching ``phi``.

characterize_foot(foot, q_needed, felt_arrival, options)

Characterize the soil at the toe from the required toe resistance.

Parameters
----------
foot : Foot
    The foot the toe has just reached; updated in place.
q_needed : float
    Unit toe resistance the target demands after subtracting the shaft, ksf.
felt_arrival : float
    Blows the foot felt before the toe arrived.
options : ModelOptions


----------------------------------------------------------------------
This is the User Guide documentation for the package.
----------------------------------------------------------------------


## Get started

### Installation

`driven-pile` is a pure-Python package that depends on NumPy and SciPy. It supports Python 3.11 and later.

```bash
pip install driven-pile
```

The plot helpers on the result objects use matplotlib, which is an optional extra:

```bash
pip install "driven-pile[plot]"
```

To work from a clone of the repository with [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/lornearnold/driven-pile.git
cd driven-pile
uv sync --group dev
uv run pytest -q -m "not slow"
```

## Units

Inputs and outputs are in US customary units throughout: feet, kips, kips per square foot (ksf) and degrees. The method was developed on construction records written in those units.


### Quick start

```{python}
#| include: false
import matplotlib as mpl

mpl.rcParams.update({
    "font.family": "serif",
    "font.serif": ["STIX Two Text"],
    "mathtext.fontset": "stix",
})
```

This page runs the full analysis on ten feet of a driving record typed in by hand: define the inputs, call `analyze`, and plot the result. The [walkthrough](../examples/walkthrough.qmd) runs each piece of the analysis by hand on a full benchmark log, and the [method page](method.qmd) gives the equations.

## Inputs

A driving record requires the hammer energy per blow (usually derived from the number of blows per minute) and the penetration resistance (usually blows per foot). A complete log also includes the hammer and pile characteristics.

```{python}
import numpy as np
import matplotlib.pyplot as plt
import driven_pile as dp

bpm = np.array([55, 55, 53, 48, 42, 42, 50, 50, 49, 46, 46, 50, 49, 46, 46, 46, 50, 49, 46, 46])
bpf = np.array([3, 5, 5, 7, 4, 9, 13, 20, 12, 16, 28, 27, 33, 31, 21, 18, 19, 22, 35, 40])

pile = dp.Pile.octagonal(width_in=24, length_ft=60)
hammer = dp.Hammer(ram_weight=20.0)  # kips

log = dp.DriveLog.from_arrays(
    pile,
    hammer,
    bpm=bpm,
    bpf=bpf,
    depth=np.arange(1, len(bpm)+1),  # ft below the first logged foot
    tip_elevation=-50.0,     # ft, toe elevation at the end of the drive
)
```

The soil profile gives the mudline, the water table and the fines content. A single fines value makes a uniform profile; a table of elevation versus percent fines is interpolated.

```{python}
soil = dp.SoilProfile(mudline=-10.0, water_elevation=0.0, fines=15.0)
```

Here the first logged foot is 5 ft below the mudline, and the driving log carries no direct information about the resistance of that soil. The analysis bounds the friction angle of that unlogged top segment from its fit to the logged feet.

## Run the analysis

`analyze` builds the capacity target from the log, bounds the top-segment friction angle, runs the deterministic analysis at the lowest admissible angle, and, with `run_mc=True`, runs the probabilistic analysis (`run_mc=False` by default). A seed makes the probabilistic result reproducible.

```{python}
result = dp.analyze(log, soil)
```


```{python}
#| fig-cap: Capacity at the time of driving. The formula capacity of each logged foot (points) is smoothed into the target (solid line), and the analysis reproduces the target with a modeled capacity (dashed line).
drive = result.drive

fig, ax = plt.subplots(figsize=(4.5, 5))
ax.plot(drive.raw_capacity, drive.elevation, ".", color="gray", label="formula per foot")
ax.plot(drive.target, drive.elevation, color="C0", label="smoothed target")
ax.plot(drive.predicted, drive.elevation, "--", color="C1", label="modeled")
ax.set_xlabel("capacity at time of driving (kips)")
ax.set_ylabel("elevation (ft)")
ax.legend(loc="upper right", framealpha=1)
ax.grid(True, alpha=0.3)
plt.show()
```

## Results

The long-term capacity is the shaft resistance after the pore pressure has dissipated plus the toe resistance at the end of the drive.
```{python}
result.drive.eod_capacity
```

The unit shaft resistance of each foot is lower at the end of the drive than after the excess pore pressure has dissipated. The shaded area between the two curves, multiplied by the pile perimeter, is the setup.

```{python}
#| fig-cap: Unit shaft resistance at the end of the drive and after pore-pressure dissipation. The shaded area is the setup.
fig, ax = plt.subplots(figsize=(4.5, 5))
ax.plot(drive.fs_eod, drive.elevation, color="C0", label="end of drive")
ax.plot(drive.fs_ltc, drive.elevation, color="C1", label="long term")
ax.fill_betweenx(drive.elevation, drive.fs_eod, drive.fs_ltc, color="C1", alpha=0.25, label="setup")
ax.set_xlabel("unit shaft resistance (ksf)")
ax.set_ylabel("elevation (ft)")
ax.legend(loc="upper right", framealpha=1)
ax.grid(True, alpha=0.3)
plt.show()
```

Summing the unit shaft resistance over the perimeter of each foot, from the mudline down, gives the shaft resistance accumulated above any elevation. The toe resistance is added at the toe, and it is the same in both cases because no toe setup is modeled.

```{python}
#| fig-cap: Shaft resistance accumulated from the mudline down, at the end of the drive and in the long term, with the toe resistance at the toe elevation.
perimeter = drive.pile.perimeter  # ft
shaft_eod = np.nancumsum(drive.fs_eod) * perimeter  # kips, one foot per entry
shaft_ltc = np.nancumsum(drive.fs_ltc) * perimeter

fig, ax = plt.subplots(figsize=(4.5, 5))
ax.plot(shaft_eod, drive.elevation, color="C0", label="shaft, end of drive")
ax.plot(shaft_ltc, drive.elevation, color="C1", label="shaft, long term")
ax.plot(drive.toe_eod, drive.elevation[-1], "o", color="k", label="toe")
ax.set_xlabel("resistance accumulated from the mudline (kips)")
ax.set_ylabel("elevation (ft)")
ax.legend(loc="upper right", framealpha=1)
ax.grid(True, alpha=0.3)
plt.show()
```

```{python}
toe = drive.toe_eod
rows = [("end of drive", shaft_eod[-1], toe),
        ("long term", shaft_ltc[-1], toe),
        ("setup", shaft_ltc[-1] - shaft_eod[-1], 0.0)]
print(f"{'':14s}{'shaft':>8s}{'toe':>8s}{'total':>8s}   (kips)")
for name, shaft, toe_part in rows:
    print(f"{name:14s}{shaft:8.0f}{toe_part:8.0f}{shaft + toe_part:8.0f}")
```

The [walkthrough](../examples/walkthrough.qmd) explains each of these results and the intermediate steps that produce them. The [method page](method.qmd) and the [parameters page](parameters.qmd) document the equations and every option.


## Reference

### The method

This page maps the equations of the method to the functions that implement them. The equation-level functions live in the submodules named below and are importable for teaching and testing; the pipeline functions `prepare_target`, `sweep_top_phi`, `run_drive`, `long_term_capacity` and `monte_carlo` chain them together, and `analyze` runs the whole chain.

## Overview

Each logged foot of driving is a load test of the soil at the pile toe. The method inverts the driving record in four steps:

1. Convert the blow count of each foot to a capacity at the time of driving with a recalibrated dynamic formula.
2. Characterize the soil sequentially, top down. At each foot, subtract the shaft resistance of the feet above in their current state and find the friction angle whose toe bearing supplies the rest.
3. Treat every hammer blow as a cycle of shear on the soil near the toe. Count the blows each foot feels, compare them with the number that would liquefy it, and track the pore-pressure ratio $r_u$. Soil with elevated pore pressure carries less shaft resistance during driving and less toe bearing.
4. Sum the shaft resistance of every foot with its pore pressure dissipated and add the toe resistance at the end of the drive. That is the long-term capacity.

Stresses are in ksf, lengths in ft, forces in kips and angles in degrees.

## Capacity at the time of driving

The recalibrated Danish formula converts the set per blow $s = 1/\text{bpf}$ and the stroke $h$ into a capacity:

$$
Q = c_1 \frac{W h}{s + s_0} + c_2, \qquad
s_0 = \sqrt{\frac{W h L}{2 A E}}
$$

with ram weight $W$, pile length $L$, section area $A$ and modulus $E$. The Puget Sound recalibration of Reddy and Stuedlein (2013) gives $c_1 = 0.45$ and $c_2 = 0$.

| Quantity | Function |
|---|---|
| stroke from the blow rate, $h = \tfrac{g}{2}\left(\tfrac{30}{\text{bpm}}\right)^2$ | `bpm_to_stroke`, `stroke_to_bpm` |
| elastic set $s_0$ | `formulas.elastic_set` |
| capacity $Q$ per foot | `formulas.danish_capacity` |
| Savitzky-Golay smoothing of $Q$ over the log | `preprocess.smooth_capacity` |
| extension of the grid up to the mudline | `preprocess.extend_to_mudline` |
| static vertical effective stress $\sigma'_{v0}$ | `preprocess.sigma_v0_profile` |
| all of the above | `prepare_target` |

`prepare_target` returns a `Target`: the smoothed capacity, blow count, fines content and $\sigma'_{v0}$ of every foot on a one-foot grid from the mudline to the toe. The feet above the first logged foot are the unlogged top segment; their capacity is NaN.

## Toe bearing

The unit toe resistance is $q_p = N_q^* \sigma'_v$ with the Vesic (1977) cavity-expansion bearing factor

$$
N_q^* = \frac{1 + 2K_0}{3}\,
\frac{3}{3 - \sin\phi}\,
e^{(\pi/2 - \phi)\tan\phi}\,
\tan^2\!\left(45^\circ + \tfrac{\phi}{2}\right)
I_{rr}^{\,4\sin\phi / 3(1 + \sin\phi)}
$$

and $K_0 = 1 - \sin\phi$. The rigidity index comes from a stress-dependent small-strain shear modulus (Seed and Idriss, 1970) reduced to the strain level of bearing failure:

$$
I_r = \frac{(G/G_{max})\, G_{max}}{\sigma'_m \tan\phi}, \qquad
G_{max} = 21.7\, K_2\, p_a \sqrt{\sigma'_m / p_a}, \qquad
\sigma'_m = \frac{1 + 2K_0}{3}\sigma'_v
$$

$K_2$ is interpolated between its values at the friction-angle bounds and $I_r$ is clamped to `irr_bounds`.

| Quantity | Function |
|---|---|
| $N_q^*$ | `bearing.nq_vesic` |
| $I_r$ | `bearing.rigidity_index` |
| $q_p$ | `bearing.toe_bearing` |
| $\phi$ from a required $q_p$ (root find) | `bearing.phi_from_toe_bearing` |
| the same by interpolation on a grid | `bearing.phi_from_toe_bearing_grid` |

The inversion returns a reason code: `ok` when a friction angle inside `[phi_lo, phi_hi]` reproduces the required bearing, `below_floor` or `above_ceiling` when the requirement lies outside the attainable range and the angle is held at the bound, and `nonfinite` when the target is NaN.

## Friction angle and blow count

The friction angle is tied to the overburden-corrected blow count $N_{1,60}$ through the band midpoints of the WSDOT Geotechnical Design Manual (2022):

$$
\phi = \min\!\left(45^\circ,\; 26 + 5.5 \log_{10}(N_{1,60} + 0.01) + 0.11\, N_{1,60}\right)
$$

The characterization needs the inverse: the $N_{1,60}$ that the characterized $\phi$ implies, which feeds the liquefaction resistance and the residual strength. `ModelOptions.dphi` shifts the line; the Monte Carlo draws it.

| Quantity | Function |
|---|---|
| $\phi(N_{1,60})$ | `spt.phi_from_n160` |
| $N_{1,60}(\phi)$ | `spt.n160_from_phi` |

## Unliquefied shaft resistance

Coyle and Castello (1981) give the unit shaft resistance of a driven pile in sand as

$$
f_s = \sigma'_{v0}\, K_t(\phi)\, 10^{-0.017\, z / B} \tan\delta
$$

with depth $z$, pile width $B$ and interface friction angle $\delta = $ `cc_delta_ratio` $\times\,\phi$. $K_t$ is tabulated at 30, 33 and 36 degrees and extended above 36 degrees in proportion to the Nordlund coefficient at the pile's displaced volume.

| Quantity | Function |
|---|---|
| $K_t(\phi)$ | `shaft.coyle_castello_k` |
| Nordlund $K_\delta$ used for the extension | `shaft.nordlund_k_delta` |
| $f_s$ | `shaft.fs_coyle_castello` |

## Blows to liquefaction

A hammer blow that fails the soil at the toe applies a cyclic stress ratio

$$
\text{CSR} = \frac{\tau_{max}}{\sigma'_{v0}} = (1 - \sin\phi)\tan\phi
$$

The cyclic resistance ratio at the 15-cycle reference is the Boulanger and Idriss (2014) curve for the clean-sand equivalent blow count $N_{1,60cs} = N_{1,60} + \Delta N(FC)$, with the overburden factor $K_\sigma$. The number of uniform cycles that triggers liquefaction follows the cyclic strength curve of Idriss and Boulanger (2008):

$$
N_L = 15 \left(\frac{\text{CRR}_{15}}{\text{CSR}}\right)^{1/b}, \qquad b = 0.34
$$

| Quantity | Function |
|---|---|
| $\Delta N(FC)$ | `liquefaction.delta_n_fines` |
| $N_{1,60cs}$ | `liquefaction.n160_clean_sand` |
| $\text{CRR}_{M7.5}$ at 1 atm | `liquefaction.crr_m75` |
| $K_\sigma$ | `liquefaction.k_sigma` |
| $\text{CRR}_{15}$ in situ | `liquefaction.crr_15` |
| CSR | `liquefaction.csr_driving` |
| $N_L$ | `liquefaction.cycles_to_liquefaction` |
| all four for one foot | `characterization.triggering_state` |

## Pore-pressure ratio

The pore-pressure ratio of a foot grows linearly with the blows it has felt:

$$
r_u = \min\!\left(\frac{N_{felt}}{N_L},\; 1\right)
$$

A foot starts feeling blows when the toe is within `zone_factor` $\times B$ above it, and keeps feeling them until it liquefies or the drive ends. A liquefied foot no longer transmits blows to the feet above it.

| Quantity | Function |
|---|---|
| $r_u$ | `liquefaction.ru_linear` |
| blow accounting over the drive | `run_drive` |

## Residual strength

Liquefied soil retains the residual strength of Kramer and Wang (2015):

$$
S_r = p_a \exp\!\left(-8.444 + 0.109\, N_{1,60} + 5.379 \left(\sigma'_{v0}/p_a\right)^{0.1}\right)
$$

with $N_{1,60}$ capped at 15, the limit of the calibration.

| Quantity | Function |
|---|---|
| $S_r$ | `liquefaction.residual_strength` |

## Shaft resistance through partially liquefied soil

Between the unliquefied and liquefied states the unit shaft resistance is the larger of the reduced frictional resistance and the mobilized residual strength (Boulanger and Brandenberg, 2004):

$$
f_s(r_u) = \max\!\big((1 - r_u)\, f_s,\; r_u\, \alpha\, S_r\big)
$$

where $\alpha$ is the Randolph and Murphy (1985) interface factor on the undrained strength ratio $S_r / \sigma'_{v0}$.

| Quantity | Function |
|---|---|
| $\alpha$ | `shaft.interface_alpha` |
| $f_s(r_u)$ | `shaft.fs_partially_liquefied` |
| unit shaft resistance of a foot now and after dissipation | `characterization.fs_current`, `characterization.fs_unliquefied` |

## Sequential implicit characterization

`run_drive` characterizes the soil one logged foot at a time, top down. The pass is sequential: each foot is solved once, from the state the feet above have reached when the toe arrives. It is implicit: the friction angle at a foot depends on the effective stress the toe bears on, which depends on the foot's own pore-pressure ratio, which depends on the liquefaction resistance that the friction angle implies, so the pair is solved to self-consistency. And the state keeps evolving behind the toe: blows at later feet raise the pore pressure of the feet above, so the shaft resistance those feet contribute to every later step is not fixed when they are characterized. At each logged foot the pass:

1. sums the shaft resistance of the feet above in their current state;
2. divides the remainder of the target capacity by the toe area to get the required unit toe resistance;
3. finds the friction angle that supplies it, together with the self-consistent pore-pressure ratio at the toe: the blows the foot has felt by the time the toe leaves it reduce the stress the toe bears on, which changes the friction angle, which changes $N_L$. The lowest root in `[0, ru_cap_toe]` is taken;
4. adds the foot's blows to every unliquefied foot within the felt zone and updates their $r_u$, marking the ones that reach $N_L$ as liquefied.

The feet of the unlogged top segment are assigned a constant friction angle `top_phi` and take part in the blow accounting like any other foot.

`sweep_top_phi` repeats the characterization for every `top_phi` from `phi_lo` to `phi_hi` in steps of `top_sweep_step` and records the root-mean-square misfit between the modeled and target capacities. The admissible band is the contiguous set of angles around the minimum whose misfit is within `max(top_sweep_tol_frac * rms_min, top_sweep_tol_kips)` of it. The deterministic analysis uses the lowest admissible angle.

## Long-term capacity

$$
Q_{LT} = P \sum_{\text{feet}} f_s^{\,unliq} \,\Delta z \;+\; A\, q_p^{\,EOD}
$$

The shaft term uses the unliquefied resistance of every foot, that is, the resistance after all excess pore pressure has dissipated. The toe term is the end-of-drive bearing of the final foot, on the stress reduced by its toe pore-pressure ratio, less the residual between the modeled and target capacities at that foot so that the end-of-drive total matches the log. No toe setup is modeled.

| Quantity | Function |
|---|---|
| shaft | `capacity.shaft_long_term` |
| toe | `capacity.toe_end_of_drive` |
| both, from a `DriveResult` | `long_term_capacity` |

## Monte Carlo

`monte_carlo` propagates five uncertainty sources through the characterization. Each realization draws:

| Source | Distribution | Option |
|---|---|---|
| bias of the capacity formula | lognormal, mean 1 | `bias_cov` |
| scatter of each foot's capacity about the smoothed target | normal, robust standard deviation of the raw-minus-smoothed residuals | `target_noise` |
| shift of the friction angle line | uniform on $\pm$ `dphi_bound` | `dphi_bound` |
| multiplier on the cyclic resistance ratio | lognormal, median 1 | `crr_sigma_ln` |
| top-segment friction angle | uniform over the admissible band | from `sweep_top_phi` |

Realizations are added in chunks until the 95 percent confidence half-width of the mean long-term capacity falls below `ci_target` of the mean, or `max_realizations` is reached. The result holds the per-realization capacities and draws and the per-foot friction angle percentiles.

## References

- Boulanger, R. W. and Brandenberg, S. J. (2004). Neutral plane solution for liquefaction-induced down-drag on vertical piles. GeoTrans 2004.
- Boulanger, R. W. and Idriss, I. M. (2014). CPT and SPT based liquefaction triggering procedures. Report UCD/CGM-14/01.
- Coyle, H. M. and Castello, R. R. (1981). New design correlations for piles in sand. Journal of the Geotechnical Engineering Division, 107(7).
- Hannigan, P. J. et al. (2016). Design and construction of driven pile foundations. FHWA GEC-12.
- Idriss, I. M. and Boulanger, R. W. (2008). Soil liquefaction during earthquakes. EERI MNO-12.
- Kramer, S. L. and Wang, C.-H. (2015). Empirical model for estimation of the residual strength of liquefied soil. Journal of Geotechnical and Geoenvironmental Engineering, 141(9).
- Randolph, M. F. and Murphy, B. S. (1985). Shaft capacity of driven piles in clay. Offshore Technology Conference.
- Reddy, S. C. and Stuedlein, A. W. (2013). Accuracy and reliability-based region-specific recalibration of dynamic pile formulas. Georisk, 7(3).
- Seed, H. B. and Idriss, I. M. (1970). Soil moduli and damping factors for dynamic response analyses. Report EERC 70-10.
- Sorensen, T. and Hansen, B. (1957). Pile driving formulae: an investigation based on dimensional considerations and a statistical analysis. 4th ICSMFE.
- Vesic, A. S. (1977). Design of pile foundations. NCHRP Synthesis 42.
- WSDOT (2022). Geotechnical Design Manual M 46-03.


### Parameters

Every parameter of the method is a field of `ModelOptions` or `MonteCarloOptions`. Pass a modified copy to any pipeline function:

```python
from dataclasses import replace
opts = replace(dp.ModelOptions(), smoothing_window=9)
out = dp.analyze(log, soil, options=opts)
```

Both option classes are frozen dataclasses, so a modified copy is the only way to change a value.

## `ModelOptions`

| Field | Default | Role | Source |
|---|---|---|---|
| `c1` | 0.45 | multiplicative recalibration coefficient of the Danish formula | Reddy and Stuedlein (2013), Puget Sound |
| `c2` | 0.0 kips | additive recalibration term | Reddy and Stuedlein (2013) |
| `phi_lo` | 25 deg | lower bound on the friction angle; floor of the inversion and start of the top-segment sweep | range of the WSDOT (2022) correlation |
| `phi_hi` | 45 deg | upper bound; ceiling of the inversion, cap of the friction angle correlation and end of the sweep | WSDOT (2022) |
| `g_ratio` | 0.05 | operative over small-strain shear modulus in the rigidity index | method default |
| `k2_lo`, `k2_hi` | 30, 75 | modulus coefficient $K_{2,max}$ at `phi_lo` and `phi_hi`, interpolated linearly | Seed and Idriss (1970) |
| `irr_bounds` | (10, 500) | clamp on the rigidity index | method default |
| `cc_delta_ratio` | 0.8 | interface friction angle over soil friction angle in the shaft resistance | Coyle and Castello (1981); see note below |
| `sr_psi_nc` | 0.22 | normally consolidated undrained strength ratio in the interface factor on the residual strength | Randolph and Murphy (1985) |
| `zone_factor` | 1.5 | a foot feels blows once the toe is within `zone_factor` times the pile width above it | method default |
| `b_exponent` | 0.34 | exponent of the cyclic strength curve | Idriss and Boulanger (2008) |
| `ru_cap_toe` | 0.9 | largest pore-pressure ratio applied to the stress the toe bears on | method default |
| `dphi` | 0 deg | shift of the friction angle line; the Monte Carlo draws it | perturbation hook |
| `crr_multiplier` | 1.0 | multiplier on the cyclic resistance ratio; the Monte Carlo draws it | perturbation hook |
| `smoothing_window` | 13 ft | Savitzky-Golay window on the per-foot capacity | method default |
| `smoothing_order` | 2 | Savitzky-Golay polynomial order | method default |
| `tip_anchor` | True | keep the unsmoothed capacity at the final foot so the end-of-drive total matches the log | method default |
| `top_sweep_step` | 1 deg | step of the top-segment sweep | method default |
| `top_sweep_tol_frac` | 0.05 | a swept angle is admissible when its misfit is within this fraction of the minimum ... | method default |
| `top_sweep_tol_kips` | 1 kip | ... or within this many kips of it, whichever is larger | method default |
| `max_iter` | 60 | iteration limit of the per-foot solves | numerics |
| `ru_tol` | 1e-4 | tolerance of the toe pore-pressure fixed point | numerics |

::: {.callout-note}
## Interface friction angle

The default interface friction angle is 0.8 times the soil friction angle, the ratio Coyle and Castello (1981) used with their earth pressure coefficients. Set `cc_delta_ratio=1.0` to take the interface friction angle equal to the soil friction angle.
:::

## `MonteCarloOptions`

| Field | Default | Role | Source |
|---|---|---|---|
| `bias_cov` | 0.35 | coefficient of variation of the lognormal bias on the formula capacity, mean 1 | Reddy and Stuedlein (2013) |
| `crr_sigma_ln` | 0.20 | log standard deviation of the lognormal multiplier on the cyclic resistance ratio, median 1 | method default |
| `dphi_bound` | 2.5 deg | half-width of the uniform shift of the friction angle line | method default |
| `target_noise` | True | add normal noise to each foot's target with the robust standard deviation of the raw-minus-smoothed residuals | method default |
| `ci_target` | 0.02 | stop when the 95 percent confidence half-width of the mean capacity is below this fraction of the mean | method default |
| `chunk` | 100 | realizations between convergence checks | numerics |
| `max_realizations` | 1200 | upper limit on realizations | numerics |
| `seed` | None | seed of the random number generator; set it for a reproducible run | numerics |

## Site and pile inputs

| Input | Default | Role |
|---|---|---|
| `SoilProfile.mudline` | required | elevation of the soil surface, ft; sets the unlogged top segment |
| `SoilProfile.fines` | required | percent passing the No. 200 sieve, one value or a table against `elevation` |
| `SoilProfile.water_elevation` | 0 ft | water table for the effective stress profile |
| `SoilProfile.gamma_total` | 0.122 ksf/ft | total unit weight of the soil |
| `Pile.modulus` | 864,000 ksf | elastic modulus of the pile material (the default is prestressed concrete) |
| `Hammer.ram_weight` | required | ram weight in kips, $W$ in the Danish formula |

Physical constants, in `driven_pile.constants`: unit weight of water 0.0624 ksf/ft, atmospheric pressure 2.116 ksf, gravitational acceleration 32.2 ft/s², and the one-foot analysis increment.