Class InMemoryStorage

Namespace

OptunaSharp.Storages

Assembly

OptunaSharp.dll

Storage class that stores data in memory of the current process. Port of optuna/storages/_in_memory.py: InMemoryStorage.

public class InMemoryStorage : BaseStorage

Inheritance

object

BaseStorage

InMemoryStorage

Inherited Members

BaseStorage.DefaultStudyNamePrefix

BaseStorage.SetStudyUserAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.SetStudySystemAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.SetTrialUserAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.SetTrialSystemAttr(int, IReadOnlyDictionary<string, object>)

BaseStorage.GetNTrials(int, IReadOnlyCollection<TrialState>)

BaseStorage.GetTrialParams(int)

BaseStorage.GetTrialUserAttrs(int)

BaseStorage.GetTrialSystemAttrs(int)

BaseStorage.RemoveSession()

BaseStorage.CheckTrialIsUpdatable(int, TrialState)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

var storage = new InMemoryStorage();
var study = Optuna.CreateStudy(storage: storage);
study.Optimize(trial => Math.Pow(trial.SuggestFloat("x", -100, 100), 2), nTrials: 10);

Constructors

InMemoryStorage()

Creates an empty storage that keeps every trial's dictionaries as Optuna's in-memory storage does.

public InMemoryStorage()

InMemoryStorage(bool)

Creates an empty storage, optionally keeping finished trials in a compact form (Rustuna plan 13, item S12).

public InMemoryStorage(bool compactFinishedTrials)

Parameters

compactFinishedTrials bool

When true, each trial is compacted as it finishes: parameters become one internal value per name against a parameter schema the study's trials share, distributions come from that schema, attributes become arrays with long ASCII strings stored as bytes, and empty dictionaries take no memory. False (the default) keeps Optuna's representation exactly.

Remarks

What stays the same: every value any API returns, and so every sampler's results; a seeded study gives the same trials either way. A finished 40-parameter random-search trial took 6.7 KB in memory and takes 0.7 KB compact; a CMA-ES trial 13.5 KB and 2.7 KB, its optimizer states stored as bytes (100,000 trials: 1,287 MB and 257 MB). Run times stay the same within noise.

What changes, which is why it is opt-in: a finished trial's Params, Distributions, UserAttrs and SystemAttrs become read-only views rather than OrderedDict<TKey, TValue> objects (a cast to OrderedDict fails, a write through IDictionary throws), and numeric values and long strings are rebuilt on each read, so two reads are equal but not the same object. The mutable accessors (ParamsDict and the other …Dict properties, and IntermediateValues) still return real dictionaries: the first such read gives the trial back a dictionary of its own, which it keeps, so changes made through them stay, at the cost of that trial's saving. A finished trial no longer shares its dictionaries with the running record it was copied from. A read of a numeric parameter through the views allocates a box; TPE, which reads every trial on every ask, copies the stored internal values instead.

Properties

CompactFinishedTrials

Whether this storage keeps finished trials in the compact form (see the constructor).

public bool CompactFinishedTrials { get; }

Property Value

bool

Methods

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 override 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 override int CreateNewTrial(int studyId, FrozenTrial? templateTrial = null)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

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 override 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 override 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 override List<FrozenTrial> GetAllTrials(int studyId, bool deepcopy = true, IReadOnlyCollection<TrialState>? states = null)

Parameters

studyId int

Storage identifier of the study; distinct from its name.

deepcopy bool

Whether to copy trial records; treat records returned with false as read-only.

states IReadOnlyCollection<TrialState>

States to include; null includes every state.

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 override 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.

GetStudyDirections(int)

Read whether a study maximizes or minimizes an objective.

public override 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 override 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 override 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 override 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 override 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 override 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 override 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 override 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 override 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.

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 override 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.

Remarks

O(1): wraps the live per-study list in a TrialsPrefixView (membership frozen at the current count, reads see current copy-on-write instances) instead of copying it — the difference between a linear and a quadratic optimization loop for GA samplers that read history every ask.

Exceptions

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 override 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 override 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.

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, string, object?)

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

public override 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 override 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.

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 override 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.

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 override 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 override 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, string, object?)

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

public override 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 override 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.

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, string, object?)

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

public override 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 override 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.

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.