Initialize a sweep

Initialize a sweep using the Python SDK or CLI to start hyperparameter searches with your sweep configuration.

Initialize a sweep to register your sweep configuration with W&B and return a sweep ID that agents use to fetch run instructions. Initialize a sweep after you define a sweep configuration and before you launch agents, so that you have a sweep ready to coordinate hyperparameter searches across one or more machines.

W&B uses a sweep controller to manage sweeps on the cloud (standard) or locally across one or more machines. After a run completes, the sweep controller issues a new set of instructions describing a new run to execute. Agents pick up these instructions and perform the runs. In a typical sweep, the controller lives on the W&B server. Agents live on your machines.

Before you initialize a sweep, you must have a sweep configuration defined either in a YAML file or a nested Python dictionary object in your script. For more information, see Define sweep configuration.

The following code snippets show how to initialize sweeps with the CLI and within a Jupyter notebook or Python script. Choose the method that matches your workflow.

The sweep and the run must be in the same project. The project name you provide when you initialize W&B (wandb.init()) must match the project name you provide when you initialize a sweep (wandb.sweep()).

Python script or notebook

Use the W&B SDK to initialize a sweep. Pass the sweep configuration dictionary to the sweep parameter. Optionally provide the name of the project for the project parameter (project) where you want W&B to store the output of the run. If you don’t specify the project, W&B puts the run in an “Uncategorized” project.

import wandb

# Example sweep configuration
sweep_configuration = {
    "method": "random",
    "name": "sweep",
    "metric": {"goal": "maximize", "name": "val_acc"},
    "parameters": {
        "batch_size": {"values": [16, 32, 64]},
        "epochs": {"values": [5, 10, 15]},
        "lr": {"max": 0.1, "min": 0.0001},
    },
}

sweep_id = wandb.sweep(sweep=sweep_configuration, project="project-name")

The wandb.sweep() function returns the sweep ID. The sweep ID includes the entity name and the project name. Note the sweep ID, since you pass it to agents when you start them. With the sweep ID, you’re ready to launch one or more agents to execute runs.

CLI

Use the W&B CLI to initialize a sweep. Provide the name of your configuration file. Optionally provide the name of the project for the project flag. If you don’t specify the project, W&B puts the run in an “Uncategorized” project.

Use the wandb sweep command to initialize a sweep. The following code example initializes a sweep for a sweeps_demo project and uses a config.yaml file for the configuration.

wandb sweep --project sweeps_demo config.yaml

This command prints out a sweep ID. The sweep ID includes the entity name and the project name. Note the sweep ID, since you pass it to agents when you start them. With the sweep ID, you’re ready to launch one or more agents to execute runs.