nlsq.robust_decomposition module

Robust matrix decomposition with multi-level fallback strategies.

This module extends the SVD fallback to provide comprehensive fallback strategies for all matrix decompositions used in optimization.

class nlsq.stability.robust_decomposition.RobustDecomposition(enable_logging=False)[source]

Bases: object

Multi-level fallback for matrix decompositions.

This class provides robust matrix decomposition methods that automatically fall back through multiple strategies if the primary method fails. The fallback chain goes from: 1. JAX on GPU (if available) 2. JAX on CPU 3. SciPy (if available) 4. NumPy 5. Safe mode with regularization

fallback_chain

Ordered list of (name, method) tuples for fallback strategies

Type:

list

logger

Logger for debugging decomposition issues

Type:

logging.Logger

__init__(enable_logging=False)[source]

Initialize robust decomposition handler.

Parameters:

enable_logging (bool) – Whether to enable detailed logging of fallback attempts

svd(matrix, full_matrices=False)[source]

Compute SVD with automatic fallback.

Parameters:

  • matrix (jnp.ndarray) – Matrix to decompose

  • full_matrices (bool) – Whether to compute full matrices

Returns:

  • U (jnp.ndarray) – Left singular vectors

  • s (jnp.ndarray) – Singular values

  • Vt (jnp.ndarray) – Right singular vectors (transposed)

Raises:

RuntimeError – If all decomposition methods fail

Return type:

tuple[Array, Array, Array]

qr(matrix, mode='reduced')[source]

Compute QR decomposition with fallback.

Parameters:

  • matrix (jnp.ndarray) – Matrix to decompose

  • mode (str) – QR mode (‘reduced’ or ‘complete’)

Returns:

  • Q (jnp.ndarray) – Orthogonal matrix

  • R (jnp.ndarray) – Upper triangular matrix

Raises:

RuntimeError – If all decomposition methods fail

Return type:

tuple[Array, Array]

cholesky(matrix, lower=True)[source]

Compute Cholesky decomposition with fallback and regularization.

Parameters:

  • matrix (jnp.ndarray) – Positive definite matrix to decompose

  • lower (bool) – Whether to return lower triangular matrix

Returns:

L – Cholesky factor (lower or upper triangular)

Return type:

jnp.ndarray

Raises:

RuntimeError – If all decomposition methods fail

solve_least_squares(A, b)[source]

Solve least squares problem with robust decomposition.

Parameters:

  • A (jnp.ndarray) – Coefficient matrix

  • b (jnp.ndarray) – Right-hand side

Returns:

x – Solution vector

Return type:

jnp.ndarray

Overview

The robust_decomposition module provides robust matrix decomposition algorithms with numerical stability enhancements.

Key Features

  • SVD with fallback strategies for ill-conditioned matrices

  • QR decomposition with pivoting

  • Cholesky decomposition with regularization

  • Condition number monitoring

Functions

Example Usage

from nlsq.robust_decomposition import robust_svd
import jax.numpy as jnp

# Ill-conditioned matrix
A = jnp.array([[1.0, 1.0], [1.0, 1.0 + 1e-10]])

# Robust SVD with fallback
U, s, Vt = robust_svd(A, fallback=True)

# Check condition number
condition_number = s[0] / s[-1]
print(f"Condition number: {condition_number:.2e}")

Fallback Strategies

The module implements multiple fallback strategies for numerical stability:

  1. Standard decomposition (JAX native)

  2. Regularized decomposition (add small diagonal term)

  3. Iterative refinement (improve solution accuracy)

# Configure fallback behavior
U, s, Vt = robust_svd(A, fallback=True, regularization=1e-10, max_attempts=3)

See Also