Metadata-Version: 2.4
Name: clivus
Version: 0.4.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 a command-line tool for slope stability analysis. It searches for critical slip surfaces in a 2-D slope model using the method of slices, parameterising candidate surfaces as Bézier curves and evaluating their factor of safety (FOS).

## Features

- Bézier-curve-based slip surface parameterisation
- Method-of-slices stability analysis (Razdolsky)
- Multiple pore pressure models: horizontal or sloping water table, or a seepage raster (Esri ASCII grid)
- Optional aquitard: pore pressure is zeroed below a named layer
- Flexible soil layering with per-layer geometry types (`thickness`, `depth`, `bottom` polyline)
- Optional surcharge loads: point loads and linearly-varying distributed loads
- Built-in clustering to identify distinct critical surfaces
- Slope geometry plots with optional raster overlay (`show`)
- Single-surface FOS or η solver for manual verification (`test`)

## Installation

```bash
pip install clivus
```

Requires Python ≥ 3.11.

## Quick Start

### 1. Create a project directory

```bash
clivus new my_project
cd my_project
```

This creates a directory with a default `clivus.toml` configuration file and a `slope.yaml` slope definition. Use them as starting points for your own analysis.

### 2. Define your slope

Edit `slope.yaml` to describe the cross-section geometry, soil layers, pore pressure conditions, and optional loads. Print a fresh template at any time with:

```bash
clivus init
```

A minimal slope definition looks like this:

```yaml
surface:
  - [0.0, 10.0]
  - [10.0, 5.0]
  - [20.0, 5.0]

layers:
  - id: clay
    name: Clay
    above: surface
    material:
      gamma: 20.0   # unit weight [kN/m³]
      c: 25.0       # cohesion [kN/m²]
      phi: 0.0      # friction angle [°]
    geometry:
      type: depth
      anchor_x: begin   # reference x for depth measurement; number, 'begin', or 'end'
      value: 4.0

base:
  name: Bedrock
  material: {gamma: 22.0, c: 100.0, phi: 35.0}

pore_pressure:
  type: water_table
  value: 8.0        # elevation [m]; or use 'points: [[x0,z0],[x1,z1],...]' for a sloping table
```

#### Pore pressure types

| `type`        | Required fields                                      | Notes                                                      |
|---------------|------------------------------------------------------|------------------------------------------------------------|
| `water_table` | `value` (elevation) **or** `points` (x/z polyline)  | Optional `aquitard: <layer_id>` zeroes u below that layer  |
| `raster`      | `file` (Esri ASCII grid path)                        | Pore pressure [kN/m²] sampled directly from grid           |

#### Geometry types for layers

| `type`      | Required fields                   | Notes                                               |
|-------------|-----------------------------------|-----------------------------------------------------|
| `thickness` | `anchor_x`, `value`, opt. `dip`   | Uniform vertical thickness from the reference above |
| `depth`     | `anchor_x`, `value`, opt. `dip`   | Bottom at absolute elevation `value`                |
| `bottom`    | `points` (x/z polyline)           | Explicit bottom boundary                            |

#### Surcharge loads (optional)

Add a `loads` list to apply vertical downward loads to the surface. Two forms are supported:

```yaml
loads:
  - {x: 7.0, q: 50.0}                            # point load [kN/m] at x = 7
  - {x0: 0.0, x1: 5.0, q0: 20.0, q1: 40.0}      # distributed load [kN/m²], linearly varying over span
```

| Field        | Meaning                                         |
|--------------|-------------------------------------------------|
| `x`, `q`     | Point load: position [m] and magnitude [kN/m]   |
| `x0`, `x1`   | Distributed load: start and end x [m]           |
| `q0`, `q1`   | Intensity [kN/m²] at `x0` and `x1` respectively |

For a uniform distributed load set `q0 = q1`.

### 3. Configure the search

Edit `clivus.toml` (or point to a custom config with `-c`) to control search parameters:

```toml
name = "my analysis"
slope = "slope.yaml"

[search]
FOS = 1.3             # surfaces below this threshold are considered critical
control_points = 6    # Bézier control points per candidate surface

[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 search

```bash
clivus search
```

Use `--overwrite` to replace existing output files:

```bash
clivus search --overwrite
```

Output files written to the project directory:

| File            | Contents                                              |
|-----------------|-------------------------------------------------------|
| `results.csv`   | All critical surfaces found                           |
| `medoids.csv`   | One representative surface per cluster                |
| `density.asc`   | Weighted slip-surface density raster (Esri ASCII)     |

### 5. Visualise results

```bash
clivus show results.csv
```

Save to a file instead of opening an interactive window:

```bash
clivus show -o slope.png results.csv
```

Overlay a raster (e.g. the density grid) with a custom colorbar label:

```bash
clivus show --raster density.asc --label "Slip density" results.csv
```

### 6. Test a specific surface

Compute the FOS for a manually defined slip surface:

```bash
clivus test --slip "arc:10.0,15.0,8.0"
```

Supported surface specs:

| Format                            | Description                                     |
|-----------------------------------|-------------------------------------------------|
| `arc:cx,cy`                       | Circular arc; radius = cy (centre y-coordinate) |
| `arc:cx,cy,r`                     | Circular arc with explicit radius               |
| `polyline:x1,y1,x2,y2,...`        | Piecewise-linear surface                        |
| `bez:x0,z0,x1,z1,...`             | Bézier control points (direct)                  |

Compute η for a given factor instead of solving for FOS:

```bash
clivus test --slip "arc:10.0,15.0,8.0" --factor 1.3
```

### 7. Clean up

```bash
clivus clean
```

Removes generated output files from the project directory.

## CLI Reference

```
clivus [-c CONFIG] COMMAND

Commands:
  new <dir>   Create a new project directory with default files
  init        Print a slope definition template to stdout
  search      Search for critical slip surfaces
  show        Plot slope geometry and optional slip surfaces or raster
  test        Compute FOS or η for a single user-defined slip surface
  clean       Delete generated output files

Options:
  -c, --config PATH   Path to config file (default: clivus.toml)

search options:
  --overwrite         Overwrite existing output files

show options:
  RESULTS             CSV file of slip surfaces (optional)
  --raster FILE       Esri ASCII grid to overlay as a colourmap
  --label TEXT        Colorbar label for --raster
  -o, --out FILE      Save figure to file instead of displaying

test options:
  --slip SPEC         Slip surface spec: arc:cx,cy[,r] | polyline:x1,y1,... | bez:x1,z1,...
  -f, --factor F      Compute η for this FOS value instead of solving for FOS
```

## License

MIT — see [LICENSE](LICENSE).
