This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Launch Library Reference

1: create_and_run_agent()
2: launch_add()
3: launch()
4: LaunchAgent
5: load_wandb_config()
6: manage_config_file()
7: manage_wandb_config()

A collection of launch APIs for W&B.

1 - create_and_run_agent()

`function` `create_and_run_agent`

create_and_run_agent(
    api: wandb.apis.internal.Api,
    config: Dict[str, Any]
) → None

2 - launch_add()

View the source code

`function` `launch_add`

launch_add(
    uri: Optional[str] = None,
    job: Optional[str] = None,
    config: Optional[Dict[str, Any]] = None,
    template_variables: Optional[Dict[str, Union[float, int, str]]] = None,
    project: Optional[str] = None,
    entity: Optional[str] = None,
    queue_name: Optional[str] = None,
    resource: Optional[str] = None,
    entry_point: Optional[List[str]] = None,
    name: Optional[str] = None,
    version: Optional[str] = None,
    docker_image: Optional[str] = None,
    project_queue: Optional[str] = None,
    resource_args: Optional[Dict[str, Any]] = None,
    run_id: Optional[str] = None,
    build: Optional[bool] = False,
    repository: Optional[str] = None,
    sweep_id: Optional[str] = None,
    author: Optional[str] = None,
    priority: Optional[int] = None
) → public.QueuedRun

Enqueue a W&B launch experiment. With either a source uri, job or docker_image.

Arguments:

uri: URI of experiment to run. A wandb run uri or a Git repository URI.
job: string reference to a wandb.Job eg: wandb/test/my-job:latest
config: A dictionary containing the configuration for the run. May also contain resource specific arguments under the key “resource_args”
template_variables: A dictionary containing values of template variables for a run queue.
Expected format of {“VAR_NAME”: VAR_VALUE}
project: Target project to send launched run to
entity: Target entity to send launched run to
queue: the name of the queue to enqueue the run to
priority: the priority level of the job, where 1 is the highest priority
resource: Execution backend for the run: W&B provides built-in support for “local-container” backend
entry_point: Entry point to run within the project. Defaults to using the entry point used in the original run for wandb URIs, or main.py for git repository URIs.
name: Name run under which to launch the run.
version: For Git-based projects, either a commit hash or a branch name.
docker_image: The name of the docker image to use for the run.
resource_args: Resource related arguments for launching runs onto a remote backend. Will be stored on the constructed launch config under resource_args.
run_id: optional string indicating the id of the launched run
build: optional flag defaulting to false, requires queue to be set if build, an image is created, creates a job artifact, pushes a reference to that job artifact to queue
repository: optional string to control the name of the remote repository, used when pushing images to a registry
project_queue: optional string to control the name of the project for the queue. Primarily used for back compatibility with project scoped queues

Example:

from wandb.sdk.launch import launch_add

project_uri = "https://github.com/wandb/examples"
params = {"alpha": 0.5, "l1_ratio": 0.01}
# Run W&B project and create a reproducible docker environment
# on a local host
api = wandb.apis.internal.Api()
launch_add(uri=project_uri, parameters=params)

Returns: an instance ofwandb.api.public.QueuedRun which gives information about the queued run, or if wait_until_started or wait_until_finished are called, gives access to the underlying Run information.

Raises: wandb.exceptions.LaunchError if unsuccessful

3 - launch()

View the source code

`function` `launch`

launch(
    api: wandb.apis.internal.Api,
    job: Optional[str] = None,
    entry_point: Optional[List[str]] = None,
    version: Optional[str] = None,
    name: Optional[str] = None,
    resource: Optional[str] = None,
    resource_args: Optional[Dict[str, Any]] = None,
    project: Optional[str] = None,
    entity: Optional[str] = None,
    docker_image: Optional[str] = None,
    config: Optional[Dict[str, Any]] = None,
    synchronous: Optional[bool] = True,
    run_id: Optional[str] = None,
    repository: Optional[str] = None
) → AbstractRun

Launch a W&B launch experiment.

Arguments:

job: string reference to a wandb.Job eg: wandb/test/my-job:latest
api: An instance of a wandb Api from wandb.apis.internal.
entry_point: Entry point to run within the project. Defaults to using the entry point used in the original run for wandb URIs, or main.py for git repository URIs.
version: For Git-based projects, either a commit hash or a branch name.
name: Name run under which to launch the run.
resource: Execution backend for the run.
resource_args: Resource related arguments for launching runs onto a remote backend. Will be stored on the constructed launch config under resource_args.
project: Target project to send launched run to
entity: Target entity to send launched run to
config: A dictionary containing the configuration for the run. May also contain resource specific arguments under the key “resource_args”.
synchronous: Whether to block while waiting for a run to complete. Defaults to True. Note that if synchronous is False and backend is “local-container”, this method will return, but the current process will block when exiting until the local run completes. If the current process is interrupted, any asynchronous runs launched via this method will be terminated. If synchronous is True and the run fails, the current process will error out as well.
run_id: ID for the run (To ultimately replace the :name: field)
repository: string name of repository path for remote registry

Example:

   from wandb.sdk.launch import launch

   job = "wandb/jobs/Hello World:latest"
   params = {"epochs": 5}
   # Run W&B project and create a reproducible docker environment
   # on a local host
   api = wandb.apis.internal.Api()
   launch(api, job, parameters=params)
   ``` 





**Returns:**
an instance of`wandb.launch.SubmittedRun` exposing information (e.g. run ID) about the launched run. 



**Raises:**
`wandb.exceptions.ExecutionError` If a run launched in blocking mode is unsuccessful.

4 - LaunchAgent

View the source code

`class` `LaunchAgent`

Launch agent class which polls run given run queues and launches runs for wandb launch.

`method` `LaunchAgent.init`

__init__(api: wandb.apis.internal.Api, config: Dict[str, Any])

Initialize a launch agent.

Arguments:

api: Api object to use for making requests to the backend.
config: Config dictionary for the agent.

`property` LaunchAgent.num_running_jobs

Return the number of jobs not including schedulers.

`property` LaunchAgent.num_running_schedulers

Return just the number of schedulers.

`property` LaunchAgent.thread_ids

Returns a list of keys running thread ids for the agent.

`method` `LaunchAgent.check_sweep_state`

check_sweep_state(
    launch_spec: Dict[str, Any],
    api: wandb.apis.internal.Api
) → None

Check the state of a sweep before launching a run for the sweep.

`method` `LaunchAgent.fail_run_queue_item`

fail_run_queue_item(
    run_queue_item_id: str,
    message: str,
    phase: str,
    files: Optional[List[str]] = None
) → None

`method` `LaunchAgent.finish_thread_id`

finish_thread_id(
    thread_id: int,
    exception: Optional[Exception, wandb.sdk.launch.errors.LaunchDockerError] = None
) → None

Removes the job from our list for now.

`method` `LaunchAgent.get_job_and_queue`

get_job_and_queue() → Optional[wandb.sdk.launch.agent.agent.JobSpecAndQueue]

`classmethod` `LaunchAgent.initialized`

initialized() → bool

Return whether the agent is initialized.

`method` `LaunchAgent.loop`

loop() → None

Loop infinitely to poll for jobs and run them.

Raises:

KeyboardInterrupt: if the agent is requested to stop.

`classmethod` `LaunchAgent.name`

name() → str

Return the name of the agent.

`method` `LaunchAgent.pop_from_queue`

pop_from_queue(queue: str) → Any

Pops an item off the runqueue to run as a job.

Arguments:

queue: Queue to pop from.

Returns: Item popped off the queue.

Raises:

Exception: if there is an error popping from the queue.

`method` `LaunchAgent.print_status`

print_status() → None

Prints the current status of the agent.

`method` `LaunchAgent.run_job`

run_job(
    job: Dict[str, Any],
    queue: str,
    file_saver: wandb.sdk.launch.agent.run_queue_item_file_saver.RunQueueItemFileSaver
) → None

Set up project and run the job.

Arguments:

job: Job to run.

`method` `LaunchAgent.task_run_job`

task_run_job(
    launch_spec: Dict[str, Any],
    job: Dict[str, Any],
    default_config: Dict[str, Any],
    api: wandb.apis.internal.Api,
    job_tracker: wandb.sdk.launch.agent.job_status_tracker.JobAndRunStatusTracker
) → None

`method` `LaunchAgent.update_status`

update_status(status: str) → None

Update the status of the agent.

Arguments:

status: Status to update the agent to.

5 - load_wandb_config()

View the source code

`function` `load_wandb_config`

load_wandb_config() → Config

Load wandb config from WANDB_CONFIG environment variable(s).

The WANDB_CONFIG environment variable is a json string that can contain multiple config keys. The WANDB_CONFIG_[0-9]+ environment variables are used for environments where there is a limit on the length of environment variables. In that case, we shard the contents of WANDB_CONFIG into multiple environment variables numbered from 0.

Returns: A dictionary of wandb config values.

6 - manage_config_file()

View the source code

`function` `manage_config_file`

manage_config_file(
    path: str,
    include: Optional[List[str]] = None,
    exclude: Optional[List[str]] = None,
    schema: Optional[Any] = None
)

Declare an overridable configuration file for a launch job.

If a new job version is created from the active run, the configuration file will be added to the job’s inputs. If the job is launched and overrides have been provided for the configuration file, this function will detect the overrides from the environment and update the configuration file on disk. Note that these overrides will only be applied in ephemeral containers. include and exclude are lists of dot separated paths with the config. The paths are used to filter subtrees of the configuration file out of the job’s inputs.

For example, given the following configuration file: yaml model: name: resnet layers: 18 training: epochs: 10 batch_size: 32

Passing include=['model'] will only include the model subtree in the job’s inputs. Passing exclude=['model.layers'] will exclude the layers key from the model subtree. Note that exclude takes precedence over include.

. is used as a separator for nested keys. If a key contains a ., it should be escaped with a backslash, e.g. include=[r'model\.layers']. Note the use of r to denote a raw string when using escape chars.

Args:

path (str): The path to the configuration file. This path must be relative and must not contain backwards traversal, i.e. ...
include (List[str]): A list of keys to include in the configuration file.
exclude (List[str]): A list of keys to exclude from the configuration file.
schema (dict | Pydantic model): A JSON Schema or Pydantic model describing describing which attributes will be editable from the Launch drawer. Accepts both an instance of a Pydantic BaseModel class or the BaseModel class itself.

Raises:

LaunchError: If the path is not valid, or if there is no active run.

7 - manage_wandb_config()

View the source code

`function` `manage_wandb_config`

manage_wandb_config(
    include: Optional[List[str]] = None,
    exclude: Optional[List[str]] = None,
    schema: Optional[Any] = None
)

Declare wandb.config as an overridable configuration for a launch job.

If a new job version is created from the active run, the run config (wandb.config) will become an overridable input of the job. If the job is launched and overrides have been provided for the run config, the overrides will be applied to the run config when wandb.init is called. include and exclude are lists of dot separated paths with the config. The paths are used to filter subtrees of the configuration file out of the job’s inputs.

For example, given the following run config contents: yaml model: name: resnet layers: 18 training: epochs: 10 batch_size: 32 Passing include=['model'] will only include the model subtree in the job’s inputs. Passing exclude=['model.layers'] will exclude the layers key from the model subtree. Note that exclude takes precedence over include. . is used as a separator for nested keys. If a key contains a ., it should be escaped with a backslash, e.g. include=[r'model\.layers']. Note the use of r to denote a raw string when using escape chars.

Args:

include (List[str]): A list of subtrees to include in the configuration.
exclude (List[str]): A list of subtrees to exclude from the configuration.
schema (dict | Pydantic model): A JSON Schema or Pydantic model describing describing which attributes will be editable from the Launch drawer. Accepts both an instance of a Pydantic BaseModel class or the BaseModel class itself.

Raises:

LaunchError: If there is no active run.

Launch Library Reference

1 - create_and_run_agent()

function create_and_run_agent

2 - launch_add()

function launch_add

3 - launch()

function launch

4 - LaunchAgent

class LaunchAgent

method LaunchAgent.__init__

property LaunchAgent.num_running_jobs

property LaunchAgent.num_running_schedulers

property LaunchAgent.thread_ids

method LaunchAgent.check_sweep_state

method LaunchAgent.fail_run_queue_item

method LaunchAgent.finish_thread_id

method LaunchAgent.get_job_and_queue

classmethod LaunchAgent.initialized

method LaunchAgent.loop

classmethod LaunchAgent.name

method LaunchAgent.pop_from_queue

method LaunchAgent.print_status

method LaunchAgent.run_job

method LaunchAgent.task_run_job

method LaunchAgent.update_status

5 - load_wandb_config()

function load_wandb_config

6 - manage_config_file()

function manage_config_file

7 - manage_wandb_config()

function manage_wandb_config

`function` `create_and_run_agent`

`function` `launch_add`

`function` `launch`

`class` `LaunchAgent`

`method` `LaunchAgent.init`

`property` LaunchAgent.num_running_jobs

`property` LaunchAgent.num_running_schedulers

`property` LaunchAgent.thread_ids

`method` `LaunchAgent.check_sweep_state`

`method` `LaunchAgent.fail_run_queue_item`

`method` `LaunchAgent.finish_thread_id`

`method` `LaunchAgent.get_job_and_queue`

`classmethod` `LaunchAgent.initialized`

`method` `LaunchAgent.loop`

`classmethod` `LaunchAgent.name`

`method` `LaunchAgent.pop_from_queue`

`method` `LaunchAgent.print_status`

`method` `LaunchAgent.run_job`

`method` `LaunchAgent.task_run_job`

`method` `LaunchAgent.update_status`

`function` `load_wandb_config`

`function` `manage_config_file`

`function` `manage_wandb_config`