Struct OnlineTuner 

pub struct OnlineTuner { /* private fields */ }

A real-time, in-loop hyperparameter tuner.

Construct one with OnlineTuner::builder; drive it with suggest/observe once per training round (or the combined drive_round). See the module documentation for the full contract.

Implementations

impl OnlineTuner

pub fn builder() -> OnlineTunerBuilder

Starts building a tuner. The default direction is Direction::Maximize and the default policy is the clustered UCB bandit with the default window (Mabc::new).

pub fn suggest(&mut self) -> Choice<'_>

The hyperparameter choices for the coming round, one per cluster.

O(clusters × arms) (arms is a small constant) and allocation-free: it rewrites the preallocated choice buffer in place and returns a borrowed Choice. Call it once per round, before observe.

pub fn observe(&mut self, round_return: f64)

Credits round_return to the arms/knobs the last suggest chose, sliding the policy forward one round. O(clusters) and allocation-free (a cluster whose reward sum stops being finite is rebuilt from its window instead).

Direction is honoured here: under Direction::Minimize a smaller return is better. Call once per round, after suggest.

pub fn round_rng(&self) -> ChaCha8Rng

The deterministic RNG of the round about to run — the stream drive_round hands its callback — for a caller that pairs suggest and observe by hand. A pure function of the seed and the number of rounds observed so far; allocation-free.

pub fn drive_round<F>(&mut self, run: F)

where F: FnOnce(&Choice<'_>, &mut ChaCha8Rng) -> f64,

Runs one round through the tuner: suggest, evaluate, observe.

The oniro-free shape of the per-round callback seam: run receives the round’s Choice and a deterministic, round-specific [ChaCha8Rng], then returns the round’s return, which is observed. The RNG is derived from this tuner’s seed and current round ordinal. It is recreated for each round, so snapshot/restore reproduces callback draws exactly.

pub const fn rounds(&self) -> u64

The number of rounds observed so far.

pub fn clusters(&self) -> usize

The number of clusters this tuner manages.

pub const fn direction(&self) -> Direction

The optimization direction.

pub fn is_flush_boundary(&self) -> bool

true when the round just observed lands on a flush interval boundary — the caller’s cue to snapshot the tuner into a journal (off the hot path). Always false if no interval was configured with OnlineTunerBuilder::flush_every.

pub fn snapshot(&self) -> Result<StateBlob>

Serializes the full tuner state into a versioned StateBlob.

This allocates (it builds JSON) and is meant to be called at interval boundaries — is_flush_boundary — never on the hot path. A caller persists the blob through any Storage::put_state to make the online run a replayable, resumable study.

Errors

Error::Storage if the state holds a non-finite float, naming its location as a JSON Pointer. That is the case while a non-finite return, or a reward sum that overflowed, is still part of the state: in a Mabc arm’s windowed sum (/engine/Mabc/clusters/…/win_sum) until its round leaves the window, or in a crate::online::PbtLite period’s sum or mean (/engine/PbtLite/period_sum, /engine/PbtLite/prev_mean) until the next period closes. Once it has aged out, a snapshot succeeds again.

pub fn restore(&mut self, blob: &StateBlob) -> Result<()>

Restores tuner state from a snapshot blob.

The snapshot must describe the same shape — same cluster names, same policy, same window or period and, for Mabc, the same candidate values — as this tuner, or the restore is refused rather than silently loading mismatched state. A refused restore leaves the tuner unchanged.

Errors

Error::Incompatible if the blob is not an ONLINE_BLOB_KIND payload of ONLINE_BLOB_VERSION. Error::Storage if it cannot be decoded, does not match this tuner’s shape, or contains invalid policy state.

Trait Implementations

impl Debug for OnlineTuner

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.