Metadata-Version: 2.4
Name: clivus
Version: 0.1.0
Summary: Command-line tool for slope stability analysis.
Project-URL: Homepage, https://github.com/thkrz/clivus
License: Copyright (c) 2026 Thomas M. Kreuzer
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of
        this software and associated documentation files (the “Software”), to deal in
        the Software without restriction, including without limitation the rights to
        use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
        of the Software, and to permit persons to whom the Software is furnished to do
        so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: matplotlib
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pyyaml
Requires-Dist: scipy
Requires-Dist: shapely
Description-Content-Type: text/markdown

# CLIVUS

**CLIVUS** is an open-source command-line tool for slope stability analysis. It
automatically searches for critical slip surfaces in a 2D slope cross-section
using Bézier-curve-shaped trial surfaces, evaluates each with a limit-equilibrium
method, and clusters the results to identify the most hazardous failure modes.

---

## Features

- **Automated slip-surface search** — generates candidate surfaces across all
  meaningful entry/exit combinations, then optimises each one with constrained
  minimisation (COBYQA) to find the lowest factor of safety
- **Limit-equilibrium analysis** — implements the Razdolsky method (`raz2`), a
  Fortran-accelerated procedure that accounts for pore pressure, cohesion,
  friction angle, and tension cracks
- **Bézier slip surfaces** — each candidate surface is a smooth Bézier curve
  defined by a configurable number of control points, avoiding the circularity
  assumption of classical methods
- **Multi-layer stratigraphy** — layers are defined by material properties and
  one of three geometry types: explicit boundary points, constant thickness, or
  constant depth (with optional dip)
- **Pore-pressure models** — supports a piecewise-linear water table or a raster
  file (AAIGrid format) for spatially variable pore pressures
- **Surcharge loads** — point and distributed surface loads can be applied to
  any location on the slope
- **Hierarchical clustering** — all sub-critical surfaces (FOS < threshold) are
  grouped using average-linkage clustering; the cluster threshold is chosen
  automatically at the largest gap in the linkage heights
- **Density map** — a weighted spatial density grid of all failure surfaces is
  written as an AAIGrid raster, suitable for direct import into a GIS
- **Parallel processing** — the search loop uses Python's `multiprocessing.Pool`
  to exploit all available CPU cores
- **Plot output** — slope geometry, pore-pressure field, critical surfaces, and
  the density map are exported as figures (matplotlib)

---

## Installation

clivus requires **Python ≥ 3.11**, a Fortran compiler, and the Meson build
system. The Fortran extension (`_lem`) is compiled and wrapped with `f2py`
during installation.

```bash
# Install build tools
pip install meson-python ninja numpy

# Clone and install
git clone https://github.com/thkrz/clivus.git
cd clivus
pip install .
```

Runtime dependencies installed automatically: `numpy`, `scipy`, `matplotlib`,
`shapely`, `pyyaml`.

---

## Quick Start

### 1 — Create a new project

```bash
clivus new my_slope
cd my_slope
```

This creates a project directory with a template `slope.yaml` and a default
`clivus.toml` configuration file.

### 2 — Define the slope

Edit `slope.yaml` to describe the slope geometry, stratigraphy, and pore
pressure. The surface is a piecewise-linear polyline given as `[x, z]` pairs.
Each stratigraphic layer specifies material properties and a geometry rule that
places its lower boundary.

```yaml
surface:
  - [0.0, 16.7]
  - [16.08, 13.4]
  - [40.0,  3.2]

layers:
  - id: fill
    name: Fill
    above: surface
    material:
      gamma: 17.28   # unit weight [kN/m³]
      c: 0.0         # cohesion [kPa]
      phi: 30.0      # friction angle [°]
    geometry:
      type: thickness
      value: 3.3
      anchor_x: begin

base:
  name: Bedrock
  material:
    gamma: 28.45
    c: 100.0
    phi: 0.0

pore_pressure:
  type: water_table
  points:
    - [0.0,  14.5]
    - [40.0,  3.2]
```

### 3 — (Optional) Tune the search

Edit `clivus.toml` to adjust the search parameters. All keys are optional; the
defaults are shown as comments.

```toml
name = "My slope"
slope = "slope.yaml"

[search]
# FOS = 1.3
# control_points = 6

[search.length]
# min = 6.0
# step = 1.0

[search.depth]
# max_ratio = 0.33
# min_ratio = 0.1
# min_drop = 2.0

[search.slices]
# target_width = 0.5
# n_max = 100
# n_min = 10
```

### 4 — Run the analysis

```bash
clivus search
```

Results are written to the project directory. Use `--overwrite` to replace
existing output.

---

## Slope Definition Reference

### Layer geometry types

| Type | Required keys | Description |
|------|--------------|-------------|
| `bottom` | `points` | Explicit `[x, z]` polyline for the layer base |
| `thickness` | `anchor_x`, `value` | Constant thickness below the layer above; `anchor_x` may be `"begin"`, `"end"`, or a coordinate |
| `depth` | `anchor_x`, `value` | Absolute elevation of the base at `anchor_x`, with optional `dip` (degrees) |

### Pore-pressure types

| Type | Required keys | Description |
|------|--------------|-------------|
| `water_table` | `value` or `points` | Flat (`value`) or piecewise-linear (`points`) water table |
| `raster` | `file` | Path to an AAIGrid (`.asc`) file with pore-pressure values |

### Load specification

Optional `loads` list in the slope file. Each entry is either:

```yaml
loads:
  - {x: 12.0, q: 50.0}           # point load [kN/m]
  - {x0: 5.0, x1: 10.0, q: 20.0} # distributed load [kPa]
```

---

## Output Files

| File | Content |
|------|---------|
| `results.csv` | All critical surfaces: control-point coordinates and FOS |
| `density.asc` | AAIGrid raster of the weighted surface density |
| `slope.png` | Slope cross-section with stratigraphy |
| `pore_pressure.png` | Pore-pressure distribution |
| `critical.png` | Critical slip surfaces coloured by FOS |
| `density.png` | Spatial density map of failure surfaces |

---

## CLI Reference

```
clivus [-c CONFIG] COMMAND

Commands:
  new <dir>   Create a new project directory with template files
  init        Print a slope definition template to stdout
  search      Search for critical slip surfaces
  clean       Delete generated output files
```

`CONFIG` defaults to `clivus.toml` in the current directory.

---

## Method

Candidate slip surfaces are generated as Bézier curves spanning every
entry/exit pair on the slope surface whose horizontal distance exceeds
`search.length.min`. For each pair, several initial shapes (a straight line
and arcs at different sag depths) seed a constrained optimiser that minimises
the factor of safety subject to geometric feasibility constraints.

The factor of safety is evaluated with the **Razdolsky limit-equilibrium
method** — a Fortran routine (`_lem.f90`) compiled via `f2py`. The method
propagates inter-slice forces along the slip surface and detects tension
cracks; if a crack is encountered, the analysis restarts from the crack tip
with a hydrostatic boundary condition.

All surfaces with FOS below the configured threshold are retained, sorted by
FOS, and clustered. The cluster threshold is chosen as the largest gap in the
sorted linkage heights (automatic elbow detection). Representative surfaces
(medoids) are identified per cluster.

---

## Examples

The `examples/chicago/` directory reproduces the **Chicago Congress Street
Cut** benchmark case (layered blue clay with a shallow water table), a
well-known reference problem in slope stability literature.

```bash
cd examples/chicago
clivus search
```

---

## Dependencies

| Package | Role |
|---------|------|
| `numpy` | Array mathematics |
| `scipy` | Optimisation (`COBYQA`), hierarchical clustering |
| `shapely` | Geometry operations for the density grid |
| `matplotlib` | Plot output |
| `pyyaml` | Slope definition parsing |
| `meson-python` | Build system (compile-time only) |

---

## License

See repository for license information.
