Environment variables¶
The variables atune sets on a trial's child process, and the one it reads itself.
These are the whole interface for tuning a program that is not a Rust library.
atune run spawns your program once per trial, hands it the sampled parameters and
the trial's identity through the environment, and reads the objective back from its
last line of standard output — so a shell script, a Python entry point or a compiled
binary is tunable with no bindings and no dependency on atune at all.
A child sees each of these only when it applies: ATUNE_CHECKPOINT is absent unless
the trial is a fork, a shrink-and-perturb restart, a resume, or a checkpoint
evaluation; the ATUNE_RESTART_* variables are set only for a restart child;
ATUNE_EVALUATE and ATUNE_RECIPE are set only while a final-stage estimand
evaluates a top-ranked trial; and the parameter variables are exported only if the
run asks for them.
This page is generated from the code that declares, sets and reads each variable, filtered through an explicit allow-list. Most of what the repository touches is test harness — switches that regenerate a golden file, or hand a role to one of the worker processes a concurrency test forks — and publishing those as though they configured a study would be worse than publishing nothing. So the list is fail-closed in both directions: a variable the code touches and the list does not classify fails the build, and so does a classified variable the code no longer touches.
Generated file. Do not edit between the pragmas below — run
cargo dev generate-all --mode write instead. Everything outside them is
hand-written and is never touched.
atune publishes 17 environment variables. The other 67 the code touches are test-harness switches — golden-blessing flags and multi-process test fixtures — and are deliberately absent: crates/atune_dev/env_public.toml classifies every one of them, and a variable in neither list fails the build rather than guessing.
Most of these are the handshake: the values atune sets on a trial's child process, for the program being tuned to read. A script that reads them needs no atune library at all.
ATUNE_STUDY¶
Declared as ENV_STUDY in crates/atune_core/src/exec/environment.rs; set by atune on a trial's child process.
The environment variable naming the child's study.
ATUNE_TRIAL¶
Declared as ENV_TRIAL in crates/atune_core/src/exec/environment.rs; set by atune on a trial's child process.
The environment variable naming the child's trial (its storage-global id).
ATUNE_TRIAL_WORKER¶
Declared as ENV_TRIAL_WORKER in crates/atune_core/src/exec/environment.rs; set by atune on a trial's child process.
The environment variable carrying the child's lifecycle owner id.
Together with ENV_TRIAL_EPOCH, this lets a child continue only the exact operation handed to it. Storage revalidates both values on every mutation; a trial id alone is not an ownership capability.
ATUNE_TRIAL_EPOCH¶
Declared as ENV_TRIAL_EPOCH in crates/atune_core/src/exec/environment.rs; set by atune on a trial's child process.
The environment variable carrying the child's lifecycle ownership epoch.
A reclaim advances this value, so a delayed child cannot report or finish work after a successor has taken ownership.
ATUNE_TRIAL_NUMBER¶
Declared as ENV_TRIAL_NUMBER in crates/atune_core/src/exec/environment.rs; set by atune on a trial's child process.
The environment variable naming the child's per-study trial number.
ATUNE_SEED¶
Declared as ENV_SEED in crates/atune_core/src/exec/environment.rs; set by atune on a trial's child process.
The environment variable carrying the child's per-trial objective seed.
ATUNE_CHECKPOINT¶
Declared as ENV_CHECKPOINT in crates/atune_core/src/exec/environment.rs; set by atune on a trial's child process.
The environment variable carrying a checkpoint reference for the child to resume from.
Set only for a forked or resumed trial (population-based training): it is the parent's — or, on a resume, the trial's own — latest checkpoint reference, a run-directory path or artifact id the child restores from (e.g. oniro's run_training_resume). atune never reads what it points at; it is a reference hand-off. Absent for an ordinary trial, so a program that never forks or resumes never sees it.
ATUNE_RESTART_MODE¶
Declared as ENV_RESTART_MODE in crates/atune_core/src/exec/environment.rs.
The environment variable naming a restart child's restart mode: fresh or shrink_perturb.
Set only for the first run of a restart child, beside ENV_RESTART_SEED. A fresh child has no ENV_CHECKPOINT and re-initializes from scratch; a shrink_perturb child loads ENV_CHECKPOINT, then shrinks the weights by ENV_RESTART_SHRINK and adds noise of scale ENV_RESTART_NOISE. Absent for every other trial, plain forks and resumes included.
ATUNE_RESTART_SEED¶
Declared as ENV_RESTART_SEED in crates/atune_core/src/exec/environment.rs.
The environment variable carrying a restart child's restart seed, for its re-initialization or perturbation noise.
Set with ENV_RESTART_MODE; derived from the study seed and the child's trial number, so it is reproducible.
ATUNE_RESTART_SHRINK¶
Declared as ENV_RESTART_SHRINK in crates/atune_core/src/exec/environment.rs.
The environment variable carrying a shrink-and-perturb child's shrink factor, in (0, 1].
Set only when ENV_RESTART_MODE is shrink_perturb.
ATUNE_RESTART_NOISE¶
Declared as ENV_RESTART_NOISE in crates/atune_core/src/exec/environment.rs.
The environment variable carrying a shrink-and-perturb child's noise scale, finite and non-negative.
Set only when ENV_RESTART_MODE is shrink_perturb.
ATUNE_EVALUATE¶
Declared as ENV_EVALUATE in crates/atune_core/src/exec/environment.rs.
The environment variable naming the final-stage estimand a held-out evaluation computes: checkpoint or recipe.
Set only during Study::evaluate_checkpoints, where the child loads ENV_CHECKPOINT (the trial's latest checkpoint) and evaluates it without training, and Study::replay_recipes, where it trains afresh following ENV_RECIPE. Absent for live trials and for a reevaluate replay.
ATUNE_RECIPE¶
Declared as ENV_RECIPE in crates/atune_core/src/exec/environment.rs.
The environment variable carrying the recipe a recipe-replay evaluation follows, as single-line atune.recipe version-1 JSON.
Set only when ENV_EVALUATE is recipe; the bytes are those the estimate record stores as its source.
ATUNE_PARAM_ (a prefix)¶
Declared as DEFAULT_PARAM_PREFIX in crates/atune_core/src/exec/environment.rs.
The default prefix for exported parameter environment variables.
With crate::exec::Subprocess::export_params a parameter lr is set as ATUNE_PARAM_lr. The prefix is non-empty by default so a parameter cannot silently clobber an inherited variable such as PATH.
SPACEDECK_CLI¶
Declared as ENV_SPACEDECK_CLI in crates/atune_core/src/exec/environment.rs; read by atune in crates/atune_core/src/exec/spacedeck.rs.
Names the spacedeck executable crate::exec::SpacedeckExecutor invokes, when the default — spacedeck on PATH — is not the one to use. Read once, when the executor is built; crate::exec::SpacedeckExecutor::cli_path overrides it.
ATUNE_JOURNAL¶
Set by atune in crates/atune_cli/src/run.rs; read by atune in crates/atune_cli/src/common.rs.
The study to act on when a command is given no --study. atune run sets it on every trial's child process, so a scripted worker that calls atune tell or atune best inherits the right journal without being passed a path. No constant declares it: it is the CLI's own default, resolved in crates/atune_cli/src/common.rs.
ATUNE_SAMPLER¶
Declared as ENV_SAMPLER in crates/atune_cli/src/common.rs; set by atune in crates/atune_cli/src/run.rs.
Sampler identity inherited by a scripted child of atune run.