Table of Contents

Class GridSampler

Namespace
OptunaSharp.Samplers
Assembly
OptunaSharp.dll

Sampler that performs exhaustive search over the define-and-run user-specified grids. Port of optuna/samplers/_grid.py: GridSampler.

With GridSampler, the trials suggest all combinations of parameters in the given search space during the study.

The C# analogue of Optuna's GridValueType = str | float | int | bool | None is CategoricalChoice, so the grid values carry the same Python-equality semantics (and the same type preservation — int vs float — that the journal format depends on).

public class GridSampler : BaseSampler
Inheritance
GridSampler
Inherited Members

Examples

var searchSpace = new Dictionary<string, IReadOnlyList<CategoricalChoice>>
{
    ["x"] = new CategoricalChoice[] { -50, 0, 50 },
    ["y"] = new CategoricalChoice[] { -99, 0, 99 },
};
var study = Optuna.CreateStudy(sampler: new GridSampler(searchSpace));
study.Optimize(Objective);

Remarks

This sampler with ask-and-tell stops the optimization (internally invoking Stop()) just after evaluating the final grid; handle that case manually. It does not take care of a parameter's quantization specified by discrete suggest methods but just samples one of the values specified in the search space. During distributed optimization different workers may occasionally suggest the same configuration, so the total number of actual trials may exceed the size of the grid.

Constructors

GridSampler(IReadOnlyDictionary<string, IReadOnlyList<CategoricalChoice>>, int?)

Materializes and shuffles the Cartesian product of the supplied candidate values.

public GridSampler(IReadOnlyDictionary<string, IReadOnlyList<CategoricalChoice>> searchSpace, int? seed = null)

Parameters

searchSpace IReadOnlyDictionary<string, IReadOnlyList<CategoricalChoice>>

A dictionary whose key and value are a parameter name and the corresponding candidates of values, respectively.

seed int?

A seed to fix the order of trials as the grid is randomly shuffled. Fixing the seed for each process is strongly recommended in distributed optimization to avoid duplicated suggestions.

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 grid is exhausted and Study.Stop is invoked outside Study.Optimize, as in manual ask-and-tell usage.

KeyError

One unvisited grid is left and the finished trial carries no grid_id (an enqueued trial), as in Optuna.

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.

Exceptions

ValueError

The grid is empty (a parameter's value list is empty) and the trial needs a grid point: NumPy's choice error, 'a' cannot be empty unless no samples are taken, as in Optuna.

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.

IsExhausted(Study)

Return true if all the possible params are evaluated, otherwise false.

public bool IsExhausted(Study study)

Parameters

study Study

Study supplying trial history, objective directions, and storage.

Returns

bool

True if every grid configuration has a finished evaluation.

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 trial has no grid identifier or the parameter name is absent from the configured grid.

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 GridSampler reference.
Edit this page