Crate atune_core 

Core model, traits and reference implementations for atune, a Rust-native hyperparameter optimization framework built for reinforcement learning.

This crate is the mandatory, dependency-light layer: the domain model (studies, trials, search spaces), the four plugin seams (Storage, Sampler, Scheduler, Objective), the in-memory storage backend and the built-in stateless samplers. Most users should depend on the atune facade instead, which re-exports everything here and adds the optional, heavier-dependency algorithms behind feature flags.

Orientation

A study (study) owns a search space (space), a seed, a budget and a growing set of trials (trial). Everything is ask/tell underneath: a worker asks storage for a trial, a Sampler fills in its parameters, the user’s Objective evaluates it while a Scheduler decides whether it may continue, and the result is told back to Storage. Workers coordinate through storage alone — there is no coordinator process.

The four seams are the extension points; each is object-safe, Send + Sync, and documented with the invariants an implementation must uphold.

Module	What it holds
error	Error, Result, the TrialPruned sentinel
id	identifiers, including the determinism-critical TrialNumber
seed	the stable seed-derivation function and the pinned RNG
seed_protocol	the RL multi-seed protocol: fans, paired CRN seeds, aggregation
clock	injected time; no std::time anywhere else
space	values, distributions, the single transform layer, schemas
pareto	multi-objective comparison: dominance, fronts, crowding, constraints, hypervolume
trial	trial state machine, snapshots, deltas
storage	the persistence seam
sampler	the sampling seam
scheduler	the pruning/pause/fork seam
objective	the user-code seam and TrialCtx
online	the in-loop real-time tuner (OnlineTuner)
exec	the subprocess executor (system feature) — run any program as a trial
study	study configuration, budgets, StudyView
telemetry	the correlation id OperationId and the bounded metric hook

Determinism

Three promises, kept by construction (the determinism contract): seed derivation is a stable, golden-tested pure function (seed::seed_for); the parameters of trial n under a stateless sampler depend only on (study seed, n, space); and the RNG algorithm is pinned to ChaCha8Rng. Iteration orders are stable everywhere — Assignment is sorted by name, SpaceSchema keeps declaration order, and nothing reaches a decision through a hash map’s order.

Portability

atune_core stays green on wasm32-unknown-unknown. Everything that needs an operating system — the system clock, thread-parallel optimize, and later filesystem-backed storage — sits behind the system feature. The feature is deliberately not named std: the crate always links std; what the flag gates is the OS surface that wasm32-unknown-unknown does not provide.

Features

• system (default) — OS facilities: system clock, thread-parallel optimize.
• conformance — exports the storage conformance suite so out-of-tree storage backends can run it against their own implementations.

Status

Milestone M3 complete. The whole RL-first core is here: the leaf model (errors, ids, seeds, clocks, spaces, trials, study config, StudyView); the reference storage backends (MemStorage and the flagship JournalStorage); the samplers sampler::Random/sampler::Grid/sampler::Tpe/sampler::Qmc; the schedulers scheduler::MedianPruner/scheduler::AshaPruner/ scheduler::HyperbandPruner and the scheduler::Patient/scheduler::WilcoxonPruner wrappers (plus scheduler::NopScheduler); the study loop (study::Study, ask/tell, objective::TrialCtx, optimize); the Subprocess executor; and the multi-seed protocol seed_protocol::SeedProtocol (CRN fans, aggregation, tune/test split). Next is M4 (population & multi-objective: PBT/DEHB/CMA-ES/NSGA-II).

Re-exports

pub use attrs::RESERVED_USER_ATTR_PREFIX;

pub use attrs::UserAttrs;

pub use attrs::validate_user_attr_key;

pub use error::Error;

pub use error::Result;

pub use storage::AbandonRequest;

pub use storage::ClaimRequest;

pub use storage::ClaimTarget;

pub use storage::FailStaleRequest;

pub use storage::FencedMutation;

pub use storage::FencedMutationRequest;

pub use storage::FinalizationAdvanceRequest;

pub use storage::FinalizationIntent;

pub use storage::FinalizationPhase;

pub use storage::FinalizedStateRequest;

pub use storage::LeaseObservation;

pub use storage::OutboxAdvanceRequest;

pub use storage::OutboxEffect;

pub use storage::OutboxEffectCompletion;

pub use storage::OutboxEffectIntent;

pub use storage::OutboxEffectKey;

pub use storage::OutboxKey;

pub use storage::OutboxPhase;

pub use storage::OutboxRecord;

pub use storage::ParamWrite;

pub use storage::ReplacementOutcome;

pub use storage::ReplacementSpec;

pub use storage::ReservationOutcome;

pub use storage::ReserveAndCreateRequest;

pub use storage::ReserveOutcome;

pub use storage::TerminalOutcome;

pub use storage::TerminalRequest;

pub use storage::TrialLifecycleStorage;

pub use storage::TrialOwnerToken;

pub use storage::TrialReservation;

pub use telemetry::OperationId;

Modules

attrs

User-owned JSON metadata attached to studies and trials.

checkpoint

Checkpoint references — atune moves references, never bytes.

clock

Time, injected rather than read.

error

The crate-wide error type.

exec

The subprocess executor: run any program, in any language, as a trial.

id

Identifier newtypes.

objective

The objective seam: the user’s code, and the handle it talks to.

online

In-loop online tuning — a real-time hyperparameter tuner that lives inside one training run.

pareto

Multi-objective comparison: dominance, fronts, crowding, constraints and hypervolume.

prelude

The everyday types, for use atune_core::prelude::*;.

sampler

The sampler seam: how a trial’s parameters are chosen.

scheduler

The scheduler seam: how a running trial’s fate is decided.

seed

Deterministic seed derivation.

seed_protocol

The multi-seed protocol: trials as fans of replicates (RL headline #1).

space

Search spaces: values, distributions, transforms, schemas.

storage

The storage seam: the only thing workers coordinate through.

study

Studies: configuration, budgets, the read snapshot, and the loop.

telemetry

Operation correlation and bounded metrics.

trial

Trials: state, snapshots, handles and deltas.

Macros

lifecycle_conformance_tests

Generates one test per lifecycle invariant for a backend factory.

lifecycle_state_conformance_tests

Generates the additive pause-with-state checks for an adapter that supports atomic seam-state persistence on the fenced pause operation.

outbox_conformance_tests

Generates the P0-OUTBOX checks for an adapter that implements the outbox extension of the lifecycle capability.

storage_conformance_tests

Generates one #[test] per storage conformance check.