jijzepttools.blackbox_optimization.neighbor_sampler

jijzepttools.blackbox_optimization.neighbor_sampler#

Neighbor sampling strategies for blackbox optimization.

This module provides neighbor generation strategies that can be used alongside surrogate model-based optimization to explore the search space through local perturbations.

Attributes#

BINARY_TOLERANCE

Classes#

NeighborSamplerParams

Parameters for neighbor sampling in BlackboxOptimization.

NeighborSampler

Neighbor sampling strategy that generates neighbors by flipping single binary variables.

Functions#

to_hashable(→ tuple)

Convert a dictionary to a hashable tuple for duplicate detection.

Module Contents#

BINARY_TOLERANCE = 1e-06#
to_hashable(obj: Any) → tuple#

Convert a dictionary to a hashable tuple for duplicate detection.

This function is specialized for dictionaries returned by BlackboxProblem.decode_from_solution(), which may contain nested dictionaries with tuple keys.

Parameters:

obj (any) – Object to convert. Typically a dict, but can handle primitives.

Returns:

A hashable tuple representation of the object.

Return type:

tuple

Examples

>>> to_hashable({"x": 1, "y": 2})
(('x', 1), ('y', 2))

>>> to_hashable({"x": 1, "y": {(0,): 1.0, (1,): 0.0}})
(('x', 1), ('y', (((0,), 1.0), ((1,), 0.0))))

Notes

Uses string representation of keys for sorting to handle mixed-type keys (e.g., strings and tuples) without TypeError.

class NeighborSamplerParams#

Parameters for neighbor sampling in BlackboxOptimization.

num_neighbors#

Number of neighbors to sample per execution. If None, generates all possible one-spin flip neighbors. If specified, randomly samples that many neighbors without replacement. Must not exceed the total number of pure binary variables. Used by: NeighborSampler.generate_neighbors() for sampling logic.

Type:

int or None, default=None

interval#

Execute neighbor sampling every N iterations in the optimization loop. For example: - interval=1 runs neighbor sampling at every iteration (0, 1, 2, …) - interval=2 runs at iterations 1, 3, 5, … - interval=5 runs at iterations 4, 9, 14, … The check is: (iteration + 1) % interval == 0 Used by: BlackboxOptimization.run() for scheduling control.

Type:

int, default=1

Notes

The interval parameter is specific to BlackboxOptimization’s execution loop and is not used by NeighborSampler itself. It is included in this class for user convenience to configure all neighbor sampling behavior in one place.

This design may be refactored in the future if NeighborSampler is used in other contexts where interval-based scheduling is not relevant.

num_neighbors: int | None = None#
interval: int = 1#
class NeighborSampler(bb_model: jijzepttools.blackbox_optimization.problem.BlackboxProblem, instance: ommx.v1.Instance, params: NeighborSamplerParams | None = None, max_start_point_cache_size: int = 10000)#

Neighbor sampling strategy that generates neighbors by flipping single binary variables.

This strategy: 1. Identifies pure binary variables (excluding categorical variables) 2. Validates that the problem has no categorical variables or constraints 3. Generates neighbors by flipping each binary variable one at a time 4. Tracks explored starting points to avoid redundant searches (with LRU cache)

Only applicable to problems with: - Pure binary variables (not categorical) - No constraints - No categorical variables anywhere in the problem

Parameters:

  • bb_model (BlackboxProblem) – The blackbox problem definition.

  • instance (ommx.v1.Instance) – The OMMX instance.

  • params (NeighborSamplerParams, optional) – Parameters for neighbor sampling. Defaults to NeighborSamplerParams().

  • max_start_point_cache_size (int, default=10000) – Maximum number of explored starting points to cache. Uses LRU (Least Recently Used) eviction to prevent unbounded memory growth. Recommended: 10000 for typical problems, increase for very large search spaces.

Raises:

ValueError – If the problem contains categorical variables or constraints.

generate_neighbors(start_point: dict) → list[dict]#

Generate one-spin flip neighbors.

Parameters:

start_point (dict) – Current solution to generate neighbors from. Must have keys that exactly match the problem variables.

Returns:

List of neighbor solutions with one flipped binary variable each. Empty list if starting point was already explored.

Return type:

list[dict]

Raises:

ValueError –

  • If start_point keys don’t match problem variables

  • If num_neighbors exceeds available pure binary variables

Contents