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 thantarget(*args, **kwargs)
.
- Returns:
- instantiatedT
The instantiated target. Instantiated using the values provided by
config
and/or overridden via*args
and**kwargs
.
See also
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
[3]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.
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.