Metadata-Version: 2.4
Name: aichem-gloss
Version: 1.0.0
Summary: Global-Local-Unexplored Sampling Strategy for Bayesian Optimization
Home-page: https://github.com/pic-ai-robotic-chemistry/aichem-gloss
Author: B. Zhang
Author-email: "B. Zhang" <zbc@ustc.edu.cn>
License: MIT
Project-URL: Homepage, https://github.com/pic-ai-robotic-chemistry/aichem-gloss
Project-URL: Documentation, https://aichem-gloss.readthedocs.io/
Project-URL: Repository, https://github.com/pic-ai-robotic-chemistry/aichem-gloss
Project-URL: Bug Tracker, https://github.com/pic-ai-robotic-chemistry/aichem-gloss/issues
Keywords: gloss,bayesian-optimization,machine-learning,chemistry,optimization,sampling-strategy
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.19.0
Requires-Dist: scipy>=1.5.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# aichem-gloss

[![PyPI version](https://badge.fury.io/py/aichem-gloss.svg)](https://badge.fury.io/py/aichem-gloss)
[![Documentation Status](https://readthedocs.org/projects/aichem-gloss/badge/?version=latest)](https://aichem-gloss.readthedocs.io/en/latest/?badge=latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/pypi/pyversions/aichem-gloss)](https://pypi.org/project/aichem-gloss/)

**Global-Local-Unexplored Sampling Strategy (GLOSS)**

## Overview

`aichem-gloss` is a Python package that implements the GLOSS algorithm, a optimization recommender that combines three complementary search strategies:

- **Global Search**: Explores the parameter space using acquisition functions with uncertainty quantification (UCB/LCB)
- **Local Search**: Exploits promising regions around the best known points for refinement
- **Unexplored Search**: Discovers underexplored regions of the parameter space with distance-based filtering

This package is particularly useful for:
- 🧪 Chemical space exploration and molecular design
- 🔬 Materials discovery and optimization
- ⚙️ Hyperparameter optimization for machine learning
- 🎯 Any expensive black-box optimization problem
- 🤖 Robotic chemistry and automated experimentation

## Features

- ✨ **Three-strategy approach**: Balanced exploration and exploitation with unexplored region discovery
- 🔄 **Strict deduplication**: Ensures diverse and non-redundant recommendations
- 🎯 **Model-agnostic**: Works with any scikit-learn compatible model (GP, RF, etc.)
- 🚀 **Easy to use**: Simple API with sensible defaults
- 📊 **Well-documented**: Comprehensive documentation and examples
- 🔧 **Flexible**: Customizable strategy distribution and acquisition parameters

## Installation

### From PyPI

```bash
pip install aichem-gloss
```

### From Conda

```bash
conda install -c conda-forge aichem-gloss
```

### From Source

```bash
git clone https://github.com/pic-ai-robotic-chemistry/aichem-gloss.git
cd aichem-gloss
pip install -e .
```

## Quick Start

```python
import numpy as np
from sklearn.gaussian_process import GaussianProcessRegressor
from aichem_gloss import GLOSSRecommender

# Define parameter bounds
bounds = [[-5, 5], [-5, 5]]

# Create and train a surrogate model
model = GaussianProcessRegressor()
X_train = np.random.uniform(-5, 5, (20, 2))
y_train = np.sum(X_train**2, axis=1)  # Example objective
model.fit(X_train, y_train)

# Create GLOSS recommender
recommender = GLOSSRecommender(
    model=model,
    bounds=bounds,
    y_better_is_smaller=True,  # Minimization problem
    kappa=1.96,  # Exploration parameter
    exploration_fraction=0.5
)

# Fit with historical data
recommender.fit(X_train, y_train)

# Get recommendations
suggestions = recommender.suggest(n_recommend=8)
print("Recommended points:", suggestions['mixed'])
```

## Documentation

Full documentation is available at [aichem-gloss.readthedocs.io](https://aichem-gloss.readthedocs.io/)

## Examples

Check out the [examples](examples/) directory for more detailed usage examples:

- `basic_usage.py`: Basic optimization with Gaussian Process
- Using with Random Forest models
- Custom acquisition functions
- Multi-objective optimization scenarios

## Algorithm Details

The GLOSS algorithm distributes recommendations across three strategies:

### Strategy Distribution

- For `n_recommend > 3`: 
  - **Global**: 50% of recommendations (exploration with UCB/LCB)
  - **Local**: 25% of recommendations (exploitation around best points)
  - **Unexplored**: 25% of recommendations (distance-based unexplored search)
- For `n_recommend ≤ 3`: All recommendations use global search

### Key Features

1. **Strict Sequential Deduplication**: Each new candidate is checked against all previously generated points to ensure diversity
2. **Dynamic History Injection**: The unexplored search dynamically updates its reference points to avoid recently generated candidates
3. **Adaptive Repulsion Radius**: Automatically calculated based on the density of historical points
4. **Fallback Mechanisms**: Multiple fallback strategies ensure robust recommendation generation

## API Overview

### GLOSSRecommender

```python
GLOSSRecommender(
    model=None,                    # Surrogate model (scikit-learn compatible)
    bounds=None,                   # Parameter bounds [[min, max], ...]
    y_better_is_smaller=False,     # True for minimization, False for maximization
    kappa=1.96,                    # Exploration-exploitation trade-off
    exploration_fraction=0.5       # Unexploredd region threshold (0.0-0.99)
)
```

### Main Methods

- `fit(X, y)`: Fit the recommender with historical data
- `suggest(n_recommend)`: Generate new candidate points
- `get_num_recommends(n_recommend)`: Calculate strategy distribution

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Citation

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

```bibtex
@software{aichem_gloss,
  title = {aichem-gloss: Global-Local-Unexplored Sampling Strategy for Bayesian Optimization},
  author = {Zhang, B.},
  year = {2025},
  url = {https://github.com/pic-ai-robotic-chemistry/aichem-gloss}
}
```

## License

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

## Acknowledgments

- Developed by the PIC AI Robotic Chemistry team
- Inspired by Bayesian optimization and active learning research
- Built with NumPy and SciPy

## Contact

- **Author**: B. Zhang
- **Email**: zbc@ustc.edu.cn
- **Organization**: PIC AI Robotic Chemistry
- **GitHub**: [pic-ai-robotic-chemistry](https://github.com/pic-ai-robotic-chemistry)

## Related Projects

- [scikit-optimize](https://scikit-optimize.github.io/): Bayesian optimization library
- [GPyOpt](https://github.com/SheffieldML/GPyOpt): Gaussian Process optimization
- [Ax](https://ax.dev/): Adaptive experimentation platform
