Skip to content

README: document --priority-range, pairs mode, and docs/ guides #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stackedsax merged 1 commit into from
Jul 18, 2026
Merged

README: document --priority-range, pairs mode, and docs/ guides #28

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
Loading