ParticleSwarmOptimizer

class ParticleSwarmOptimizer(search_space: dict[str, list], initial_evaluations: list[tuple[dict, float]], constraints: list[callable] = None, random_state: int = None, rand_rest_p: float = 0, boundary: str = 'clip', population: int = 10, inertia: float = 0.5, cognitive_weight: float = 0.5, social_weight: float = 0.5, temp_weight: float = 0.2)

Particle Swarm optimizer with ask/tell interface.

Parameters:

search_spacedict[str, list]

The search space to explore.

initial_evaluationslist[tuple[dict, float]]

Previously evaluated parameters and their scores to seed the optimizer.

constraintslist, optional

Constraint functions restricting the search space.

random_stateint or None, default=None

Seed for reproducibility.

rand_rest_pfloat, default=0

Probability of random restart.

populationint, default=10

Number of particles in the swarm.

inertiafloat, default=0.5

Weight applied to a particle’s current velocity.

cognitive_weightfloat, default=0.5

Attraction strength toward each particle’s personal best.

social_weightfloat, default=0.5

Attraction strength toward the swarm’s global best.

temp_weightfloat, default=0.2

Temperature-like randomness weight added to velocity update.

Attributes:

best_para

Return the best parameters found as a dictionary.

best_score

Best score found so far.

best_value

Return the best values found (raw parameter values).

Methods

ask([n])	Propose n parameter sets to evaluate.
tell(scores)	Report evaluation results for the most recently asked positions.

ask(n: int = 1) → list[dict]

Propose n parameter sets to evaluate.

Parameters:

nint, default=1

Number of parameter sets to generate. The optimizer uses _iterate_batch(n) internally, which may leverage algorithm-specific batch generation (e.g. diverse acquisition points for SMBO, population cycling for PSO/GA).

Returns:

list[dict]

List of n parameter dictionaries to evaluate.

Raises:

RuntimeError

If the optimizer has not been initialized (no initial_evaluations provided) or if ask() is called before tell() returned results for the previous ask().

property best_para

Return the best parameters found as a dictionary.

Resolution order: 1. Explicitly set _best_para (used by the ask/tell mixin). 2. SearchTracker-derived value when search() has populated it. 3. Fallback computed from _pos_best.

The tracker path is preferred because _pos_best can lag behind the true best for some optimizers that only update it on accepted moves. In v2 the fallback path is slated for removal; the tracker becomes the single source of truth.

property best_score: float

Best score found so far.

Returns -inf if no evaluations have been performed yet.

property best_value

Return the best values found (raw parameter values).

Returns:

list or None

List of best values in parameter order, or None if no evaluation has been performed yet.

tell(scores: list[float]) → None

Report evaluation results for the most recently asked positions.

The scores must correspond to the parameter sets returned by the preceding ask(), in the same order.

Parameters:

scoreslist[float]

The objective function scores for each parameter set. Higher is better. For minimization problems, negate the scores before passing them here.

Raises:

RuntimeError

If called without a preceding ask().

ValueError

If the number of scores doesn’t match the preceding ask().