API reference

HillClimber

class hill_climber.HillClimber[source]

Bases: object

Hill climbing optimizer with replica exchange.

This optimizer uses parallel tempering (replica exchange) to improve global optimization. Multiple replicas run at different temperatures, periodically exchanging configurations to enhance exploration and exploitation.

Parameters:

data – Input data as numpy array (N, M) or pandas DataFrame with M columns
objective_func – Function taking M column arrays, returns (metrics_dict, objective_value)
mode – ‘maximize’, ‘minimize’, or ‘target’ (default: ‘maximize’)
target_value – Target value (only used if mode=’target’)
max_time – Maximum runtime in minutes (default: 10.0)
initial_step_spread – Initial perturbation spread as fraction of input range (default: 0.25 = 25%). Step values are sampled from a gaussian distribution with mean 0 and standard deviation calculated per-feature as: feature_range * initial_step_spread. Each feature uses its own range for more appropriate perturbations across different scales.
final_step_spread – Final perturbation spread as fraction of input range (default: None). If specified, step spread linearly decreases from initial_step_spread to final_step_spread over the course of max_time, enabling time-based cooling for more refined optimization near the end of the run.
perturb_fraction – Fraction of data points to perturb each step (default: 0.001)
n_replicas – Number of replicas for parallel tempering (default: 4), setting to 1 runs simulated annealing without replica exchange
T_min – Base temperature (will be used as T_min for ladder) (default: 0.0001)
T_max – Maximum temperature for hottest replica (default: 100 * T_min)
cooling_rate – Temperature decay rate per successful step (default: 1e-10)
temperature_scheme – ‘geometric’ or ‘linear’ temperature spacing (default: ‘geometric’)
exchange_interval – Steps between exchange attempts (default: 100)
exchange_strategy – ‘even_odd’, ‘random’, or ‘all_neighbors’ (default: ‘even_odd’)
checkpoint_file – Path to save checkpoints (default: None, no checkpointing)
checkpoint_interval – Batches between checkpoint saves (default: 1, i.e., every batch)
db_enabled – Enable database logging for dashboard (default: True)
db_path – Path to SQLite database file (default: ‘../data/hill_climb.db’)
db_step_interval – Collect metrics every Nth step. Uses tiered sampling: 1 for exchange_interval<10, 10 for 10-99, 100 for 100-999, 1000 for >=1000 (default: None, auto-calculated)
verbose – Print progress messages (default: False)
n_workers – Number of worker processes (default: n_replicas)

__init__(data, objective_func, mode='maximize', target_value=None, max_time=10.0, initial_step_spread=0.25, final_step_spread=None, perturb_fraction=0.001, n_replicas=4, T_min=0.0001, T_max=None, cooling_rate=1e-10, temperature_scheme='geometric', exchange_interval=100, exchange_strategy='even_odd', checkpoint_file=None, checkpoint_interval=1, db_enabled=True, db_path=None, db_step_interval=None, verbose=False, n_workers=None)[source]

Initialize HillClimber optimizer.

Parameters:

objective_func (Callable)
mode (str)
target_value (float | None)
max_time (float)
initial_step_spread (float)
final_step_spread (float | None)
perturb_fraction (float)
n_replicas (int)
T_min (float)
T_max (float | None)
cooling_rate (float)
temperature_scheme (str)
exchange_interval (int)
exchange_strategy (str)
checkpoint_file (str | None)
checkpoint_interval (int)
db_enabled (bool)
db_path (str | None)
db_step_interval (int | None)
verbose (bool)
n_workers (int | None)

climb()[source]

Run replica exchange optimization.

Returns:

Best configuration found across all replicas.: If database is enabled, use the dashboard to view optimization history.

Return type:

np.ndarray

get_replicas()[source]

Get best data from all replicas.

Returns:

Tuple of DataFrames (or numpy arrays if input was numpy), one for each replica,: containing the best data found by that replica. Ordered by replica_id.

Return type:

tuple

save_checkpoint(filepath)[source]

Save current state to checkpoint file.

Parameters:: filepath (str)

classmethod load_checkpoint(filepath, objective_func, reset_temperatures=False)[source]

Load optimization state from checkpoint.

Parameters:

filepath (str) – Path to checkpoint file
objective_func (Callable) – Objective function (must match original)
reset_temperatures (bool) – If True, reset replica temperatures to original ladder values If False (default), continue from saved temperatures

Returns:

HillClimber instance with restored state

Configuration

OptimizerConfig

class hill_climber.OptimizerConfig[source]

Bases: object

Configuration for HillClimber optimizer.

objective_func

Function taking M column arrays, returns (metrics_dict, objective_value)

Type:: Callable

mode

Optimization mode - ‘maximize’, ‘minimize’, or ‘target’

Type:: str

target_value

Target value (only used if mode=’target’)

Type:: float | None

max_time

Maximum runtime in minutes

Type:: float

initial_step_spread

Initial perturbation spread as fraction of input range (default: 0.25 = 25%)

Type:: float

final_step_spread

Final perturbation spread at end of run (default: None = no cooling)

Type:: float | None

perturb_fraction

Fraction of data points to perturb each step

Type:: float

n_replicas

Number of replicas for parallel tempering (default: 4)

Type:: int

T_min

Base temperature (will be used as T_min for ladder)

Type:: float

T_max

Maximum temperature for hottest replica (default: 100 * T_min)

Type:: float | None

cooling_rate

Temperature decay rate per successful step

Type:: float

temperature_scheme

‘geometric’ or ‘linear’ temperature spacing

Type:: str

exchange_interval

Steps between exchange attempts

Type:: int

exchange_strategy

‘even_odd’, ‘random’, or ‘all_neighbors’

Type:: str

checkpoint_file

Path to save checkpoints (default: None, no checkpointing)

Type:: str | None

checkpoint_interval

Batches between checkpoint saves (default: 1)

Type:: int

db_enabled

Enable database logging for dashboard (default: True)

Type:: bool

db_path

Path to SQLite database file (default: ‘../data/hill_climb.db’)

Type:: str | None

db_step_interval

Collect metrics every Nth step (default: exchange_interval // 10, or 1 if exchange_interval <= 10)

Type:: int | None

verbose

Print progress messages (default: False)

Type:: bool

n_workers

Number of worker processes (default: n_replicas)

Type:: int | None

objective_func: Callable

mode: str = 'maximize'

target_value: float | None = None

max_time: float = 10.0

initial_step_spread: float = 0.25

final_step_spread: float | None = None

perturb_fraction: float = 0.001

n_replicas: int = 4

T_min: float = 0.0001

T_max: float | None = None

cooling_rate: float = 1e-10

temperature_scheme: str = 'geometric'

exchange_interval: int = 100

exchange_strategy: str = 'even_odd'

checkpoint_file: str | None = None

checkpoint_interval: int = 1

db_enabled: bool = True

db_path: str | None = None

db_step_interval: int | None = None

verbose: bool = False

n_workers: int | None = None

__post_init__()[source]: Validate configuration after initialization.

__init__(objective_func, mode='maximize', target_value=None, max_time=10.0, initial_step_spread=0.25, final_step_spread=None, perturb_fraction=0.001, n_replicas=4, T_min=0.0001, T_max=None, cooling_rate=1e-10, temperature_scheme='geometric', exchange_interval=100, exchange_strategy='even_odd', checkpoint_file=None, checkpoint_interval=1, db_enabled=True, db_path=None, db_step_interval=None, verbose=False, n_workers=None)

Parameters:

objective_func (Callable)
mode (str)
target_value (float | None)
max_time (float)
initial_step_spread (float)
final_step_spread (float | None)
perturb_fraction (float)
n_replicas (int)
T_min (float)
T_max (float | None)
cooling_rate (float)
temperature_scheme (str)
exchange_interval (int)
exchange_strategy (str)
checkpoint_file (str | None)
checkpoint_interval (int)
db_enabled (bool)
db_path (str | None)
db_step_interval (int | None)
verbose (bool)
n_workers (int | None)

Return type:

None

State management

ReplicaState

class hill_climber.ReplicaState[source]

Bases: object

State container for a single replica in the hill climber optimization.

This dataclass provides type safety and IDE autocomplete for replica state, replacing the previous dictionary-based approach.

replica_id

Replica identifier

Type:: int

temperature

Current temperature

Type:: float

current_data

Current data configuration

Type:: numpy.ndarray

current_objective

Current objective value

Type:: float

best_data

Best data found so far

Type:: numpy.ndarray

best_objective

Best objective value found

Type:: float

best_metrics

Best metrics dictionary

Type:: Dict[str, Any]

perturbation_num

Global perturbation counter (monotonically increasing)

Type:: int

num_accepted

Number of accepted steps

Type:: int

num_improvements

Number of improvements found

Type:: int

temperature_history

List of (step, temperature) tuples for temperature changes

Type:: List[Tuple[int, float]]

exchange_attempts

Total number of exchange attempts

Type:: int

exchange_acceptances

Number of successful exchanges

Type:: int

partner_history

List of partner replica IDs for successful exchanges

Type:: List[int]

original_data

Original input data before optimization

Type:: numpy.ndarray | None

hyperparameters

Optimization hyperparameters dictionary

Type:: Dict[str, Any]

start_time

Unix timestamp when replica started

Type:: float

Key attributes

perturbation_num (int): Global perturbation counter (monotonically increasing)
num_accepted (int): Number of SA-accepted steps
num_improvements (int): Number of improvements found
best_data (np.ndarray): Best solution found
best_objective (float): Best objective value
best_metrics (Dict): User-defined metrics at best solution
current_data (np.ndarray): Current solution being explored
current_objective (float): Current objective value
temperature (float): Current temperature

replica_id: int

temperature: float

current_data: ndarray

current_objective: float

best_data: ndarray

best_objective: float

best_metrics: Dict[str, Any]

perturbation_num: int = 0

num_accepted: int = 0

num_improvements: int = 0

temperature_history: List[Tuple[int, float]]

exchange_attempts: int = 0

exchange_acceptances: int = 0

partner_history: List[int]

original_data: ndarray | None = None

hyperparameters: Dict[str, Any]

start_time: float

to_dict()[source]

Convert ReplicaState to dictionary for backwards compatibility.

Returns:: Dictionary representation of replica state with all attributes.
Return type:: Dict

classmethod from_dict(state_dict)[source]

Create ReplicaState from dictionary for backwards compatibility.

Parameters:: state_dict (Dict) – Dictionary containing replica state with keys matching ReplicaState attributes.
Returns:: New ReplicaState instance populated from dictionary.
Return type:: ReplicaState

__init__(replica_id, temperature, current_data, current_objective, best_data, best_objective, best_metrics=<factory>, perturbation_num=0, num_accepted=0, num_improvements=0, temperature_history=<factory>, exchange_attempts=0, exchange_acceptances=0, partner_history=<factory>, original_data=None, hyperparameters=<factory>, start_time=<factory>)

Parameters:

replica_id (int)
temperature (float)
current_data (ndarray)
current_objective (float)
best_data (ndarray)
best_objective (float)
best_metrics (Dict[str, Any])
perturbation_num (int)
num_accepted (int)
num_improvements (int)
temperature_history (List[Tuple[int, float]])
exchange_attempts (int)
exchange_acceptances (int)
partner_history (List[int])
original_data (ndarray | None)
hyperparameters (Dict[str, Any])
start_time (float)

Return type:

None

hill_climber.create_replica_state(replica_id, temperature, current_data, current_objective, best_data, best_objective, original_data=None, hyperparameters=None)[source]

Create a new replica state dictionary.

Legacy function for backwards compatibility. For new code, prefer using ReplicaState dataclass directly.

Parameters:

replica_id (int) – Replica identifier.
temperature (float) – Initial temperature.
current_data (np.ndarray) – Current data configuration.
current_objective (float) – Current objective value.
best_data (np.ndarray) – Best data found so far.
best_objective (float) – Best objective value found.
original_data (np.ndarray, optional) – Original input data before optimization. Default is None.
hyperparameters (Dict, optional) – Optimization hyperparameters. Default is None.

Returns:

Dictionary containing replica state.

Return type:

Dict

Replica exchange components

TemperatureLadder

class hill_climber.TemperatureLadder[source]

Bases: object

Manages temperature ladder for replica exchange.

Provides methods to create geometric, linear, or custom temperature schedules for parallel tempering optimization.

temperatures: ndarray

property n_replicas: int

Number of replicas in the ladder.

Returns:: Number of replicas.
Return type:: int

classmethod geometric(n_replicas, T_min, T_max)[source]

Create geometric temperature ladder.

Parameters:

n_replicas (int) – Number of replicas.
T_min (float) – Minimum (coldest) temperature.
T_max (float) – Maximum (hottest) temperature.

Returns:

Instance with geometrically spaced temperatures.

Return type:

TemperatureLadder

classmethod linear(n_replicas, T_min, T_max)[source]

Create linear temperature ladder.

Parameters:

n_replicas (int) – Number of replicas.
T_min (float) – Minimum (coldest) temperature.
T_max (float) – Maximum (hottest) temperature.

Returns:

Instance with linearly spaced temperatures.

Return type:

TemperatureLadder

classmethod custom(temperatures)[source]

Create custom temperature ladder.

Parameters:: temperatures (List[float]) – List of temperatures (will be sorted).
Returns:: Instance with custom temperatures.
Return type:: TemperatureLadder

__init__(temperatures)

Parameters:: temperatures (ndarray)
Return type:: None

ExchangeScheduler

class hill_climber.ExchangeScheduler[source]

Bases: object

Determines which replica pairs attempt exchanges each round.

__init__(n_replicas, strategy='even_odd')[source]

Initialize scheduler.

Parameters:

n_replicas (int) – Number of replicas.
strategy (str) – Exchange strategy - ‘even_odd’, ‘random’, or ‘all_neighbors’. Default is ‘even_odd’.

get_pairs()[source]

Get list of replica pairs to attempt exchange.

Returns:: List of (i, j) tuples where i < j.
Return type:: List[Tuple[int, int]]
Raises:: ValueError – If strategy is unknown.

Core functions

Helper functions for hill climbing optimization.

hill_climber.climber_functions.perturb_vectors(data, perturb_fraction=0.1, bounds=None, step_spread=1.0)[source]

Randomly perturb a fraction of elements in the data.

This function uses JIT-compiled core logic for performance. Works directly with numpy arrays - no DataFrame conversions. Perturbations are sampled from a normal distribution with mean 0.

Parameters:

data (np.ndarray) – Input data as numpy array with shape (N, M).
perturb_fraction (float) – Fraction of total elements to perturb. Default is 0.1. Note: HillClimber uses 0.001 as its default.
bounds (tuple, optional) – Tuple of (min_bounds, max_bounds) arrays for each column. If None, uses data min/max. Default is None.
step_spread (float or np.ndarray) – Standard deviation of normal distribution for perturbations. Can be a scalar (same for all features) or array (per-feature). Default is 1.0.

Returns:

Perturbed numpy array with same shape as input.

Return type:

np.ndarray

hill_climber.climber_functions.extract_columns(data)[source]

Extract columns from numpy array.

Works with multi-column data by returning each column separately.

Parameters:: data (np.ndarray) – Numpy array with shape (N, M) where N = samples, M = features.
Returns:: Tuple of 1D numpy arrays, one for each column.
Return type:: tuple

Examples

>>> data = np.array([[1, 2], [3, 4], [5, 6]])
>>> x, y = extract_columns(data)
>>> print(x)  # [1, 3, 5]
>>> print(y)  # [2, 4, 6]

hill_climber.climber_functions.calculate_objective(data, objective_func)[source]

Calculate objective value using provided objective function.

Extracts columns from data and passes them to the objective function. Supports multi-column data.

Parameters:

data (np.ndarray) – Input data as numpy array with shape (N, M).
objective_func (Callable) – Function that takes M column arrays and returns (metrics_dict, objective_value).

Returns:

Tuple of (metrics_dict, objective_value) where metrics_dict is a: dictionary of metric names to values, and objective_value is a float.

Return type:

tuple

Examples

>>> def obj_func(x, y):
...     return {'mean_x': x.mean()}, x.mean() + y.mean()
>>> data = np.array([[1, 2], [3, 4]])
>>> metrics, objective = calculate_objective(data, obj_func)