Training

DLManaka and Manaka share teacher data but use different trainers. This page covers only the common entry points and configuration rules. Trainer-specific behavior is documented in DLManaka training and Manaka supervised training.

Install

PyTorch is optional and selected by accelerator:

uv sync --extra cpu     # no NVIDIA GPU
uv sync --extra cu129   # NVIDIA GPU

The three axes

manaka train identifies a run by three independent choices.

flag	meaning	values
--type	trainer/evaluator family	dl, sym
--network	network shape	e.g. b15_c256, pair16_d128_o3_h512
--mode	training source	supervised, zero

manaka train --type dl  --mode supervised
manaka train --type dl  --mode zero --network b15_c256
manaka train --type sym --mode zero

A shape name is the configuration. Avoid separate nicknames: file names, run names and directories should carry the shape code.

When the shape is chosen

• DLManaka: the shape lives in the TOML config and is read at training time.
• Manaka: the shape is embedded in the .mnw file and is chosen when the initial weights are created.

manaka init --type sym --network pair16_d128_o3_h512 --out runs/manaka/gen0.mnw

manaka-train shape --network CODE parses a Manaka shape and prints its canonical form.

Configuration

Repository defaults live in tideborn.toml, one section per type × mode. Keys map directly to the underlying command-line flags. Use --set for a one-run override:

manaka train --type dl --mode zero \
  --set data.train_path=data/selfplay/gen4/train

External trainer configs remain authoritative for their own schema:

• configs/*.toml — DLManaka trainer
• tideborn/tools/openbench/config.toml — rating workers

Arguments after -- pass directly to the underlying trainer.

Meaning of zero

zero means no teacher data is used for training. Generation 0 starts from random weights and later generations train on self-play. A zero run may still use the fixed teacher holdout for validation so that validation metrics remain comparable across generations.

DLManaka

Smoke test:

manaka train --type dl -- summary --config configs/smoke.toml
manaka train --type dl -- --config configs/smoke.toml

Common configs:

config	purpose
configs/smoke.toml	CPU/synthetic smoke test
configs/cpu.toml	small network intended for CPU inference
configs/rtx4070ti.toml	single-GPU production shape
configs/a100x8.toml	multi-GPU training

Long runs can detach:

manaka train --type dl --mode supervised --detach
manaka train watch --out-dir runs/ckpt/rtx4070ti
manaka train stop  --out-dir runs/ckpt/rtx4070ti

Checkpoints are written atomically as step-*.pt. Re-running the same command resumes from the newest checkpoint unless --fresh is set.

For distributed training:

torchrun --standalone --nproc-per-node 8 -m tideborn.trainer train \
  --config configs/a100x8.toml

Current device-specific speed settings belong in the benchmark, not here.

Manaka

Manaka reads one .mnw file and writes the next. GPU training must be built and requested explicitly:

cargo build --release -p manaka-train --features cuda

manaka init --type sym --network f4 --out runs/manaka/gen0.mnw

manaka train --type sym -- \
  --data data/manaka/gen79 \
  --weights runs/manaka/gen0.mnw \
  --out runs/manaka/gen1.mnw \
  --steps 2000 --batch 1024 --lr 1e-3 --q-ratio 0.5 --device cuda

Weight-format versions are strict. Old shapes are rebuilt and retrained rather than converted between incompatible .mnw versions.

For cluster builds, images/Dockerfile.train takes CUDA_COMPUTE_CAP; use the target GPU's value. Current training throughput is in the benchmark.

Distillation target

--target chooses what a run copies out of the teacher. It defaults to policy, which is what every run before the flag existed did.

--target	policy loss	value target
policy (default)	trained	win rate, [-1, 1]
cp	not computed; the head's forward never runs	win rate on a tanh shape, centipawns on a linear one

cp exists to make a control run possible. NNUE-style engines are distilled on the evaluation alone, so a Manaka shape fitted to both a policy and a value is not a like-for-like comparison against one. With the same corpus distilled into a plain NNUE-shaped net and into Manaka's own on the value only, a bad result separates the teacher data is bad from the architecture is bad — which neither run can tell on its own.

The scale follows the shape's output layer, not the flag. A tanh value row cannot leave [-1, 1], so a shape without nnue stays on the win rate however --target is set; asking for centipawns there is neither an error nor honoured. A linear row is a centipawn score, and under --target cp it is given the teacher's own: the squash value_from_cp applied is undone, then divided by what an engine reads one unit as — 127 · 64 / FV_SCALE, so 508 at the default.

That division is the point of the mode. A linear row fitted to a [-1, 1] target tops out at 508 cp however large the position's real score is, and a 1512 cp position comes back as 387. Alpha-beta prunes on centipawn margins, so a baseline built that way is not one.

--fv-scale names the FV_SCALE the exported net will be read against, and has to match the engine's own: that number lives beside the file rather than inside it. It is read only under --target cp.

--q-ratio is unchanged and orthogonal. It still says how far the target leans towards the searched value and away from the game outcome, and the two are still mixed in win-rate space before any conversion — the outcome is ±1 and stands for no finite centipawn, so a blend taken after the conversion would have nothing to mix into. --target cp warns when it is below 1.0 rather than refusing, because NNUE's own training mixes the outcome in too.

Two things to expect from a cp run on a linear shape:

• The learning rate has to come down. The target's range widens from [-1, 1] to about ±14.7, and a squared error grows with it.
• The policy columns report NaN — in the metric lines and in wandb alike. The column stays in the row so two runs can still be laid over each other; a zero there would read as a head that got every move wrong rather than one that was never trained.

--value-weight is refused alongside --target cp: with no policy loss to weigh it against, a factor on the only loss is the learning rate under another name.

Where to look next

topic	document
data origin and validation	Teacher data
record/shard schemas	Training data formats
DLManaka trainer internals	DLManaka training
Manaka supervised findings	Manaka supervised training
Manaka generation loop	Manaka generation loop
measured architecture comparisons	Results