clivus 0.4.0

Command-line tool for slope stability analysis.

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

pip install clivus

Requires Python ≥ 3.11.

Quick Start

1. Create a project directory

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:

clivus init

A minimal slope definition looks like this:

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:

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:

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

clivus search

Use --overwrite to replace existing output files:

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

clivus show results.csv

Save to a file instead of opening an interactive window:

clivus show -o slope.png results.csv

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

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

6. Test a specific surface

Compute the FOS for a manually defined slip surface:

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:

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

7. Clean up

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.