Launcher

dapi.launcher.generate_sweep(command, sweep, directory=None, *, placeholder_style='token', debug=None, preview=False)[source]

Generate sweep commands and write PyLauncher input files.

When preview is True, returns a DataFrame of all parameter combinations without writing any files — useful for inspecting the sweep in a notebook before committing.

When preview is False (default), expands command into one command per parameter combination and writes runsList.txt and call_pylauncher.py into directory.

Parameters:

  • command (str) – Command template containing placeholders that match keys in sweep. Environment variables like $WORK or $SLURM_JOB_ID are left untouched.

  • sweep (Mapping[str, Sequence[Any]]) – Mapping of placeholder name to a sequence of values. Example: {"ALPHA": [0.3, 0.5], "BETA": [1, 2]}.

  • directory (str | Path | None) – Directory to write files into. Created if it doesn’t exist. Required when preview is False.

  • placeholder_style (str) –

    How placeholders appear in command:

    • "token" (default): bare tokens, e.g. ALPHA

    • "braces": brace-wrapped, e.g. {ALPHA}

  • debug (str | None) – Optional debug string passed to ClassicLauncher (e.g. "host+job"). Ignored when preview is True.

  • preview (bool) – If True, return a DataFrame of parameter combinations without writing files.

Returns:

List[str] of generated commands when preview is False, or a pandas.DataFrame of parameter combinations when True.

Raises:

  • TypeError – If a sweep value is not a non-string sequence.

  • ValueError – If a sweep value is empty, placeholder_style is invalid, or directory is missing when preview is False.

Return type:

List[str] | DataFrame