Class BaseStorage

Namespace

OptunaSharp.Storages

Assembly

OptunaSharp.dll

Base class for storages. Port of optuna/storages/_base.py: BaseStorage.

This class is not supposed to be directly accessed by library users. It abstracts a backend database and provides internal interfaces to read/write histories of studies and trials.

Thread safety — a storage class instance can be shared among multiple threads, and must therefore be thread-safe. It must guarantee that a data instance read from the storage must not be modified by subsequent writes: a FrozenTrial returned by GetTrial(int) should not be updated by subsequent SetTrial... calls. This is usually achieved by replacing the old data with a copy on write.

Ownership of RUNNING trials — trials in finished states are not allowed to be modified; trials in the WAITING state are not allowed to be modified except for the state field.

public abstract class BaseStorage

Inheritance

object

BaseStorage

Derived

CachedStorage

InMemoryStorage

JournalStorage

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Fields

DefaultStudyNamePrefix

Prefix prepended to automatically generated study names.

public const string DefaultStudyNamePrefix = "no-name-"

Field Value

string

Methods

CheckTrialIsUpdatable(int, TrialState)

Check whether a trial state is updatable.

public virtual void CheckTrialIsUpdatable(int trialId, TrialState trialState)

Parameters

trialId int

ID of the trial (only used for an error message).

trialState TrialState

Trial state to check.

Exceptions

UpdateFinishedTrialError

If the trial is already finished.

KeyError

A finished-state check attempts to load a nonexistent trial.

CreateNewStudy(IReadOnlyList<StudyDirection>, string?)

Create a new study from a name. If no name is specified, the storage class generates a name. The returned study ID is unique among all current and deleted studies.

public abstract int CreateNewStudy(IReadOnlyList<StudyDirection> directions, string? studyName = null)

Parameters

directions IReadOnlyList<StudyDirection>

Objective directions in the same order as the objective values.

studyName string

Name identifying the study in the selected storage.

Returns

int

Unique storage identifier assigned to the created study.

Exceptions

DuplicatedStudyError

If a study with the same name already exists.

CreateNewTrial(int, FrozenTrial?)

Create and add a new trial to a study. The returned trial ID is unique among all current and deleted trials.

public abstract int CreateNewTrial(int studyId, FrozenTrial? templateTrial = null)

Parameters

studyId int

ID of the study.

templateTrial FrozenTrial

Template FrozenTrial with default user-attributes, system-attributes, intermediate-values, and a state.

Returns

int

Unique storage identifier of the created trial.

Exceptions

KeyError

If no study with the matching ID exists.

DeleteStudy(int)

Delete a study.

public abstract void DeleteStudy(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Exceptions

KeyError

If no study with the matching ID exists.

GetAllStudies()

Read a list of FrozenStudy objects, sorted by study ID.

public abstract List<FrozenStudy> GetAllStudies()

Returns

List<FrozenStudy>

Study metadata records ordered by storage identifier.

GetAllTrials(int, bool, IReadOnlyCollection<TrialState>?)

Read all trials in a study, sorted by trial ID.

public abstract List<FrozenTrial> GetAllTrials(int studyId, bool deepcopy = true, IReadOnlyCollection<TrialState>? states = null)

Parameters

studyId int

ID of the study.

deepcopy bool

Whether to copy the list of trials before returning. Set to true if you intend to update the list or elements of the list.

states IReadOnlyCollection<TrialState>

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

Returns

List<FrozenTrial>

Trials in identifier order, optionally filtered by state and copied.

Exceptions

KeyError

If no study with the matching ID exists.

GetBestTrial(int)

Return the trial with the best value in a study. Valid only during single-objective optimization.

public virtual FrozenTrial GetBestTrial(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

FrozenTrial

Best completed single-objective trial by objective value; feasibility is handled by Study.

Exceptions

KeyError

If no study with the matching ID exists.

RuntimeError

If the study has more than one direction.

ValueError

If no trials have been completed.

GetNTrials(int, IReadOnlyCollection<TrialState>?)

Count the number of trials in a study.

public virtual int GetNTrials(int studyId, IReadOnlyCollection<TrialState>? states = null)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

states IReadOnlyCollection<TrialState>

States to include; null includes every state.

Returns

int

Number of trials matching the requested state filter.

Exceptions

KeyError

If no study with the matching ID exists.

GetStudyDirections(int)

Read whether a study maximizes or minimizes an objective.

public abstract List<StudyDirection> GetStudyDirections(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

List<StudyDirection>

Objective directions in objective-value order; callers must not mutate shared storage records.

Exceptions

KeyError

If no study with the matching ID exists.

GetStudyIdFromName(string)

Read the ID of a study.

public abstract int GetStudyIdFromName(string studyName)

Parameters

studyName string

Name identifying the study in the selected storage.

Returns

int

Storage identifier of the named study.

Exceptions

KeyError

If no study with the matching name exists.

GetStudyNameFromId(int)

Read the study name of a study.

public abstract string GetStudyNameFromId(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

string

Registered study name.

Exceptions

KeyError

If no study with the matching ID exists.

GetStudySystemAttrs(int)

Read the optuna-internal attributes of a study.

public abstract OrderedDict<string, object?> GetStudySystemAttrs(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

OrderedDict<string, object>

Internal metadata snapshot; callers must not mutate shared storage records.

Exceptions

KeyError

If no study with the matching ID exists.

GetStudyUserAttrs(int)

Read the user-defined attributes of a study.

public abstract OrderedDict<string, object?> GetStudyUserAttrs(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

OrderedDict<string, object>

User metadata snapshot; callers must not mutate shared storage records.

Exceptions

KeyError

If no study with the matching ID exists.

GetTrial(int)

Read a trial.

public abstract FrozenTrial GetTrial(int trialId)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

Returns

FrozenTrial

Stored trial record; treat it as read-only unless copied.

Exceptions

KeyError

If no trial with the matching ID exists.

GetTrialIdFromStudyIdTrialNumber(int, int)

Read the trial ID of a trial.

public virtual int GetTrialIdFromStudyIdTrialNumber(int studyId, int trialNumber)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

trialNumber int

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

Returns

int

Storage identifier corresponding to the per-study trial number.

Exceptions

KeyError

If no trial with the matching study ID and trial number exists.

ArgumentOutOfRangeException

The trial number is negative.

GetTrialNumberFromId(int)

Read the trial number of a trial (unique within a study, and sequential).

public virtual int GetTrialNumberFromId(int trialId)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

Returns

int

Zero-based sequential trial number within its study.

Exceptions

KeyError

If no trial with the matching ID exists.

GetTrialParam(int, string)

Read the internal representation of a trial parameter.

public virtual double GetTrialParam(int trialId, string paramName)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

paramName string

Parameter name used as the storage and distribution lookup key.

Returns

double

Parameter value converted into its distribution's internal representation.

Exceptions

KeyError

If no trial with the matching ID exists, or no such parameter exists.

GetTrialParams(int)

Read the parameter dictionary of a trial (external representations).

public virtual IReadOnlyDictionary<string, object?> GetTrialParams(int trialId)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

Returns

IReadOnlyDictionary<string, object>

Parameter names mapped to external values; treat shared data as read-only.

Exceptions

KeyError

If no trial with the matching ID exists.

GetTrialSystemAttrs(int)

Read the optuna-internal attributes of a trial.

public virtual IReadOnlyDictionary<string, object?> GetTrialSystemAttrs(int trialId)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

Returns

IReadOnlyDictionary<string, object>

Internal attributes of the stored trial.

Exceptions

KeyError

If no trial with the matching ID exists.

GetTrialUserAttrs(int)

Read the user-defined attributes of a trial.

public virtual IReadOnlyDictionary<string, object?> GetTrialUserAttrs(int trialId)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

Returns

IReadOnlyDictionary<string, object>

User attributes of the stored trial.

Exceptions

KeyError

If no trial with the matching ID exists.

GetTrialsPrefixView(int)

Read all trials of a study as a fixed-membership, zero-copy window when the backend can afford one — the O(1) sibling of GetAllTrials(deepcopy: false) for samplers that consult history on every ask (a per-ask list copy makes the optimization loop quadratic in trial count). The window's membership is frozen at the call; each read returns the trial's current snapshot.

public virtual IReadOnlyList<FrozenTrial> GetTrialsPrefixView(int studyId)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

Returns

IReadOnlyList<FrozenTrial>

Trials in identifier order; treat the collection and its records as read-only. The base implementation falls back to GetAllTrials(deepcopy: false), so backends without a live in-memory list keep their existing (copying) behavior and only InMemoryStorage-like backends get the O(1) path.

Exceptions

KeyError

If no study with the matching ID exists.

RemoveSession()

Clean up all connections to a database.

public virtual void RemoveSession()

SetStudySystemAttr(int, IReadOnlyDictionary<string, object?>)

Optuna's set_study_system_attr name for SetStudySystemAttrs(int, IReadOnlyDictionary<string, object?>): several optuna-internal attributes in one call.

public void SetStudySystemAttr(int studyId, IReadOnlyDictionary<string, object?> attrs)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no study with the matching ID exists.

SetStudySystemAttr(int, string, object?)

Register an optuna-internal attribute to a study, overwriting any existing value.

public abstract void SetStudySystemAttr(int studyId, string key, object? value)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no study with the matching ID exists.

SetStudySystemAttrs(int, IReadOnlyDictionary<string, object?>)

Register several optuna-internal attributes to a study at once (Rustuna's set_study_system_attrs; plan 13, item S8): the result of SetStudySystemAttr(int, string, object?) once per entry, in order.

public virtual void SetStudySystemAttrs(int studyId, IReadOnlyDictionary<string, object?> attrs)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order; persistent backends require JSON-serializable values.

Remarks

The default writes one entry per call; see SetStudyUserAttrs(int, IReadOnlyDictionary<string, object?>) for what the overrides do.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no study with the matching ID exists.

SetStudyUserAttr(int, IReadOnlyDictionary<string, object?>)

Optuna's set_study_user_attr name for SetStudyUserAttrs(int, IReadOnlyDictionary<string, object?>): several user-defined attributes in one call.

public void SetStudyUserAttr(int studyId, IReadOnlyDictionary<string, object?> attrs)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no study with the matching ID exists.

SetStudyUserAttr(int, string, object?)

Register a user-defined attribute to a study, overwriting any existing value.

public abstract void SetStudyUserAttr(int studyId, string key, object? value)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no study with the matching ID exists.

SetStudyUserAttrs(int, IReadOnlyDictionary<string, object?>)

Register several user-defined attributes to a study at once, overwriting existing values (Rustuna's set_study_user_attrs; Rustuna plan 13, item S8). Optuna has no such call: the result is what calling SetStudyUserAttr(int, string, object?) once per entry, in the dictionary's order, leaves.

public virtual void SetStudyUserAttrs(int studyId, IReadOnlyDictionary<string, object?> attrs)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order; persistent backends require JSON-serializable values.

Remarks

This default writes one entry per call, exactly as a caller looping over SetStudyUserAttr(int, string, object?) would, so any storage supports it; it is atomic only as far as each single call is. The built-in storages override it to write in one step: one lock in memory, one appended batch in a journal, one transaction in a database. An empty dictionary writes nothing and checks nothing.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no study with the matching ID exists.

SetTrialIntermediateValue(int, long, double)

Report an intermediate value of an objective function, overwriting any existing value associated with the step.

public abstract void SetTrialIntermediateValue(int trialId, long step, double intermediateValue)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

step long

Reporting step whose intermediate objective observation is stored. 64-bit, like Python's unbounded int; a backend whose schema column is narrower (Optuna's PostgreSQL/MySQL INTEGER) refuses a step it cannot hold instead of truncating it.

intermediateValue double

Intermediate objective observation to store at the reporting step.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialParam(int, string, double, BaseDistribution)

Set a parameter to a trial.

public abstract void SetTrialParam(int trialId, string paramName, double paramValueInternal, BaseDistribution distribution)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

paramName string

Parameter name used as the storage and distribution lookup key.

paramValueInternal double

Parameter value in the distribution's internal numeric representation.

distribution BaseDistribution

Distribution defining the parameter representation and allowed values.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

ValueError

The distribution is incompatible with an existing parameter distribution.

SetTrialStateValues(int, TrialState, IReadOnlyList<double>?)

Update the state and values of a trial. If values is not null, this method overwrites any existing trial values.

public abstract bool SetTrialStateValues(int trialId, TrialState state, IReadOnlyList<double>? values = null)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

state TrialState

Trial state to record or inspect.

values IReadOnlyList<double>

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

Returns

bool

true if the state is successfully updated; false if the state is kept the same (which happens when updating a RUNNING trial to RUNNING).

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialSystemAttr(int, IReadOnlyDictionary<string, object?>)

Optuna's set_trial_system_attr name for SetTrialSystemAttrs(int, IReadOnlyDictionary<string, object?>): several optuna-internal attributes in one call.

public void SetTrialSystemAttr(int trialId, IReadOnlyDictionary<string, object?> attrs)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialSystemAttr(int, string, object?)

Set an optuna-internal attribute to a trial, overwriting any existing value.

public abstract void SetTrialSystemAttr(int trialId, string key, object? value)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialSystemAttrs(int, IReadOnlyDictionary<string, object?>)

Set several optuna-internal attributes of a trial at once (Rustuna's set_trial_system_attrs; plan 13, item S8): the result of SetTrialSystemAttr(int, string, object?) once per entry, in order.

public virtual void SetTrialSystemAttrs(int trialId, IReadOnlyDictionary<string, object?> attrs)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order; persistent backends require JSON-serializable values.

Remarks

The default writes one entry per call; see SetTrialUserAttrs(int, IReadOnlyDictionary<string, object?>) for what the overrides do.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialUserAttr(int, IReadOnlyDictionary<string, object?>)

Optuna's set_trial_user_attr name for SetTrialUserAttrs(int, IReadOnlyDictionary<string, object?>): several user-defined attributes in one call.

public void SetTrialUserAttr(int trialId, IReadOnlyDictionary<string, object?> attrs)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialUserAttr(int, string, object?)

Set a user-defined attribute to a trial, overwriting any existing value.

public abstract void SetTrialUserAttr(int trialId, string key, object? value)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

key string

Attribute name; a later write replaces its stored value.

value object

Attribute value; persistent backends require JSON-serializable data.

Exceptions

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

SetTrialUserAttrs(int, IReadOnlyDictionary<string, object?>)

Set several user-defined attributes of a trial at once, overwriting existing values (Rustuna's set_trial_user_attrs; Rustuna plan 13, item S8). Optuna has no such call: the result is what calling SetTrialUserAttr(int, string, object?) once per entry, in the dictionary's order, leaves.

public virtual void SetTrialUserAttrs(int trialId, IReadOnlyDictionary<string, object?> attrs)

Parameters

trialId int

Storage identifier of the trial; distinct from its per-study trial number.

attrs IReadOnlyDictionary<string, object>

The attributes, written in enumeration order; persistent backends require JSON-serializable values.

Remarks

This default writes one entry per call, as a caller's own loop would, so any storage supports it; a failure part-way leaves the entries before it written. The built-in storages override it to write in one step and check the trial once, so a finished or unknown trial gets nothing written: one lock in memory, one appended batch of ordinary single-attribute records in a journal (what Python's journal reader expects), one transaction in a database. An empty dictionary writes nothing and checks nothing.

Exceptions

ArgumentNullException

attrs is null.

KeyError

If no trial with the matching ID exists.

UpdateFinishedTrialError

If the trial is already finished.

See Also

Official Optuna storage API.