Hill climber documentation

A flexible simulated annealing optimizer with replica exchange for generating synthetic datasets with specific properties (or whatever else you can dream up).

Hill Climber is a Python package to optimize datasets with user-defined objective functions. It’s particularly useful for:

  • Generating synthetic data with specific statistical properties

  • Exploring relationships between different correlation measures

  • Creating datasets for testing and benchmarking

  • Educational demonstrations of optimization algorithms

Installation

pip install parallel-hill-climber

For real-time monitoring dashboard support:

pip install parallel-hill-climber[dashboard]

See Installation for more options including development setup.

Contents:

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

  • Type-safe configuration: Dataclass-based configuration with automatic validation

  • Flexible objective functions: Define custom objectives for any statistical property

  • Simulated annealing: Escape local optima and find global solutions

  • Multi-column data: Optimize datasets with any number of features

  • Structured state management: ReplicaState dataclass with type hints for clarity and IDE support

  • Checkpointing: Save and resume long-running optimizations with configurable checkpoint intervals

  • JIT compilation: Numba-optimized core functions for performance

Data format

Hill Climber works with tabular data in the following format:

  • Input shape: (N, M) where N = number of samples (rows), M = number of features (columns)

  • Accepted formats: NumPy arrays or pandas DataFrames

  • Objective functions: Receive M separate 1D arrays (one per feature column)

    • For 2 features: objective_func(x, y)

    • For 3 features: objective_func(x, y, z)

    • For M features: objective_func(col1, col2, ..., colM)

Python version support

  • Python 3.10+

  • Tested on Python 3.10, 3.11, and 3.12

Indices and tables