From cea295c99906714c64b84ccfca8261c750e07bd4 Mon Sep 17 00:00:00 2001 From: stackedsax Date: Sat, 18 Jul 2026 14:36:00 -0700 Subject: [PATCH] README: document --priority-range, pairs mode, and the docs/ guides Stitches the recently-added functionality into the README now that the feature PRs have landed: the --priority-range flag and the priority-normalization rationale, the corpus 'pairs' scraper mode, and cross-links to the new docs/gotchas.md and docs/translation-rules.md guides. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_016PnTz6Zxqa4jHocK8kCbyx --- README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f947dfd..d82da93 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,15 @@ of potential translation loss): bammm convert --from slurm --to splat --input-dir corpus/slurm --output-dir out/ --report ``` +Priority is normalized onto a canonical 0–1000 band (higher = higher priority) +so it survives conversion between schedulers that disagree on range and +direction. Widen the band with `--priority-range MIN:MAX` (e.g. `0:100000`) to +reduce rounding loss when round-tripping schedulers with large native ranges: + +```sh +bammm convert --from pbs --to slurm --priority-range 0:100000 job.pbs +``` + ### Validating specs `bammm validate` checks that specs parse (and, with `--to`, convert) without @@ -178,7 +187,11 @@ BAMMM tells you upfront when a conversion is lossy. Some things genuinely cannot - **Slurm het-jobs** — only Slurm can execute them natively; approximated as multi-task elsewhere. - **Run.ai GPU fractions** — virtual GPU partitioning rounds to whole GPUs on every other scheduler. -The full list is in [SPEC.md § Known Lossy Translations](SPEC.md#known-lossy-translations) and [conversions/README.md](conversions/README.md). +The full list is in [SPEC.md § Known Lossy Translations](SPEC.md#known-lossy-translations) and [conversions/README.md](conversions/README.md). The sharp edges that bite people — the camelCase field rule, priority direction, `extensions.*` passthrough — are collected in [docs/gotchas.md](docs/gotchas.md). + +Need a translation BAMMM doesn't do out of the box? A user-defined +[declarative rules file](docs/translation-rules.md) is designed (not yet built) +to let you adjust mappings without patching source. ## Development @@ -214,8 +227,13 @@ scraper is config-driven — one entry per scheduler — and runs under `uv`: export GITHUB_TOKEN=ghp_... uv run scripts/corpus/fetch_corpus.py --list # supported schedulers make corpus SCHED=slurm # scrape a corpus +make corpus SCHED=pairs # hunt repos with ≥2 formats ``` +The `pairs` mode is different: instead of scraping one scheduler by file, it +finds repos that contain specs for two or more schedulers side by side — +candidate cross-scheduler *equivalent* pairs for conversion ground truth. + See [CLAUDE.md](CLAUDE.md) for architecture decisions, the build plan, and notes for contributors. ## Collaboration