Reference#

Encyclopedia Hydrazennica.

All reference documentation includes detailed Examples sections. Please scroll to the bottom of any given reference page to see the examples.

Creating, Storing, and Working with Configs#

hydra-zen provides us with tools for creating and working with configs. Among these, the most essential functions for creating configs are make_config() and builds(). hydra_zen.store is used to store configs so that we (and Hydra) can access them later. Then, instantiate() can be used to resolve these configs so that they return the data and class-instances that we need for our application.

Creating Configs#

`builds`(hydra_target, /, *pos_args[, ...])	`builds(target, args, kw)` returns a Hydra-compatible config that, when instantiated, returns `target(args, **kw)`.
`just`(obj, *[, zen_convert, hydra_recursive, ...])	`just(obj)` returns a config that, when instantiated, just returns `obj`.
`kwargs_of`(_BuildsFn__hydra_target, *[, ...])	Returns a config whose signature matches that of the provided target.
`BuildsFn`()	A class that can be modified to customize the behavior of `builds`, `just`, `kwargs_of`, and `make_config`.
`hydrated_dataclass`(target, *pos_args[, ...])	A decorator that uses `builds` to create a dataclass with the appropriate Hydra-specific fields for specifying a targeted config [R8dd265aa7612-1].
`make_config`(*fields_as_args[, ...])	Returns a config with user-defined field names and, optionally, associated default values and/or type annotations.

Storing Configs#

hydra_zen.store

`ZenStore`([name, deferred_to_config, ...])	An abstraction over Hydra's store, for creating multiple, isolated config stores.
`wrapper.default_to_config`(target[, ...])	Creates a config that describes `target`.

Creating and Launching Jobs with Hydra#

hydra-zen provides users the ability to launch a Hydra job via a Python function instead of from a commandline interface.

`zen`(func, /, pre_call, ZenWrapper)	A wrapper that returns a function that will auto-extract, resolve, and instantiate fields from an input config based on the wrapped function's signature.
`launch`(config, task_function[, overrides, ...])	Launches a Hydra job from a Python function rather than a CLI.
`wrapper.Zen`(_Zen__func, *[, exclude, ...])	Implements the wrapping logic that is exposed by `hydra_zen.zen`

Instantiating and Resolving Configs#

`instantiate`(config, *args[, _target_wrapper_])	Instantiates the target of a targeted config.
`get_target`(obj)	Returns the target-object from a targeted config.

Utilities#

`make_custom_builds_fn`(*[, zen_partial, ...])	Returns the `builds` function, but with customized default values.
`is_partial_builds`(x)	Returns `True` if the input is a targeted structured config that entails partial instantiation, either via `_partial_=True` [R01589f11ee6f-1] or via `_zen_partial=True`.
`uses_zen_processing`(x)	Returns `True` if the input is a targeted structured config that relies on zen-processing features during its instantiation process.
`ZenField`([hint, default, name])	Specifies a field's name and/or type-annotation and/or default value.

Working with YAMLs#

Hydra serializes all configs to a YAML-format text when launching a job. The following utilities can be used to work with YAML-serialized configs.

`to_yaml`(cfg, *[, resolve, sort_keys])	Serialize a config as a yaml-formatted string.
`save_as_yaml`(config, f[, resolve])	Save a config to a yaml-format file
`load_from_yaml`(file_)	Load a config from a yaml-format file

hydra_zen.typing#

`DataclassOptions`	Specifies dataclass-creation options via `builds`, `just` et al.
`ZenConvert`	A TypedDict that provides a type-checked interface for specifying zen-convert options that configure the hydra-zen config-creation functions (e.g., `builds`, `just`, and `make_config`).

Configuration-Value Types Supported by Hydra and hydra-zen#

The types of values that can be specified in configs are limited by their ability to be serialized to a YAML format. hydra-zen provides automatic support for an additional set of common types via its config-creation functions.

Types Supported Natively by Hydra#

Values of the following types can be specified directly in configs:

NoneType
bool
int
float
str
list
dict
enum.Enum
bytes (support added in OmegaConf 2.2.0)
pathlib.Path (support added in OmegaConf 2.2.1)

Auto-Config Support for Additional Types via hydra-zen#

Values of additional types can be specified directly via hydra-zen’s config-creation functions (and other utility functions like to_yaml()) and those functions will automatically create dataclass instances to represent those values in a way that is compatible with Hydra. For example, a complex value can be passed directly to make_config(), and hydra-zen will generate a dataclass instance that represents that complex value in a Hydra-compatible way.

Demonstrating auto-config support for complex, functools.partial and dataclasses.dataclass#

>>> from hydra_zen import builds, just, make_config, to_yaml, instantiate
>>> def print_yaml(x): print(to_yaml(x))

>>> Conf = make_config(value=2.0 + 3.0j)
>>> print_yaml(Conf)
value:
  real: 2.0
  imag: 3.0
  _target_: builtins.complex

>>> from functools import partial

>>> Conf2 = builds(dict, x=partial(int, 3))
>>> print_yaml(Conf2)
_target_: builtins.dict
x:
  _target_: builtins.int
  _partial_: true
  _args_:
  - 3
>>> instantiate(Conf2)
{'x': functools.partial(<class 'int'>, 3)}

>>> from typing import Callable, Sequence
>>> from dataclasses import dataclass
>>>
>>> @dataclass
... class Bar:
...    reduce_fn: Callable[[Sequence[float]], float] = sum
>>>
>>> just_bar = just(Bar())

>>> print_yaml(just_bar)
_target_: __main__.Bar
reduce_fn:
  _target_: hydra_zen.funcs.get_obj
  path: builtins.sum

>>> instantiate(just_bar)
Bar(reduce_fn=<built-in function sum>)

Auto-config behaviors can be configured via the zen-convert API.

hydra-zen provides specialized auto-config support for values of the following types:

bytes (support provided for OmegaConf < 2.2.0)
bytearray
complex
collections.Counter
collections.defaultdict
collections.deque
datetime.timedelta
functools.partial() (note: not compatible with pickling)
pathlib.Path (support provided for OmegaConf < 2.2.1)
pathlib.PosixPath
pathlib.WindowsPath
range
set
frozenset
dataclasses.dataclass() (note: not compatible with pickling)
hydra_zen.wrapper.Zen

hydra-zen also provides auto-config support for some third-pary libraries:

pydantic.dataclasses.dataclass
pydantic.Field
torch.optim.optimizer.required (i.e. the default parameter for lr in Optimizer)
numpy.ufunc and nunmpy array dispatchers (e.g. np.sum)
jax.numpy.ufunc and jax compiled functions (e.g. jax.vmap)

Third-Party Utilities#

Runtime Data Validation#

Although Hydra provides some runtime type-checking functionality, it only supports a limited set of types and annotations. hydra-zen offers support for more robust runtime type-checking capabilities via various third-party libraries.

`beartype.validates_with_beartype`(obj)	Enables runtime type-checking of values, via the library `beartype`.
`pydantic.validates_with_pydantic`(obj, *[, ...])
`pydantic.pydantic_parser`(target, *[, parser])	A target-wrapper that adds pydantic parsing to the target.