Namespace OptunaSharp

Classes

Base class for trials. Port of optuna/trial/_base.py: BaseTrial.

Note that this class is not supposed to be directly accessed by library users.

Exception for CLI.

CLI raises this exception when it receives invalid configuration.

The observed-components channel: the convention by which an objective exposes a per-trial residual/component vector r = (r_1, …, r_m) for an objective that decomposes as f(x) = mean_i r_i(x). It is carried on a trial as the Key user attribute so that samplers which can exploit residual structure — JanusSampler (the paper's primary, recommended mode, where its Jacobian signal is sharpest) and the multi-objective JANUS metric — read the same vector through one documented reader instead of re-deriving an ad-hoc string-key reader each.

Contract. Components are per-trial terms of a mean decomposition, so all trials that carry them should use a consistent length m across the study; the terms are treated as nonnegative residual magnitudes (JANUS uses √max(r, 0), so a negative entry is permitted but read by the algorithm at its clamp of zero). A vector containing a non-finite value (NaN / ±∞) is rejected — written vectors are validated up front, and a stored vector that is empty, non-numeric, or non-finite reads back as "absent" so the consumer degrades gracefully (JANUS falls back to its scalar residual-coordinate mode when not all trials in its window carry valid components).

Wire key. The underlying user-attr key is exactly "component_losses" ("rae" is a recognized read alias), so an objective written against OptunaSharp runs unchanged against the Python reference janus_optuna, and vice versa — the channel is pure convention plus this reader/writer, storage-agnostic (it round-trips through the same user-attr path RDB / journal storages already serialize).

DuplicatedStudyError

Exception for a duplicated study name.

This error is raised when a specified study name already exists in the storage.

EnumCategoricalExtensions: Typed read-back for enum-valued categorical parameters — the read side of the TEnum lens (see EnumCategorical). Because a categorical is persisted as a bare member-name string with no type memory, the caller must name TEnum at the moment of reading; resolution is therefore deferred to here and can fail if the stored string is not a member of the requested enum.

FixedTrial

A trial class which suggests a fixed value for each parameter. Port of optuna/trial/_fixed.py: FixedTrial.

This object has the same methods as Trial, and it suggests pre-defined parameter values. The parameter values can be determined at the construction of the FixedTrial object. In contrast to Trial, FixedTrial does not depend on Study, and it is useful for deploying optimization results.

FrozenStudy

Basic attributes of a Study. Port of optuna/study/_frozen.py: FrozenStudy.

This class is private in Optuna and not referenced by Optuna users.

FrozenTrial

Status and results of a Trial. Port of optuna/trial/_frozen.py.

An object of this class has the same methods as Trial, but is not associated with, nor has any references to a Study.

It will suggest the parameter values stored in Params and will not sample values from any distributions. It can be passed to objective functions and is useful for deploying optimization results.

MaxTrialsCallback

Set a maximum number of trials before ending the study. Port of optuna/_callbacks.py: MaxTrialsCallback (exposed as optuna.study.MaxTrialsCallback).

While the nTrials argument of Study.Optimize sets the number of trials that will be run, you may want to continue running until you have a certain number of successfully completed trials, or stop the study when you have a certain number of trials that fail. This MaxTrialsCallback class allows you to set a maximum number of trials for a particular TrialState before stopping the study.

Optuna: The top-level Optuna API surface: ports of the module-level functions re-exported by optuna/init.py (create_study, load_study, delete_study, copy_study, get_all_study_summaries, get_all_study_names).

OptunaError: Base class for Optuna specific errors.

OptunaSharpVersion: Version metadata for OptunaSharp — the .NET port of Optuna. This mirrors Optuna's optuna/version.py (version): the package version and the Optuna release this port tracks as its behavioral source of truth.

StopSignals: Turns the first Ctrl+C (SIGINT) or SIGTERM the process receives into a cancelled Token, so that a console program stops Study.Optimize gracefully: no trial starts after the signal, the trials in flight finish and are stored, and Optimize throws OperationCanceledException. A second signal ends the process as it would without this class. OptunaSharp only, and opt-in: OptunaSharp never installs a handler by itself, because a signal handler is process-wide.

StorageInternalError

Exception for storage operation.

This error is raised when an operation failed in backend DB of storage.

Study

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.

StudyDirectionExtensions: Converts objective directions to the names used in Optuna messages.

StudySummary

Basic attributes and aggregated results of a Study. Port of optuna/study/_study_summary.py: StudySummary.

Trial

A trial is a process of evaluating an objective function. Port of optuna/trial/_trial.py: Trial.

This object is passed to an objective function and provides interfaces to get parameter suggestion, manage the trial's state, and set/get user-defined attributes of the trial.

Note that the direct use of this constructor is not recommended. This object is seamlessly instantiated and passed to the objective function behind the Optimize(Func<Trial, double>, int?, double?, int, Type[]?, IEnumerable<Action<Study, FrozenTrial>>?, bool, bool, TrialExecutorOptions?, CancellationToken) method; hence library users do not care about instantiation of this object.

TrialExecutorOptions: Options for the executor that runs the trials of Study.Optimize(nJobs: …). Optuna has no counterpart; with no options set anywhere, trials run on OptunaSharp's reused dedicated threads, as before these options existed.

TrialPruned

Exception for pruned trials.

This error tells a trainer that the current Trial was pruned. It is supposed to be raised after ShouldPrune() as shown in the following example.

TrialStateExtensions: Provides completion checks and Python-compatible trial state names.

TrialsTable: A plain, dependency-free table of trials — the Core-tier stand-in for pandas in Study.trials_dataframe (plan §2.4: the Microsoft.Data.Analysis adapter is a Tier X package that converts from this).

UpdateFinishedTrialError

Exception for updating a finished trial.

This error is raised when attempting to update a finished trial. (Python: inherits both OptunaError and RuntimeError; C# keeps the OptunaError base.)

Enums

SamplerConcurrency: How the workers of one Study.Optimize(nJobs: …) call reach the study's sampler. With nJobs: 1, and for every Ask/Tell outside Optimize, the study's own sampler serves every trial, whatever is chosen here.

StudyDirection: Direction of a Study. Port of optuna/study/_study_direction.py; the numeric values are Optuna's and are persisted by storages.

TrialExecutorKind: Which threads run the trials of Study.Optimize(nJobs: …) when nJobs is not 1. With nJobs: 1 every trial runs on the calling thread, whatever is chosen here.

TrialState: State of a Trial. Port of optuna/trial/_state.py; the numeric values are Optuna's and are persisted by storages.

Table of Contents

Namespace OptunaSharp

Classes

Enums