Metadata-Version: 2.2
Name: xslope
Version: 0.4.1
Summary: Slope stability analysis (limit equilibrium and FEM) in Python.
Author: Norman L. Jones
License: Apache-2.0
Project-URL: Homepage, https://github.com/njones61/xslope
Project-URL: Documentation, https://xslope.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/njones61/xslope
Project-URL: Issues, https://github.com/njones61/xslope/issues
Keywords: slope,stability,geotechnical,FEM,limit equilibrium
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: NOTICE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: scipy
Requires-Dist: shapely
Requires-Dist: openpyxl
Requires-Dist: lxml
Requires-Dist: tabulate
Requires-Dist: python-docx
Provides-Extra: fem
Requires-Dist: gmsh; extra == "fem"
Provides-Extra: cad
Requires-Dist: ezdxf; extra == "cad"
Provides-Extra: gui
Requires-Dist: PySide6; extra == "gui"
Requires-Dist: pyobjc-framework-Cocoa; sys_platform == "darwin" and extra == "gui"
Requires-Dist: ezdxf; extra == "gui"
Provides-Extra: ai
Requires-Dist: litellm; extra == "ai"
Requires-Dist: keyring; extra == "ai"

# xslope

**xslope** is an open-source Python package for geotechnical slope stability and
seepage analysis. It answers the question a slope engineer has to answer on every
embankment, cut, dam, and levee — *is this slope stable, and by how much?* — with
three analysis engines that share one input file:

- **Limit equilibrium (LEM)** — the method of slices with seven methods: Ordinary
  Method of Slices, Simplified Janbu, Bishop's Simplified, Corps of Engineers,
  Lowe & Karafiath, Spencer, and Morgenstern–Price. Circular and non-circular
  surfaces, automated critical-surface search, rapid drawdown, reinforcement,
  seismic loading, and Monte Carlo reliability analysis.
- **Finite element seepage** — saturated/unsaturated groundwater flow, steady-state
  or transient, on a mesh generated from the same slope geometry. It produces the
  pore pressure field used by the stability analyses, rather than assuming pore
  pressures from a piezometric line, and also serves as a standalone 2D groundwater
  flow solver.
- **Finite element slope stability** — elastic–perfectly plastic Mohr–Coulomb
  analysis with the Shear Strength Reduction Method, which lets the failure
  mechanism emerge instead of requiring an assumed failure surface.

Problems are defined in an Excel template, which keeps the workflow accessible to
practitioners while the analysis and plotting run in Python. A companion desktop
application, **XSLOPE Studio**, provides a point-and-click interface to the same
engine.

## Installation

xslope requires Python 3.9 or later and is published on
[PyPI](https://pypi.org/project/xslope/):

```bash
pip install xslope
```

That installs everything needed for limit equilibrium analysis. Optional extras add
the remaining capabilities:

```bash
pip install "xslope[fem]"       # seepage and finite element analysis (adds gmsh)
pip install "xslope[gui]"       # XSLOPE Studio, the desktop application
pip install "xslope[ai]"        # Studio's AI assistant
pip install "xslope[cad]"       # DXF import/export
pip install "xslope[gui,fem,ai,cad]"  # everything
```

Studio is launched with the `xslope-studio` command. On Debian/Ubuntu Linux
(including Google Colab), gmsh needs system OpenGL libraries — run
`apt-get install -y libgl1 libglu1-mesa` before installing the `fem` extra.

## Example

A problem is an Excel file. This example uses one of the sample problems from this
repository, so download it into the current directory first:

```bash
curl -O https://raw.githubusercontent.com/njones61/xslope/main/docs/inputs/slope/xslope_simple1.xlsx
```

Then load it, build slices on its failure surface, solve for the factor of safety,
and plot the result:

```python
from xslope.fileio import load_slope_data
from xslope.slice import generate_slices
from xslope.solve import solve_selected
from xslope.plot import plot_solution

slope_data = load_slope_data("xslope_simple1.xlsx")

circle = slope_data['circles'][0]
success, result = generate_slices(slope_data, circle=circle, num_slices=20)
slice_df, failure_surface = result

results = solve_selected('bishop', slice_df)
print(f"FS = {results['FS']:.3f}")          # FS = 1.279

plot_solution(slope_data, slice_df, failure_surface, results)
```

To search for the critical surface instead of analyzing a single one:

```python
from xslope.search import circular_search
from xslope.plot import plot_circular_search_results

fs_cache, converged, search_path, circle_cache = circular_search(slope_data, 'bishop')
print(f"minimum FS = {fs_cache[0]['FS']:.3f}")   # minimum FS = 1.215

plot_circular_search_results(slope_data, fs_cache, search_path)
```

More sample problems are in [`docs/inputs/slope/`](docs/inputs/slope) in this
repository. To start a problem from scratch instead, a blank copy of the input
template ships inside the installed package, at the path returned by
`xslope.fileio.default_template_path()`.

## Documentation

Full documentation — theory, input template reference, worked examples, XSLOPE
Studio, and verification against published benchmarks — is at
**[xslope.org](https://xslope.org)**.

## Support and contributing

Questions, bug reports, and feature requests go to
[GitHub Issues](https://github.com/njones61/xslope/issues). Contributors should start
with the [contributing guide](https://xslope.org/en/latest/coding/contributing/),
which covers the development install, coding conventions, and the test suite.

## Citation

If you use xslope in published work, please cite the archived release:

> Jones, N. L. (2026). *xslope* (Version 0.2.1) [Computer software].
> https://doi.org/10.5281/zenodo.21830232

Machine-readable metadata is in [CITATION.cff](CITATION.cff).

## License

This project is licensed under the Apache License, Version 2.0 - see the [LICENSE.txt](LICENSE.txt) file for details.

## Copyright

Copyright 2025 Norman L. Jones

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
