---
name: driven-pile
description: >
  Long-term capacity of driven piles from the pile-driving log: a pore-pressure-tracking inversion of blow counts. Use when writing Python code that uses the driven_pile package.
license: GNU General Public License v3 or later (GPLv3+)
compatibility: Requires Python >=3.11.
---

# driven-pile

Long-term capacity of driven piles from the pile-driving log: a pore-pressure-tracking inversion of blow counts.

## Installation

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

## API overview

### Inputs

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

- `DriveLog`: A pile-driving record, one entry per logged foot
- `Pile`: Pile geometry and stiffness
- `Hammer`: Driving hammer
- `SoilProfile`: Ground conditions at a pile location
- `bpm_to_stroke`: Hammer stroke from the blow rate of a free-falling ram
- `stroke_to_bpm`: Blow rate of a free-falling ram from its stroke; inverse of `bpm_to_stroke`

### Options

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

- `ModelOptions`: Parameters of the drive model
- `MonteCarloOptions`: Monte Carlo settings

### Pipeline

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

- `analyze`: Characterize the soil from a driving log and estimate long-term capacity
- `prepare_target`: Build the capacity target from a driving log
- `sweep_top_phi`: Sweep a constant top-segment friction angle and find the admissible band
- `run_drive`: Characterize every foot sequentially from the capacity target, top down
- `long_term_capacity`: Long-term shaft and toe resistance of a `DriveResult`
- `monte_carlo`: Realizations of the long-term capacity under the five uncertainty sources

### Results

Dataclasses of plain NumPy arrays.

- `Analysis`: Everything `analyze` produces
- `Target`: Per-foot capacity target and static soil state on the analysis grid
- `TopPhiBand`: Admissible friction angles for the unlogged top segment
- `DriveResult`: Soil characterization and capacities from one drive-model run
- `MonteCarloResult`: Monte Carlo realizations of the long-term capacity

### DriveResult Methods

Methods for the DriveResult class

- `DriveResult.n_logged`
- `DriveResult.logged`
- `DriveResult.reason_counts`
- `DriveResult.fraction_liquefied`
- `DriveResult.plot_profile`
- `DriveResult.plot_fit`

### Equation-level functions

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

- `formulas.elastic_set`
- `formulas.danish_capacity`
- `preprocess.smooth_capacity`
- `preprocess.sigma_v0_profile`
- `preprocess.extend_to_mudline`
- `preprocess.residual_scale`
- `bearing.nq_vesic`
- `bearing.rigidity_index`
- `bearing.toe_bearing`
- `bearing.phi_from_toe_bearing`
- `bearing.phi_from_toe_bearing_grid`
- `spt.phi_from_n160`
- `spt.n160_from_phi`
- `shaft.coyle_castello_k`
- `shaft.nordlund_k_delta`
- `shaft.fs_coyle_castello`
- `shaft.interface_alpha`
- `shaft.fs_partially_liquefied`
- `liquefaction.delta_n_fines`
- `liquefaction.n160_clean_sand`
- `liquefaction.crr_m75`
- `liquefaction.k_sigma`
- `liquefaction.crr_15`
- `liquefaction.csr_driving`
- `liquefaction.cycles_to_liquefaction`
- `liquefaction.ru_linear`
- `liquefaction.residual_strength`
- `capacity.shaft_long_term`
- `capacity.toe_end_of_drive`
- `characterization.triggering_state`
- `characterization.characterize_foot`

## Resources

- [Full documentation](https://lornearnold.github.io/driven-pile/)
- [llms.txt](llms.txt) — Indexed API reference for LLMs
- [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs
- [Source code](https://github.com/lornearnold/driven-pile)