Table of Contents

Class PsoSampler

Namespace
OptunaSharp.Samplers
Assembly
OptunaSharp.dll

A sampler driving a textbook-faithful global-best OptunaSharp.Samplers.ParticleSwarm.Pso Particle Swarm optimizer (Kennedy & Eberhart 1995; Shi & Eberhart 1998 inertia weight) through the Optuna protocol. PSO maintains a swarm of particles, each carrying a position, a velocity and a personal-best memory, and the swarm shares one global best; each particle's velocity is nudged toward its personal best and the global best (with an inertia term), giving a robust derivative-free scalar optimizer that complements CmaEsSampler and DifferentialEvolutionSampler as a benchmark baseline.

Bootstrapping. PSO needs an initial swarm before it can move particles, so the first max(nStartupTrials, populationSize) completed trials are drawn by the independent sampler and become the initial swarm (velocities start at rest); swarm moves are proposed from then on.

Two protocol concessions (as DifferentialEvolutionSampler): (1) the canonical PSO velocity/position update is unconstrained, so each asked candidate is clamped to the transformed unit box and the next generation recovers each particle's realized velocity as x_evaluated − x_previous (a velocity reset on bound contact — a standard PSO bound-handling rule). (2) The per-trial protocol asks one candidate per trial from freshly-restored state; each trial is stamped with its generation and its target index so the swarm's update pairs each evaluated position with the right particle once the generation completes.

Inertia schedule. Optuna is trial-budget-driven and does not expose a maximum generation to the sampler, so the linearly-decreasing inertia weight decays from w to wMin over inertiaDecayGenerations generations (constant at wMin thereafter). Categorical parameters and single-value distributions are handled by the independent sampler, as in CmaEsSampler.

Not OptunaHub's PSOSampler. OptunaHub's samplers/pso is another PSO, with a constant inertia, which this class does not follow, so a study moved over from it gets other defaults and other trials (registry pinned in refs/optunahub-registry):

OptunaHub PSOSamplerThis class
n_particles=10popsize: max(10, 4 + ⌊3 ln d⌋)
inertia=0.5, constantw = 0.9 decreasing linearly to wMin = 0.4 over inertiaDecayGenerations = 100
cognitive=1.5, social=1.5c1 = c2 = 1.49445
velocity clamped to the full range of each parametermaxVelocityRate = 0.2 of the unit box
search_space, seedseed; the search space is inferred; plus nStartupTrials, independentSampler, warnIndependentSampling
public sealed class PsoSampler : BaseSampler
Inheritance
PsoSampler
Inherited Members

Examples

var study = Optuna.CreateStudy(sampler: new PsoSampler(seed: 42));
study.Optimize(t =>
{
    double s = 0;
    for (int i = 0; i < 10; i++) { double x = t.SuggestFloat($"x{i}", -5, 5); s += x * x; }
    return s;
}, nTrials: 400);

Constructors

PsoSampler(int, BaseSampler?, bool, int?, int?, double, double, int, double, double, double)

Configures particle velocities, inertia decay, and independent startup sampling.

public PsoSampler(int nStartupTrials = 1, BaseSampler? independentSampler = null, bool warnIndependentSampling = true, int? seed = null, int? popsize = null, double w = 0.9, double wMin = 0.4, int inertiaDecayGenerations = 100, double c1 = 1.49445, double c2 = 1.49445, double maxVelocityRate = 0.2)

Parameters

nStartupTrials int

Minimum independent trials before PSO begins; PSO always waits for at least populationSize completed trials to seed the initial swarm, whichever is larger.

independentSampler BaseSampler

Sampler for parameters outside the relative search space (default RandomSampler).

warnIndependentSampling bool

Emit a warning when a parameter is sampled independently.

seed int?

Random seed for PSO.

popsize int?

Swarm size (default max(10, 4 + ⌊3 ln d⌋); must be ≥ 2).

w double

Initial inertia weight (Shi & Eberhart's w_max, default 0.9).

wMin double

Final inertia weight (Shi & Eberhart's w_min, default 0.4).

inertiaDecayGenerations int

Generations over which the inertia weight decays linearly from w to wMin (default 100).

c1 double

Cognitive (personal-best) acceleration coefficient (default 1.49445).

c2 double

Social (global-best) acceleration coefficient (default 1.49445).

maxVelocityRate double

Per-coordinate velocity clamp as a fraction of the box width (default 0.2).

Exceptions

ArgumentException

The requested population size is below two or maximum velocity rate is nonpositive.

Methods

AfterTrial(Study, FrozenTrial, TrialState, IReadOnlyList<double>?)

Trial post-processing: called after the objective function returns and right before the trial is finished and its state is stored.

public override void AfterTrial(Study study, FrozenTrial trial, TrialState state, IReadOnlyList<double>? values)

Parameters

study Study

Study that owns the trial being finished.

trial FrozenTrial

Trial snapshot before its terminal state is written to storage.

state TrialState

Terminal state being recorded: complete, pruned, or failed.

values IReadOnlyList<double>

Resulting trial values in objective order; non-null for a successful trial.

BeforeTrial(Study, FrozenTrial)

Trial pre-processing: called during trial initialization, just before the InferRelativeSearchSpace(Study, FrozenTrial) call.

public override void BeforeTrial(Study study, FrozenTrial trial)

Parameters

study Study

Study that owns the newly initialized trial.

trial FrozenTrial

New trial snapshot available before search-space inference.

InferRelativeSearchSpace(Study, FrozenTrial)

Infer the search space that will be used by relative sampling in the target trial.

This method is called right before SampleRelative(Study, FrozenTrial, OrderedDict<string, BaseDistribution>), and the search space returned by this method is passed to it. The parameters not contained in the search space will be sampled by using SampleIndependent(Study, FrozenTrial, string, BaseDistribution).

public override OrderedDict<string, BaseDistribution> InferRelativeSearchSpace(Study study, FrozenTrial trial)

Parameters

study Study

Study supplying trial history, directions, and storage.

trial FrozenTrial

Current trial snapshot; copy it before modifying its contents.

Returns

OrderedDict<string, BaseDistribution>

Parameter distributions eligible for joint sampling, in sampler-defined order.

ReseedRng()

Reseed sampler's random number generator.

Parallel optimization calls this hook before a worker's sequential trial loop. Concrete samplers refresh their random streams so workers do not deliberately reuse a seeded sequence. OptunaSharp workers share the study's sampler instance; this hook does not clone it or make concurrent sampling reproducible.

public override void ReseedRng()

SampleIndependent(Study, FrozenTrial, string, BaseDistribution)

Sample a parameter for a given distribution.

This method is called only for the parameters not contained in the search space returned by SampleRelative(Study, FrozenTrial, OrderedDict<string, BaseDistribution>). This method is suitable for sampling algorithms that do not use relationship between parameters such as random sampling and TPE.

public override object? SampleIndependent(Study study, FrozenTrial trial, string paramName, BaseDistribution paramDistribution)

Parameters

study Study

Study supplying trial history, directions, and storage.

trial FrozenTrial

Current trial snapshot; copy it before modifying its contents.

paramName string

Name of the parameter being suggested.

paramDistribution BaseDistribution

Distribution defining the parameter's domain and scale.

Returns

object

A value in the distribution's external representation, including null categorical choices.

Exceptions

ValueError

The study has multiple objectives, but this sampler requires a scalar objective.

SampleRelative(Study, FrozenTrial, OrderedDict<string, BaseDistribution>)

Sample parameters in a given search space.

The trial invokes this method lazily when it first needs relative parameters and caches the result for its remaining suggestions. This method is suitable for sampling algorithms that use relationship between parameters such as Gaussian Process and CMA-ES.

public override OrderedDict<string, object?> SampleRelative(Study study, FrozenTrial trial, OrderedDict<string, BaseDistribution> searchSpace)

Parameters

study Study

Study supplying trial history, directions, and storage.

trial FrozenTrial

Current trial snapshot; copy it before modifying its contents.

searchSpace OrderedDict<string, BaseDistribution>

Distributions returned by InferRelativeSearchSpace(Study, FrozenTrial).

Returns

OrderedDict<string, object>

Jointly sampled external parameter values; omitted parameters use independent sampling.

Exceptions

ValueError

The study has multiple objectives, but this sampler requires a scalar objective.

Edit this page