clivus 0.1.0

Command-line tool for slope stability analysis.

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.

# 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

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.

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.

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

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:

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.

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.