Table of Contents

Class ComponentLosses

Namespace
OptunaSharp
Assembly
OptunaSharp.dll

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

public static class ComponentLosses
Inheritance
ComponentLosses
Inherited Members

Examples

study.Optimize(t =>
{
    var r = new double[dim];
    double f = 0;
    for (int i = 0; i < dim; i++) { double x = t.SuggestFloat($"x{i}", -5, 5); r[i] = (x - 0.5) * (x - 0.5); f += r[i]; }
    t.SetComponentLosses(r);   // expose the residual vector; JANUS fits J directly from it
    return f / dim;
}, nTrials: 300);

Fields

Key

The user-attribute key that carries the component vector. Kept verbatim for objective portability with the Python reference (see the type remarks).

public const string Key = "component_losses"

Field Value

string

LegacyKey

A recognized read-only alias for Key (the reference accepts user_attrs["component_losses"] or user_attrs["rae"]). Reading prefers Key and only falls back to this alias when the canonical value is absent or invalid.

public const string LegacyKey = "rae"

Field Value

string

Methods

TryRead(IReadOnlyDictionary<string, object?>, out double[])

Read the observed-components vector from a trial's user attributes. Tolerant of the value being a double[] (the in-process form) or any numeric sequence (the JSON wire form that storages deserialize to). Returns false — leaving components empty — when the attribute is absent, empty, non-numeric, contains null, or contains a non-finite value; on success components is a fresh, caller-owned copy.

public static bool TryRead(IReadOnlyDictionary<string, object?> userAttrs, out double[] components)

Parameters

userAttrs IReadOnlyDictionary<string, object>

The trial's user-attribute dictionary (e.g. UserAttrs).

components double[]

The parsed residual vector, or an empty array when none is present.

Returns

bool

true if a valid, non-empty, all-finite vector was read.

Edit this page