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
------------

.. code-block:: bash

   pip install parallel-hill-climber

For real-time monitoring dashboard support:

.. code-block:: bash

   pip install parallel-hill-climber[dashboard]

See :doc:`installation` for more options including development setup.

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   installation
   quickstart
   user_guide
   dashboard
   api
   notebooks
   advanced

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

Links
-----

- **PyPI Package**: `parallel-hill-climber <https://pypi.org/project/parallel-hill-climber/>`__
- **GitHub Repository**: `hill_climber <https://github.com/gperdrizet/hill_climber>`__
- **Issue Tracker**: `Issues <https://github.com/gperdrizet/hill_climber/issues>`__

.. raw:: html

   <script>
   document.querySelectorAll('a[href*="github.com"], a[href*="pypi.org"]').forEach(function(link) {
       link.setAttribute('target', '_blank');
   });
   </script>

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`