Install atune¶
atune ships in three forms and they install differently: a Rust library you add
to a Cargo.toml, a Python package you import, and a command-line binary called
atune. Pick the one you will actually use — none of them needs the others.
Nothing is published yet
No version of atune has been released. cargo add atune and
pip install atune are the commands that will work; today neither index
has anything to serve. Every route below therefore has two halves: the
one-line install for after the first release, and the build-from-a-clone
that works right now. Where a command cannot work yet, this page says so
rather than letting you find out.
What you need¶
| To use | You need |
|---|---|
| The Rust library | Rust 1.92 or newer. That is the workspace's rust-version, and the crates are edition 2024; an older toolchain refuses the build outright rather than failing halfway through it. |
| The Python package | GIL-enabled (non-free-threaded) CPython 3.10 or newer, and numpy 1.21 or newer, which the package depends on for trials_dataframe(). Until there is a wheel to download you also need a Rust toolchain and maturin. |
The atune binary |
Rust 1.92 or newer, and a C compiler. The CLI bundles SQLite and compiles the amalgamation from source, so it needs no system libsqlite3 and every machine ends up with the same SQLite — at the price of a C toolchain at build time. |
A release will shorten the first two rows. The published wheels target
GIL-enabled CPython and use abi3-py310, so one wheel per platform covers every
GIL-enabled CPython from 3.10 upward and no Rust toolchain is involved in
installing one. Free-threaded builds, including cp314t, are not shipped.
Get the source¶
Every route below starts here while there is nothing on an index to install from:
git clone https://github.com/AndrejOrsula/atune && cd atune
The repository is a cargo workspace. cargo build --workspace compiles all of
it and verifies that your toolchain meets the workspace requirements.
The Rust library¶
After the first release: cargo add atune.
From the clone, add a path dependency to your own crate — the directory is
crates/atune, and cargo accepts atune = { path = "…/crates/atune" } wherever
it would accept a version.
atune is the crate you depend on. Underneath it sits atune_core, which is
deliberately small and compiles to wasm32; the facade is where the heavier
algorithms live, each behind a cargo feature. The default feature set is
system — the operating-system surface, which means a system clock and
thread-parallel optimize. Everything else is opt-in: sqlite, remote,
cmaes, gp, pb2, carbs, importance, diagnose, optuna-compat,
optuna-rdb.
Turning one on is the usual features = ["cmaes", "sqlite"]. Which feature
carries which sampler, scheduler or storage backend — and what each one adds to
your dependency graph — is on the feature reference,
which is generated from the manifests and so cannot drift from them.
The Python package¶
After the first release: pip install atune.
From the clone, build the extension module into your active environment with
maturin — pip install maturin, then
maturin develop --release -m crates/atune_py/Cargo.toml.
Use --release for a normal package build. -m points maturin at the binding
crate, which is not at the repository root.
Two things about the Python surface are worth knowing before you write against it, because both are deliberate and neither is guessable:
- A sampler
seedargument raises.atune.samplers.Tpe(seed=7)— the Optuna spelling — is rejected with a message naming the knob that does work, because determinism in atune belongs to the study seed,create_study(seed=42). The keyword is kept in the signature only so the mistake can be answered rather than silently ignored, which is exactly why a PythonTpe()and a RustTpe::new()produce the same run. See Determinism. - The package uses Maturin's mixed Rust/Python layout, not a single module.
atune/__init__.pyis the import shim beside the nativeatune/atuneextension (with the platform's extension suffix); the wheel ships generatedatune/__init__.pyi,atune/samplers.pyi,atune/schedulers.pyi, andatune/py.typed.atune.samplersandatune.schedulersare real importable submodules, and mypy and pyright discover all three typed surfaces. - Remote storage is not part of the Python wheel. Python storage accepts
:memory:, journal paths and SQLite paths. Use Rust or the CLI for anatune://host:portendpoint.
The command-line tool¶
After the first release: cargo install atune_cli. Note the mismatch — the
crate is atune_cli and the binary it installs is called atune.
From the clone: cargo install --path crates/atune_cli.
This is the route that needs no integration at all. It tunes a program that reads its settings from its command line or its environment and prints a number, in any language. Tune any program is that story end to end, and every flag is on the CLI reference.
Check that it works¶
Three checks, one per form, all run from the clone.
| Form | Command | What you should see |
|---|---|---|
| Rust | cargo run -p atune --example rastrigin |
best trial #151: f = 1.865055, then a block headed atune-parity/1 |
| Python | python examples/python/rastrigin.py |
the same trial number, 151, and the same value |
| CLI | atune --version |
atune 0.1.0 |
The Rust example is the one to reach for first: it needs nothing beyond cargo
and exercises the deterministic Rastrigin path used by the parity checks.
The Rust and Python lines are not "roughly the same run" — they print the same numbers to the last bit, and that is asserted by a test rather than hoped for. If your two runs disagree, something is wrong, and Determinism is the page that says what.
Building this documentation¶
You are reading pages built from the same repository, and you can build them
yourself. It needs uv and an environment with the
atune wheel in it, because the Python API reference is produced by importing
the module rather than by parsing it:
maturin develop -m crates/atune_py/Cargo.toml, then
uv run --with-requirements docs/requirements.txt mkdocs serve.
Without the wheel the build fails on the API reference instead of quietly skipping it — the same fail-closed rule the rest of the site follows, and the reason no page here can show you code that does not run.
Where to go next¶
| If you want to | Go to |
|---|---|
| Run and understand one study, in order | Your first study — the next page |
| Tune a program you did not write | Tune any program |
| Know what a study, a trial or a sampler is | Studies and trials |
| Find the feature flag a given algorithm needs | Feature reference |