API REFERENCE/omnibias-core

omnibias.core.verified.linalg_array

0.5.0rc1Release candidatePython >=3.10Apache-2.0

Coefficient recurrences, activation contracts, jet algebra, and verified arithmetic shared by the numerical backends.

import omnibias.core.verified.linalg_array

Module contract & mathematical conventions

Vectorized outward-rounded symmetric LDL^T: inertia and definiteness.

omnibias.core.verified.eig_operator owns the scalar reference path (~omnibias.core.verified.eig_operator.interval_ldlt_inertia and friends) built from ~omnibias.core.verified.interval.Interval objects. This module is its ~omnibias.core.verified.interval_array.IntervalArray twin: the same left-looking factorization, driven one column at a time with NumPy endpoint arrays instead of one Python object per matrix entry.

Soundness is inherited rather than re-argued. Every elementary step reuses the *same* outward-rounded primitives as the scalar path -- one numpy.nextafter step per computed endpoint, min/max over the four corner products for a multiplication -- and the pivot loop applies them in the same order, so each returned interval encloses the corresponding exact factor of every symmetric point matrix in the input box. With all pivots sign-definite, S = L D L^T is a congruence and Sylvester's law of inertia fixes the inertia of the whole box. A pivot interval that straddles 0 leaves the sign -- hence the inertia -- uncertified, and the factorization returns None rather than a guess.

Only the lower triangle and the diagonal of the input are read, matching the scalar path: the statement is about symmetric point matrices whose lower triangle lies in the supplied box.

Every result here is a **fixed finite matrix** statement. It carries no continuum, operator-limit, or spectral-asymptotics claim.

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

IntervalLDLT

omnibias.core.verified.IntervalLDLTSource ↗

class IntervalLDLT

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.

A certified interval LDL^T factorization of a symmetric matrix box.

lower is the full (n, n) unit-lower factor (exact ones on the diagonal, exact zeros above it) and diagonal is the length-n pivot vector. Each entry encloses the corresponding exact factor of every symmetric point matrix in the factored box.

Parameters

Name	Type & default	Contract
lowerdataclass field	IntervalArrayRequired	See the operation contract and implementation below.
diagonaldataclass field	IntervalArrayRequired	See the operation contract and implementation below.

Executed regression · deterministic boxes match scalar reference and numpy

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_deterministic_boxes_match_scalar_reference_and_numpy(
    midpoint: list[list[float]], radius: float
) -> None:
    """Named matrices: parity with the scalar path plus a true-spectrum check."""
    center = np.asarray(midpoint, dtype=np.float64)
    box = _symmetric_box(center, radius)
    _assert_matches_scalar_reference(box)

    # A dense deterministic interior grid, symmetrized on the lower triangle.
    samples = [
        _symmetrize_lower(box.lo + fraction * (box.hi - box.lo))
        for fraction in np.linspace(0.0, 1.0, 9)
    ]
    _assert_matches_numpy_spectrum(box, [np.clip(s, box.lo, box.hi) for s in samples])

python -m pytest "packages/omnibias-core/tests/verified/test_linalg_array.py::test_deterministic_boxes_match_scalar_reference_and_numpy[0.0-diagonal_indefinite]" -q

Fields & methods

lowerfield

lower: IntervalArray

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

View source ↗

diagonalfield

diagonal: IntervalArray

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

View source ↗

sizeproperty

size(self) -> int

The matrix dimension n.

Returns: int

Executed regression · deterministic boxes match scalar reference and numpy

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_deterministic_boxes_match_scalar_reference_and_numpy(
    midpoint: list[list[float]], radius: float
) -> None:
    """Named matrices: parity with the scalar path plus a true-spectrum check."""
    center = np.asarray(midpoint, dtype=np.float64)
    box = _symmetric_box(center, radius)
    _assert_matches_scalar_reference(box)

    # A dense deterministic interior grid, symmetrized on the lower triangle.
    samples = [
        _symmetrize_lower(box.lo + fraction * (box.hi - box.lo))
        for fraction in np.linspace(0.0, 1.0, 9)
    ]
    _assert_matches_numpy_spectrum(box, [np.clip(s, box.lo, box.hi) for s in samples])

python -m pytest "packages/omnibias-core/tests/verified/test_linalg_array.py::test_deterministic_boxes_match_scalar_reference_and_numpy[0.0-diagonal_indefinite]" -q

Method implementation

    def size(self) -> int:
        """The matrix dimension ``n``."""
        return self.diagonal.shape[0]

View source ↗

Read the implementation

class IntervalLDLT:
    """A certified interval ``LDL^T`` factorization of a symmetric matrix box.

    ``lower`` is the full ``(n, n)`` unit-lower factor (exact ones on the
    diagonal, exact zeros above it) and ``diagonal`` is the length-``n`` pivot
    vector.  Each entry encloses the corresponding exact factor of every
    symmetric point matrix in the factored box.
    """

    lower: IntervalArray
    diagonal: IntervalArray

    @property
    def size(self) -> int:
        """The matrix dimension ``n``."""
        return self.diagonal.shape[0]

Other public import paths

• omnibias.core.verified.IntervalLDLT
• omnibias.core.verified.linalg_array.IntervalLDLT

FUNCTION

interval_ldlt_factor_array

omnibias.core.verified.interval_ldlt_factor_arraySource ↗

interval_ldlt_factor_array(matrix: IntervalArrayLike) -> IntervalLDLT | None

Certified interval LDL^T of a symmetric matrix box (or None).

The vectorized twin of ~omnibias.core.verified.eig_operator.interval_ldlt_factor. Returns None as soon as a pivot interval straddles 0, because the pivot sign -- and therefore the inertia of the box -- cannot be certified there.

Parameters

Name	Type & default	Contract
matrixpositional-or-keyword	IntervalArrayLikeRequired	See the operation contract and implementation below.

ReturnsIntervalLDLT | None

Executed regression · straddling pivot is reported as uncertified

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_straddling_pivot_is_reported_as_uncertified() -> None:
    """A box that contains a singular matrix cannot certify an inertia."""
    box = IntervalArray([[-0.5, 1.0], [1.0, 3.0]], [[0.5, 1.0], [1.0, 3.0]])
    assert interval_ldlt_inertia_array(box) is None
    assert interval_ldlt_pivots_array(box) is None
    assert interval_ldlt_factor_array(box) is None
    assert is_positive_definite_array(box) is False
    assert interval_ldlt_inertia(_scalar_matrix(box)) is None

python -m pytest "packages/omnibias-core/tests/verified/test_linalg_array.py::test_straddling_pivot_is_reported_as_uncertified" -q

Regression example · domain errors

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_domain_errors() -> None:
    with pytest.raises(ValueError, match="two-dimensional"):
        interval_ldlt_inertia_array(IntervalArray.point([1.0, 2.0]))
    with pytest.raises(ValueError, match="non-empty square"):
        interval_ldlt_inertia_array(IntervalArray.point([[1.0, 2.0]]))
    with pytest.raises(ValueError, match="non-empty square"):
        interval_ldlt_pivots_array(IntervalArray.point(np.zeros((0, 0))))
    with pytest.raises(ValueError, match="two-dimensional"):
        interval_ldlt_factor_array(IntervalArray.point(np.zeros((2, 2, 2))))

python -m pytest packages/omnibias-core/tests/verified/test_linalg_array.py -k test_domain_errors -q

Read the implementation

def interval_ldlt_factor_array(matrix: IntervalArrayLike) -> IntervalLDLT | None:
    r"""Certified interval ``LDL^T`` of a symmetric matrix box (or ``None``).

    The vectorized twin of
    :func:`~omnibias.core.verified.eig_operator.interval_ldlt_factor`.  Returns
    ``None`` as soon as a pivot interval straddles ``0``, because the pivot sign
    -- and therefore the inertia of the box -- cannot be certified there.
    """
    factor = _ldlt_endpoints(*_square_endpoints(matrix))
    if factor is None:
        return None
    lower_lo, lower_hi, pivot_lo, pivot_hi = factor
    return IntervalLDLT(
        lower=IntervalArray(lower_lo, lower_hi),
        diagonal=IntervalArray(pivot_lo, pivot_hi),
    )

Related APIsomnibias.core.verified.IntervalArray↗omnibias.core.verified.IntervalLDLT↗

Other public import paths

• omnibias.core.verified.interval_ldlt_factor_array
• omnibias.core.verified.linalg_array.interval_ldlt_factor_array

FUNCTION

interval_ldlt_inertia_array

omnibias.core.verified.interval_ldlt_inertia_arraySource ↗

interval_ldlt_inertia_array(matrix: IntervalArrayLike) -> Inertia | None

Certified inertia of a symmetric matrix box via vectorized LDL^T.

Returns the same ~omnibias.core.verified.eig_operator.Inertia the scalar ~omnibias.core.verified.eig_operator.interval_ldlt_inertia reports, or None when a pivot straddles 0. Every symmetric point matrix in the box shares the returned signature.

Parameters

Name	Type & default	Contract
matrixpositional-or-keyword	IntervalArrayLikeRequired	See the operation contract and implementation below.

ReturnsInertia | None

Executed regression · straddling pivot is reported as uncertified

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_straddling_pivot_is_reported_as_uncertified() -> None:
    """A box that contains a singular matrix cannot certify an inertia."""
    box = IntervalArray([[-0.5, 1.0], [1.0, 3.0]], [[0.5, 1.0], [1.0, 3.0]])
    assert interval_ldlt_inertia_array(box) is None
    assert interval_ldlt_pivots_array(box) is None
    assert interval_ldlt_factor_array(box) is None
    assert is_positive_definite_array(box) is False
    assert interval_ldlt_inertia(_scalar_matrix(box)) is None

python -m pytest "packages/omnibias-core/tests/verified/test_linalg_array.py::test_straddling_pivot_is_reported_as_uncertified" -q

Regression example · domain errors

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_domain_errors() -> None:
    with pytest.raises(ValueError, match="two-dimensional"):
        interval_ldlt_inertia_array(IntervalArray.point([1.0, 2.0]))
    with pytest.raises(ValueError, match="non-empty square"):
        interval_ldlt_inertia_array(IntervalArray.point([[1.0, 2.0]]))
    with pytest.raises(ValueError, match="non-empty square"):
        interval_ldlt_pivots_array(IntervalArray.point(np.zeros((0, 0))))
    with pytest.raises(ValueError, match="two-dimensional"):
        interval_ldlt_factor_array(IntervalArray.point(np.zeros((2, 2, 2))))

python -m pytest packages/omnibias-core/tests/verified/test_linalg_array.py -k test_domain_errors -q

Read the implementation

def interval_ldlt_inertia_array(matrix: IntervalArrayLike) -> Inertia | None:
    r"""Certified inertia of a symmetric matrix box via vectorized ``LDL^T``.

    Returns the same :class:`~omnibias.core.verified.eig_operator.Inertia` the
    scalar :func:`~omnibias.core.verified.eig_operator.interval_ldlt_inertia`
    reports, or ``None`` when a pivot straddles ``0``.  Every symmetric point
    matrix in the box shares the returned signature.
    """
    factor = _ldlt_endpoints(*_square_endpoints(matrix))
    if factor is None:
        return None
    _, _, pivot_lo, pivot_hi = factor
    midpoint = 0.5 * (pivot_lo + pivot_hi)
    midpoint = cast(FloatArray, np.minimum(np.maximum(midpoint, pivot_lo), pivot_hi))
    negative = int(np.count_nonzero(pivot_hi < 0.0))
    return Inertia(
        negative=negative,
        positive=pivot_lo.shape[0] - negative,
        pivots=tuple(float(value) for value in midpoint),
    )

Related APIsomnibias.core.verified.Inertia↗

Other public import paths

• omnibias.core.verified.interval_ldlt_inertia_array
• omnibias.core.verified.linalg_array.interval_ldlt_inertia_array

FUNCTION

interval_ldlt_pivots_array

omnibias.core.verified.interval_ldlt_pivots_arraySource ↗

interval_ldlt_pivots_array(matrix: IntervalArrayLike) -> IntervalArray | None

Certified interval LDL^T pivots of a symmetric matrix box (or None).

The vectorized twin of ~omnibias.core.verified.eig_operator.interval_ldlt_pivots: the length-n pivot vector D_jj in order. The box is certified positive definite exactly when the result is not None and every pivot has lo > 0.

Parameters

Name	Type & default	Contract
matrixpositional-or-keyword	IntervalArrayLikeRequired	See the operation contract and implementation below.

ReturnsIntervalArray | None

Executed regression · wide box around a definite matrix loses definiteness

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_wide_box_around_a_definite_matrix_loses_definiteness() -> None:
    """Widening a certified box eventually returns an honest inconclusive."""
    center = np.array([[1.0, 0.0], [0.0, 1.0]])
    assert is_positive_definite_array(_symmetric_box(center, 0.25)) is True
    assert is_positive_definite_array(_symmetric_box(center, 4.0)) is False

python -m pytest "packages/omnibias-core/tests/verified/test_linalg_array.py::test_wide_box_around_a_definite_matrix_loses_definiteness" -q

Regression example · straddling pivot is reported as uncertified

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_straddling_pivot_is_reported_as_uncertified() -> None:
    """A box that contains a singular matrix cannot certify an inertia."""
    box = IntervalArray([[-0.5, 1.0], [1.0, 3.0]], [[0.5, 1.0], [1.0, 3.0]])
    assert interval_ldlt_inertia_array(box) is None
    assert interval_ldlt_pivots_array(box) is None
    assert interval_ldlt_factor_array(box) is None
    assert is_positive_definite_array(box) is False
    assert interval_ldlt_inertia(_scalar_matrix(box)) is None

python -m pytest packages/omnibias-core/tests/verified/test_linalg_array.py -k test_straddling_pivot_is_reported_as_uncertified -q

Read the implementation

def interval_ldlt_pivots_array(matrix: IntervalArrayLike) -> IntervalArray | None:
    r"""Certified interval ``LDL^T`` pivots of a symmetric matrix box (or ``None``).

    The vectorized twin of
    :func:`~omnibias.core.verified.eig_operator.interval_ldlt_pivots`: the
    length-``n`` pivot vector ``D_jj`` in order.  The box is certified positive
    definite exactly when the result is not ``None`` and every pivot has
    ``lo > 0``.
    """
    factor = _ldlt_endpoints(*_square_endpoints(matrix))
    return None if factor is None else IntervalArray(factor[2], factor[3])

Related APIsomnibias.core.verified.IntervalArray↗

Other public import paths

• omnibias.core.verified.interval_ldlt_pivots_array
• omnibias.core.verified.linalg_array.interval_ldlt_pivots_array

FUNCTION

is_positive_definite_array

omnibias.core.verified.is_positive_definite_arraySource ↗

is_positive_definite_array(matrix: IntervalArrayLike) -> bool

True iff a symmetric matrix box is *certified* positive definite.

Parameters

Name	Type & default	Contract
matrixpositional-or-keyword	IntervalArrayLikeRequired	See the operation contract and implementation below.

Returnsbool

Executed regression · wide box around a definite matrix loses definiteness

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_wide_box_around_a_definite_matrix_loses_definiteness() -> None:
    """Widening a certified box eventually returns an honest inconclusive."""
    center = np.array([[1.0, 0.0], [0.0, 1.0]])
    assert is_positive_definite_array(_symmetric_box(center, 0.25)) is True
    assert is_positive_definite_array(_symmetric_box(center, 4.0)) is False

python -m pytest "packages/omnibias-core/tests/verified/test_linalg_array.py::test_wide_box_around_a_definite_matrix_loses_definiteness" -q

Regression example · straddling pivot is reported as uncertified

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_straddling_pivot_is_reported_as_uncertified() -> None:
    """A box that contains a singular matrix cannot certify an inertia."""
    box = IntervalArray([[-0.5, 1.0], [1.0, 3.0]], [[0.5, 1.0], [1.0, 3.0]])
    assert interval_ldlt_inertia_array(box) is None
    assert interval_ldlt_pivots_array(box) is None
    assert interval_ldlt_factor_array(box) is None
    assert is_positive_definite_array(box) is False
    assert interval_ldlt_inertia(_scalar_matrix(box)) is None

python -m pytest packages/omnibias-core/tests/verified/test_linalg_array.py -k test_straddling_pivot_is_reported_as_uncertified -q

Read the implementation

def is_positive_definite_array(matrix: IntervalArrayLike) -> bool:
    """``True`` iff a symmetric matrix box is *certified* positive definite."""
    pivots = interval_ldlt_pivots_array(matrix)
    return pivots is not None and bool(np.all(pivots.lo > 0.0))

Related APIsomnibias.core.verified.interval_ldlt_pivots_array↗

Other public import paths

• omnibias.core.verified.is_positive_definite_array
• omnibias.core.verified.linalg_array.is_positive_definite_array

← Package overviewRunnable learning examples →