hydra_zen.launch

hydra_zen.launch(config, task_function, overrides=None, multirun=False, version_base=<class 'hydra_zen._launch._NotSet'>, to_dictconfig=False, config_name='zen_launch', job_name='zen_launch', with_log_configuration=True, **override_kwargs)

Launches a Hydra job from a Python function rather than a CLI.

launch is designed to closely match the interface of the standard Hydra CLI. For example, launching a Hydra job from the CLI via:

$ python my_task.py job/group=group_name job.group.param=1

corresponds to the following usage of launch:

>>> job = launch(config, task_function, overrides=["job/group=group_name", "job.group.param=1"])

Parameters:

configDataClass_ | Type[DataClass_] | Mapping[str, Any]

A config that will be passed to task_function.

task_functionCallable[[DictConfig], Any]

The function that Hydra will execute. Its input will be config, which has been modified via the specified overrides

overridesOptional[Union[OverrideMapping, List[str]]] (default: None)

If provided, sets/overrides values in config. See [1] and [2] for a detailed discussion of the “grammar” supported by overrides.

multirunbool (default: False)

Launch a Hydra multi-run ([3]).

version_baseOptional[str], optional (default=not-specified)

Available starting with Hydra 1.2.0. - If the version_base parameter is not specified, Hydra 1.x will use defaults compatible with version 1.1. Also in this case, a warning is issued to indicate an explicit version_base is preferred. - If the version_base parameter is None, then the defaults are chosen for the current minor Hydra version. For example for Hydra 1.2, then would imply config_path=None and hydra.job.chdir=False. - If the version_base parameter is an explicit version string like “1.1”, then the defaults appropriate to that version are used.

to_dictconfigbool (default: False)

If True, convert a dataclasses.dataclass to a omegaconf.DictConfig. Note, this will remove Hydra’s cabability for validation with structured configurations.

config_namestr (default: “zen_launch”)

Name of the stored configuration in Hydra’s ConfigStore API.

job_namestr (default: “zen_launch”)

with_log_configurationbool (default: True)

If True, enables the configuration of the logging subsystem from the loaded config.

**override_kwargsOverrideValues

Keyword arguments to override existing configuration values. Note, this only works when the configuration value name is a valid Python identifier; e.g., this does not support adding (+param) values.

Returns:

resulthydra.core.utils.JobReturn | Any

If multirun is False:

A JobReturn object storing the results of the Hydra experiment via the following attributes

• cfg: Reflects config

• overrides: Reflects overrides

• return_value: The return value of the task function

• hydra_cfg: The Hydra configuration object

• working_dir: The experiment working directory

• task_name: The task name of the Hydra job

• status: A JobStatus enum reporting whether or not the job completed successfully

Else:

Return values of all launched jobs (depends on the Sweeper implementation).

References

[1]

https://hydra.cc/docs/advanced/override_grammar/basic

[2]

https://hydra.cc/docs/configure_hydra/intro

[3]

https://hydra.cc/docs/tutorials/basic/running_your_app/multi-run

Examples

Basic usage

Let’s define and launch a trivial Hydra app.

>>> from hydra_zen import make_config, launch, to_yaml

First, we will define a config, which determines the configurable interface to our “app”. For the purpose of example, we’ll design the “interface” of this config to accept two configurable parameters: a and b.

>>> Conf = make_config("a", "b")

Our task function accepts the config as an input and uses it to run some generic functionality. For simplicity’s sake, let’s design this task function to: convert the job’s config to a yaml-formatted string, print it, and then return the string.

>>> def task_fn(cfg):
...     out = to_yaml(cfg)  # task's input config, converted to yaml-string
...     print(out)
...     return out

Now, let’s use launch to run this task function via Hydra, using particular configured values (or, “overrides”) for a and b.

>>> job_out = launch(Conf, task_fn, a=1, b='foo')
a: 1
b: foo

Let’s inspect job_out to see the ways that it summarizes the results of this job.

>>> job_out.return_value  # the value returned by `task_fn`
'a: 1\nb: foo\n'

>>> job_out.working_dir  # where the job's outputs, logs, and configs are saved
'outputs/2021-10-19/15-27-11'

>>> job_out.cfg  # the particular config used to run our task-function
{'a': 1, 'b': 'foo'}

>>> job_out.overrides  # the overrides that we provides
['a=1', "b='foo'"]

>>> job_out.status  # the job's completion status
<JobStatus.COMPLETED: 1>

Launching a multirun job

We can launch multiple runs of our task-function, using various configured values. Let’s launch a multirun that sweeps over three configurations

>>> (outputs,) = launch(
...     Conf,
...     task_fn,
...     a="1,2,3",
...     b="bar",
...     multirun=True,
... )
[2021-10-19 17:50:07,334][HYDRA] Launching 3 jobs locally
[2021-10-19 17:50:07,334][HYDRA]    #0 : a=1 b='bar'
a: 1
b: bar
[2021-10-19 17:50:07,434][HYDRA]    #1 : a=2 b='bar'
a: 2
b: bar
[2021-10-19 17:50:07,535][HYDRA]    #2 : a=3 b='bar'
a: 3
b: bar

outputs contains three corresponding JobReturns instances.

>>> len(outputs)
3
>>> [j.cfg for j in outputs]
[{'a': 1, 'b': 'bar'}, {'a': 2, 'b': 'bar'}, {'a': 3, 'b': 'bar'}]

Each run’s outputs, logs, and configs are saved to separate working directories

>>> [j.working_dir for j in outputs]
['multirun/2021-10-19/17-50-07\\0',
'multirun/2021-10-19/17-50-07\\1',
'multirun/2021-10-19/17-50-07\\2']

Launching with quoted overrides

Some of the Hydra CLI override syntax cannot be specified as keyword arguments. In such cases we can instead provide a list or a dict with quoted overrides.

>>> job_out = launch(Conf, task_fn, a=1, b="foo", overrides={"+c": 22})
a: 1
b: foo
c: 22
>>> job_out.overrides  # the overrides that we provides
['a=1', 'b=foo', '+c=22']

>>> launch(Conf, task_fn, overrides=["a=1", "b='foo'", "+c=22"])
a: 1
b: foo
c: 22

Using hydra_zen.multirun

Multi-run values can be specified directly, without having to form a quoted multi-run string, by using the hydra_zen.multi_run list to store the values.

>>> import random
>>> from hydra_zen import launch, instantiate, make_config, multirun
>>> values_for_experiment = [random.uniform(0, 1) for i in range(10)]

>>> jobs = launch(
...     make_config(),
...     instantiate,
...     overrides={
...          "+param": multirun(values_for_experiment)
...     },
...     multirun=True
... )

If, instead, you want to configure a list as a single value - not to be iterated over in a multirun - you can instead use hydra_zen.hydra_list.