omnibias.curvature.torch.regularize

0.1.0a2AlphaPython >=3.10AGPL / commercial

Scoped parameter-curvature formulas, Fisher and Gauss–Newton constructions, natural steps, and sharpness utilities.

import omnibias.curvature.torch.regularize

Module contract & mathematical conventions

The eps -> 0 rank / regularization collapse (PyTorch differentiable register).

The algebraically corresponding PyTorch twin of omnibias.curvature.regularize. Tikhonov solving collapses onto the Moore-Penrose / minimum-norm solution as the damping vanishes, (A + eps I)^{-1} b -> A^+ b; naively taking eps -> 0 blows up whenever A is rank-deficient. This module takes that limit *stably* and pairs it with the rigorous conditioning certificate in omnibias.core.verified.conditioning:

regularized_solve -- (A + eps I)^{-1} b.
min_norm_solve -- the collapse limit done right (eigen-truncated A^+ b).
regularization_path -- the measured homotopy x(eps) over a grid.
rank_collapse -- certified-damping (target condition number) or min-norm entry point, attaching a sealed conditioning certificate.

The certified damping and the sealed certificate are produced by the shared pure-Python core verifier, so for the same matrix they are **algebraically corresponding** to the JAX twin (the numerical solves match to a calibrated tolerance).

Collapse honesty

This eps -> 0 collapse is a **distinct** limit from the founding multi-bias delta -> 0 derivative collapse and from the beta -> inf feasibility penalty of the discrete-optimization packages -- same spirit, different parameter, never conflated. Nothing here rides the sigma derivative tower; the solves are ordinary numerical (LAPACK-class) operations and only the conditioning enclosure is verified.

Requires the optional torch extra (pip install "omnibias-curvature[torch]"); it is not imported by the JAX-only top-level omnibias.curvature.

Numerical scope: shared coefficients and formulas do not establish universal floating-point identity across backends, devices, compiler transforms, or reduction orders. Compare the chosen path with dtype-appropriate tolerances; even float64 is not a general bitwise-equality guarantee. Algebraic initialization identities likewise need a numerical check for the selected coefficients and reduction order.

Shared formulas do not imply universal floating-point identity. Verify dtype, shape, derivative-order support, and the stated numerical assumptions for the path you use.

Module source ↗Source revision 9a2d73df0573Running reference examples →

CLASS

CollapseResult

omnibias.curvature.torch.CollapseResultSource ↗

class CollapseResult

Dataclass constructor fields; inherited fields, if any, are declared by the base class. A field(...) expression describes a default factory or field options, not a literal argument default.

The outcome of a rank / regularization collapse (torch twin of the JAX result).

Parameters

Name	Type & default	Contract
`solution`dataclass field	`Tensor`Required	See the operation contract and implementation below.
`effective_rank`dataclass field	`int`Required	See the operation contract and implementation below.
`eps`dataclass field	`float`Required	See the operation contract and implementation below.
`certificate`dataclass field	`dict[str, Any] \| None`Required	See the operation contract and implementation below.

Regression example · rank collapse target condition

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_rank_collapse_target_condition() -> None:
    rng = np.random.default_rng(3)
    A_np = _spd(rng, 5, cond=1e6)
    res = rank_collapse(_t(A_np), _t(rng.normal(size=5)), target_condition=100.0)
    assert isinstance(res, CollapseResult)
    assert res.eps > 0.0
    assert np.linalg.cond(A_np + res.eps * np.eye(5)) <= 100.0 + 1e-6
    assert res.certificate is not None and verify_certificate_digest(res.certificate)

python -m pytest packages/omnibias-curvature/tests/test_torch_regularize.py -k test_rank_collapse_target_condition -q

Fields & methods

solutionfield

solution: Tensor

Declared Tensor field on CollapseResult. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

effective_rankfield

effective_rank: int

Declared int field on CollapseResult. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

epsfield

eps: float

Declared float field on CollapseResult. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

certificatefield

certificate: dict[str, Any] | None

Declared dict[str, Any] | None field on CollapseResult. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

Read the implementation

class CollapseResult:
    """The outcome of a rank / regularization collapse (torch twin of the JAX result)."""

    solution: Tensor
    effective_rank: int
    eps: float
    certificate: dict[str, Any] | None

Other public import paths

omnibias.curvature.torch.CollapseResult
omnibias.curvature.torch.regularize.CollapseResult

FUNCTION

min_norm_solve

omnibias.curvature.torch.min_norm_solveSource ↗

min_norm_solve(matrix: Tensor, rhs: Tensor, *, rcond: float | None=None) -> Tensor

The eps -> 0 limit done right: the minimum-norm / pseudoinverse solution.

Computes A^+ b via a symmetric eigendecomposition with small-eigenvalue truncation, so the limit is taken *stably* instead of letting (A + eps I)^{-1} b blow up. matrix must be symmetric.

Parameters

Name	Type & default	Contract
`matrix`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`rhs`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`rcond`keyword-only	`float \| None`Default: None	See the operation contract and implementation below.

ReturnsTensor

Executed regression · min norm solve matches pinv

Recorded coverage confirms this test executed the API body. This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_min_norm_solve_matches_pinv() -> None:
    rng = np.random.default_rng(1)
    for _ in range(8):
        p = int(rng.integers(3, 6))
        A = _low_rank(rng, p, p - 1)
        y = rng.normal(size=p)
        b = A @ y  # range-consistent
        x = min_norm_solve(_t(A), _t(b), rcond=1e-9)
        x0 = np.linalg.pinv(A, rcond=1e-9) @ b
        assert np.allclose(x.numpy(), x0, rtol=1e-7, atol=1e-7)
        assert numerical_rank(_t(A), rcond=1e-9) == p - 1

python -m pytest "packages/omnibias-curvature/tests/test_torch_regularize.py::test_min_norm_solve_matches_pinv" -q

Regression example · regularized solve normal equations

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_regularized_solve_normal_equations() -> None:
    rng = np.random.default_rng(0)
    p = 6
    A = _t(_spd(rng, p))
    b = _t(rng.normal(size=p))
    eps = 1e-2
    x = regularized_solve(A, b, eps=eps)
    resid = (A + eps * torch.eye(p, dtype=torch.float64)) @ x - b
    assert float(torch.max(torch.abs(resid))) < 1e-10

python -m pytest packages/omnibias-curvature/tests/test_torch_regularize.py -k test_regularized_solve_normal_equations -q

Read the implementation

def min_norm_solve(matrix: Tensor, rhs: Tensor, *, rcond: float | None = None) -> Tensor:
    r"""The ``eps -> 0`` limit done right: the minimum-norm / pseudoinverse solution.

    Computes ``A^+ b`` via a symmetric eigendecomposition with small-eigenvalue
    truncation, so the limit is taken *stably* instead of letting
    ``(A + eps I)^{-1} b`` blow up. ``matrix`` must be symmetric.
    """
    _validate_square_system(matrix, rhs)
    w, vecs = torch.linalg.eigh(matrix)
    rc = _default_rcond(matrix) if rcond is None else float(rcond)
    cutoff = rc * torch.max(torch.abs(w))
    keep = torch.abs(w) > cutoff
    safe_w = torch.where(keep, w, torch.ones_like(w))
    inv_w = torch.where(keep, 1.0 / safe_w, torch.zeros_like(w))
    out: Tensor = vecs @ (inv_w * (vecs.T @ rhs))
    return out

Other public import paths

omnibias.curvature.torch.min_norm_solve
omnibias.curvature.torch.regularize.min_norm_solve

FUNCTION

numerical_rank

omnibias.curvature.torch.numerical_rankSource ↗

numerical_rank(matrix: Tensor, *, rcond: float | None=None) -> int

The numerical rank of a symmetric matrix at the rcond cutoff.

Parameters

Name	Type & default	Contract
`matrix`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`rcond`keyword-only	`float \| None`Default: None	See the operation contract and implementation below.

Returnsint

Explicit validation & failure cases

When matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1], raises ValueError(f'matrix must be square (P, P), got {tuple(matrix.shape)}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · rank collapse target condition

Full file, imports & fixtures ↗

def test_rank_collapse_target_condition() -> None:
    rng = np.random.default_rng(3)
    A_np = _spd(rng, 5, cond=1e6)
    res = rank_collapse(_t(A_np), _t(rng.normal(size=5)), target_condition=100.0)
    assert isinstance(res, CollapseResult)
    assert res.eps > 0.0
    assert np.linalg.cond(A_np + res.eps * np.eye(5)) <= 100.0 + 1e-6
    assert res.certificate is not None and verify_certificate_digest(res.certificate)

python -m pytest "packages/omnibias-curvature/tests/test_torch_regularize.py::test_rank_collapse_target_condition" -q

Regression example · min norm solve matches pinv

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_min_norm_solve_matches_pinv() -> None:
    rng = np.random.default_rng(1)
    for _ in range(8):
        p = int(rng.integers(3, 6))
        A = _low_rank(rng, p, p - 1)
        y = rng.normal(size=p)
        b = A @ y  # range-consistent
        x = min_norm_solve(_t(A), _t(b), rcond=1e-9)
        x0 = np.linalg.pinv(A, rcond=1e-9) @ b
        assert np.allclose(x.numpy(), x0, rtol=1e-7, atol=1e-7)
        assert numerical_rank(_t(A), rcond=1e-9) == p - 1

python -m pytest packages/omnibias-curvature/tests/test_torch_regularize.py -k test_min_norm_solve_matches_pinv -q

Read the implementation

def numerical_rank(matrix: Tensor, *, rcond: float | None = None) -> int:
    r"""The numerical rank of a symmetric ``matrix`` at the ``rcond`` cutoff."""
    if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
        raise ValueError(f"matrix must be square (P, P), got {tuple(matrix.shape)}")
    w = torch.linalg.eigvalsh(matrix)
    rc = _default_rcond(matrix) if rcond is None else float(rcond)
    cutoff = rc * torch.max(torch.abs(w))
    return int(torch.sum(torch.abs(w) > cutoff))

Other public import paths

omnibias.curvature.torch.numerical_rank
omnibias.curvature.torch.regularize.numerical_rank

FUNCTION

rank_collapse

omnibias.curvature.torch.rank_collapseSource ↗

rank_collapse(matrix: Tensor, rhs: Tensor, *, target_condition: float | None=None, rcond: float | None=None, certify: bool=True) -> CollapseResult

High-level eps -> 0 collapse: min-norm limit or certified-damped solve.

target_condition is None takes the collapse limit with min_norm_solve (eps = 0); otherwise the smallest certified damping meeting the target condition number is used. When certify is set the result carries a sealed ~omnibias.core.verified.conditioning.conditioning_certificate -- identical to the JAX twin's for the same matrix (both come from the shared core verifier). theorem_prover_verified is not asserted here.

Parameters

Name	Type & default	Contract
`matrix`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`rhs`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`target_condition`keyword-only	`float \| None`Default: None	See the operation contract and implementation below.
`rcond`keyword-only	`float \| None`Default: None	See the operation contract and implementation below.
`certify`keyword-only	`bool`Default: True	See the operation contract and implementation below.

ReturnsCollapseResult

Executed regression · rank collapse target condition

Full file, imports & fixtures ↗

def test_rank_collapse_target_condition() -> None:
    rng = np.random.default_rng(3)
    A_np = _spd(rng, 5, cond=1e6)
    res = rank_collapse(_t(A_np), _t(rng.normal(size=5)), target_condition=100.0)
    assert isinstance(res, CollapseResult)
    assert res.eps > 0.0
    assert np.linalg.cond(A_np + res.eps * np.eye(5)) <= 100.0 + 1e-6
    assert res.certificate is not None and verify_certificate_digest(res.certificate)

python -m pytest "packages/omnibias-curvature/tests/test_torch_regularize.py::test_rank_collapse_target_condition" -q

Regression example · torch jax parity

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_torch_jax_parity() -> None:
    jax = pytest.importorskip("jax")
    jax.config.update("jax_enable_x64", True)
    import jax.numpy as jnp
    from omnibias.curvature import regularize as jreg

    rng = np.random.default_rng(20260729)
    # well-conditioned instance for the tight solve-parity check (the qubo lesson)
    A_np = _spd(rng, 5, cond=50.0)
    b_np = rng.normal(size=5)
    A_j, b_j = jnp.asarray(A_np), jnp.asarray(b_np)
    A_t, b_t = _t(A_np), _t(b_np)

    for eps in (1e-1, 1e-3, 1e-6):
        xj = np.asarray(jreg.regularized_solve(A_j, b_j, eps=eps))
        xt = regularized_solve(A_t, b_t, eps=eps).numpy()
        assert np.allclose(xj, xt, rtol=1e-9, atol=1e-9)

    # min-norm agrees (A^+ b is unique; eigh conventions differ, so looser tol)
    xj = np.asarray(jreg.min_norm_solve(A_j, b_j, rcond=1e-10))
    xt = min_norm_solve(A_t, b_t, rcond=1e-10).numpy()
    assert np.allclose(xj, xt, rtol=1e-8, atol=1e-8)

    # the certified damping + sealed certificate are bit-identical across backends
    rj = jreg.rank_collapse(A_j, b_j, target_condition=10.0)
    rt = rank_collapse(A_t, b_t, target_condition=10.0)
    assert rj.eps == rt.eps  # exact: same pure-Python certified_damping
    assert rj.certificate is not None and rt.certificate is not None
    assert rj.certificate["digest"] == rt.certificate["digest"]
    assert rj.effective_rank == rt.effective_rank

python -m pytest packages/omnibias-curvature/tests/test_torch_regularize.py -k test_torch_jax_parity -q

Read the implementation

def rank_collapse(
    matrix: Tensor,
    rhs: Tensor,
    *,
    target_condition: float | None = None,
    rcond: float | None = None,
    certify: bool = True,
) -> CollapseResult:
    r"""High-level ``eps -> 0`` collapse: min-norm limit or certified-damped solve.

    ``target_condition is None`` takes the collapse limit with :func:`min_norm_solve`
    (``eps = 0``); otherwise the smallest certified damping meeting the target
    condition number is used. When ``certify`` is set the result carries a sealed
    :func:`~omnibias.core.verified.conditioning.conditioning_certificate` -- identical
    to the JAX twin's for the same matrix (both come from the shared core verifier).
    ``theorem_prover_verified`` is not asserted here.
    """
    _validate_square_system(matrix, rhs)
    if target_condition is None:
        eps = 0.0
        solution = min_norm_solve(matrix, rhs, rcond=rcond)
    else:
        rows = _to_float_rows(matrix)
        eps = certified_damping(rows, target_condition=float(target_condition))
        solution = regularized_solve(matrix, rhs, eps=eps)
    rank = numerical_rank(matrix, rcond=rcond)
    certificate: dict[str, Any] | None = None
    if certify:
        rows = _to_float_rows(matrix)
        certificate = conditioning_certificate(
            rows,
            target_condition=target_condition,
            eps=(eps if target_condition is not None else None),
        )
    return CollapseResult(
        solution=solution, effective_rank=rank, eps=float(eps), certificate=certificate
    )

Other public import paths

omnibias.curvature.torch.rank_collapse
omnibias.curvature.torch.regularize.rank_collapse

FUNCTION

regularization_path

omnibias.curvature.torch.regularization_pathSource ↗

regularization_path(matrix: Tensor, rhs: Tensor, eps_grid: Tensor) -> Tensor

Stacked Tikhonov solutions x(eps) over eps_grid (the collapse homotopy).

Parameters

Name	Type & default	Contract
`matrix`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`rhs`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`eps_grid`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.

ReturnsTensor

Explicit validation & failure cases

When grid.ndim != 1, raises ValueError(f'eps_grid must be 1-D, got shape {tuple(grid.shape)}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · regularization path rows

Full file, imports & fixtures ↗

def test_regularization_path_rows() -> None:
    rng = np.random.default_rng(2)
    p = 4
    A = _t(_spd(rng, p))
    b = _t(rng.normal(size=p))
    grid = torch.tensor([1e-1, 1e-2, 1e-3], dtype=torch.float64)
    path = regularization_path(A, b, grid)
    assert path.shape == (3, p)
    for k, eps in enumerate([1e-1, 1e-2, 1e-3]):
        assert torch.allclose(path[k], regularized_solve(A, b, eps=eps))

python -m pytest "packages/omnibias-curvature/tests/test_torch_regularize.py::test_regularization_path_rows" -q

Read the implementation

def regularization_path(matrix: Tensor, rhs: Tensor, eps_grid: Tensor) -> Tensor:
    r"""Stacked Tikhonov solutions ``x(eps)`` over ``eps_grid`` (the collapse homotopy)."""
    p = _validate_square_system(matrix, rhs)
    grid = torch.as_tensor(eps_grid)
    if grid.ndim != 1:
        raise ValueError(f"eps_grid must be 1-D, got shape {tuple(grid.shape)}")
    eye = torch.eye(p, dtype=matrix.dtype, device=matrix.device)
    rows = [torch.linalg.solve(matrix + float(e) * eye, rhs) for e in grid]
    return torch.stack(rows)

Other public import paths

omnibias.curvature.torch.regularization_path
omnibias.curvature.torch.regularize.regularization_path

FUNCTION

regularized_solve

omnibias.curvature.torch.regularized_solveSource ↗

regularized_solve(matrix: Tensor, rhs: Tensor, *, eps: float=0.001) -> Tensor

The Tikhonov-regularized solve (A + eps I)^{-1} b (see the JAX twin).

Parameters

Name	Type & default	Contract
`matrix`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`rhs`positional-or-keyword	`Tensor`Required	See the operation contract and implementation below.
`eps`keyword-only	`float`Default: 0.001	See the operation contract and implementation below.

ReturnsTensor

Explicit validation & failure cases

When eps < 0.0, raises ValueError(f'eps must be >= 0, got {eps}').

These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.

Executed regression · regularized solve normal equations

Full file, imports & fixtures ↗

def test_regularized_solve_normal_equations() -> None:
    rng = np.random.default_rng(0)
    p = 6
    A = _t(_spd(rng, p))
    b = _t(rng.normal(size=p))
    eps = 1e-2
    x = regularized_solve(A, b, eps=eps)
    resid = (A + eps * torch.eye(p, dtype=torch.float64)) @ x - b
    assert float(torch.max(torch.abs(resid))) < 1e-10

python -m pytest "packages/omnibias-curvature/tests/test_torch_regularize.py::test_regularized_solve_normal_equations" -q

Regression example · regularized solve guards

This example belongs to the pinned upstream test suite. It may use fixtures and imports from its full file. Run it from that checkout with its test dependencies installed.

Full file, imports & fixtures ↗

def test_regularized_solve_guards() -> None:
    with pytest.raises(ValueError, match="square"):
        regularized_solve(torch.zeros((2, 3), dtype=torch.float64), torch.zeros(2, dtype=torch.float64))
    with pytest.raises(ValueError, match="eps must be"):
        regularized_solve(torch.eye(3, dtype=torch.float64), torch.zeros(3, dtype=torch.float64), eps=-1.0)

python -m pytest packages/omnibias-curvature/tests/test_torch_regularize.py -k test_regularized_solve_guards -q

Read the implementation

def regularized_solve(matrix: Tensor, rhs: Tensor, *, eps: float = 1e-3) -> Tensor:
    r"""The Tikhonov-regularized solve ``(A + eps I)^{-1} b`` (see the JAX twin)."""
    p = _validate_square_system(matrix, rhs)
    if eps < 0.0:
        raise ValueError(f"eps must be >= 0, got {eps}")
    damped = matrix + eps * torch.eye(p, dtype=matrix.dtype, device=matrix.device)
    out: Tensor = torch.linalg.solve(damped, rhs)
    return out

Other public import paths

omnibias.curvature.torch.regularized_solve
omnibias.curvature.torch.regularize.regularized_solve

← Package overview Runnable learning examples →

omnibias.curvature.torch.regularize

CollapseResult​

Parameters

Fields & methods

min_norm_solve​

Parameters

numerical_rank​

Parameters

rank_collapse​

Parameters

regularization_path​

Parameters

regularized_solve​

Parameters

CollapseResult

min_norm_solve

numerical_rank

rank_collapse

regularization_path

regularized_solve