spd_learn.functional.safe_clamp_eigenvalues#

spd_learn.functional.safe_clamp_eigenvalues(eigenvalues: Tensor, name: Literal['eigval_clamp', 'eigval_log', 'eigval_sqrt', 'eigval_inv_sqrt', 'eigval_power', 'loewner_equal', 'batchnorm_var', 'dropout', 'trace_norm', 'stiefel_init', 'division_safe'] = 'eigval_clamp', *, config: NumericalConfig | None = None, return_mask: bool = False) → Tensor | tuple[source]#

Safely clamp eigenvalues with dtype-aware threshold.

This function clamps eigenvalues to ensure they are positive and numerically stable. It uses a dtype-aware threshold to balance stability and precision.

Parameters:

  • eigenvalues (torch.Tensor) – The eigenvalues to clamp.

  • name (ThresholdName, default="eigval_clamp") – The type of threshold to use.

  • config (NumericalConfig, optional) – Configuration to use. If None, uses the global numerical_config.

  • return_mask (bool, default=False) – If True, also return a boolean mask indicating which eigenvalues were clamped.

Returns:

The clamped eigenvalues. If return_mask=True, returns a tuple of (clamped_eigenvalues, clamped_mask).

Return type:

torch.Tensor or tuple

Examples

>>> import torch
>>> from spd_learn.functional.numerical import safe_clamp_eigenvalues
>>> eigvals = torch.tensor([1e-10, 1e-5, 1e-3, 1.0])
>>> clamped = safe_clamp_eigenvalues(eigvals, "eigval_log")
>>> print(clamped)
tensor([1.1921e-05, 1.1921e-05, 1.0000e-03, 1.0000e+00])