Skip to content

Job Generation

Template-based SLURM job script generation with parameter sweeps.

Overview

The JobGenerator class generates SLURM job scripts from Jinja2 templates combined with parameter specifications. It supports:

  • Grid-based parameter sweeps
  • Explicit parameter lists
  • Dynamic SLURM argument computation via Python functions
  • Custom job naming patterns

Classes

JobGenerator

JobGenerator

JobGenerator(template_path: Union[str, Path], parameters: Dict[str, Any], slurm_defaults: Optional[Dict[str, Any]] = None, slurm_logic_file: Optional[Union[str, Path]] = None, slurm_logic_function: str = 'get_slurm_args', job_name_pattern: Optional[str] = None, logs_dir: Optional[Union[str, Path]] = None, config: Optional[Config] = None)

Generator for SLURM job scripts from templates and parameters.

The generator combines: - Jinja2 templates for job script structure - Parameter grids or lists for job variations - Optional Python logic for SLURM argument customization - Collection integration for tracking generated jobs

Example

generator = JobGenerator( ... template_path="templates/train.job.j2", ... parameters={"mode": "grid", "values": {"lr": [0.01, 0.1]}}, ... slurm_defaults={"partition": "gpu", "time": "24:00:00"}, ... ) scripts = generator.generate(output_dir="jobs/exp1/job_scripts")

Initialize the job generator.

Parameters:

Name Type Description Default
template_path Union[str, Path]

Path to the Jinja2 template file.

required
parameters Dict[str, Any]

Parameter specification (mode + values).

required
slurm_defaults Optional[Dict[str, Any]]

Default SLURM arguments.

None
slurm_logic_file Optional[Union[str, Path]]

Path to Python file with SLURM args function.

None
slurm_logic_function str

Name of the function in slurm_logic_file.

'get_slurm_args'
job_name_pattern Optional[str]

Jinja2 pattern for job names.

None
logs_dir Optional[Union[str, Path]]

Directory for job output files (used in templates).

None
config Optional[Config]

Configuration object.

None
Source code in src/slurmkit/generate.py
def __init__(
    self,
    template_path: Union[str, Path],
    parameters: Dict[str, Any],
    slurm_defaults: Optional[Dict[str, Any]] = None,
    slurm_logic_file: Optional[Union[str, Path]] = None,
    slurm_logic_function: str = "get_slurm_args",
    job_name_pattern: Optional[str] = None,
    logs_dir: Optional[Union[str, Path]] = None,
    config: Optional[Config] = None,
):
    """
    Initialize the job generator.

    Args:
        template_path: Path to the Jinja2 template file.
        parameters: Parameter specification (mode + values).
        slurm_defaults: Default SLURM arguments.
        slurm_logic_file: Path to Python file with SLURM args function.
        slurm_logic_function: Name of the function in slurm_logic_file.
        job_name_pattern: Jinja2 pattern for job names.
        logs_dir: Directory for job output files (used in templates).
        config: Configuration object.
    """
    if config is None:
        config = get_config()

    self.config = config
    self.template_path = Path(template_path)
    self.parameters = parameters
    self.job_name_pattern = job_name_pattern
    self.logs_dir = Path(logs_dir) if logs_dir else None
    self.slurm_logic_file = Path(slurm_logic_file) if slurm_logic_file else None
    self.slurm_logic_function = slurm_logic_function

    # Parameter parse / filter logic (optional)
    self.param_parse_func = None
    if isinstance(self.parameters, dict):
        parse_spec = self.parameters.get("parse")
        if callable(parse_spec):
            self.param_parse_func = parse_spec
        else:
            parsed_parse = parse_python_file_function_spec(
                parse_spec,
                default_function="parse_params",
                spec_label="Parameter parser",
            )
            if parsed_parse is not None:
                self.param_parse_func = load_param_parse_function(
                    parsed_parse["file"],
                    parsed_parse["function"],
                )

    self.param_filter_func = None
    if isinstance(self.parameters, dict) and self.parameters.get("mode", "grid") == "grid":
        filter_spec = self.parameters.get("filter")
        if callable(filter_spec):
            self.param_filter_func = filter_spec
        else:
            parsed_filter = parse_python_file_function_spec(
                filter_spec,
                default_function="include_params",
                spec_label="Parameter filter",
            )
            if parsed_filter is not None:
                self.param_filter_func = load_param_filter_function(
                    parsed_filter["file"],
                    parsed_filter["function"],
                )

    # SLURM arguments - merge config defaults with job spec defaults
    # Config defaults provide the base, job spec defaults override
    self.slurm_defaults = config.get_slurm_defaults().copy()
    if slurm_defaults:
        self.slurm_defaults.update(slurm_defaults)
    self.slurm_logic_func = None

    if self.slurm_logic_file:
        self.slurm_logic_func = load_slurm_args_function(
            self.slurm_logic_file,
            self.slurm_logic_function,
        )

    # Set up Jinja2 environment
    template_dir = self.template_path.parent
    self._env = Environment(
        loader=FileSystemLoader(str(template_dir)),
        keep_trailing_newline=True,
        trim_blocks=True,    # removes the first newline after a block tag
        lstrip_blocks=True,  # strips leading whitespace from block-tag lines
    )

from_spec classmethod

from_spec(spec_path: Union[str, Path], config: Optional[Config] = None, collection_name: Optional[str] = None, interpolation_context: Optional[Mapping[str, Any]] = None) -> 'JobGenerator'

Create a generator from a job spec file.

Parameters:

Name Type Description Default
spec_path Union[str, Path]

Path to the job spec YAML file.

required
config Optional[Config]

Configuration object.

None
collection_name Optional[str]

Optional collection name used in path interpolation.

None
interpolation_context Optional[Mapping[str, Any]]

Optional explicit interpolation context.

None

Returns:

Type Description
'JobGenerator'

Configured JobGenerator instance.

Source code in src/slurmkit/generate.py
@classmethod
def from_spec(
    cls,
    spec_path: Union[str, Path],
    config: Optional[Config] = None,
    collection_name: Optional[str] = None,
    interpolation_context: Optional[Mapping[str, Any]] = None,
) -> "JobGenerator":
    """
    Create a generator from a job spec file.

    Args:
        spec_path: Path to the job spec YAML file.
        config: Configuration object.
        collection_name: Optional collection name used in path interpolation.
        interpolation_context: Optional explicit interpolation context.

    Returns:
        Configured JobGenerator instance.
    """
    spec_path = Path(spec_path)
    spec = load_job_spec(spec_path)

    # Resolve template/callback paths relative to spec file.
    spec_dir = spec_path.parent

    template_path = spec.get("template", "")
    if not Path(template_path).is_absolute():
        template_path = spec_dir / template_path

    parameters = resolve_parameters_callback_specs(
        spec.get("parameters", {}),
        base_dir=spec_dir,
    )

    slurm_logic_file = None
    slurm_logic_function = "get_slurm_args"
    slurm_args = spec.get("slurm_args", {})

    logic_spec = resolve_python_file_function_spec(
        slurm_args.get("logic"),
        base_dir=spec_dir,
        default_function="get_slurm_args",
        spec_label="SLURM args logic",
    )
    if logic_spec is not None:
        slurm_logic_file = Path(logic_spec["file"])
        slurm_logic_function = logic_spec["function"]

    config = config or get_config()
    context = dict(interpolation_context or {})
    if not context:
        context = build_job_subdir_context(
            spec_data=spec,
            spec_path=spec_path,
            collection_name=collection_name,
            project_root=getattr(config, "project_root", None),
        )
    job_paths = resolve_spec_job_paths(spec, config, interpolation_context=context)

    return cls(
        template_path=template_path,
        parameters=parameters,
        slurm_defaults=slurm_args.get("defaults"),
        slurm_logic_file=slurm_logic_file,
        slurm_logic_function=slurm_logic_function,
        job_name_pattern=spec.get("job_name_pattern"),
        logs_dir=job_paths["logs_dir"],
        config=config,
    )

generate

generate(output_dir: Union[str, Path], collection: Optional[Collection] = None, dry_run: bool = False) -> List[Dict[str, Any]]

Generate job scripts.

Parameters:

Name Type Description Default
output_dir Union[str, Path]

Directory to write generated scripts.

required
collection Optional[Collection]

Collection to add generated jobs to.

None
dry_run bool

If True, don't write files, just return what would be generated.

False

Returns:

Type Description
List[Dict[str, Any]]

List of generated job info dicts with keys:

List[Dict[str, Any]]
  • job_name: Generated job name
List[Dict[str, Any]]
  • script_path: Path to the script file
List[Dict[str, Any]]
  • parameters: Job parameters
List[Dict[str, Any]]
  • slurm_args: Computed SLURM arguments
Source code in src/slurmkit/generate.py
def generate(
    self,
    output_dir: Union[str, Path],
    collection: Optional[Collection] = None,
    dry_run: bool = False,
) -> List[Dict[str, Any]]:
    """
    Generate job scripts.

    Args:
        output_dir: Directory to write generated scripts.
        collection: Collection to add generated jobs to.
        dry_run: If True, don't write files, just return what would be generated.

    Returns:
        List of generated job info dicts with keys:
        - job_name: Generated job name
        - script_path: Path to the script file
        - parameters: Job parameters
        - slurm_args: Computed SLURM arguments
    """
    generated = []
    for item in self.plan(output_dir=output_dir, collection=collection):
        job_info = self.generate_one(
            output_dir=output_dir,
            params=item["parameters"],
            job_name=item["job_name"],
            dry_run=dry_run,
        )

        generated.append(job_info)

        # Dry-run planning must not mutate the target collection.
        if collection is not None and not dry_run:
            collection.add_job(
                job_name=item["job_name"],
                script_path=job_info["script_path"],
                parameters=item["parameters"],
            )

    return generated

Functions

expand_grid

expand_grid(params: Dict[str, List[Any]], filter_func: Optional[Callable[[Dict[str, Any]], bool]] = None) -> Iterator[Dict[str, Any]]

Expand a parameter grid into all combinations.

Takes a dictionary where values are lists and yields all combinations as individual dictionaries.

Parameters:

Name Type Description Default
params Dict[str, List[Any]]

Dictionary mapping parameter names to lists of values.

required
filter_func Optional[Callable[[Dict[str, Any]], bool]]

Optional predicate to include/exclude combinations. If provided, only combinations where filter_func(params) is True are yielded.

None

Yields:

Type Description
Dict[str, Any]

Dictionary for each combination of parameter values.

Example

list(expand_grid({"a": [1, 2], "b": ["x", "y"]})) [{'a': 1, 'b': 'x'}, {'a': 1, 'b': 'y'}, {'a': 2, 'b': 'x'}, {'a': 2, 'b': 'y'}]

Source code in src/slurmkit/generate.py
def expand_grid(
    params: Dict[str, List[Any]],
    filter_func: Optional[Callable[[Dict[str, Any]], bool]] = None,
) -> Iterator[Dict[str, Any]]:
    """
    Expand a parameter grid into all combinations.

    Takes a dictionary where values are lists and yields all
    combinations as individual dictionaries.

    Args:
        params: Dictionary mapping parameter names to lists of values.
        filter_func: Optional predicate to include/exclude combinations.
            If provided, only combinations where filter_func(params) is True
            are yielded.

    Yields:
        Dictionary for each combination of parameter values.

    Example:
        >>> list(expand_grid({"a": [1, 2], "b": ["x", "y"]}))
        [{'a': 1, 'b': 'x'}, {'a': 1, 'b': 'y'}, {'a': 2, 'b': 'x'}, {'a': 2, 'b': 'y'}]
    """
    if not params:
        yield {}
        return

    keys = list(params.keys())
    values = [params[k] if isinstance(params[k], list) else [params[k]] for k in keys]

    for combo in itertools.product(*values):
        combo_dict = dict(zip(keys, combo))
        if filter_func is not None and not filter_func(combo_dict):
            continue
        yield combo_dict

expand_parameters

expand_parameters(spec: Dict[str, Any], filter_func: Optional[Callable[[Dict[str, Any]], bool]] = None, parse_func: Optional[Callable[[Dict[str, Any]], Union[Dict[str, Any], List[Dict[str, Any]]]]] = None) -> List[Dict[str, Any]]

Expand a parameter specification into a list of parameter dicts.

Supports two modes: - "grid": All combinations of parameter values - "list": Explicit list of parameter dictionaries

Parameters:

Name Type Description Default
spec Dict[str, Any]

Parameter specification with "mode" and "values" keys. mode: "grid" or "list" values: For grid mode, dict of param_name -> list of values. For list mode, list of param dicts.

required
filter_func Optional[Callable[[Dict[str, Any]], bool]]

Optional predicate for grid mode to include/exclude combinations.

None
parse_func Optional[Callable[[Dict[str, Any]], Union[Dict[str, Any], List[Dict[str, Any]]]]]

Optional callback to derive effective parameters for each generated job before filtering and rendering. The callback may return a single dict or a list of dicts.

None

Returns:

Type Description
List[Dict[str, Any]]

List of parameter dictionaries.

Example

spec = {"mode": "grid", "values": {"lr": [0.01, 0.1], "bs": [32]}} expand_parameters(spec) [{'lr': 0.01, 'bs': 32}, {'lr': 0.1, 'bs': 32}]

spec = {"mode": "list", "values": [{"lr": 0.01}, {"lr": 0.1}]} expand_parameters(spec) [{'lr': 0.01}, {'lr': 0.1}]

Source code in src/slurmkit/generate.py
def expand_parameters(
    spec: Dict[str, Any],
    filter_func: Optional[Callable[[Dict[str, Any]], bool]] = None,
    parse_func: Optional[Callable[[Dict[str, Any]], Union[Dict[str, Any], List[Dict[str, Any]]]]] = None,
) -> List[Dict[str, Any]]:
    """
    Expand a parameter specification into a list of parameter dicts.

    Supports two modes:
    - "grid": All combinations of parameter values
    - "list": Explicit list of parameter dictionaries

    Args:
        spec: Parameter specification with "mode" and "values" keys.
            mode: "grid" or "list"
            values: For grid mode, dict of param_name -> list of values.
                    For list mode, list of param dicts.
        filter_func: Optional predicate for grid mode to include/exclude
            combinations.
        parse_func: Optional callback to derive effective parameters for each
            generated job before filtering and rendering. The callback may
            return a single dict or a list of dicts.

    Returns:
        List of parameter dictionaries.

    Example:
        >>> spec = {"mode": "grid", "values": {"lr": [0.01, 0.1], "bs": [32]}}
        >>> expand_parameters(spec)
        [{'lr': 0.01, 'bs': 32}, {'lr': 0.1, 'bs': 32}]

        >>> spec = {"mode": "list", "values": [{"lr": 0.01}, {"lr": 0.1}]}
        >>> expand_parameters(spec)
        [{'lr': 0.01}, {'lr': 0.1}]
    """
    mode = spec.get("mode", "grid")
    values = spec.get("values", {})

    if parse_func is None:
        parse_spec = spec.get("parse")
        if callable(parse_spec):
            parse_func = parse_spec
        else:
            parsed_parse = parse_python_file_function_spec(
                parse_spec,
                default_function="parse_params",
                spec_label="Parameter parser",
            )
            if parsed_parse is not None:
                parse_func = load_param_parse_function(
                    parsed_parse["file"],
                    parsed_parse["function"],
                )

    if mode == "list":
        param_list = values if isinstance(values, list) else [values]
        expanded = []
        for params in param_list:
            expanded.extend(normalize_param_parse_output(params, parse_func))
        return expanded

    elif mode == "grid":
        if filter_func is None:
            filter_spec = spec.get("filter")
            if callable(filter_spec):
                filter_func = filter_spec
            else:
                parsed_filter = parse_python_file_function_spec(
                    filter_spec,
                    default_function="include_params",
                    spec_label="Parameter filter",
                )
                if parsed_filter is not None:
                    filter_func = load_param_filter_function(
                        parsed_filter["file"],
                        parsed_filter["function"],
                    )
        expanded = []
        for params in expand_grid(values):
            parsed_params = normalize_param_parse_output(params, parse_func)
            for effective_params in parsed_params:
                if filter_func is not None and not filter_func(effective_params):
                    continue
                expanded.append(effective_params)
        return expanded

    else:
        raise ValueError(f"Unknown parameter mode: {mode}. Use 'grid' or 'list'.")

load_job_spec

load_job_spec(spec_path: Union[str, Path]) -> Dict[str, Any]

Load a job specification from a YAML file.

Parameters:

Name Type Description Default
spec_path Union[str, Path]

Path to the job spec YAML file.

required

Returns:

Type Description
Dict[str, Any]

Parsed job specification dictionary.

Raises:

Type Description
FileNotFoundError

If the file doesn't exist.

Source code in src/slurmkit/generate.py
def load_job_spec(spec_path: Union[str, Path]) -> Dict[str, Any]:
    """
    Load a job specification from a YAML file.

    Args:
        spec_path: Path to the job spec YAML file.

    Returns:
        Parsed job specification dictionary.

    Raises:
        FileNotFoundError: If the file doesn't exist.
    """
    spec_path = Path(spec_path)

    if not spec_path.exists():
        raise FileNotFoundError(f"Job spec not found: {spec_path}")

    with open(spec_path, "r") as f:
        spec = yaml.safe_load(f) or {}

    return spec

generate_job_name

generate_job_name(params: Dict[str, Any], pattern: Optional[str] = None, env: Optional[Environment] = None) -> str

Generate a job name from parameters.

Uses a Jinja2 pattern to format the job name from parameter values.

Parameters:

Name Type Description Default
params Dict[str, Any]

Job parameters.

required
pattern Optional[str]

Jinja2 pattern for job name. If None, uses param values joined by underscores.

None
env Optional[Environment]

Jinja2 environment. If None, creates a new one.

None

Returns:

Type Description
str

Generated job name.

Example

generate_job_name({"model": "resnet", "lr": 0.01}, "{{ model }}_lr{{ lr }}") 'resnet_lr0.01'

Source code in src/slurmkit/generate.py
def generate_job_name(
    params: Dict[str, Any],
    pattern: Optional[str] = None,
    env: Optional[Environment] = None,
) -> str:
    """
    Generate a job name from parameters.

    Uses a Jinja2 pattern to format the job name from parameter values.

    Args:
        params: Job parameters.
        pattern: Jinja2 pattern for job name. If None, uses param values joined by underscores.
        env: Jinja2 environment. If None, creates a new one.

    Returns:
        Generated job name.

    Example:
        >>> generate_job_name({"model": "resnet", "lr": 0.01}, "{{ model }}_lr{{ lr }}")
        'resnet_lr0.01'
    """
    if pattern is None:
        # Default: join param values with underscores
        parts = [f"{k}{v}" for k, v in sorted(params.items())]
        return "_".join(parts)

    if env is None:
        env = Environment()

    template = env.from_string(pattern)
    return template.render(**params)

Usage Example

from slurmkit import JobGenerator

# Create generator from a job spec file
generator = JobGenerator.from_spec("experiments/exp1/job_spec.yaml")

# Generate all job scripts
jobs = generator.generate()

for job in jobs:
    print(f"Generated: {job['script_path']}")
    print(f"  Parameters: {job['params']}")
    print(f"  Job name: {job['job_name']}")

Manual Configuration

from slurmkit.generate import JobGenerator, expand_grid

# Expand parameter grid
params_list = expand_grid({
    "learning_rate": [0.001, 0.01, 0.1],
    "batch_size": [32, 64]
})

# Create generator manually
generator = JobGenerator(
    template_path="templates/train.job.j2",
    output_dir="jobs/exp1/job_scripts",
    parameters=params_list,
    slurm_defaults={"partition": "gpu", "time": "24:00:00"},
    job_name_pattern="lr{{ learning_rate }}_bs{{ batch_size }}"
)

# Generate scripts
jobs = generator.generate()