API REFERENCE/omnibias-core

omnibias.core.realization.rank

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.realization.rank

Module contract & mathematical conventions

Operand-bound rational rank and generic polynomial Jacobian rank.

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

ExactRankWitness

omnibias.core.realization.ExactRankWitnessSource ↗

class ExactRankWitness

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 module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
sourcedataclass field	MatrixRequired	See the operation contract and implementation below.
rankdataclass field	intRequired	See the operation contract and implementation below.
leftdataclass field	MatrixRequired	See the operation contract and implementation below.
rightdataclass field	MatrixRequired	See the operation contract and implementation below.
minor_rowsdataclass field	tuple[int, ...]Required	See the operation contract and implementation below.
minor_colsdataclass field	tuple[int, ...]Required	See the operation contract and implementation below.
minor_valuedataclass field	FractionRequired	See the operation contract and implementation below.

Fields & methods

sourcefield

source: Matrix

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

View source ↗

rankfield

rank: int

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

View source ↗

leftfield

left: Matrix

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

View source ↗

rightfield

right: Matrix

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

View source ↗

minor_rowsfield

minor_rows: tuple[int, ...]

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

View source ↗

minor_colsfield

minor_cols: tuple[int, ...]

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

View source ↗

minor_valuefield

minor_value: Fraction

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

View source ↗

verifymethod

verify(self) -> bool

See the class contract above and the exact method implementation below.

Returns: bool

Method implementation

    def verify(self) -> bool:
        if (
            not self.source
            or not self.source[0]
            or type(self.rank) is not int
            or any(len(row) != len(self.source[0]) for row in self.source)
            or any(type(i) is not int for i in (*self.minor_rows, *self.minor_cols))
        ):
            return False
        try:
            for rows in (self.source, self.left, self.right):
                for row in rows:
                    for value in row:
                        rational(value)
            rational(self.minor_value)
        except TypeError:
            return False
        m, n, r = len(self.source), len(self.source[0]), self.rank
        if r < 0 or r > min(m, n):
            return False
        if len(self.left) != m or any(len(row) != r for row in self.left):
            return False
        if len(self.right) != r or any(len(row) != n for row in self.right):
            return False
        if len(self.minor_rows) != r or len(self.minor_cols) != r:
            return False
        if len(set(self.minor_rows)) != r or len(set(self.minor_cols)) != r:
            return False
        if any(i < 0 or i >= m for i in self.minor_rows) or any(
            j < 0 or j >= n for j in self.minor_cols
        ):
            return False
        if any(
            self.source[i][j]
            != sum((self.left[i][k] * self.right[k][j] for k in range(r)), Fraction(0))
            for i in range(m)
            for j in range(n)
        ):
            return False
        d = determinant([[self.source[i][j] for j in self.minor_cols] for i in self.minor_rows])
        return d == self.minor_value and d != 0

View source ↗

Read the implementation

class ExactRankWitness:
    source: Matrix
    rank: int
    left: Matrix
    right: Matrix
    minor_rows: tuple[int, ...]
    minor_cols: tuple[int, ...]
    minor_value: Fraction

    def verify(self) -> bool:
        if (
            not self.source
            or not self.source[0]
            or type(self.rank) is not int
            or any(len(row) != len(self.source[0]) for row in self.source)
            or any(type(i) is not int for i in (*self.minor_rows, *self.minor_cols))
        ):
            return False
        try:
            for rows in (self.source, self.left, self.right):
                for row in rows:
                    for value in row:
                        rational(value)
            rational(self.minor_value)
        except TypeError:
            return False
        m, n, r = len(self.source), len(self.source[0]), self.rank
        if r < 0 or r > min(m, n):
            return False
        if len(self.left) != m or any(len(row) != r for row in self.left):
            return False
        if len(self.right) != r or any(len(row) != n for row in self.right):
            return False
        if len(self.minor_rows) != r or len(self.minor_cols) != r:
            return False
        if len(set(self.minor_rows)) != r or len(set(self.minor_cols)) != r:
            return False
        if any(i < 0 or i >= m for i in self.minor_rows) or any(
            j < 0 or j >= n for j in self.minor_cols
        ):
            return False
        if any(
            self.source[i][j]
            != sum((self.left[i][k] * self.right[k][j] for k in range(r)), Fraction(0))
            for i in range(m)
            for j in range(n)
        ):
            return False
        d = determinant([[self.source[i][j] for j in self.minor_cols] for i in self.minor_rows])
        return d == self.minor_value and d != 0

Related APIsomnibias.core.realization.polynomial.rational↗omnibias.core.realization.rank.determinant↗

Other public import paths

• omnibias.core.realization.ExactRankWitness
• omnibias.core.realization.rank.ExactRankWitness

CLASS

GenericRankReport

omnibias.core.realization.GenericRankReportSource ↗

class GenericRankReport

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 module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
lowerdataclass field	intRequired	See the operation contract and implementation below.
upperdataclass field	intRequired	See the operation contract and implementation below.
sampledataclass field	tuple[Fraction, ...]Required	See the operation contract and implementation below.
sample_witnessdataclass field	ExactRankWitnessRequired	See the operation contract and implementation below.
vanishing_minorsdataclass field	tuple[SparsePolynomial, ...]Required	See the operation contract and implementation below.
completedataclass field	boolRequired	See the operation contract and implementation below.
detaildataclass field	strRequired	See the operation contract and implementation below.

Fields & methods

lowerfield

lower: int

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

View source ↗

upperfield

upper: int

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

View source ↗

samplefield

sample: tuple[Fraction, ...]

Declared tuple[Fraction, ...] field on GenericRankReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

sample_witnessfield

sample_witness: ExactRankWitness

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

View source ↗

vanishing_minorsfield

vanishing_minors: tuple[SparsePolynomial, ...]

Declared tuple[SparsePolynomial, ...] field on GenericRankReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

completefield

complete: bool

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

View source ↗

detailfield

detail: str

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

View source ↗

Read the implementation

class GenericRankReport:
    lower: int
    upper: int
    sample: tuple[Fraction, ...]
    sample_witness: ExactRankWitness
    vanishing_minors: tuple[SparsePolynomial, ...]
    complete: bool
    detail: str

Other public import paths

• omnibias.core.realization.GenericRankReport
• omnibias.core.realization.rank.GenericRankReport

CONSTANT

Matrix

omnibias.core.realization.rank.MatrixSource ↗

Matrix = tuple[tuple[Fraction, ...], ...]

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

Matrix = tuple[tuple[Fraction, ...], ...]

FUNCTION

certify_generic_rank

omnibias.core.realization.certify_generic_rankSource ↗

certify_generic_rank(outputs: Sequence[SparsePolynomial], sample: Sequence[Rational], *, max_minors: int=1000) -> GenericRankReport

Generic rank of a polynomial map, never a global constant-rank claim.

The exact sample minor establishes a lower bound. All next-order minors must vanish identically to close the upper bound. Otherwise report bounds.

Parameters

Name	Type & default	Contract
outputspositional-or-keyword	Sequence[SparsePolynomial]Required	See the operation contract and implementation below.
samplepositional-or-keyword	Sequence[Rational]Required	See the operation contract and implementation below.
max_minorskeyword-only	intDefault: 1000	See the operation contract and implementation below.

ReturnsGenericRankReport

Explicit validation & failure cases

• When not outputs or not sample or any((p.nvars != len(sample) for p in outputs)), raises ValueError('nonempty polynomial map and compatible sample required').

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

Executed regression · binary two output complex closure has full ambient dimension

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_binary_two_output_complex_closure_has_full_ambient_dimension():
    # Full Jacobian rank six independently anchors the full-space ED endpoint.
    source = compile_coefficient_map(PolynomialNetworkSpec.monomial((2, 2, 2)))
    report = certify_generic_rank(source.polynomials, (1, 0, 0, 1, 1, 0, 0, 1))
    assert len(source.polynomials) == 6
    assert report.complete and report.lower == report.upper == 6

python -m pytest "packages/omnibias-core/tests/test_realization_algebra.py::test_binary_two_output_complex_closure_has_full_ambient_dimension" -q

Regression example · generic rank uses symbolic minors not one singular sample

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_generic_rank_uses_symbolic_minors_not_one_singular_sample():
    x = SparsePolynomial.variable(2, 0)
    y = SparsePolynomial.variable(2, 1)
    report = certify_generic_rank((x * x, x * y), (1, 2))
    assert report.complete and report.lower == report.upper == 2
    singular = certify_generic_rank((x * x, x * y), (0, 0))
    assert singular.lower >= 1 and singular.upper == 2
    dependent = certify_generic_rank((x * x, 2 * x * x), (1, 0))
    assert dependent.complete and dependent.lower == dependent.upper == 1

python -m pytest packages/omnibias-core/tests/test_realization_algebra.py -k test_generic_rank_uses_symbolic_minors_not_one_singular_sample -q

Read the implementation

def certify_generic_rank(
    outputs: Sequence[SparsePolynomial], sample: Sequence[Rational], *, max_minors: int = 1000
) -> GenericRankReport:
    """Generic rank of a polynomial map, never a global constant-rank claim.

    The exact sample minor establishes a lower bound. All next-order minors
    must vanish identically to close the upper bound. Otherwise report bounds.
    """
    if not outputs or not sample or any(p.nvars != len(sample) for p in outputs):
        raise ValueError("nonempty polynomial map and compatible sample required")
    jac = tuple(tuple(p.derivative(j) for j in range(len(sample))) for p in outputs)
    witness = certify_matrix_rank([[p.evaluate(sample) for p in row] for row in jac])
    r = witness.rank
    upper = min(len(outputs), len(sample))
    if r == upper:
        return GenericRankReport(
            r, r, tuple(map(rational, sample)), witness, (), True, "nonzero maximal sample minor"
        )
    size = r + 1
    if comb(len(outputs), size) * comb(len(sample), size) > max_minors:
        return GenericRankReport(
            r,
            upper,
            tuple(map(rational, sample)),
            witness,
            (),
            False,
            "symbolic minor budget exceeded",
        )
    zeros: list[SparsePolynomial] = []
    try:
        for rows in combinations(range(len(outputs)), size):
            for cols in combinations(range(len(sample)), size):
                d = polynomial_determinant([[jac[i][j] for j in cols] for i in rows])
                if d.terms:
                    return GenericRankReport(
                        max(r, size),
                        upper,
                        tuple(map(rational, sample)),
                        witness,
                        tuple(zeros),
                        False,
                        "nonzero symbolic minor gives a stronger generic lower bound; choose another sample",
                    )
                zeros.append(d)
    except AlgebraBudgetExceeded as exc:
        return GenericRankReport(
            r, upper, tuple(map(rational, sample)), witness, tuple(zeros), False, str(exc)
        )
    return GenericRankReport(
        r,
        r,
        tuple(map(rational, sample)),
        witness,
        tuple(zeros),
        True,
        "sample lower minor and all next-order polynomial minors",
    )

Related APIsomnibias.core.realization.GenericRankReport↗omnibias.core.realization.certify_matrix_rank↗omnibias.core.realization.rank.polynomial_determinant↗

Other public import paths

• omnibias.core.realization.certify_generic_rank
• omnibias.core.realization.rank.certify_generic_rank

FUNCTION

certify_matrix_rank

omnibias.core.realization.certify_matrix_rankSource ↗

certify_matrix_rank(rows: Sequence[Sequence[Rational]]) -> ExactRankWitness

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
rowspositional-or-keyword	Sequence[Sequence[Rational]]Required	See the operation contract and implementation below.

ReturnsExactRankWitness

Explicit validation & failure cases

• When not result.verify(), raises ArithmeticError('exact rank witness failed replay').

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

Executed regression · resealed rank factor substitution cannot borrow original minor

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_resealed_rank_factor_substitution_cannot_borrow_original_minor():
    certificate = _examples()[2]
    false = deepcopy(certificate)
    false["payload"]["left"][0][0] = [100, 1]
    false = seal_certificate(false)
    assert not verify_replay_certificate(false)
    assert generate_replay_obligation(false) is not None

python -m pytest "packages/omnibias-core/tests/proof/test_realization_replay.py::test_resealed_rank_factor_substitution_cannot_borrow_original_minor" -q

Regression example · source rank factorization and minor

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_source_rank_factorization_and_minor(a, rank):
    witness = certify_matrix_rank(a)
    assert witness.rank == rank and witness.verify()
    changed = (
        tuple(x + (1 if i == 0 else 0) for i, x in enumerate(witness.source[0])),
        *witness.source[1:],
    )
    assert not replace(witness, source=changed).verify()
    assert not replace(witness, minor_value=witness.minor_value + 1).verify()
    assert not replace(witness, source=()).verify()
    assert not replace(witness, source=((Q(1),), ())).verify()
    assert not replace(witness, rank=True).verify()

python -m pytest packages/omnibias-core/tests/test_realization_algebra.py -k test_source_rank_factorization_and_minor -q

Read the implementation

def certify_matrix_rank(rows: Sequence[Sequence[Rational]]) -> ExactRankWitness:
    source = matrix(rows)
    reduced, pivots = rref(source)
    r = len(pivots)
    left = tuple(tuple(row[j] for j in pivots) for row in source)
    right = tuple(tuple(row) for row in reduced[:r])
    if r:
        _, row_pivots = rref(tuple(zip(*left, strict=True)))
        selected = tuple(row_pivots)
    else:
        selected = ()
    minor = determinant([[source[i][j] for j in pivots] for i in selected])
    result = ExactRankWitness(source, r, left, right, selected, tuple(pivots), minor)
    if not result.verify():
        raise ArithmeticError("exact rank witness failed replay")
    return result

Related APIsomnibias.core.proof.lift.rref↗omnibias.core.realization.ExactRankWitness↗omnibias.core.realization.rank.determinant↗omnibias.core.realization.rank.matrix↗

Other public import paths

• omnibias.core.realization.certify_matrix_rank
• omnibias.core.realization.rank.certify_matrix_rank

FUNCTION

determinant

omnibias.core.realization.rank.determinantSource ↗

determinant(rows: Sequence[Sequence[Rational]]) -> Fraction

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
rowspositional-or-keyword	Sequence[Sequence[Rational]]Required	See the operation contract and implementation below.

ReturnsFraction

Explicit validation & failure cases

• When len(a[0]) != n, raises ValueError('determinant requires a square matrix').

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

Executed regression · resealed rank factor substitution cannot borrow original minor

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_resealed_rank_factor_substitution_cannot_borrow_original_minor():
    certificate = _examples()[2]
    false = deepcopy(certificate)
    false["payload"]["left"][0][0] = [100, 1]
    false = seal_certificate(false)
    assert not verify_replay_certificate(false)
    assert generate_replay_obligation(false) is not None

python -m pytest "packages/omnibias-core/tests/proof/test_realization_replay.py::test_resealed_rank_factor_substitution_cannot_borrow_original_minor" -q

Read the implementation

def determinant(rows: Sequence[Sequence[Rational]]) -> Fraction:
    if not rows:
        return Fraction(1)
    a = [list(row) for row in matrix(rows)]
    n = len(a)
    if len(a[0]) != n:
        raise ValueError("determinant requires a square matrix")
    out = Fraction(1)
    for j in range(n):
        pivot = next((i for i in range(j, n) if a[i][j]), None)
        if pivot is None:
            return Fraction(0)
        if pivot != j:
            a[j], a[pivot] = a[pivot], a[j]
            out = -out
        d = a[j][j]
        out *= d
        for i in range(j + 1, n):
            q = a[i][j] / d
            for k in range(j + 1, n):
                a[i][k] -= q * a[j][k]
    return out

Related APIsomnibias.core.realization.rank.matrix↗

FUNCTION

matrix

omnibias.core.realization.rank.matrixSource ↗

matrix(rows: Sequence[Sequence[Rational]]) -> Matrix

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
rowspositional-or-keyword	Sequence[Sequence[Rational]]Required	See the operation contract and implementation below.

ReturnsMatrix

Explicit validation & failure cases

• When not rows or not rows[0] or any((len(row) != len(rows[0]) for row in rows)), raises ValueError('matrix must be nonempty and rectangular').

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

Executed regression · resealed rank factor substitution cannot borrow original minor

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_resealed_rank_factor_substitution_cannot_borrow_original_minor():
    certificate = _examples()[2]
    false = deepcopy(certificate)
    false["payload"]["left"][0][0] = [100, 1]
    false = seal_certificate(false)
    assert not verify_replay_certificate(false)
    assert generate_replay_obligation(false) is not None

python -m pytest "packages/omnibias-core/tests/proof/test_realization_replay.py::test_resealed_rank_factor_substitution_cannot_borrow_original_minor" -q

Read the implementation

def matrix(rows: Sequence[Sequence[Rational]]) -> Matrix:
    if not rows or not rows[0] or any(len(row) != len(rows[0]) for row in rows):
        raise ValueError("matrix must be nonempty and rectangular")
    return tuple(tuple(rational(v) for v in row) for row in rows)

Related APIsomnibias.core.realization.polynomial.rational↗

FUNCTION

polynomial_determinant

omnibias.core.realization.rank.polynomial_determinantSource ↗

polynomial_determinant(rows: Sequence[Sequence[SparsePolynomial]]) -> SparsePolynomial

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
rowspositional-or-keyword	Sequence[Sequence[SparsePolynomial]]Required	See the operation contract and implementation below.

ReturnsSparsePolynomial

Explicit validation & failure cases

• When not rows or any((len(row) != len(rows) for row in rows)), raises ValueError('nonempty square polynomial matrix required').

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

Executed regression · generic rank uses symbolic minors not one singular sample

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_generic_rank_uses_symbolic_minors_not_one_singular_sample():
    x = SparsePolynomial.variable(2, 0)
    y = SparsePolynomial.variable(2, 1)
    report = certify_generic_rank((x * x, x * y), (1, 2))
    assert report.complete and report.lower == report.upper == 2
    singular = certify_generic_rank((x * x, x * y), (0, 0))
    assert singular.lower >= 1 and singular.upper == 2
    dependent = certify_generic_rank((x * x, 2 * x * x), (1, 0))
    assert dependent.complete and dependent.lower == dependent.upper == 1

python -m pytest "packages/omnibias-core/tests/test_realization_algebra.py::test_generic_rank_uses_symbolic_minors_not_one_singular_sample" -q

Read the implementation

def polynomial_determinant(rows: Sequence[Sequence[SparsePolynomial]]) -> SparsePolynomial:
    if not rows or any(len(row) != len(rows) for row in rows):
        raise ValueError("nonempty square polynomial matrix required")
    first = rows[0][0]
    if len(rows) == 1:
        return first
    out = SparsePolynomial.constant(first.nvars, 0, budget=first.budget)
    for j, p in enumerate(rows[0]):
        sub = [[v for k, v in enumerate(row) if k != j] for row in rows[1:]]
        out = out + p * polynomial_determinant(sub) * (-1 if j % 2 else 1)
    return out

← Package overviewRunnable learning examples →