Metadata-Version: 2.4
Name: pygeomodeling
Version: 0.3.2
Summary: Advanced Gaussian Process Regression and Kriging toolkit for SPE9 reservoir modeling
Author: Kyle T. Jones
Author-email: "K. Jones" <kyletjones@gmail.com>
Maintainer-email: "K. Jones" <kyletjones@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/kylejones200/pygeomodeling
Project-URL: Repository, https://github.com/kylejones200/pygeomodeling
Project-URL: Documentation, https://github.com/kylejones200/pygeomodeling#readme
Project-URL: Bug Tracker, https://github.com/kylejones200/pygeomodeling/issues
Keywords: geomodeling,GPR,kriging,SPE9,reservoir,gaussian-process,geostatistics
Classifier: Development Status :: 4 - Beta
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: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0.0,>=1.24.0
Requires-Dist: pandas<3.0.0,>=1.5.0
Requires-Dist: scipy<2.0.0,>=1.10.0
Requires-Dist: scikit-learn<2.0.0,>=1.3.0
Requires-Dist: joblib<2.0.0,>=1.2.0
Requires-Dist: matplotlib<4.0.0,>=3.7.0
Requires-Dist: signalplot>=0.1.0
Requires-Dist: pykrige<2.0.0,>=1.6.0
Requires-Dist: gstools<2.0.0,>=1.4.0
Requires-Dist: numba<1.0.0,>=0.58.0
Requires-Dist: tqdm<5.0.0,>=4.65.0
Provides-Extra: dev
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == "dev"
Requires-Dist: ipykernel<7.0.0,>=6.20.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: coverage>=7.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Provides-Extra: advanced
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "advanced"
Requires-Dist: gpytorch<2.0.0,>=1.11.0; extra == "advanced"
Requires-Dist: botorch<1.0.0,>=0.8.0; extra == "advanced"
Requires-Dist: optuna<4.0.0,>=3.2.0; extra == "advanced"
Provides-Extra: geospatial
Requires-Dist: rasterio<2.0.0,>=1.3.0; extra == "geospatial"
Requires-Dist: fiona<2.0.0,>=1.9.0; extra == "geospatial"
Requires-Dist: geopandas<1.0.0,>=0.13.0; extra == "geospatial"
Requires-Dist: shapely<3.0.0,>=2.0.0; extra == "geospatial"
Requires-Dist: xarray<2024.0.0,>=2023.1.0; extra == "geospatial"
Requires-Dist: netcdf4<2.0.0,>=1.6.0; extra == "geospatial"
Requires-Dist: h5py<4.0.0,>=3.8.0; extra == "geospatial"
Provides-Extra: performance
Requires-Dist: cupy<13.0.0,>=12.0.0; extra == "performance"
Provides-Extra: visualization
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "all"
Requires-Dist: gpytorch<2.0.0,>=1.11.0; extra == "all"
Requires-Dist: botorch<1.0.0,>=0.8.0; extra == "all"
Requires-Dist: optuna<4.0.0,>=3.2.0; extra == "all"
Requires-Dist: rasterio<2.0.0,>=1.3.0; extra == "all"
Requires-Dist: fiona<2.0.0,>=1.9.0; extra == "all"
Requires-Dist: geopandas<1.0.0,>=0.13.0; extra == "all"
Requires-Dist: shapely<3.0.0,>=2.0.0; extra == "all"
Requires-Dist: xarray<2024.0.0,>=2023.1.0; extra == "all"
Requires-Dist: netcdf4<2.0.0,>=1.6.0; extra == "all"
Requires-Dist: h5py<4.0.0,>=3.8.0; extra == "all"
Requires-Dist: jupyter<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: ipykernel<7.0.0,>=6.20.0; extra == "all"
Requires-Dist: black>=23.0.0; extra == "all"
Requires-Dist: pytest>=7.0.0; extra == "all"
Requires-Dist: pytest-cov>=4.0.0; extra == "all"
Requires-Dist: pytest-xdist>=3.0.0; extra == "all"
Requires-Dist: pytest-mock>=3.10.0; extra == "all"
Requires-Dist: pytest-timeout>=2.1.0; extra == "all"
Requires-Dist: coverage>=7.0.0; extra == "all"
Requires-Dist: flake8>=6.0.0; extra == "all"
Requires-Dist: mypy>=1.0.0; extra == "all"
Requires-Dist: pre-commit>=3.0.0; extra == "all"
Requires-Dist: mkdocs>=1.5.0; extra == "all"
Requires-Dist: mkdocs-material>=9.0.0; extra == "all"
Requires-Dist: mkdocstrings[python]>=0.20.0; extra == "all"
Requires-Dist: pymdown-extensions>=10.0.0; extra == "all"
Dynamic: author
Dynamic: license-file
Dynamic: requires-python

# PyGeomodeling

[![PyPI version](https://badge.fury.io/py/pygeomodeling.svg)](https://badge.fury.io/py/pygeomodeling)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/kylejones200/pygeomodeling/workflows/Tests/badge.svg)](https://github.com/kylejones200/pygeomodeling/actions)
[![Documentation](https://readthedocs.org/projects/pygeomodeling/badge/?version=latest)](https://pygeomodeling.readthedocs.io/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

Advanced Gaussian Process Regression and Kriging toolkit for SPE9 reservoir modeling. This toolkit provides a comprehensive framework for spatial modeling of reservoir properties using both traditional Gaussian Process models and cutting-edge Deep Gaussian Process architectures.

## Key Features

### Core Capabilities

- **GRDECL Parser**: Load and parse Eclipse GRDECL files with automatic property extraction
- **Unified Toolkit**: Single interface supporting both scikit-learn and GPyTorch workflows
- **Advanced Models**: Traditional GP (RBF, Matérn, Combined kernels) and Deep GP with neural network features
- **Rich Visualization**: Comprehensive plotting utilities for model comparison and spatial analysis

### Features (v0.3.0)

- **Error Handling**: Comprehensive validation with helpful error messages
- **Model Serialization**: Save/load models with versioning and metadata
- **Spatial Cross-Validation**: Proper validation for geostatistical data
- **Parallel Processing**: 3-4x speedup with multi-core training
- **Hyperparameter Tuning**: Optuna integration for optimization
- **Variogram Analysis**: Semi-variogram modeling for spatial correlation (NEW!)
- **Tutorial Notebooks**: Interactive learning with Jupyter
- **Research-Ready**: Built for reproducible scientific research

## Installation

### Basic Installation (Traditional GP Models)

```bash
pip install pygeomodeling
```

### With Advanced Deep GP Features

```bash
pip install pygeomodeling[advanced]
```

### Complete Installation (All Features)

```bash
pip install pygeomodeling[all]
```

### Development Installation

```bash
git clone https://github.com/kylejones200/pygeomodeling.git
cd pygeomodeling
./setup_dev.sh  # Automated setup
# or manually: pip install -e ".[dev,docs,all]"
```

## Quick Start

### Basic Usage

```python
from pygeomodeling import GRDECLParser, UnifiedSPE9Toolkit

# Load SPE9 dataset
parser = GRDECLParser('path/to/SPE9.GRDECL')
data = parser.load_data()

# Create toolkit and train model
toolkit = UnifiedSPE9Toolkit()
toolkit.load_spe9_data(data)
X_train, X_test, y_train, y_test = toolkit.create_train_test_split()

# Train traditional GP model
model = toolkit.create_sklearn_model('gpr', kernel_type='combined')
toolkit.train_sklearn_model(model, 'combined_gpr')
results = toolkit.evaluate_model('combined_gpr', X_test, y_test)

print(f"R² Score: {results.r2:.4f}")
```

### Deep GP Experiment

```python
from pygeomodeling import DeepGPExperiment

# Run comprehensive comparison
experiment = DeepGPExperiment()
results = experiment.run_comparison_experiment()

# Results automatically saved to deep_gp_comparison.png
print(f"Best model: {max(results.keys(), key=lambda x: results[x]['metrics']['r2_score'])}")
```

## What's Included

### Core Modules

- **`grdecl_parser.py`**: Eclipse GRDECL file parser with SPE9 support
- **`unified_toolkit.py`**: Main toolkit with sklearn and GPyTorch backends
- **`model_gp.py`**: Advanced GPyTorch models (Standard GP, Deep GP)
- **`plot.py`**: Comprehensive visualization utilities
- **`deep_gp_experiment.py`**: Ready-to-run comparison experiments

### Example Scripts

- **`main.py`**: Traditional geomodeling workflow
- **`package.py`**: Packaging and distribution helper

## Scientific Applications

This toolkit has been designed for:

- **Reservoir Modeling**: Spatial interpolation of permeability and porosity
- **Uncertainty Quantification**: Gaussian Process uncertainty estimates
- **Model Comparison**: Traditional vs Deep GP performance analysis
- **Geostatistical Research**: Advanced spatial modeling techniques

## Model Performance

Based on SPE9 reservoir dataset analysis:

- **Traditional GP (Combined Kernel)**: R² = 0.277 (Best)
- **Deep GP (Small)**: R² = 0.189
- **Training Time**: ~1.3-1.8 seconds per model

*Traditional Gaussian Process models with combined RBF+Matérn kernels outperform Deep GP models for SPE9 spatial patterns, demonstrating the effectiveness of classical geostatistical approaches for this dataset.*

## Dependencies

### Core Dependencies (Always Installed)

- numpy >= 1.24.0
- pandas >= 1.5.0
- scikit-learn >= 1.3.0
- matplotlib >= 3.7.0
- pykrige >= 1.6.0

### Optional Dependencies

- **Advanced**: torch, gpytorch, botorch, optuna (for Deep GP models)
- **Geospatial**: rasterio, geopandas, shapely (for advanced spatial analysis)
- **Performance**: numba (for JIT compilation)
- **Visualization**: matplotlib, signalplot (for publication-quality plots)

## Documentation

Tutorial notebooks are available in the [examples/](examples/) directory.

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.

## License

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

## Support

For questions, issues, or contributions:

- **Issues**: [GitHub Issues](https://github.com/kylejones200/pygeomodeling/issues)
- **Email**: <kyletjones@gmail.com>
- **Documentation**: [Project Wiki](https://github.com/kylejones200/pygeomodeling/wiki)

## Citation

If you use this toolkit in your research, please cite:

```bibtex
@software{jones2025spe9geomodeling,
  title={SPE9 Geomodeling Toolkit: Advanced Gaussian Process Regression for Reservoir Modeling},
  author={Jones, Kyle T.},
  year={2025},
  url={https://github.com/kylejones200/pygeomodeling}
}
```

## Outputs

- `PERMX_GPR.GRDECL`: predicted permeability in GRDECL format
- `SIGMA_GPR.GRDECL`: standard deviation (uncertainty) of predictions
- `gpr_prediction_slices.png`: side-by-side slice visualization
