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#

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:

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:

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.