Class OptunaStudyFactory

Namespace

OptunaSharp.Extensions

Assembly

OptunaSharp.dll

The default IOptunaStudyFactory: resolves the optional BaseSampler / BasePruner / BaseStorage from the service provider at each call and delegates to CreateStudy(BaseStorage?, BaseSampler?, BasePruner?, string?, StudyDirection?, bool, IEnumerable<StudyDirection>?). Registered by AddOptunaStudyFactory(IServiceCollection, Action<OptunaStudyOptions>?); construct it directly only when composing a container by hand.

public sealed class OptunaStudyFactory : IOptunaStudyFactory

Inheritance

object

OptunaStudyFactory

Implements

IOptunaStudyFactory

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Services are resolved with GetService<T>(IServiceProvider) (not required-service resolution) precisely so that an unregistered sampler/pruner/storage yields null and Optuna's built-in default is used — matching a plain optuna.create_study().

Resolution happens per CreateStudy(string?, StudyDirection?, bool?, IEnumerable<StudyDirection>?) call, against the provider passed to the constructor. AddOptunaStudyFactory(IServiceCollection, Action<OptunaStudyOptions>?) registers this type as transient, so that provider is the one that resolved the factory: a request scope, whose scoped registrations are then honored instead of being captured by the root, or the root provider for a singleton consumer. A transient sampler or pruner (the default of the factory registrations) is therefore a new instance per study, as a fresh TPESampler() is per Python create_study() call. Sharing one stateful sampler across studies mixes their state.

Disposal follows the resolving provider. A sampler, pruner or storage that implements IDisposable and is not a singleton is disposed when that provider is: at the end of the request scope, or at application shutdown for the root. Every OptunaSharp storage that owns a resource also implements IAsyncDisposable, so an asynchronously disposed scope (ASP.NET Core's request scopes) closes it with DisposeAsync and a synchronously disposed one with Dispose. A study that keeps optimizing after its request scope ends needs a singleton registration, or a factory resolved from a scope that lives as long as the study.

Constructors

OptunaStudyFactory(IServiceProvider, OptunaStudyOptions)

Creates a factory that draws its algorithm/storage from services and its defaults from options.

public OptunaStudyFactory(IServiceProvider services, OptunaStudyOptions options)

Parameters

services IServiceProvider

The provider queried (per call) for the optional sampler, pruner, and storage.

options OptunaStudyOptions

The default study shape applied when a CreateStudy(string?, StudyDirection?, bool?, IEnumerable<StudyDirection>?) argument is omitted.

Exceptions

ArgumentNullException

services or options is null.

Methods

CreateStudy(string?, StudyDirection?, bool?, IEnumerable<StudyDirection>?)

Create (or, with load_if_exists, re-attach to) a Study using the container's registered BaseSampler / BasePruner / BaseStorage (each optional — an unregistered one falls back to Optuna's default: TPESampler, MedianPruner, in-memory storage). Every parameter overrides the matching OptunaStudyOptions default for this one call.

public Study CreateStudy(string? studyName = null, StudyDirection? direction = null, bool? loadIfExists = null, IEnumerable<StudyDirection>? directions = null)

Parameters

studyName string

The study name, or null to use DefaultStudyName (and, if that is also null, a storage-generated unique name).

direction StudyDirection?

The single-objective direction, or null to fall back to the options. Must not be combined with directions.

loadIfExists bool?

Whether to return an existing same-named study instead of raising on conflict; null uses LoadIfExists.

directions IEnumerable<StudyDirection>

The multi-objective directions, or null to fall back to the options. Must not be combined with direction.

Returns

Study

A study bound to the resolved storage, using the resolved sampler and pruner.

Exceptions

ValueError

Both a single and a multi direction are in effect (from arguments or options), the directions sequence is empty, or a direction is neither minimize nor maximize.

DuplicatedStudyError

The effective study name already exists and the effective load_if_exists is false.