Metadata-Version: 2.5
Name: lithovox-stability
Version: 0.1.0
Summary: Read, write and calculate Deltares D-Stability (.stix) files
Project-URL: Homepage, https://www.lithovox.com
Author: LithoVox
License: MIT
License-File: LICENSE
Keywords: deltares,dstability,slope-stability,stix
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.15,>=3.10
Requires-Dist: pydantic-extra-types>=2.5
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: pydantic>=2.5
Requires-Dist: shapely>=2.0
Requires-Dist: zipp>=3.15
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == 'plot'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: python-multipart>=0.0.9; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.23; extra == 'server'
Provides-Extra: test
Requires-Dist: fastapi>=0.100; extra == 'test'
Requires-Dist: httpx>=0.24; extra == 'test'
Requires-Dist: pytest>=7.3; extra == 'test'
Requires-Dist: python-multipart>=0.0.9; extra == 'test'
Requires-Dist: uvicorn[standard]>=0.23; extra == 'test'
Description-Content-Type: text/markdown

# LithoVox-Stability

A stripped-down version of [GEOLib](https://github.com/Deltares/GEOLib) that
only supports the Deltares **D-Stability** `.stix` format, plus:

* platform independent execution of the D-Stability console
  (Windows `.exe` and Linux/macOS via `dotnet <console>.dll`),
* migration of old `.stix` files with `D-Stability Migration Console`,
* an optional **FastAPI** server to run calculations through HTTP.

## Installation

```bash
pip install lithovox-stability            # read, edit and write .stix files
pip install "lithovox-stability[plot]"    # + model.plot() (matplotlib)
pip install "lithovox-stability[server]"  # + the API server
```

## Connecting to D-Stability

The D-Stability executables are **not** part of this package. Install
D-Stability yourself and tell lithovox-stability where it is. Settings are
read from environment variables or a `lithovox_stability.env` file in the
working directory (see `lithovox_stability.env.example`). There is no
auto-detection.

| Setting | Default | Description |
| --- | --- | --- |
| `DSTABILITY_FOLDER` | `None` | Folder with the D-Stability binaries (`D-Stability Console.exe`/`.dll`). |
| `DSTABILITY_CONSOLE_PATH` | `None` | Explicit console `.exe`/`.dll` (overrides the folder). |
| `DSTABILITY_MIGRATION_CONSOLE_PATH` | `None` | Explicit migration console `.exe`/`.dll`. |
| `DOTNET_PATH` | `dotnet` | `dotnet` executable used on Linux/macOS. |
| `TIMEOUT` | `600` | Maximum calculation time in seconds. |
| `CALCULATION_FOLDER` | `calculations` | API server: folder for temporary calculation folders. |
| `API_USERNAME` / `API_PASSWORD` | `test` / `test` | API server: HTTP basic auth credentials. |

On Windows the `.exe` is started directly. On Linux/macOS the `.dll` is
started with the .NET 8 runtime (`dotnet "D-Stability Console.dll"`), so
install that runtime as well.

Reading and writing `.stix` files does not need D-Stability at all.

## Usage

```python
from lithovox_stability import DStabilityModel

# Read an existing .stix file
model = DStabilityModel.from_stix("input.stix")

# Inspect or edit the model
print(model.output)                       # results, if present
model.add_scenario("New scenario")        # only through the model API!
model.serialize("edited.stix")

# Run D-Stability (writes the results back into the .stix file)
model.execute()
```

Files created with an old D-Stability version (with e.g.
`ShearStrengthModelTypeAbovePhreaticLevel: CPhi`) must be migrated first:

```python
migrated = DStabilityModel.convert_legacy_file("old.stix", "new.stix")
model = DStabilityModel.from_stix(migrated)
```

## API server

```bash
pip install "lithovox-stability[server]"
uvicorn lithovox_stability.service.main:app --host 0.0.0.0 --port 8000
```

| Endpoint | Description |
| --- | --- |
| `GET /health` | Platform and console availability. |
| `POST /calculate` | Upload a `.stix` file, returns the calculated `.stix` file. |
| `POST /calculate/model` | Post/return the JSON representation of the model. |
| `POST /convert` | Upload an old `.stix` file, returns the migrated file. |

```bash
curl -u test:test -F "file=@input.stix" -o result.stix http://localhost:8000/calculate
```

## Tests

```bash
pip install -e ".[test]"
pytest
```

The tests use `tests/data/test.stix`. Tests marked `console` run D-Stability
and are skipped unless `DSTABILITY_FOLDER` or `DSTABILITY_CONSOLE_PATH` points
to a working installation, for example:

```bash
DSTABILITY_FOLDER=/path/to/dstability pytest
```
