hydra_zen.instantiate#

hydra_zen.instantiate(config, *args, _target_wrapper_=None, **kwargs)[source]#

Instantiates the target of a targeted config.

This is an alias of hydra.utils.instantiate() [1].

By default, instantiate will recursively instantiate nested configurations [1].

Parameters:

configBuilds[Type[T] | Callable[…, T]]

The targeted config whose target will be instantiated/called.

*args: Any

Override values, specified by-position. Take priority over the positional values provided by config.

**kwargsAny

Override values, specified by-name. Take priority over the named values provided by config.

_target_wrapper_Callable[[F], F] | None, optional (default=None)

If specified, this wrapper is applied to _all_ targets during instantiation. This can be used to add custom validation/parsing to the config-instantiation process.

I.e., For any target reached during recursive instantiation, _target_wrapper_(target)(*args, **kwargs) will be called rather than target(*args, **kwargs).

Returns:

instantiatedT: The instantiated target. Instantiated using the values provided by config and/or overridden via *args and **kwargs.

See also

builds: Returns a config, which describes how to instantiate/call <hydra_target>.
just: Produces a config that, when instantiated by Hydra, “just” returns the un-instantiated target-object

Notes

This is an alias for hydra.utils.instantiate, but adds additional static type information.

During instantiation, Hydra performs runtime validation of data based on a limited set of type-annotations that can be associated with the fields of the provided config [2] [3].

Hydra supports a string-based syntax for variable interpolation, which enables configured values to be set in a self-referential and dynamic manner [4].

References

[1] (1,2)

https://hydra.cc/docs/advanced/instantiate_objects/overview

[2] (1,2)

https://omegaconf.readthedocs.io/en/latest/structured_config.html#simple-types

[3]

https://omegaconf.readthedocs.io/en/latest/structured_config.html#runtime-type-validation-and-conversion

[4] (1,2)

https://omegaconf.readthedocs.io/en/latest/usage.html#variable-interpolation

Examples

>>> from hydra_zen import builds, instantiate, just

Basic Usage

Instantiating a config that targets a class/type.

>>> ConfDict = builds(dict, x=1)  # a targeted config
>>> instantiate(ConfDict)  # calls `dict(x=1)`
{'x': 1}

Instantiating a config that targets a function.

>>> def f(z): return z
>>> ConfF = builds(f, z=22)  # a targeted config
>>> instantiate(ConfF)  # calls `f(z=22)`
22

Providing a manual override, via instantiate(..., **kwargs)

>>> instantiate(ConfF, z='foo')  # calls `f(z='foo')`
'foo'

Recursive instantiation through nested configs.

>>> inner = builds(dict, b="hi")
>>> outer = builds(dict, a=inner)
>>> instantiate(outer) # calls `dict(a=dict(b='hi))`
{'a': {'b': 'hi'}}

Leveraging Variable Interpolation

Hydra provides a powerful language for absolute and relative interpolated variables among configs [4]. Let’s make a config where multiple fields reference the field name via absolute interpolation.

>>> from hydra_zen import make_config
>>> Conf = make_config("name", a="${name}", b=builds(dict, x="${name}"))

Resolving the interpolation key: name

>>> instantiate(Conf, name="Jeff")
{'a': 'Jeff', 'b': {'x': 'Jeff'}, 'name': 'Jeff'}

Runtime Data Validation via Hydra

>>> def g(x: float): return x  # note the annotation: float
>>> Conf_g = builds(g, populate_full_signature=True)
>>> instantiate(Conf_g, x=1.0)
1.0

Passing a non-float to x will produce a validation error upon instantiation

>>> instantiate(Conf_g, x='hi')
ValidationError: Value 'hi' could not be converted to Float
    full_key: x
    object_type=Builds_g

Only a subset of primitive types are supported by Hydra’s validation system [2]. See Runtime Data Validation for more general data validation capabilities via hydra-zen.