Table of Contents

Class BruteForceSampler

Namespace
OptunaSharp.Samplers
Assembly
OptunaSharp.dll

Sampler that performs exhaustive search over the define-by-run search space. Port of optuna/samplers/_brute_force.py: BruteForceSampler (experimental since 3.1.0).

This sampler performs exhaustive search on the defined search space. Each suggestion builds a tree over the trials observed so far — each internal node is a parameter and its children are keyed by the parameter's candidate values (internal repr); a root-to-leaf path is one complete params — then samples an unexplored branch, blending exact-uniform with flat-uniform weighting to prevent starvation of unexplored branches. It stops the study (internally invoking Stop()) once the space is exhausted.

public class BruteForceSampler : BaseSampler
Inheritance
BruteForceSampler
Inherited Members

Examples

double Objective(Trial trial)
{
    var c = trial.SuggestCategorical("c", new CategoricalChoice[] { "float", "int" }).Value as string;
    if (c == "float")
        return trial.SuggestFloat("x", 1, 3, step: 0.5);
    long a = trial.SuggestInt("a", 1, 3);
    long b = trial.SuggestInt("b", a, 3);
    return a + b;
}

var study = Optuna.CreateStudy(sampler: new BruteForceSampler());
study.Optimize(Objective);

Remarks

The defined search space must be finite. Therefore, when using FloatDistribution or SuggestFloat(string, double, double, double?, bool), step = null is not allowed (a ValueError is raised). The sampler may fail to try the entire search space when the suggestion ranges or parameters are changed in the same Study.

Constructors

BruteForceSampler(int?, bool)

Configures traversal of finite parameter choices discovered while the objective runs.

public BruteForceSampler(int? seed = null, bool avoidPrematureStop = false)

Parameters

seed int?

A seed to fix the order of trials as the search order is randomly shuffled. Please note that it is not recommended using this option in distributed optimization settings since this option cannot ensure the order of trials and may increase the number of duplicate suggestions during distributed optimization.

avoidPrematureStop bool

If true, the sampler performs a strict exhaustive search. Please note that enabling this option may increase the likelihood of duplicate sampling. When this option is not enabled (default), the sampler applies a looser criterion for determining when to stop the search, which may result in incomplete coverage of the search space.

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.

Exceptions

RuntimeError

The search tree is exhausted and Study.Stop is invoked outside Study.Optimize.

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.

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.

Remarks

Diverges from Optuna under concurrent asks ([Misaligned], owner's decision 2026-11-08): a point another running trial holds is never handed out again, in either mode. Optuna's default mode already prefers points nobody runs but reads running trials from the storage, one parameter late; its strict mode (avoidPrematureStop: true) hands running points out again on purpose, so that a dead worker's point still gets evaluated. Measured before the change with 8 trials asked at once: 3-8 repeats per 88 trials of a 90-point space in strict mode, 0-1 in the default mode.

How: the values handed to each running trial are recorded, so the tree holds every running path as far as it is chosen, and a running trial whose path ends above a branch counts as taking one of that branch's points (TreeNodeBase.CountFreeUnexplored). A trial enters a branch only while it has a point left for it, and re-evaluates a finished point only when no branch has an unexplored one. An unexpanded branch counts as one point, so near the end of the space, when running trials hold nearly every unexplored point, a trial may re-evaluate a finished point while one is still free.

Footgun: in strict mode, a point whose worker died is no longer re-run by another worker; once it is the only unexplored point, asks receive finished points until the dead trial is failed (by a heartbeat, or by hand) and its point is free again. A sequential run has no other running trial and is unchanged.

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.

See Also

Official Optuna BruteForceSampler reference.
Edit this page