Metadata-Version: 2.1
Name: pykarstnsim
Version: 1.0.1
Summary: A Python interface for the KarstNSim C++ library
Keywords: karst,simulation,geology,hydrogeology,3d,pybind11
Author: ISSKA SISKA – Swiss Institute for Speleology and Karst Studies
License: MIT License
         
         Copyright 2025 SISKA - Swiss Institute for Speleology and Karst Studies
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Operating System :: OS Independent
Project-URL: Homepage, https://github.com/ISSKA/pykarstnsim
Project-URL: Repository, https://github.com/ISSKA/pykarstnsim
Project-URL: Issues, https://github.com/ISSKA/pykarstnsim/issues
Project-URL: Documentation, https://github.com/ISSKA/KarstNSim_Public/blob/main/config_reference.md
Requires-Python: >=3.9
Requires-Dist: numpy>=2.0.2
Description-Content-Type: text/markdown

# PyKarstNSim

A Python interface for the [KarstNSim](https://github.com/ring-team/KarstNSim_Public) C++ library, enabling graph-based and geologically-driven simulation of 3D karst networks directly from Python. This wrapper was developed by the [SISKA (Swiss Institute for Speleology and Karst Studies)](https://www.isska.ch) 

## About

PyKarstNSim provides Python bindings to KarstNSim, a powerful tool for simulating realistic karst network geometries. This package is based on the  [KarstNSim_Public](https://github.com/ring-team/KarstNSim_Public) repository developed by the RING team.

### Credits

KarstNSim was originally developed by:

- **Augustin Gouy** (PhD development, 2022-2025)
- **Benoît Thébault** (initial implementation, 2022)
- Supervised by **Pauline Collon** and **Vincent Bailly-Comte**

The methodology adapts the karst synthesis approach from:

> Paris, A., Guérin, E., Peytavie, A., Collon, P., Galin, E., 2021. _Synthesizing Geologically Coherent Cave Networks_. Comput. Graph. Forum 40, 277–287. https://doi.org/10.1111/cgf.14420

### Citation

If you use this package, please cite the original KarstNSim publication:

```bibtex
@article{Gouy2024,
    author = {Gouy, Augustin and Collon, Pauline and Bailly-Comte, Vincent and Galin, Eric and Antoine, Christophe and Thebault, Benoît and Landrein, Philippe},
    doi = {10.1016/j.jhydrol.2024.130878},
    journal = {Journal of Hydrology},
    title = {{KarstNSim: A graph-based method for 3D geologically-driven simulation of karst networks}},
    year = {2024}
}
```

## Installation

### Using [uv](https://docs.astral.sh/uv/) (recommended)

```bash
uv add pykarstnsim
```

### Using pip

```bash
pip install pykarstnsim
```

## Usage

See the [pykarstnsim-demo](https://github.com/ISSKA/pykarstnsim-demo) repository for working examples and tutorials.

## Documentation

For detailed information about:

- **Simulation methodology**: See the [2024 publication](https://doi.org/10.1016/j.jhydrol.2024.130878) and [2025 thesis](https://hal.univ-lorraine.fr/tel-05114757v1)
- **Input parameters and configuration**: Refer to the [config reference](https://github.com/ISSKA/KarstNSim_Public/blob/main/config_reference.md) in the C++ repository
- **Algorithm details**: Consult the full [KarstNSim documentation](https://github.com/ring-team/KarstNSim_Public)

## Requirements

- Python >= 3.9
- NumPy >= 2.0.2

## Contributing

Contributions are welcome! To set up a development environment:

### Using uv (recommended)

```bash
git clone https://github.com/ISSKA/pykarstnsim.git
cd pykarstnsim
uv sync
```

### Using pip

```bash
git clone https://github.com/ISSKA/pykarstnsim.git
cd pykarstnsim
pip install -e .
```

## Maintainers

PyKarstNSim is maintained by [ISSKA](https://www.isska.ch) and **Augustin Gouy** (a.gouy.proaddress@gmail.com), the original author of KarstNSim.

## License

See [LICENSE](LICENSE) file for details. License is shared with the original KarstNSim C++ library.

## Contact

For issues specific to the Python bindings, please open an issue on this repository.

For questions about the underlying KarstNSim methodology:

- Augustin Gouy: a.gouy.proaddress@gmail.com
- Pauline Collon: pauline.collon@univ-lorraine.fr
