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, with no required Python dependencies; trials_dataframe() needs numpy 1.21 or newer, from the atune[dataframe] extra. Until there is a wheel to download you also need a Rust toolchain, maturin, and a C compiler (bundled SQLite). |
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 Python row. 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 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 behind cargo features. The default system feature enables OS
facilities; other features are opt-in. See the generated
feature reference for the complete list and its
dependency effects.
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.
- The Python API reference documents sampler seed behavior and the package's compiled modules and generated typing files.
- 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¶
For the site build command and its wheel prerequisite, see the documentation gate.
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 |