Class Study

Namespace

OptunaSharp

Assembly

OptunaSharp.dll

A study corresponds to an optimization task, i.e., a set of trials. Port of optuna/study/study.py: Study.

This object provides interfaces to run a new Trial, access trials' history, set/get user-defined attributes of the study itself.

Note that the direct use of this constructor is not recommended. To create and load a study, please refer to CreateStudy(BaseStorage?, BaseSampler?, BasePruner?, string?, StudyDirection?, bool, IEnumerable<StudyDirection>?) and LoadStudy(string?, BaseStorage, BaseSampler?, BasePruner?) respectively.

public class Study

Inheritance

object

Study

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

Study(string, BaseStorage, BaseSampler?, BasePruner?)

Opens an existing named study using a shared storage backend.

public Study(string studyName, BaseStorage storage, BaseSampler? sampler = null, BasePruner? pruner = null)

Parameters

studyName string

Name identifying the study in the selected storage.

storage BaseStorage

Storage backend holding study and trial records. An RDB backend (any ICachedStorageBackend, such as the SQLite or EF Core RDBStorage) is wrapped in a new CachedStorage; every other storage, including one that is already a CachedStorage, is used as given.

sampler BaseSampler

Sampler for parameter suggestions; null selects TPE.

pruner BasePruner

Pruning strategy; null selects the median pruner.

Remarks

Python's Study.init passes its storage through storages.get_storage, and so does this constructor. Without the wrap, a study opened by LoadStudy(string?, BaseStorage, BaseSampler?, BasePruner?), by the CLI or by calling this constructor directly would read the whole study from the database each time a sampler asks for the trial history. CreateStudy(BaseStorage?, BaseSampler?, BasePruner?, string?, StudyDirection?, bool, IEnumerable<StudyDirection>?) has already wrapped its storage, which then passes through unchanged. Each constructed study wraps separately, as each Python load_study call does: two studies opened over one RDBStorage have two caches.

Exceptions

KeyError

The named study does not exist in storage.

Properties

BestParams

Return parameters of the best trial in the study. This feature can only be used for single-objective optimization.

public IReadOnlyDictionary<string, object?> BestParams { get; }

Property Value

IReadOnlyDictionary<string, object>

Exceptions

RuntimeError

The study has multiple objectives.

ValueError

No completed trial, or no feasible completed trial, is available.

KeyError

The study has been removed from storage.

BestTrial

Return the best trial in the study.

This feature can only be used for single-objective optimization. If your study is multi-objective, use BestTrials instead.

In constrained optimization, the best trial is selected from trials that satisfy all constraints. A trial is considered feasible when all of its constraint values are less than or equal to 0.0.

public FrozenTrial BestTrial { get; }

Property Value

FrozenTrial

Exceptions

RuntimeError

The study has multiple objectives.

ValueError

No completed trial, or no feasible completed trial, is available.

KeyError

The study has been removed from storage.

BestTrials

Return trials located at the Pareto front in the study.

A trial is located at the Pareto front if there are no trials that dominate the trial. It's called that a trial t0 dominates another trial t1 if all(v0 <= v1) and any(v0 < v1) over their values.

public List<FrozenTrial> BestTrials { get; }

Property Value

List<FrozenTrial>

BestValue

Return the best objective value in the study. This feature can only be used for single-objective optimization.

public double BestValue { get; }

Property Value

double

Exceptions

RuntimeError

The study has multiple objectives.

ValueError

No completed trial, or no feasible completed trial, is available.

KeyError

The study has been removed from storage.

Direction

Return the direction of the study. This feature can only be used for single-objective optimization. If your study is multi-objective, use Directions instead.

public StudyDirection Direction { get; }

Property Value

StudyDirection

Exceptions

RuntimeError

The study has multiple objectives.

Directions

Return the directions of the study.

public IReadOnlyList<StudyDirection> Directions { get; }

Property Value

IReadOnlyList<StudyDirection>

ExecutorOptions

The executor options this study's Optimize(nJobs: …) calls use when a call passes none: which threads run the trials. null (the default) defers to Default, read at the start of each call. Optuna has no counterpart.

public TrialExecutorOptions? ExecutorOptions { get; set; }

Property Value

TrialExecutorOptions

Remarks

The second of the executor's levels: a call's executorOptions argument overrides it, and it overrides Default. The DI study factory sets it from DefaultExecutorOptions when it builds the study, so a value set here afterwards replaces that DI default.

It belongs to this Study object and is not stored: a study opened again with LoadStudy(string?, BaseStorage, BaseSampler?, BasePruner?) starts with null. Two threads running Optimize on one study object share it; each call takes its own snapshot when it starts.

MetricNames

Return metric names. Use SetMetricNames(IReadOnlyList<string>) to set the metric names first.

public List<string>? MetricNames { get; }

Property Value

List<string>

Pruner

The pruner in use.

public BasePruner Pruner { get; set; }

Property Value

BasePruner

Sampler

The sampler in use.

public BaseSampler Sampler { get; set; }

Property Value

BaseSampler

StudyName

The study name.

public string StudyName { get; }

Property Value

string

Trials

Return all trials in the study, ordered by trial number. This is a short form of GetTrials(deepcopy: true, states: null).

public List<FrozenTrial> Trials { get; }

Property Value

List<FrozenTrial>

UserAttrs

Return user attributes of the study.

public OrderedDict<string, object?> UserAttrs { get; }

Property Value

OrderedDict<string, object>

Methods

AddTrial(FrozenTrial)

Add trial to study. The trial is validated before being added.

This method should in general be used to add already evaluated trials (trial.State.IsFinished() == true). To queue trials for evaluation, please refer to EnqueueTrial(OrderedDict<string, object?>, OrderedDict<string, object?>?, bool).

public void AddTrial(FrozenTrial trial)

Parameters

trial FrozenTrial

Trial record or active trial on which the operation acts.

Remarks

Records are inserted one at a time; a later failure does not roll back records already added.

Exceptions

ValueError

A trial has invalid state, timestamps, values, parameters, or distributions, or the objective count differs from this study.

KeyError

The study has been removed from storage.

AddTrials(IEnumerable<FrozenTrial>)

Add trials to study. The trials are validated before being added.

public void AddTrials(IEnumerable<FrozenTrial> trials)

Parameters

trials IEnumerable<FrozenTrial>

Trial records to process in enumeration order.

Remarks

Records are inserted one at a time; a later failure does not roll back records already added.

Exceptions

ValueError

A trial has invalid state, timestamps, values, parameters, or distributions, or the objective count differs from this study.

KeyError

The study has been removed from storage.

Ask(OrderedDict<string, BaseDistribution>?)

Create a new trial from which hyperparameters can be suggested.

This method is part of an alternative to Optimize(Func<Trial, double>, int?, double?, int, Type[]?, IEnumerable<Action<Study, FrozenTrial>>?, bool, bool, TrialExecutorOptions?, CancellationToken) that allows controlling the lifetime of a trial outside the scope of func. Each call to this method should be followed by a call to Tell(Trial, double, bool) to finish the created trial.

public Trial Ask(OrderedDict<string, BaseDistribution>? fixedDistributions = null)

Parameters

fixedDistributions OrderedDict<string, BaseDistribution>

A dictionary containing the parameter names and parameter's distributions. Each parameter in this dictionary is automatically suggested for the returned trial, even when the suggest method is not explicitly invoked by the user.

Returns

Trial

An active trial claimed from the waiting queue or newly created; finish it with Tell.

Remarks

A failure while pre-suggesting fixed distributions can leave an already-created trial running. This manual interface does not start a heartbeat worker.

Exceptions

ValueError

A supplied distribution or pre-suggested parameter is invalid.

Exception

Storage or a sampler hook fails while creating or initializing the trial.

EnqueueTrial(OrderedDict<string, object?>, OrderedDict<string, object?>?, bool)

Enqueue a trial with given parameter values. You can fix the next sampling parameters which will be evaluated in your objective function.

public void EnqueueTrial(OrderedDict<string, object?> @params, OrderedDict<string, object?>? userAttrs = null, bool skipIfExists = false)

Parameters

params OrderedDict<string, object>

Parameter values to pass your objective function.

userAttrs OrderedDict<string, object>

A dictionary of user-specific attributes other than params.

skipIfExists bool

When true, prevents duplicate trials from being enqueued again.

Remarks

Duplicate checking and insertion are separate storage operations; concurrent callers can enqueue the same parameters.

GetTrials(bool, IReadOnlyCollection<TrialState>?)

Return all trials in the study, ordered by trial number.

public virtual List<FrozenTrial> GetTrials(bool deepcopy = true, IReadOnlyCollection<TrialState>? states = null)

Parameters

deepcopy bool

Flag to control whether to apply deep copy to the trials. Note that if you set the flag to false, you shouldn't mutate any fields of the returned trials.

states IReadOnlyCollection<TrialState>

Trial states to filter on. If null, include all states.

Returns

List<FrozenTrial>

Trials in ascending trial-number order, optionally filtered and copied.

Exceptions

KeyError

The study no longer exists in storage.

Optimize(Func<Trial, IReadOnlyList<double>>, int?, double?, int, Type[]?, IEnumerable<Action<Study, FrozenTrial>>?, bool, bool, TrialExecutorOptions?, CancellationToken)

Optimize a multi-objective function. See Optimize(Func<Trial, double>, int?, double?, int, Type[]?, IEnumerable<Action<Study, FrozenTrial>>?, bool, bool, TrialExecutorOptions?, CancellationToken).

public void Optimize(Func<Trial, IReadOnlyList<double>> func, int? nTrials = null, double? timeout = null, int nJobs = 1, Type[]? @catch = null, IEnumerable<Action<Study, FrozenTrial>>? callbacks = null, bool gcAfterTrial = false, bool showProgressBar = false, TrialExecutorOptions? executorOptions = null, CancellationToken ct = default)

Parameters

func Func<Trial, IReadOnlyList<double>>

Objective delegate returning a scalar or values in study direction order.

nTrials int?

Maximum trials started by this invocation; null leaves the count unlimited.

timeout double?

Maximum scheduling duration in seconds; null leaves elapsed time unlimited.

nJobs int

Concurrent trial workers; -1 uses the processor count.

catch Type[]

Objective exception types to mark failed and continue; other objective exceptions stop optimization.

callbacks IEnumerable<Action<Study, FrozenTrial>>

Callbacks invoked after a trial finishes, receiving the study and finished trial.

gcAfterTrial bool

Whether to request full garbage collection after each trial.

showProgressBar bool

Whether to show supported trial-count or timeout progress.

executorOptions TrialExecutorOptions

Which threads run the trials when nJobs is not 1; null uses ExecutorOptions, then Default. Read once, when the call starts.

ct CancellationToken

Cancels the run: no trial starts once it is cancelled, the trials in flight finish, then OperationCanceledException is thrown; see the single-objective overload.

Remarks

Running objectives are allowed to finish when the count, timeout, Stop request, or cancellation ends scheduling. Callback failures are not covered by the objective catch list.

Exceptions

RuntimeError

Optimization is invoked recursively on the same thread.

ValueError

nJobs is 0 or below -1, as Python's ThreadPoolExecutor refuses.

ArgumentOutOfRangeException

The executor options in effect return an undefined executor kind or an invalid idle timeout; only a derived TrialExecutorOptions class can.

OperationCanceledException

ct was cancelled before the scheduling ended, or an objective threw this exception while it was cancelled. Thrown after every trial in flight is stored; CancellationToken is ct.

Exception

An objective raises an exception outside catch, or a callback, sampler, pruner, or storage operation fails; the original failure propagates.

Optimize(Func<Trial, double>, int?, double?, int, Type[]?, IEnumerable<Action<Study, FrozenTrial>>?, bool, bool, TrialExecutorOptions?, CancellationToken)

Optimize an objective function.

Optimization is done by choosing a suitable set of hyperparameter values from a given range. Uses a sampler which implements the task of value suggestion based on a specified distribution. The sampler is specified in CreateStudy(BaseStorage?, BaseSampler?, BasePruner?, string?, StudyDirection?, bool, IEnumerable<StudyDirection>?) and the default choice for the sampler is TPE.

public void Optimize(Func<Trial, double> func, int? nTrials = null, double? timeout = null, int nJobs = 1, Type[]? @catch = null, IEnumerable<Action<Study, FrozenTrial>>? callbacks = null, bool gcAfterTrial = false, bool showProgressBar = false, TrialExecutorOptions? executorOptions = null, CancellationToken ct = default)

Parameters

func Func<Trial, double>

A callable that implements objective function.

nTrials int?

The number of trials for each process. null represents no limit in terms of the number of trials.

timeout double?

Stop study after the given number of second(s). null represents no limit.

nJobs int

The number of parallel jobs. If this argument is set to -1, the number is set to CPU count.

catch Type[]

A study continues to run even when a trial raises one of the exceptions specified in this argument. Default is an empty array, i.e. the study will stop for any exception except for TrialPruned.

callbacks IEnumerable<Action<Study, FrozenTrial>>

List of callback functions that are invoked at the end of each trial, receiving the Study and the resulting FrozenTrial.

gcAfterTrial bool

Flag to determine whether to automatically run garbage collection after each trial.

showProgressBar bool

Flag to show progress bars or not.

executorOptions TrialExecutorOptions

Which threads run the trials when nJobs is not 1. null (the default) uses ExecutorOptions, then Default, which start as OptunaSharp's reused dedicated threads. Read once, when the call starts. Not part of Optuna's API.

ct CancellationToken

Cancels the run (OptunaSharp only; Python stops on KeyboardInterrupt). Once it is cancelled no trial starts, the trials in flight finish and are stored, and this method throws OperationCanceledException carrying it. A running objective may stop early through CancellationToken: its trial is then stored FAIL, whatever catch holds. An already cancelled token runs no trial. StopSignals turns Ctrl+C and SIGTERM into such a token; a .NET Generic Host passes IHostApplicationLifetime.ApplicationStopping.

Remarks

Running objectives are allowed to finish when the count, timeout, Stop request, or cancellation ends scheduling. Callback failures are not covered by the objective catch list.

Exceptions

RuntimeError

Optimization is invoked recursively on the same thread.

ValueError

nJobs is 0 or below -1, as Python's ThreadPoolExecutor refuses.

ArgumentOutOfRangeException

The executor options in effect return an undefined executor kind or an invalid idle timeout; only a derived TrialExecutorOptions class can, because its setters validate.

OperationCanceledException

ct was cancelled before the scheduling ended, or an objective threw this exception while it was cancelled. Thrown after every trial in flight is stored; CancellationToken is ct.

Exception

An objective raises an exception outside catch, or a callback, sampler, pruner, or storage operation fails; the original failure propagates.

SetMetricNames(IReadOnlyList<string>)

Set metric names. This method names each dimension of the returned values of the objective function. It is particularly useful in multi-objective optimization. (Experimental since Optuna 3.2.0.)

public void SetMetricNames(IReadOnlyList<string> metricNames)

Parameters

metricNames IReadOnlyList<string>

One display name per objective, in objective order.

Exceptions

ValueError

The number of names differs from the number of objectives.

SetUserAttr(IReadOnlyDictionary<string, object?>)

Optuna's set_user_attr name for SetUserAttrs(IReadOnlyDictionary<string, object?>): several user attributes in one call.

public void SetUserAttr(IReadOnlyDictionary<string, object?> attrs)

Parameters

attrs IReadOnlyDictionary<string, object>

The attributes, set in enumeration order. The values should be JSON serializable.

Exceptions

ArgumentNullException

attrs is null.

KeyError

The study no longer exists in storage; nothing is set.

Exception

A configured storage fails; its exception propagates.

SetUserAttr(string, object?)

Set a user attribute to the study.

public void SetUserAttr(string key, object? value)

Parameters

key string

A key string of the attribute.

value object

A value of the attribute. The value should be JSON serializable.

SetUserAttrs(IReadOnlyDictionary<string, object?>)

Set several user attributes to the study at once (Rustuna's set_user_attrs; plan 13, item S8), with one storage call: the stored result is what SetUserAttr(string, object?) once per entry leaves.

public void SetUserAttrs(IReadOnlyDictionary<string, object?> attrs)

Parameters

attrs IReadOnlyDictionary<string, object>

The attributes, set in enumeration order. The values should be JSON serializable.

Exceptions

ArgumentNullException

attrs is null.

KeyError

The study no longer exists in storage; nothing is set.

Exception

A configured storage fails; its exception propagates.

Stop()

Exit from the current optimization loop after the running trials finish.

This method lets the running Optimize(Func<Trial, double>, int?, double?, int, Type[]?, IEnumerable<Action<Study, FrozenTrial>>?, bool, bool, TrialExecutorOptions?, CancellationToken) method return immediately after all trials which the method spawned finishes. This method only works when it is called inside an objective function or callback.

public virtual void Stop()

Exceptions

RuntimeError

The call is outside this thread's active optimization loop.

Tell(Trial, IReadOnlyList<double>?, TrialState?, bool)

Finish a trial created with Ask(OrderedDict<string, BaseDistribution>?).

public FrozenTrial Tell(Trial trial, IReadOnlyList<double>? values = null, TrialState? state = null, bool skipIfFinished = false)

Parameters

trial Trial

A Trial object.

values IReadOnlyList<double>

Optional objective value or a sequence of such values in case the study is used for multi-objective optimization. Argument must be provided if state is COMPLETE and should be null if it is FAIL or PRUNED.

state TrialState?

State to be reported. Must be null, COMPLETE, FAIL or PRUNED. If null, it will be updated to COMPLETE or FAIL depending on whether validation for values reported succeed or not.

skipIfFinished bool

Flag to control whether exception should be raised when values for already finished trial are told. If true, tell is skipped without any error when the trial is already finished.

Returns

FrozenTrial

A FrozenTrial representing the resulting trial (deep-copied).

Remarks

Thread-safe for one trial: tells of it through this study's storage instance, from any thread and from the optimize loop, act in turn. Exactly one stores its result and reaches the sampler's AfterTrial; every later one is refused with Cannot tell a COMPLETE trial. (or the trial's state), or skipped when skipIfFinished is set. Optuna behaves the same in practice, because its GIL makes that order near certain; without the ordering, two tells could both pass the check and both reach AfterTrial.

Exceptions

ValueError

The trial number is invalid, the trial is not running, its requested state and values disagree, or explicit completion has invalid objective values.

KeyError

The requested trial cannot be found.

Exception

The sampler AfterTrial hook or the storage backend fails.

UpdateFinishedTrialError

Another storage instance or process finished the trial while this tell was writing it; the storage admits one of them.

Tell(Trial, double, bool)

Finish a trial created with Ask(OrderedDict<string, BaseDistribution>?) reporting a single objective value.

public FrozenTrial Tell(Trial trial, double value, bool skipIfFinished = false)

Parameters

trial Trial

Trial record or active trial on which the operation acts.

value double

Single objective value used to infer the completed state.

skipIfFinished bool

Whether to return an already-finished record without changing its state or values.

Returns

FrozenTrial

A FrozenTrial representing the resulting trial (deep-copied).

Remarks

Thread-safe for one trial: tells of it through this study's storage instance, from any thread and from the optimize loop, act in turn. Exactly one stores its result and reaches the sampler's AfterTrial; every later one is refused with Cannot tell a COMPLETE trial. (or the trial's state), or skipped when skipIfFinished is set. Optuna behaves the same in practice, because its GIL makes that order near certain; without the ordering, two tells could both pass the check and both reach AfterTrial.

Exceptions

ValueError

The trial number is invalid, the trial is not running, its requested state and values disagree, or explicit completion has invalid objective values.

KeyError

The requested trial cannot be found.

Exception

The sampler AfterTrial hook or the storage backend fails.

UpdateFinishedTrialError

Another storage instance or process finished the trial while this tell was writing it; the storage admits one of them.

Tell(int, IReadOnlyList<double>?, TrialState?, bool)

Finish a trial identified by its number.

public FrozenTrial Tell(int trialNumber, IReadOnlyList<double>? values = null, TrialState? state = null, bool skipIfFinished = false)

Parameters

trialNumber int

Zero-based trial number within the study, not a storage identifier.

values IReadOnlyList<double>

Objective values in study direction order, or null when no objective values are recorded.

state TrialState?

Complete, Pruned, Fail, or null to infer Complete or Fail from objective-value validation.

skipIfFinished bool

Whether to return an already-finished record without changing its state or values.

Returns

FrozenTrial

A detached copy of the resulting stored trial.

Remarks

Thread-safe for one trial: tells of it through this study's storage instance, from any thread and from the optimize loop, act in turn. Exactly one stores its result and reaches the sampler's AfterTrial; every later one is refused with Cannot tell a COMPLETE trial. (or the trial's state), or skipped when skipIfFinished is set. Optuna behaves the same in practice, because its GIL makes that order near certain; without the ordering, two tells could both pass the check and both reach AfterTrial.

Exceptions

ValueError

The trial number is invalid, the trial is not running, its requested state and values disagree, or explicit completion has invalid objective values.

KeyError

The requested trial cannot be found.

Exception

The sampler AfterTrial hook or the storage backend fails.

UpdateFinishedTrialError

Another storage instance or process finished the trial while this tell was writing it; the storage admits one of them.

Tell(int, double, bool)

Finish a trial identified by its number, reporting a single objective value.

public FrozenTrial Tell(int trialNumber, double value, bool skipIfFinished = false)

Parameters

trialNumber int

Zero-based trial number within the study, not a storage identifier.

value double

Single objective value used to infer the completed state.

skipIfFinished bool

Whether to return an already-finished record without changing its state or values.

Returns

FrozenTrial

A detached copy of the resulting stored trial.

Remarks

Thread-safe for one trial: tells of it through this study's storage instance, from any thread and from the optimize loop, act in turn. Exactly one stores its result and reaches the sampler's AfterTrial; every later one is refused with Cannot tell a COMPLETE trial. (or the trial's state), or skipped when skipIfFinished is set. Optuna behaves the same in practice, because its GIL makes that order near certain; without the ordering, two tells could both pass the check and both reach AfterTrial.

Exceptions

ValueError

The trial number is invalid, the trial is not running, its requested state and values disagree, or explicit completion has invalid objective values.

KeyError

The requested trial cannot be found.

Exception

The sampler AfterTrial hook or the storage backend fails.

UpdateFinishedTrialError

Another storage instance or process finished the trial while this tell was writing it; the storage admits one of them.

TrialsDataframe(string[]?, bool)

Export trials as a TrialsTable (the Core-tier analog of Study.trials_dataframe; the pandas-equivalent adapter is a Tier X package). If there are no trials, an empty table is returned.

public TrialsTable TrialsDataframe(string[]? attrs = null, bool multiIndex = false)

Parameters

attrs string[]

Field names of FrozenTrial to include as columns.

multiIndex bool

Whether the returned table keeps two-level column labels; when false, hierarchical columns such as (params, x) are flattened to params_x.

Returns

TrialsTable

An ordered TrialsTable of selected trial fields; this port does not require a pandas runtime.

See Also

Official Optuna study contract.