Configuration integrations

PhiJAX does not require a particular configuration layout. phijax.integrations.hydra can build typed runtime objects from project-owned Hydra configs. phijax.integrations.omegaconf provides reusable resolvers.

This page documents the integration functions provided by the package. For a complete config tree, CLI entrypoints, and experiment composition, use the PhiJAX Hydra template.

Hydra factories

The factory helpers instantiate callbacks, loggers, a Trainer, DataModule, lazy model factory, objective, PhiModule, loss balancer, and optimizer. A balancer config is directly instantiable and does not need an intermediate factory field:

model:
  balancer:
    _target_: phijax.balancers.ExactNTKBalancer
    update_every_n_steps: 100
    update_start_step: 100
    kernel_size: 256
    kernel_chunk_size: 1

The project passes model.balancer to instantiate_balancer(). Use Trainer.fit() for ordinary training or the core build_training_plan() function when an advanced fit_state() workflow needs an explicit plan.

instantiate_data_module [source]

instantiate_data_module(
    config: DictConfig,
) -> PhiDataModule

Instantiate one configured DataModule without preparing a runtime stage.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Hydra-instantiable DataModule configuration.	required

Returns:

Type	Description
`PhiDataModule`	Unprepared DataModule whose stage lifecycle is owned by :class:`phijax.Trainer`.

Raises:

Type	Description
`TypeError`	If `config` does not instantiate :class:`PhiDataModule`.

instantiate_model_factory [source]

instantiate_model_factory(
    config: DictConfig,
) -> ModelFactory

Instantiate a lazy model factory from one Hydra target.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Hydra-instantiable model-builder configuration.	required

Returns:

Type	Description
`ModelFactory`	Callable retaining architecture options while leaving key, normalization, and precision unbound.

Raises:

Type	Description
`TypeError`	If the configured target cannot produce a callable factory.

instantiate_module [source]

instantiate_module(
    config: DictConfig,
    model: ModelFactory,
    objective: Objective,
    *,
    name: str,
) -> BasePhiModule

Instantiate a configurable application module blueprint.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Hydra-instantiable module configuration.	required
`model`	`ModelFactory`	Lazy initialized-model factory.	required
`objective`	`Objective`	Instantiated objective producing named scalar losses.	required
`name`	`str`	Human-readable application identity.	required

Returns:

Type	Description
`BasePhiModule`	Module implementing the trainer-facing lifecycle and computation contract.

Raises:

Type	Description
`TypeError`	If `config` does not instantiate :class:`BasePhiModule`.

instantiate_objective [source]

instantiate_objective(config: DictConfig) -> Objective

Instantiate and validate one objective configuration.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Hydra-instantiable objective configuration.	required

Returns:

Type	Description
`Objective`	Objective implementing the generic scalar-loss contract.

Raises:

Type	Description
`TypeError`	If `config` does not instantiate :class:`Objective`.

instantiate_balancer [source]

instantiate_balancer(
    config: DictConfig, loss_names: Sequence[str]
) -> Any

Instantiate and validate one loss balancer.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Directly Hydra-instantiable balancer configuration containing `_target_` and constructor options.	required
`loss_names`	`Sequence[str]`	Stable objective loss names injected into the balancer.	required

Returns:

Type	Description
`Any`	Loss balancer exposing initialization and scalar combination operations.

Raises:

Type	Description
`TypeError`	If the constructed object does not implement the balancer contract.

instantiate_optimizer [source]

instantiate_optimizer(
    config: DictConfig,
) -> optax.GradientTransformation

Instantiate and validate one Optax optimizer configuration.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Hydra-instantiable optimizer configuration.	required

Returns:

Type	Description
`GradientTransformation`	Optax gradient transformation.

Raises:

Type	Description
`TypeError`	If the constructed object is not an Optax gradient transformation.

Callback and logger entries are active when they are present in the composed configuration. To disable one, remove its entry from the config or use Hydra's deletion override:

python train.py '~callbacks.early_stopping'

The complete callbacks or logger group may be null. Named entries must define _target_; do not add an enabled field or leave a named entry set to null.

instantiate_callbacks [source]

instantiate_callbacks(
    config: DictConfig | None,
) -> tuple[Callback, ...]

Instantiate and validate callback configurations.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig \| None`	Optional callback configuration mapping.	required

Returns:

Type	Description
`tuple[Callback, ...]`	Ordered callback instances.

Raises:

Type	Description
`TypeError`	If an entry is invalid or does not instantiate :class:`Callback`.
`ValueError`	If an entry is null, lacks `_target_`, or uses `enabled`.

instantiate_loggers [source]

instantiate_loggers(
    config: DictConfig | None,
) -> LoggerCollection

Instantiate external loggers without acquiring their runtime resources.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig \| None`	Optional logger configuration mapping.	required

Returns:

Type	Description
`LoggerCollection`	Validated logger collection in configuration order.

Raises:

Type	Description
`TypeError`	If an entry is invalid or does not instantiate :class:`ExperimentLogger`.
`ValueError`	If an entry is null, lacks `_target_`, or uses `enabled`.

instantiate_trainer [source]

instantiate_trainer(
    config: DictConfig,
    callbacks: Sequence[Callback] = (),
    logger: bool
    | ExperimentLogger
    | Sequence[ExperimentLogger]
    | None = False,
) -> Trainer

Instantiate a trainer with already constructed host services.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Hydra-instantiable trainer configuration.	required
`callbacks`	`Sequence[Callback]`	Ordered callback instances owned by the trainer.	`()`
`logger`	`bool \| ExperimentLogger \| Sequence[ExperimentLogger] \| None`	Default logger flag, one backend, several backends, or `None` to disable logging.	`False`

Returns:

Type	Description
`Trainer`	Instantiated trainer owning the configured callbacks and loggers.

Raises:

Type	Description
`TypeError`	If `config` does not instantiate :class:`Trainer`.

build_trainer [source]

build_trainer(config: DictConfig) -> Trainer

Build a trainer from root callback, trainer, and logger groups.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Root Hydra configuration containing `callbacks`, `trainer`, and `logger`.	required

Returns:

Type	Description
`Trainer`	Fully configured trainer.

Projects that need the individual construction steps can inject the already constructed services directly:

from phijax.integrations.hydra import (
    instantiate_callbacks,
    instantiate_loggers,
    instantiate_trainer,
    to_hyperparameters,
)

callbacks = instantiate_callbacks(config.get("callbacks"))
loggers = instantiate_loggers(config.get("logger"))
trainer = instantiate_trainer(config.trainer, callbacks, logger=loggers)

hyperparameters = to_hyperparameters(config)
result = trainer.fit(module, datamodule=data, optimizer=optimizer, seed=seed, hyperparameters=hyperparameters)

Logger constructors do not acquire local or remote resources. The Trainer starts and closes them only on global rank zero when the task runs.

to_hyperparameters [source]

to_hyperparameters(
    config: DictConfig, *, resolve: bool = False
) -> dict[str, Any]

Convert a composed Hydra config into logger-ready plain containers.

The Trainer owns the actual rank-safe logger call when the returned mapping is passed to :meth:phijax.Trainer.fit or :meth:phijax.Trainer.fit_state.

Parameters:

Name	Type	Description	Default
`config`	`DictConfig`	Composed root Hydra configuration.	required
`resolve`	`bool`	Whether to resolve OmegaConf interpolations before conversion.	`False`

Returns:

Type	Description
`dict[str, Any]`	Plain nested mapping accepted by the Trainer's `hyperparameters` argument.

Raises:

Type	Description
`TypeError`	If `config` does not contain a mapping at its root.

OmegaConf resolvers

Project entrypoints should register resolvers before Hydra composition:

from phijax.integrations.omegaconf import register_omegaconf_resolvers

register_omegaconf_resolvers()

Resolver	Example	Purpose
`math`	`${math:pi}`	Public Python `math` member
`op`	`${op:truediv,0.01,${math:pi}}`	Public `operator` function
`op.ternary`	`${op.ternary,true,a,b}`	Conditional value
`tuple`	`${tuple:1,2,3}`	Tuple rather than list
`call`	`${call:module.function,arg}`	Trusted imported callable
`target.name`	`${target.name:${model.optimizer._target_}}`	Final Hydra target name
`assert`	`${assert:true}`	Strict or warning assertion

Use target.name when a callback needs a stable label for a configured service without duplicating configuration. For example, an optimizer target can name its learning-rate metric automatically:

model:
  optimizer:
    _target_: optax.adamw

callbacks:
  lr_monitor:
    _target_: phijax.callbacks.LearningRateMonitor
    schedule: ${model.scheduler}
    optimizer_name: ${target.name:${model.optimizer._target_}}

This configuration logs optimizer/lr-adamw. The resolver preserves the target's spelling rather than guessing how custom names or acronyms should be capitalized.

Configuration can execute imported callables through Hydra targets and the call resolver. Compose only trusted configuration files.

register_omegaconf_resolvers [source]

register_omegaconf_resolvers() -> None

Register PhiJAX's general-purpose OmegaConf resolvers idempotently.

The registry exposes configuration assertions, standard-library operators, ternary selection, importable callable invocation, tuple construction, Hydra target names, and public constants or callables from :mod:math. Resolver registration modifies OmegaConf process-global state, so this function is safe to call repeatedly before Hydra composition.

Examples:

${math:pi} resolves to :data:math.pi, while ${op:truediv,0.01,${math:pi}} resolves to 0.01 / math.pi.

import_from_module [source]

import_from_module(dotpath: str) -> Any

Import an object from its fully qualified dotted path.

Parameters:

Name	Type	Description	Default
`dotpath`	`str`	Module path followed by the requested attribute name.	required

Returns:

Type	Description
`Any`	Imported module attribute.

Raises:

Type	Description
`ValueError`	If `dotpath` does not contain both a module and attribute name.