parallel-hill-climber 2.1.2

A Python package for hill climbing optimization with replica exchange and simulated annealing

Hill Climber

A Python package for hill climbing optimization of user-supplied objective functions with simulated annealing. Designed for flexible multi-objective optimization with support for multi-column datasets.

1. Documentation

View Full Documentation on GitHub Pages

2. Features

• Replica Exchange (Parallel Tempering): Multiple replicas at different temperatures exchange configurations for improved global optimization
• Real-Time Monitoring Dashboard: Streamlit-based modular dashboard for live progress visualization with SQLite backend
• Simulated Annealing: Temperature-based acceptance of suboptimal solutions to escape local minima
• Flexible Objectives: Support for any objective function with multiple metrics
• Multi-Column Support: Optimize datasets with any number of features/columns
• Checkpoint/Resume: Save and resume long-running optimizations with configurable checkpoint intervals
• JIT Compilation: Numba-optimized core functions for performance

3. Quick Start

3.1. Installation

Install the package directly from PyPI to use it in your own projects:

pip install parallel-hill-climber

For detailed usage, configuration options, and advanced features, see the full documentation.

3.2. Example climb

Simple hill climb to maximize the Pearson correlation coefficient between two random uniform features:

import numpy as np
import pandas as pd

from hill_climber import HillClimber

# Create sample data
data = pd.DataFrame({
    'x': np.random.rand(100),
    'y': np.random.rand(100)
})

# Define objective function
def my_objective(x, y):
    correlation = pd.Series(x).corr(pd.Series(y))
    metrics = {'correlation': correlation}
    return metrics, correlation

# Create optimizer with replica exchange
climber = HillClimber(
    data=data,
    objective_func=my_objective,
    max_time=1,  # minutes
    mode='maximize',
    n_replicas=4  # Use 4 replicas for parallel tempering
)

# Run optimization
best_data, history_df = climber.climb()

3.3. Real-Time Monitoring Dashboard

Monitor optimization progress in real-time with the Streamlit dashboard:

from hill_climber import HillClimber

# Enable database logging
climber = HillClimber(
    data=data,
    objective_func=my_objective,
    max_time=30,
    n_replicas=8,
    db_enabled=True,  # Enable real-time monitoring
    db_path='optimization.db',
    checkpoint_interval=10  # Checkpoint every 10 batches
)

# Run optimization
best_data, history = climber.climb()

Launch the dashboard in a separate terminal:

pip install "parallel-hill-climber[dashboard]"
hill-climber-dashboard

The dashboard provides:

• Replica leaderboard showing top performers
• Exploration rate (total perturbations/sec) and progress rate (accepted steps/sec)
• Interactive time series plots for all metrics across replicas
• Temperature exchange event markers
• Plot normalization and layout options
• Run information including objective function name, dataset size, and hyperparameters

See DASHBOARD_README.md for complete dashboard documentation.

3.4. Example Notebooks

The notebooks/ directory contains demonstration of key concepts and complete worked examples demonstrating various use cases:

1. Simulated Annealing: Introduction to simulated annealing algorithm
2. Pearson & Spearman: Optimizing for different correlation measures
3. Mean & Std: Creating distributions with matching statistics but diverse structures
4. Entropy & Correlation: Low correlation with internal structure
5. Feature Interactions: Machine learning feature engineering demonstrations
6. Checkpointing: Long-running optimization with save/resume

4. Development Environment Setup

To explore the examples, modify the code, or contribute:

4.1. Setup Option 1: GitHub Codespaces (No local setup required)

1. Fork this repository
2. Open in GitHub Codespaces
3. The development environment will be configured automatically
4. Documentation will be built and served at http://localhost:8000 automatically

4.2. Setup Option 2: Local Development

1. Clone or fork the repository:

   git clone https://github.com/gperdrizet/hill_climber.git
   cd hill_climber
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4.3. Building Documentation

You can build and view a local copy of the documentation as follows:

cd docs
make html
# View docs by opening docs/build/html/index.html in a browser
# Or serve locally with: python -m http.server 8000 --directory build/html

4.4. Running Tests

To run the test suite:

# Run all tests
python tests/run_tests.py

# Or with pytest if installed
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_hill_climber.py

# Run with coverage
python -m pytest tests/ --cov=hill_climber

5. Contributing

Contributions welcome! Please ensure all tests pass before submitting pull requests.

6. License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for full details.

In summary, you are free to use, modify, and distribute this software, but any derivative works must also be released under the GPL-3.0 license.

7. Citation

If you use this package in your research, please use the "Cite this repository" button at the top of the GitHub repository page to get properly formatted citations in APA, BibTeX, or other formats.