After many months and a lot of hard work by many people, Hydra 1.2 is released! Hydra 1.2 comes with OmegaConf 2.2, which has its own share of improvements.

This blog post highlights some of the most prominent features, check the release notes for a complete list of changes:

• Hydra 1.2 release notes
• OmegaConf 2.2 release notes

Major new features in Hydra 1.2​

• Easier integration with existing systems
  • Support not changing working directory at runtime
  • Default to not implicitly adding directories to the config path
• Improved support for reproducible experiments
  • Support defining multirun mode and sweeping parameters through config
  • Improved callback support for logging / persisting job runs
  • A new --experimental-rerun option to reproduce persisted single runs
• Improved instantiate API functionality
  • Support for instances partially defined from config, via a _partial_ keyword
  • Accept ListConfig/list-type config as top-level input
• Better alignment with ecosystem versions
  • Support for Python 3.10, and ANTLR 4.9
• OmegaConf 2.2:
  • More flexible type hints in structured configs
  • Native support for bytes and pathlib.Path

Object instantiation enhancements​

• Lists can now be passed directly to the instantiate API. For example one can now do:

from hydra.utils import instantiate

lst = [
    {"_target_": "pathlib.Path", "_args_": ["foo"]},
    {"_target_": "pathlib.Path", "_args_": ["bar"]},
]

paths = instantiate(lst)
print(paths)

Resulting in:

$ python demo.py
[PosixPath('foo'), PosixPath('bar')]

• Instances can now be partially defined in config with the _partial_ keyword. Please see the Instantiate API - Partial Instantiation docs for a detailed example.

OmegaConf 2.2 highlights​

More flexible type hints in structured configs​

OmegaConf 2.2's structured configs support runtime type checking for an expanded set of type hints. It is now possible to use nested container types (e.g. dict-of-dict or list-of-list), unions of primitive types, and containers with optional element types.

Here is an example demonstrating these new capabilities:

from dataclasses import dataclass
from typing import Dict, List, Optional, Union
from omegaconf import OmegaConf

@dataclass
class DemoConfig:
    union: Union[int, str, bool]
    dict_of_union: Dict[str, Union[int, str]]
    list_of_dict: List[Dict[int, float]]
    dict_of_optional: Dict[str, Optional[int]]

cfg = OmegaConf.structured({"foo": DemoConfig})
cfg.foo.dict_of_union = {"abc": 123}  # ok
cfg.foo.dict_of_union = {"abc": 10.1}  # raises ValidationError!
# Value '10.1' of type 'float' is incompatible with type hint 'Union[int, str]'

Native support for bytes and pathlib.Path​

OmegaConf now supports binary data via Python's bytes type.

cfg = OmegaConf.create({b"binary_key": b"binary_value"})

In addition, OmegaConf now supports pathlib.Path instances as config values, easing workflows that involve the file system.

from pathlib import Path
cfg.my_homedir = Path.home()
assert cfg.my_homedir.is_dir()

The bytes and pathlib.Path types can be used as type hints in structured config class definitions, and configs containing binary and Path data can be round-tripped to/from yaml files via OmegaConf's save/load/to_yaml/create methods.

yaml_data = OmegaConf.to_yaml(cfg)
cfg2 = OmegaConf.create(yaml_data)
assert cfg2[b"binary_key"] == b"binary_value"
assert isinstance(cfg2.my_homedir, Path)

Migrating from 1.1​

Hydra 1.2 is a major release. For most people, migrating from 1.1 to 1.2 will be smooth. In addition, for this release we introduce support for more compatible upgrades through the version_base mechanism. New users are encouraged to use the latest defaults by setting version_base=None with @hydra.main() and hydra.initialize(), while existing users have more control over what potentially incompatible changes are introduced when upgrading to Hydra 1.2. Please see the "Behavior changes" section of the Hydra 1.2 release notes for details. OmegaConf 2.2 also has some API changes and deprecations (not protected by version_base), detailed in its release notes. Please feel free to reach out for help if you see a change in behavior that is not mentioned in the release notes.

That's it for now, take Hydra 1.2 for a spin!

After many months and a lot of hard work by many people, Hydra 1.1 is finally out!
Hydra 1.1 comes with OmegaConf 2.1, which has its own share of awesome new features.

This blog post highlights some of the most prominent features, check the release notes for a complete list of changes:

• Hydra 1.1 release notes
• OmegaConf 2.1 release notes

Major new features in Hydra 1.1​

• More powerful config composition
  • Every config can now have a Defaults List
  • Composition order of current config can be controlled via the _self_ keyword in the Defaults List
  • Support for composing multiple configs from the same config group
  • Support for configuring the config search path from the primary config
• Recursive instantiation
• Experimental callbacks support
• OmegaConf 2.1:
  • Relative interpolations
  • New OmegaConf interpolation grammar supporting nested interpolations and much more
  • More powerful custom resolvers

More powerful config composition​

Config composition is the key area of improvement in Hydra 1.1.
The biggest change is support for a Defaults List in any config, and not just the primary config.

This enables many new capabilities:

• Any config can now "extend" other configs. This enables config files to be associated with a Structured Config schema and to extend other config files
• A top level "experiment config" can now override the Defaults List as well as config values
• Complex frameworks can now have their own Defaults List, reducing boilerplate

Other related changes include the ability to change the order a config is composed relative to config in its Defaults List by adding _self_ to the Defaults List and the ability to use multiple configs from the same config group.

Learn more:

• The Defaults List
• Extending configs
• Structured Configs Schema
• Configuring Experiments
• Select multiple configs from config group

Object instantiation enhancements​

hydra.utils.instantiate() now instantiates nested objects recursively.

Other enhancements include:

• Support for positional arguments via the _args_ config key
• Support for parameter conversion strategy was added via the _convert_ config key

Learn more here.

Hydra callbacks​

A new experimental mechanism for user defined callbacks was added. Callbacks enable user code to be executed automatically at various points in the lifecycle of your application. There are many potential use cases for this, for example automatic registration with your favorite experiment-tracking service.

Learn more here.

OmegaConf 2.1 highlights​

OmegaConf 2.1 includes many enhancements, bug fixes, and performance improvements.

Relative interpolations​

Relative interpolations enable accessing a config node relative to the node defining the interpolation:

x: 10
b:
  y: 20
  a: {x}    # 10, absolute interpolation
  b: ${.y}  # 20, relative interpolation
  c: ${..x} # 10, relative interpolation

Nested interpolations​

OmegaConf 2.1 adds a new interpolation grammar supporting more sophisticated usage of interpolations.
In the following example, the default value to use if the environment variable DB_USER does not exist is defined in the default_user config node:

default_user: root
db_user: ${oc.env:DB_USER,${default_user}}

More powerful custom resolvers​

OmegaConf custom resolvers can now access parent config node or the config root by defining keyword parameters named _parent_ and _root_.

In the example below, we use _parent_ to implement a sum function that defaults to 0 if the node does not exist:

def sum(a, b, *, _parent_):
  return _parent_.get(a, 0) + _parent_.get(b, 0)

OmegaConf.register_new_resolver("sum", sum)
cfg = OmegaConf.create({
  "node": {
    "a": 1,
    "b": 2,
    "a_plus_b": "${sum:a,b}",
    "a_plus_z": "${sum:a,z}",
  },
})
print(cfg.node.a_plus_b)  # 3
print(cfg.node.a_plus_z)  # 1

Other notable improvements​

• Config composition, especially for large configs - is significantly faster.
• OmegaConf.resolve(cfg) can be used for in-place interpolation resolution on a config object
• Improved compatibility of OmegaConf config objects with plain dict and list
• Support for bracketed style (foo.bar is equivalent to foo[bar]), this covers interpolations and OmegaConf.{update, select} usage
• PyDev.Debugger integration for easier debugging of config objects in PyCharm and VSCode

Migrating from 1.0​

Hydra 1.1 is a major release. For most people, migrating from 1.0 to 1.1 will be smooth. However, there are some breaking changes listed in the release notes of OmegaConf 2.1 and Hydra 1.1. Most changes come with a deprecation warning pointing to a specific migration guide page. Please feel free to reach out for help if you see a change in behavior that is not mentioned in the release notes.

That's it for now, take Hydra 1.1 for a spin!

Ray is a simple yet powerful Python library for parallel and distributed programming. Among the many features it provides, Ray comes with a cluster launcher that can be used to provision resources and start a Ray cluster on top of them. Hydra Ray Launcher is built on top of the Ray Tasks API and the Ray cluster launcher.

Launching to a new or existing AWS cluster​

Hydra Ray Launcher simplifies your experience by allowing the Ray cluster setup to be configured transparently by Hydra (eliminating the need for an external YAML file while maintaining the flexibility). Hydra Ray Launcher comes with reasonable default configurations which can be found here (under the heading, “Discover ray_aws launcher's config”). You can override them in your application config or from the command line to fit your use case. The following Ray Launcher example code (e.g., my_app.py) is runnable and can be found here.

Launch your Hydra application to AWS by simply overriding: hydra/launcher=ray_aws:

$ python my_app.py hydra/launcher=ray_aws task=1,2 --multirun
[HYDRA] Ray Launcher is launching 2 jobs, 
[HYDRA]        #0 : task=1
[HYDRA]        #1 : task=2
...
[HYDRA] Running command: ['ray', 'up', '-y', '/var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmp20qvoy15.yaml']
[HYDRA] Output: INFO services.py:1090 -- View the Ray dashboard at http://127.0.0.1:8265
(pid=3823)[__main__][INFO] - Executing task 1
(pid=3822)[__main__][INFO] - Executing task 2
[HYDRA] Stopping cluster now. (stop_cluster=true)
[HYDRA] Deleted the cluster (provider.cache_stopped_nodes=false)
[HYDRA] Running command: ['ray', 'down', '-y', '/var/folders/n_/9qzct77j68j6n9lh0lw3vjqcn96zxl/T/tmpfm2ems9v.yaml']

Launching to a new local Ray Cluster​

If you want to do a quick local test, you can spin up a local Ray cluster at application run time by specifying hydra/launcher=ray. In this example, we create a new Ray cluster at application time.

$ python my_app.py  --multirun hydra/launcher=ray 
[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-12-17/16-11-28
[HYDRA] Initializing ray with config: {'address': None}
2020-12-17 16:11:29,340 INFO services.py:1090 -- View the Ray dashboard at http://127.0.0.1:8265
[HYDRA]        #0 : 
(pid=62642) [__main__][INFO] - Executing task 1

Launching to an existing local Ray Cluster​

You can launch the application on an existing local Ray cluster by configuring the cluster address and overriding hydra/launcher=ray. In the following example we configure the Ray cluster address to local ray cluster and Hydra Ray Launcher was able to connect to the existing Ray cluster and execute the application code:

$ python my_app.py  --multirun hydra/launcher=ray hydra.launcher.ray.init.address=localhost:6379
[HYDRA] Ray Launcher is launching 1 jobs, sweep output dir: multirun/2020-11-10/15-13-32
[HYDRA] Initializing ray with config: {'num_cpus': None, 'num_gpus': None, 'address': 'localhost:6379'}
INFO worker.py:633 -- Connecting to existing Ray cluster at address: 10.30.99.17:6379
[HYDRA]        #0 :
(pid=93358) [__main__][INFO] - Executing task 1

Hydra Ray Launcher is built on top of Hydra 1.0 and you have access to all of the benefits Hydra brings:

Parameter sweeps and optimization​

Hyperparameter sweeps are common in machine learning research. Hydra has built-in grid search and provides several Sweeper plugins for hyperparameter optimization. Sweepers can be used together with Launchers for sweeping on different computing platforms. Start from our documentation here to find more.

Config type safety​

Modern Hydra applications and Hydra Plugins leverage Structured Configs for config validation, and Hydra Ray Launcher is no exception. In the following example, we try to override the Ray cluster’s autoscaling mode with an illegal value:

$ python my_app.py --multirun hydra.launcher.ray.cluster.autoscaling_mode=foo
Error merging override hydra.launcher.ray.cluster.autoscaling_mode=foo
Invalid value 'foo', expected one of [default, aggressive]
        full_key: hydra.launcher.ray.cluster.autoscaling_mode
        reference_type=RayClusterConf
        object_type=RayClusterConf

Set the environment variable HYDRA_FULL_ERROR=1 for a complete stack trace.

That’s it for now! Please try out the new Hydra Ray Launcher and let us know what you think. We are always happy to connect with you via GitHub or the Hydra Chat.

After many months and a lot of hard work by many people, Hydra 1.0 is finally out! Despite some very big changes, this is still the Hydra you love - only bigger, stronger and with more heads.

Major new features in Hydra 1.0​

• Config type safety via Structured Configs
• More powerful command line
• New plugins enabling remote launching and hyper parameter optimization
• Improved error reporting
• Reduce nesting levels with config packages

Config type safety via Structured Configs​

Structured Configs is a powerful new feature that enables strongly typed configs that can be validated both statically and at runtime. With Structured Configs, you use Python dataclasses to describe your configuration structure and types. They can be used as an alternative to YAML files, or as a way to validate YAML files automatically.

@dataclass
class MySQLConfig:
    host: str = "localhost"
    port: int = 3306

cs = ConfigStore.instance()
cs.store(name="config", node=MySQLConfig)

@hydra.main(config_name="config")
def my_app(cfg: MySQLConfig) -> None:
    if cfg.pork == 80: # pork should be port!
        print("Is this a webserver?!")

my_app.py:22: error: "MySQLConfig" has no attribute "pork"
Found 1 error in 1 file (checked 1 source file)

$ python my_app.py port=fail
Error merging override port=fail
Value 'fail' could not be converted to Integer
        full_key: port
        reference_type=Optional[MySQLConfig]
        object_type=MySQLConfig

Learn more at the Structured Configs tutorial.

More powerful command line​

Hydra 1.0 introduces a new command line with many new capabilities, such as:

• Override, Add or Delete config values or Default list choices
• Cast values to coerce their type
• Specify dictionaries and lists as values

Override as usual

Prefix with + to add a new field to
the config

Prefix with ~ to delete a field from
the config

Cast values to coerce their type.

Support for dictionaries and lists

$ python my_app.py db.user=root
db:
  user: root
  pass: secret

$ python my_app.py +db.timeout=10
db:
  user: omry
  pass: secret
  timeout: 10

$ python my_app.py '~db.pass'
db:
  user: omry

$ python my_app.py 'db.pass=str(42)'
db:
  user: omry
  pass: '42'

$ python my_app.py \
  '+db.params={a:10,b:20}'
db:
  user: omry
  pass: secret
  params:
    a: 10
    b: 20

Learn more at the Basic Override syntax page.

Sweeper improvements​

Advanced command line capabilities are making Hydra's Basic Sweeper more powerful.

• Specify numeric ranges via the command line
• Use glob to select multiple config group options without specifying them explicitly
• Control sweeping order with sort and shuffle

Use glob to easily select
multiple config group options

Use range to specify a range of
numbers

You can sort sweep to run order

You can also shuffle sweeps to run
in random order

$ python my_app.py -m 'db=glob(*)'
# Will sweep over all db options

$ python my_app.py --multirun \
  '+number=range(1,4)'
# number will take the values
# 1,2 and 3

$ python my_app.py --multirun \
  '+num=sort(3,1,2)'
# Sweep over num in order

$ python my_app.py --multirun \
  '+num=sort(3,1,2,reverse=true)'
# Sweep over num in reverse order

$ python my_app.py --multirun \
  '+num=shuffle(3,1,2)'
# Sweep over num in random order

Learn more at the Extended Override grammar page.

New plugins​

Launchers​

One of the early promises of Hydra was that it will enable you to easily launch your application to different clusters. Hydra 1.0 adds a few Launchers plugins that starts to make good on that promise.

• The Submitit Launcher can launch applications to SLURM cluster using Submitit.
• The Redis Queue launcher can launch applications to Redis Queue server.
• The Joblib Launcher can launch your application with joblib, enabling parallel local execution.

Sweepers​

Two new Sweeper plugins enables you to automatically find optimal parameters without changing a line of code.

• The Ax Sweeper brings the power of Ax to your Hydra app
• The Nevergrad Sweeper brings the power of Nevergrad to your Hydra app

Note that both Sweepers are still in beta and some changes are expected soon. Your feedback can help shape them.

Tab completion​

In addition to Bash, Hydra now supports Fish shell Tab Completion.

Compose API improvements​

The experimental Compose API is maturing. It is now possible to initialize Hydra in one of 3 ways:

• initialize(): Initialize with a config path relative to the caller
• initialize_config_module() : Initialize with config_module (absolute)
• initialize_config_dir() : Initialize with a config_dir on the file system (absolute)

All initialization methods can be used to initialize Hydra globally or in a context. Making the Compose API ideal for Unit tests and Jupyter notebooks.

Learn more at the Compose API page.

Improved error reporting​

Reported errors will have un-interesting stack frames removed by default. You can enable the complete stack trace with the environment variable HYDRA_FULL_ERROR=1.

@hydra.main()
def my_app(cfg: DictConfig) -> None:
    1 / 0 # hmmm, seems fishy

if __name__ == "__main__":
    my_app()

$ python my_app.py
Traceback (most recent call last):
  File "my_app.py", line 9, in my_app
    1 / 0
ZeroDivisionError: division by zero

Set the environment variable HYDRA_FULL_ERROR=1 for a complete stack trace.

$ HYDRA_FULL_ERROR=1 python my_app.py
Traceback (most recent call last):
  File "my_app.py", line 13, in <module>
    my_app()
  File "/home/omry/dev/hydra/hydra/main.py", line 32, in decorated_main
    _run_hydra(
  File "/home/omry/dev/hydra/hydra/_internal/utils.py", line 355, in _run_hydra
    run_and_report(
  File "/home/omry/dev/hydra/hydra/_internal/utils.py", line 210, in run_and_report
    raise ex
  File "/home/omry/dev/hydra/hydra/_internal/utils.py", line 207, in run_and_report
    return func()
  File "/home/omry/dev/hydra/hydra/_internal/utils.py", line 356, in <lambda>
    lambda: hydra.run(
  File "/home/omry/dev/hydra/hydra/_internal/hydra.py", line 107, in run
    return run_job(
  File "/home/omry/dev/hydra/hydra/core/utils.py", line 125, in run_job
    ret.return_value = task_function(task_cfg)
  File "my_app.py", line 9, in my_app
    1 / 0
ZeroDivisionError: division by zero

Reduce nesting levels with config packages​

Hydra 1.0 introduces the ability to specify the root config package in the config file. Specifying the root config package help reducing nesting levels in config files. Config packages can be overridden via the Defaults List or the command line, allowing the reuse of the the same config in multiple place in the resulting output without having to duplicate it.

db:
  host: localhost
  port: 3306

# @package _group_
host: localhost
port: 3306

defaults:
- db@db.src: mysql
- db@db.dst: mysql

db:
  src:
    host: localhost
    port: 3306
  dst:
    host: localhost
    port: 3306

Learn more at the Overriding packages page.

Misc improvements​

• The params field is eliminated from instantiated objects configs (details)
• Support for setting environment variables via the config. (hydra.job.env_set) (details)
• Hydra's config can now be accessed through interpolation using ${hydra:key}, for example ${hydra:job.name} (details)
• Introduced --info flag for quick access to debug information (details)
• Add --package flag, can be used with --cfg to print a specific config package (details)
• Override the config_path and config_name from the command line with --config-name and --config-path (details)
• Add an additional config directory to the search path with --config-dir (details)

Migrating from 0.11​

For most people, migrating from 0.11 to 1.0 will be smooth. However, you will have issues if you are relying on Python 2 support or have used internal APIs.

• Hydra 1.0 drops support for Python 2.
• If you are relying on internal APIs, Hydra 1.0 will likely break your code. Maintaining backward compatibility for internal APIs is not a goal.
• Hydra 0.11 Configs pickled and stored will not unpickle with Hydra 1.0 due to internal changes in OmegaConf.

There are multiple new deprecation warnings, each with a link to mini migration guide.

That's it for now, take Hydra 1.0 for a spin!

Catching up on some previous content:

Apr/8/2020​

FLOSS Weekly interview

Feb/3/2020​

PyTorch Medium channel blog post

Oct/3/2019​

Facebook engineering blog release post