# gbatch Reference

`gbatch` submits jobs to the scheduler (similar to Slurm `sbatch`).

## Usage

```bash
gbatch [options] <script>
gbatch [options] <command> [args...]
gbatch new <name>
gbatch completion <shell>
```

## Common Options

```bash
# Resources
gbatch --gpus 1 python train.py
gbatch --time 2:00:00 python train.py
gbatch --memory 8G python train.py
gbatch --gpu-memory 20G --shared --gpus 1 python train.py

# Scheduling
gbatch --priority 50 python urgent.py
gbatch --name my-run python train.py
gbatch --project ml-research python train.py

# Environment
gbatch --conda-env myenv python script.py

# Dependencies
gbatch --depends-on <job_id|@|@~N> python next.py
gbatch --depends-on-all 1,2,3 python merge.py     # AND
gbatch --depends-on-any 4,5 python fallback.py    # OR
gbatch --depends-on 123 --no-auto-cancel python next.py

Shorthands: `@` = most recent job, `@~N` = Nth most recent submission.

# Arrays
gbatch --array 1-10 python task.py --i '$GFLOW_ARRAY_TASK_ID'

# Params (cartesian product)
gbatch --param lr=0.001,0.01 --param bs=32,64 python train.py --lr {lr} --batch-size {bs}
gbatch --param-file params.csv --name-template 'run_{id}' python train.py --id {id}
gbatch --max-concurrent 2 --param lr=0.001,0.01 python train.py --lr {lr}

# Preview
gbatch --dry-run --gpus 1 python train.py
```

## Slurm-Compatible Aliases

To ease migration from Slurm `sbatch`, `gbatch` accepts a few common flag aliases:

- `--nice` → `--priority`
- `--job-name` (or `-J`) → `--name`
- `--gres` → `--gpus` (expects an integer GPU count, e.g. `--gres 2`)
- `--dependency` → `--depends-on`
- `--time-limit` / `--timelimit` → `--time`

## Time Format (`--time`)

- `HH:MM:SS` (e.g. `2:30:00`)
- `MM:SS` (e.g. `5:30`)
- `MM` minutes (e.g. `30`)

Note: a single number is **minutes**. Use `0:30` for 30 seconds.

## Memory Format (`--memory`)

- `100` (MB)
- `1024M`
- `2G`

Aliases: `--max-mem`, `--max-memory`.

`--memory` controls host RAM, not GPU VRAM.

## GPU Memory Format (`--gpu-memory`)

- `8192` (MB)
- `16384M`
- `24G`

Aliases: `--max-gpu-mem`, `--max-gpu-memory`.

`--gpu-memory` controls per-GPU VRAM.

## Shared GPU Mode (`--shared`)

- Use `--shared` to allow jobs to share the same GPU with other shared jobs.
- Shared jobs must specify `--gpu-memory`.
- `--shared` never mixes with exclusive jobs on the same GPU.

## Script Directives

When submitting a script, `gbatch` can parse a small subset of options from lines like:

```bash
#!/bin/bash
# GFLOW --gpus=1
# GFLOW --shared
# GFLOW --time=2:00:00
# GFLOW --memory=4G
# GFLOW --gpu-memory=20G
# GFLOW --priority=20
# GFLOW --conda-env=myenv
# GFLOW --depends-on=123
# GFLOW --project=ml-research
```

Notes:

- CLI flags override script directives.
- Script directives support only `--depends-on` (single dependency).

## Project Tracking (`--project`)

- Use `-P/--project <code>` to attach an optional project code to submitted jobs.
- Project values are normalized by trimming surrounding whitespace; blank values are treated as unset.
- Maximum length is 64 characters.
- Project value is immutable after submission.
- CLI `--project` overrides `# GFLOW --project=...` in scripts.
