MUTANT 0.1.0

MUTANT 0.1.0 — first public release.

First public release.

Added

• Documentation: overview, search space, algorithm, data, training/INT8, case study,
  reproducibility, API, provenance and roadmap (docs/); full README; CITATION.cff.
• mutant.viz (optional [viz] extra): Pareto landscape, convergence, size-band heatmap,
  winners' fingerprint, loop diagram, test IoU vs size and architecture cards, light/dark themes;
  scripts/build_figures.py regenerates docs/figures/ from a run directory; two executed
  notebooks in notebooks/.
• Search aborts when every candidate of a generation fails (systematic error) instead of
  silently producing a front of failed individuals.
• scripts/release_check.sh (also run in CI): fails on private paths/names, dataset-specific
  wording in the generic code, or Italian residue; all comments, docstrings and CLI texts are
  in English.
• runs/case_study/: the three real search runs converted to the current schema and the four
  finalists transcribed from the original training logs (checkpoints not included).
• mutant train: full training of a searched genotype (FP32 with early stopping →
  temperature/threshold calibration → quantization-aware training with the PyTorch 2 export
  flow (torchao, x86 quantizer) → INT8 conversion → test metrics, CPU latency and weight size);
  artifacts best_fp32.pth, best_qat.pth, int8_model.pt2, history.json, run_summary.json.
• mutant eval: evaluate an FP32 checkpoint and/or an INT8 .pt2 program on a split, with
  calibration on the validation split (--binary-logit {logodds,target} selects how two logits
  are reduced to the calibrated scalar; wrapper prefixes in checkpoints are stripped).
• Calibration on a random subset of at most calib_max_pixels validation pixels (memory-bound).
• label_fn modules can live next to dataset.json.
• Losses for the full training: Dice+Focal (search default), Dice+CE, Focal Tversky.
• Dataset-agnostic data layer: dataset.json specification (DatasetSpec), tiles
  (.npz) and geotiff adapters (label_map / label_fn decoding, class-balanced tile
  filtering, cached tile index, optional padded edge tiles so that every pixel of a scene is
  evaluated once), label-preserving flip/rot90 augmentation, per-channel
  statistics, and the mutant data {check,stats,synth} utilities.
• Any number of classes and a configurable target class (--num-classes, --target-class;
  -1 optimizes the mean IoU); per-class IoU from a global confusion matrix.
• mutant command-line entry point with search, data and sync-mlflow sub-commands.
• src-layout package mutant (core, space, model, search, train, data, cli).
• Continuous integration (lint, unit tests, synthetic end-to-end search, CLI smoke).

Changed

• MUTANT_OUTPUT_DIR applies to every command; runs are seeded globally (seed_everything)
  and per DataLoader worker, so augmentation is reproducible; the GeoTIFF index cache is
  invalidated when directories or scenes change.

Removed

• The inert --w-miou option and the unused scalar fitness.
• Search outputs (runs/, mlflow/) are written under the working directory
  (override with MUTANT_OUTPUT_DIR), never next to the installed package.
• The search space has a single, fully implemented CNN vocabulary; attention tokens and
  frozen-encoder profiles are tracked in docs/ROADMAP.md.

Install: pip install torch (CPU or CUDA wheel) then pip install -e ".[dev]" from a clone; docs in docs/, quick start in the README.