Metadata-Version: 2.4
Name: geotwinnet
Version: 1.0.0
Summary: A graph-based framework for geotechnical site representation and digital twin modeling
Author-email: Wang Lai <wanglai@imust.edu.cn>
License-Expression: MIT
Project-URL: Homepage, https://github.com/wanglai25/geotwinnet
Project-URL: Source, https://github.com/wanglai25/geotwinnet.git
Project-URL: Issues, https://github.com/wanglai25/geotwinnet/issues
Keywords: geotechnical,subsurface-modeling,graph-neural-networks,site-representation,digital-twin
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.15.1
Requires-Dist: pandas>=0.23.4
Requires-Dist: scipy>=1.1.0
Requires-Dist: scikit-learn>=0.19.2
Requires-Dist: torch>=1.4.0
Requires-Dist: torch-geometric>=1.6.0
Requires-Dist: matplotlib>=2.2.3
Requires-Dist: pillow>=5.2.0
Requires-Dist: pyvista>=0.30.0
Requires-Dist: tqdm>=4.26.0
Requires-Dist: openpyxl>=2.5.6
Requires-Dist: xlrd>=1.1.0
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# GeoTwinNet - A Graph-Based Framework for Geotechnical Site Representation and Digital Twin Modeling

[![PyPI version](https://badge.fury.io/py/geotwinnet.svg)](https://badge.fury.io/py/geotwinnet)
[![Python version](https://img.shields.io/pypi/pyversions/geotwinnet.svg)](https://pypi.org/project/geotwinnet/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://github.com/wanglai25/geotwinnet/workflows/CI/badge.svg)](https://github.com/wanglai25/geotwinnet/actions)

GeoTwinNet is a Python framework for **graph-based geotechnical site representation and digital twin modeling**.  
It integrates multi-source geological data processing, spatial graph construction, graph neural networks, and 3D visualization into a unified pipeline for subsurface understanding and prediction.

---

## ✨ Features

- 🏔️ **Multi-source Data Integration**: Support for Excel/CSV geological datasets  
- 🧠 **Graph Neural Networks**: GNN-based learning for site representation  
- 🔗 **Spatial Graph Construction**: Graph generation from borehole and spatial data  
- 🎨 **3D Visualization**: PyVista-based rendering and cross-section analysis  
- 💻 **Interactive GUI**: PyQt5-based interface for workflow exploration  
- ⚙️ **Scalable Training**: GPU acceleration with PyTorch  
- 📦 **Model Export**: Export results to PLY, OBJ, STL formats  

---

## 🚀 Quick Start

### Installation

```bash
pip install geotwinnet
```

### Basic Usage

```python
from geotwinnet import DataHandler, GeoModel, GeoVisualizer

# Load and process geological data
handler = DataHandler()
unique_types, num_classes = handler.load_data('geological_data.xlsx')
rect = handler.compute_mbr()
bounds = handler.align_coordinates(x_res=10, y_res=2, z_res=1)
params_dict = handler.create_param_dict()

# Generate spatial graph
coords, labels, edges = handler.generate_grid(bounds, r=2)

# Train GNN model
model = GeoModel()
model.prepare_data(coords, labels, edges)
model.build_model(
    num_classes=num_classes,
    hidden_size=48,
    gcn_layers=3,
    mlp_layers=3,
    dropout=0.2
)
history = model.train(epochs=100, lr=3e-3)

# Prediction and visualization
predictions, probabilities = model.predict()
visualizer = GeoVisualizer()
mesh = visualizer.create_model(coords, predictions)
visualizer.show_model(mesh)
```

## Data Format

Your geological data should include these columns:

- `X`, `Y`, `Z`: Spatial coordinates
- `Soil/Rock type`: Soil/rock type classification  
- `Borehole ID`: Borehole ID (optional)
- `Borehole type`: Borehole type (optional)

Additional geotechnical parameters (e.g., strength, density, etc.) can be automatically incorporated for extended modeling.

## Examples

See the [examples/](examples/) directory for complete workflow examples:

- `basic_usage.py`: Simple modeling workflow
- `advanced_visualization.py`: Custom visualization techniques
- `batch_processing.py`: Process multiple datasets
- `custom_model.py`: Create custom GNN architectures

## Documentation

- [Installation Guide](docs/installation.md)
- [API Reference](docs/api.md)
- [User Tutorial](docs/tutorial.md)
- [Developer Guide](docs/development.md)

## System Requirements

- Python 3.8+
- 8GB RAM minimum (16GB recommended)
- CUDA-compatible GPU (optional, for acceleration)
- OpenGL support for 3D visualization

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use GeoTwinNet in your research, please cite:

```bibtex
@software{geotwinnet2026,
  author = {Wang, Lai and GeoTwinNet Development Team},
  title = {GeoTwinNet: Graph-Based Learning for Geotechnical Site Representation and Digital Twin Modeling},
  url = {https://github.com/wanglai25/geotwinnet},
  version = {1.0.0},
  year = {2026}
}
```

## Support

- 📧 Email: <wanglai@imust.edu.cn>
- 🐛 Issues: [GitHub Issues](https://github.com/wanglai25/geotwinnet/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/wanglai25/geotwinnet/discussions)
