rockslope 0.1.1

Stereonet-based tools for rock slope kinematic analysis.

RockSlope

RockSlope is a Python library for stereonet-based structural geology and rock slope kinematic analysis. It provides a high-level workflow for handling joint orientation data, defining joint sets, computing orientation statistics, performing kinematic failure analyses, visualizing results on stereonets, and generating text-based reports.

The public API is centered around the RockMass class, which is intended for end users. Lower-level modules implement spherical geometry, statistics, plotting, and kinematic checks and are considered internal.

---

Features

RockSlope supports the following core capabilities:

• Management of joint orientation data (dip direction / dip).
• Conversion between geological orientations and spherical unit vectors.
• Definition of joint sets using circular and rectangular selection windows.
• Spherical statistical analysis:
  • Mean axes
  • Fisher confidence angles
  • Variability angles
  • Fisher and Davis kappa estimates
• Stereonet plotting with Matplotlib:
  • Poles, great circles, intersections
  • Selection windows
  • Mean axes and confidence circles
  • Density plots (Kamb method)
• Rock slope kinematic analysis:
  • Planar sliding (with and without lateral limits)
  • Wedge sliding
  • Flexural toppling
  • Direct toppling (intersection- and base-plane based)
• Generation of reStructuredText reports summarizing statistics and kinematics.

All angles passed to the public API are expected in degrees. Internally, computations are performed in radians using unit vectors on the sphere.

---

Installation

Once published on PyPI:

pip install rockslope

For local development using the src layout:

python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate
pip install -e .[dev]

This installs RockSlope in editable mode together with development dependencies.

---

Quick Start

Basic Usage

import numpy as np
from rockslope import RockMass

# Joint orientations as dip direction / dip (degrees)
joints = np.array([
    [230.0, 23.0],
    [145.0, 45.0],
    [240.0, 30.0],
])

rockmass = RockMass(joints)

# Define a slope orientation
rockmass.add_slope(dip_direction=90.0, dip=45.0)

# Define joint sets using selection windows
rockmass.add_circular_selection(
    dip_direction=320.0,
    dip=25.0,
    apical_angle=60.0,
)

# Compute statistics for the defined sets
rockmass.compute_statistics()

# Compute kinematic failure modes
rockmass.compute_kinematics(joint_friction=30.0, lateral_limit=30.0)

# Plot a stereonet with planar sliding results
rockmass.plot(
    poles=True,
    selection_windows=True,
    confidence_angles="fisher",
    kinematics="planar_sliding",
    show=True,
)

---

Selection Windows

RockSlope supports two types of selection windows for defining joint sets:

• Circular selection Defined by a central orientation and an apical angle.

• Rectangular selection Defined by a central orientation with separate declination and inclination bounds.

Selections are stored internally and used for both statistical analysis and plotting.

---

Kinematic Analysis

Kinematic checks are performed against a defined slope orientation. The following failure modes are supported:

• Planar sliding (with optional lateral limits)
• Planar sliding without lateral limits
• Wedge sliding (primary and secondary zones)
• Flexural toppling
• Direct toppling (intersection-based and base-plane based)

Results are stored on the RockMass instance and can be visualized on stereonets or summarized in reports.

---

Reporting

RockSlope can generate a text-based report in reStructuredText format:

rockmass.get_report(
    projectname="Example Slope",
    author="Author Name",
    date="2026-01-01",
    description="Kinematic analysis of a rock slope",
    save_as="report.rst",
)

The report includes:

• Project metadata
• Number of planes and intersections
• Joint set statistics (if computed)
• Kinematic analysis summary (if computed)

---

Data Import

Joint orientations can be loaded from CSV files:

from rockslope import joints_from_csv

joints = joints_from_csv(
    "joints.csv",
    col_dip_direction=0,
    col_dip=1,
    skip=1,
    delimiter=";",
)

The CSV file must contain dip direction and dip values in degrees.

---

Internal Modules

The following modules are used internally by RockMass:

• sphericmath: spherical geometry and vector operations
• sphericstats: spherical statistics and parameter estimation
• selections: circular and rectangular selection windows
• plot: Matplotlib stereonet projection and plotting utilities
• kinematics: rock slope kinematic checks
• rstbuilder: helpers for report generation

These modules are considered implementation details and are not part of the stable public API.

---

Documentation

RockSlope uses Google-style docstrings and Sphinx with the Napoleon extension. To build the documentation locally:

pip install -e .[dev]
sphinx-build -b html docs docs/_build/html

The API documentation focuses on the high-level RockMass interface.

---

Testing

A pytest-based test suite is included:

pip install -e .[dev]
pytest

---

License

RockSlope is released under the MIT License. See the LICENSE file for details.