Repository Architecture

Top-level layout

Core source code is in hyperion/:

hyperion/np: NumPy models and metric/util function stacks.
hyperion/torch: PyTorch stack (layers, architectures, models, training).
hyperion/io: unified data/audio IO abstractions.
hyperion/utils: tables, dataset manifests, trial/key/score tooling.
hyperion/data_prep: dataset preparation classes.
hyperion/text_norm: text normalization utilities.
hyperion/metrics: high-level evaluator classes.
hyperion/bin: executable scripts exposed as package entry points.

Supporting folders:

docs/: Sphinx documentation.
tests/: unit/integration tests.

NumPy stack

hyperion.np contains the NumPy-based modeling/evaluation components.

The base class is:

class hyperion.np.HyperNPModel(name: str | None = None, **kwargs: Any)[source]

Base class for machine learning models based on numpy.

name: optional identifier for the model.

registry: ClassVar[Dict[str, Type[HyperNPModel]]] = {'NPModel': <class 'hyperion.np.hyper_np_model.NPModel'>}

__init__(name: str | None = None, **kwargs: Any) → None[source]

Initialize base model metadata.

Parameters:

name – Optional identifier for the model instance. If None, the class name is used.
**kwargs – Reserved for subclass compatibility.

copy() → HyperNPModel[source]: Returns a clone of the model.

clone() → HyperNPModel[source]: Returns a clone of the model.

property is_init: bool: Returns True if the model has been initialized.

init_to_false() → None[source]: Sets the model as non initialized.

initialize() → None[source]

Initialize model parameters/state.

Subclasses can override this method when they have lazy initialization logic.

fit(x: ndarray, sample_weight: ndarray | None = None, x_val: ndarray | None = None, sample_weight_val: ndarray | None = None) → None[source]

Trains the model.

Parameters:

x – train data matrix with shape (num_samples, x_dim).
sample_weight – weight of each sample in the training loss shape (num_samples,).
x_val – validation data matrix with shape (num_val_samples, x_dim).
sample_weight_val – weight of each sample in the val. loss.

Raises:

NotImplementedError – If not implemented by a subclass.

fit_generator(x: Any, x_val: Any | None = None) → None[source]

Trains the model from a data generator function.

Parameters:

x – train data generation function.
x_val – validation data generation function.

Raises:

NotImplementedError – If not implemented by a subclass.

save(file_path: str | Path) → None[source]

Saves the model to file.

Parameters:: file_path – filename path.

save_params(f: File) → None[source]

Saves model parameters into the file.

Parameters:: f – file handle.

_save_params_from_dict(f: File, params: Mapping[str, Any], dtypes: type | Mapping[str, Any] | None = None) → None[source]

Saves a dictionary of model parameters into the file.

Parameters:

f – file handle.
params – dictionary of model parameters.
dtypes – dictionary indicating the dtypes of the model parameters.

classmethod load_config(file_path: str | Path) → Dict[str, Any][source]

Loads the model configuration from file.

Parameters:: file_path – path to the file where the model is stored.
Returns:: Dictionary containing the model configuration.

classmethod load(file_path: str | Path) → HyperNPModel[source]

Loads the model from file.

Parameters:: file_path – path to the file where the model is stored.
Returns:: Model object.

classmethod load_params(f: File, config: Dict[str, Any]) → HyperNPModel[source]

Initializes the model from the configuration and loads the model parameters from file.

Parameters:

f – file handle.
config – configuration dictionary.

Returns:

Model object.

static _load_params_to_dict(f: File, name: str | None, params: Sequence[str], dtypes: type | Mapping[str, Any] | None = None) → Dict[str, ndarray | None][source]

Loads the model parameters from file to a dictionary.

Parameters:

f – file handle.
name – model identifier or None.
params – parameter names.
dtypes – dictionary containing the dtypes of the parameters.

Returns:

Dictionary with model parameters.

get_config() → Dict[str, Any][source]: Returns the model configuration dict.

to_json(**kwargs: Any) → str[source]

Return model configuration serialized as JSON.

Parameters:: **kwargs – Extra keyword arguments forwarded to json.dumps().
Returns:: JSON string with model configuration.

static load_config_from_json(json_str: str) → Dict[str, Any][source]: Convert JSON configuration string to dictionary.

static _bootstrap_registry() → None[source]: Import common NP subpackages so subclasses register themselves.

static _find_module_for_class_name(class_name: str) → str | None[source]

Find module path for a registered class name by scanning NP sources.

Parameters:: class_name – Target class name to locate.
Returns:: Dotted module path if found, otherwise None.

static auto_load(file_path: str | Path, extra_objs: Dict[str, Type[HyperNPModel]] | None = None) → HyperNPModel[source]

Auto-load a serialized model based on the saved class_name.

Parameters:

file_path – Path to model file.
extra_objs – Optional mapping from class name to class object used as a fallback when class is not yet registered.

Returns:

Instantiated model loaded from file_path.

Raises:

Exception – If the class cannot be resolved/imported.

Major subpackages include:

hyperion.np.pdfs (PLDA/GMM and related density models)
hyperion.np.classifiers
hyperion.np.transforms
hyperion.np.score_norm
hyperion.np.metrics

PyTorch stack

The PyTorch stack is layered:

hyperion.torch.layers: primitive layers.
hyperion.torch.layer_blocks: reusable blocks composed from layers.
hyperion.torch.narchs: neural architectures composed from blocks/layers.
hyperion.torch.models: top-level models composed from architectures.

Base classes:

class hyperion.torch.HyperTorchModel(*args: Any, **kwargs: Any)[source]

Base class for PyTorch models and neural network architectures.

registry: Dict[str, Type[HyperTorchModel]] = {'TorchModel': <class 'hyperion.torch.hyper_torch_model.TorchModel'>}

classmethod __init_subclass__(**kwargs: Any) → None[source]

Register subclasses by class name for dynamic loading.

Parameters:: **kwargs – Additional subclass initialization options.

__init__(bias_weight_decay: float | None = None)[source]

Initialize model-level training controls.

Parameters:: bias_weight_decay – Optional decay value for bias/1D parameter group.

get_config(no_class_name: bool = False) → Dict[str, Any][source]

Return a serializable configuration dictionary.

Parameters:: no_class_name – If True, omit class_name from the config.
Returns:: Configuration dictionary used to reconstruct the model.

copy() → HyperTorchModel[source]

Return a deep copy of this model.

Returns:: A deep-copied model instance.

clone() → HyperTorchModel[source]

Return a deep copy of this model (alias of copy).

Returns:: A deep-copied model instance.

trainable_parameters(recurse: bool = True) → Iterator[torch.nn.Parameter][source]

Yield parameters with requires_grad=True.

Parameters:: recurse – Whether to recurse into submodules.
Returns:: Iterator of trainable parameters.

non_trainable_parameters(recurse: bool = True) → Iterator[torch.nn.Parameter][source]

Yield parameters with requires_grad=False.

Parameters:: recurse – Whether to recurse into submodules.
Returns:: Iterator of non-trainable parameters.

trainable_named_parameters(recurse: bool = True) → Iterator[Tuple[str, torch.nn.Parameter]][source]

Yield (name, parameter) pairs for trainable parameters.

Parameters:: recurse – Whether to recurse into submodules.
Returns:: Iterator of named trainable parameters.

non_trainable_named_parameters(recurse: bool = True) → Iterator[Tuple[str, torch.nn.Parameter]][source]

Yield (name, parameter) pairs for non-trainable parameters.

Parameters:: recurse – Whether to recurse into submodules.
Returns:: Iterator of named non-trainable parameters.

parameter_summary(verbose: bool = False) → Tuple[int, int, int, int, int][source]

Return parameter and buffer counts.

Parameters:: verbose – If True, log a summary line.
Returns:: Tuple (total, trainable, non_trainable_plus_buffers, non_trainable, buffers).

print_parameter_list() → None[source]: Log names of trainable, non-trainable, and buffer tensors.

has_param_groups() → bool[source]

Return whether model exposes custom optimizer parameter groups.

Returns:: True if bias_weight_decay is enabled.

trainable_param_groups() → List[Dict[str, Any]][source]

Build optimizer parameter groups for trainable parameters.

Returns:: Optimizer parameter-group dictionaries.

freeze() → None[source]: Disable gradients for all parameters.

unfreeze() → None[source]: Enable gradients for all parameters.

has_batchnorms() → bool[source]

Return True if the model contains any batch-normalization layer.

Returns:: True when any batchnorm module is found.

change_dropouts(dropout_rate: float) → None[source]

Set dropout probability on dropout and RNN modules.

Parameters:: dropout_rate – New dropout rate.

property train_mode: str

full or frozen.

Returns:: Active train mode string.
Type:: Current train mode

set_train_mode(mode: str) → None[source]

Switch model between full-train and frozen-parameter modes.

Parameters:: mode – Target mode (full or frozen).

_train(train_mode: str) → None[source]

Apply PyTorch train/eval state for a custom train mode.

Parameters:: train_mode – Mode to apply (full or frozen).

train(mode: bool = True) → HyperTorchModel[source]

Override nn.Module.train to honor self.train_mode.

Parameters:: mode – If False, force eval mode.
Returns:: self.

static valid_train_modes() → List[str][source]

Return the list of supported train modes.

Returns:: Supported train-mode names.

save(file_path: str | Path) → None[source]

Save model config and state dictionary to disk.

Parameters:: file_path – Destination checkpoint path.

Resolve config/state_dict from args or a checkpoint file.

Parameters:

file_path – Optional checkpoint path.
cfg – Optional pre-loaded model config.
state_dict – Optional pre-loaded state dict.

Returns:

Tuple (cfg, state_dict) with class_name removed from config.

classmethod load(file_path: str | Path | None = None, cfg: Dict[str, Any] | None = None, state_dict: Dict[str, torch.Tensor] | None = None) → HyperTorchModel[source]

Instantiate model from config and optionally load weights.

Parameters:

file_path – Optional checkpoint path.
cfg – Optional model config.
state_dict – Optional model weights.

Returns:

Instantiated model.

get_reg_loss() → int[source]

Return regularization loss contribution for this model.

Returns:: Regularization loss term.

get_loss() → int[source]

Return auxiliary loss contribution for this model.

Returns:: Auxiliary loss term.

property device: torch.device

Return unique device shared by parameters and buffers.

Returns:: Device where all parameters and buffers reside.

static _remove_module_prefix(state_dict: Dict[str, torch.Tensor]) → Dict[str, torch.Tensor][source]

Remove leading module. prefixes from state-dict keys.

Parameters:: state_dict – State dict to normalize.
Returns:: Normalized state dict.

static _fix_xvector_cfg(cfg: Dict[str, Any]) → Dict[str, Any][source]

Normalize legacy XVector config keys to current names.

Parameters:: cfg – Model config dictionary.
Returns:: Updated config dictionary.

static _fix_hf_wav2xvector(cfg: Dict[str, Any], state_dict: Dict[str, torch.Tensor]) → Tuple[Dict[str, Any], Dict[str, torch.Tensor]][source]

Migrate legacy HF wav2xvector fusion config and checkpoint layout.

Parameters:

cfg – Model config dictionary.
state_dict – Model checkpoint weights.

Returns:

Updated (cfg, state_dict).

static _fix_resnet_qvector_cfg(cfg: Dict[str, Any]) → Dict[str, Any][source]

Drop deprecated ResNetQVector config keys.

Parameters:: cfg – Model config dictionary.
Returns:: Updated config dictionary.

static _fix_model_compatibility(class_obj: Type[HyperTorchModel], cfg: Dict[str, Any], state_dict: Dict[str, torch.Tensor]) → Tuple[Dict[str, Any], Dict[str, torch.Tensor]][source]

Apply compatibility fixes for deprecated model formats.

Parameters:

class_obj – Model class to instantiate.
cfg – Configuration dictionary.
state_dict – Serialized model weights.

Returns:

Updated (cfg, state_dict).

static _is_hf_path(file_path: Path) → bool[source]

Return True for HF-style org/repo/file paths.

Parameters:: file_path – Path to validate.
Returns:: True if path shape matches expected HF format.

static _get_from_hf(file_path: Path, cache_dir: str | Path = None, local_dir: str | Path = None) → str[source]

Download a file from Hugging Face Hub and return its local path.

Parameters:

file_path – HF-style path org/repo/file.
cache_dir – Optional HF cache directory.
local_dir – Optional local download directory.

Returns:

Local filesystem path to downloaded file.

static _try_to_get_from_hf(file_path: Path, cache_dir: str | Path = None, local_dir: str | Path = None) → Path[source]

Resolve local file path, downloading from HF Hub when needed.

Parameters:

file_path – Local path or prefixed HF path.
cache_dir – Optional HF cache directory.
local_dir – Optional local download directory.

Returns:

Resolved local path.

static _bootstrap_registry() → None[source]

Import common torch subpackages so subclasses register themselves.

HyperTorchModel.registry is populated when subclass definitions are imported. CLI scripts often import only HyperTorchModel and call auto_load, so we need a lazy import step before class lookup.

static _find_module_for_class_name(class_name: str) → str | None[source]

Find module path for class name by scanning torch source files.

Parameters:: class_name – Target class name.
Returns:: Dotted module path if found, otherwise None.

Load model from checkpoint with dynamic class resolution.

Parameters:

file_path – Local path or HF-style path.
model_name – State-dict prefix; defaults to model.
extra_objs – Optional mapping from class names to model classes.
map_location – torch.load map location.
cache_dir – Optional HF cache directory.
local_dir – Optional local download directory.

Returns:

Loaded model instance.

Training and data

Training/data-related packages live under hyperion.torch:

hyperion.torch.data: datasets and sampler factories.
hyperion.torch.trainers: trainer implementations.
hyperion.torch.lr_schedulers and hyperion.torch.wd_schedulers.

Current canonical trainer foundation is:

Third-party wrappers (TPM)

hyperion.torch.tpm provides wrappers for third-party models/toolkits, including Hugging Face models, DNSMOS, UTMOS, and VoxProfile evaluators.

Metrics layering

Metrics/evaluation are split into three layers:

hyperion.np.metrics: NumPy metric functions.
hyperion.torch.metrics: torch metric utilities.
hyperion.metrics: high-level evaluator classes that can combine both.

CLI generation

hyperion/bin scripts are converted to package entry points by generate_pyproject.py.

Deprecated script directories hyperion/bin_deprec and hyperion/bin_deprec2 are intentionally excluded from current docs.