API REFERENCE/omnibias-core

omnibias.core.realization.membership

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.membership

Module contract & mathematical conventions

Complete real membership for three declared polynomial architecture families.

All classifications are global for the named homogeneous architecture only. The returned parameters/path are replayed against an exact coefficient map.

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

MembershipReport

omnibias.core.realization.MembershipReportSource ↗

class MembershipReport

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
statusdataclass field	Literal['realizable', 'closure_only', 'excluded']Required	See the operation contract and implementation below.
familydataclass field	strRequired	See the operation contract and implementation below.
sourcedataclass field	PolynomialRealizationMapRequired	See the operation contract and implementation below.
targetdataclass field	tuple[Fraction, ...]Required	See the operation contract and implementation below.
witnessdataclass field	RationalRealizationWitness | AlgebraicRealizationWitness | NoneRequired	See the operation contract and implementation below.
closure_pathdataclass field	LaurentClosureWitness | NoneRequired	See the operation contract and implementation below.
detaildataclass field	strRequired	See the operation contract and implementation below.

Fields & methods

statusfield

status: Literal['realizable', 'closure_only', 'excluded']

Declared Literal['realizable', 'closure_only', 'excluded'] field on MembershipReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

familyfield

family: str

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

View source ↗

sourcefield

source: PolynomialRealizationMap

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

View source ↗

targetfield

target: tuple[Fraction, ...]

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

View source ↗

witnessfield

witness: RationalRealizationWitness | AlgebraicRealizationWitness | None

Declared RationalRealizationWitness | AlgebraicRealizationWitness | None field on MembershipReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

closure_pathfield

closure_path: LaurentClosureWitness | None

Declared LaurentClosureWitness | None field on MembershipReport. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

detailfield

detail: str

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

View source ↗

Read the implementation

class MembershipReport:
    status: Literal["realizable", "closure_only", "excluded"]
    family: str
    source: PolynomialRealizationMap
    target: tuple[Fraction, ...]
    witness: RationalRealizationWitness | AlgebraicRealizationWitness | None
    closure_path: LaurentClosureWitness | None
    detail: str

Other public import paths

• omnibias.core.realization.MembershipReport
• omnibias.core.realization.membership.MembershipReport

FUNCTION

classify_binary_quadratic

omnibias.core.realization.classify_binary_quadraticSource ↗

classify_binary_quadratic(coefficients: Sequence[Sequence[Rational]]) -> MembershipReport

Shared two-square units, any output count; rows use (x², xy, y²).

Parameters

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

ReturnsMembershipReport

Explicit validation & failure cases

• When len(c[0]) != 3, raises ValueError('binary quadratic coefficient rows must have three entries').
• When not closure.verify(source), raises ArithmeticError('contact-plane Laurent witness failed').
• When not witness_a.verify(source), raises ArithmeticError('real algebraic square witness failed').

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

Executed regression · random real binary networks are never excluded

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_random_real_binary_networks_are_never_excluded():
    rng = random.Random(802)
    for _ in range(16):
        a, b, c, d = [Q(rng.randrange(-3, 4)) for _ in range(4)]
        rows = []
        for _ in range(3):
            u, v = [Q(rng.randrange(-2, 3)) for _ in range(2)]
            rows.append([u * a * a + v * c * c, 2 * (u * a * b + v * c * d), u * b * b + v * d * d])
        report = classify_binary_quadratic(rows)
        assert report.status == "realizable" and report.witness.verify(report.source)

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

Regression example · portable rational algebraic and closure witnesses bind source

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_portable_rational_algebraic_and_closure_witnesses_bind_source():
    import json

    for report in (
        classify_linear([[1, 2], [0, 1]], (2,)),
        classify_binary_quadratic([[1, 0, 2], [0, 1, 0]]),
        classify_binary_quadratic([[1, 0, 0], [0, 1, 0]]),
    ):
        witness = report.witness or report.closure_path
        payload = json.loads(json.dumps(witness.to_payload()))
        assert witness_from_payload(payload, report.source).verify(report.source)
        payload["target"][0] = [100, 1]
        with pytest.raises(ValueError):
            witness_from_payload(payload, report.source)

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

Read the implementation

def classify_binary_quadratic(coefficients: Sequence[Sequence[Rational]]) -> MembershipReport:
    """Shared two-square units, any output count; rows use (x², xy, y²)."""
    c = matrix(coefficients)
    if len(c[0]) != 3:
        raise ValueError("binary quadratic coefficient rows must have three entries")
    source = compile_coefficient_map(PolynomialNetworkSpec.monomial((2, 2, len(c)), 2))
    target = _target(source, c, ((2, 0), (1, 1), (0, 2)))
    rank = certify_matrix_rank(c)
    if rank.rank > 2:
        return MembershipReport(
            "excluded",
            "binary_quadratic_width2",
            source,
            target,
            None,
            None,
            "coefficient rank exceeds two, including in the closure",
        )
    if rank.rank <= 1:
        row = next((row for row in c if any(row)), (Fraction(0),) * 3)
        d, forms = _signed_squares(((row[0], row[1] / 2), (row[1] / 2, row[2])))
        forms = forms + ((Fraction(0), Fraction(0)),) * (2 - len(forms))
        d = d + (Fraction(0),) * (2 - len(d))
        pivot = next((i for i, x in enumerate(row) if x), None)
        out = [(Fraction(0) if pivot is None else r[pivot] / row[pivot]) for r in c]
        theta = tuple(v for f in forms for v in f) + tuple(scale * v for scale in out for v in d)
        witness = rational_realization_witness(source, theta, target)
        return MembershipReport(
            "realizable",
            "binary_quadratic_width2",
            source,
            target,
            witness,
            None,
            "rank-one output span with rational signed squares",
        )
    b = [c[i] for i in rank.minor_rows]
    m12, m13, m23 = (determinant([[r[i], r[j]] for r in b]) for i, j in ((0, 1), (0, 2), (1, 2)))
    delta = m13 * m13 - m12 * m23
    if delta < 0:
        return MembershipReport(
            "excluded",
            "binary_quadratic_width2",
            source,
            target,
            None,
            None,
            "negative real square-direction discriminant; outside the Euclidean closure",
        )
    if delta == 0:
        u, v = (Fraction(1), m13 / m12) if m12 else (Fraction(0), Fraction(1))
        s, t = (Fraction(0), Fraction(1)) if u else (Fraction(1), Fraction(0))
        basis = ((u * u, 2 * u * v, v * v), (2 * u * s, 2 * (u * t + v * s), 2 * v * t))
        coords = [_row_coordinates(row, basis) for row in c]
        path: tuple[LaurentPolynomial, ...] = (
            LaurentPolynomial({0: u}),
            LaurentPolynomial({0: v}),
            LaurentPolynomial({0: u, 1: s}),
            LaurentPolynomial({0: v, 1: t}),
        )
        path += tuple(
            p
            for a, b0 in coords
            for p in (LaurentPolynomial({0: a, -1: -b0}), LaurentPolynomial({-1: b0}))
        )
        closure = LaurentClosureWitness(source.fingerprint, path, target)
        if not closure.verify(source):
            raise ArithmeticError("contact-plane Laurent witness failed")
        return MembershipReport(
            "closure_only",
            "binary_quadratic_width2",
            source,
            target,
            None,
            closure,
            "rank-two tangent plane has only one square direction; explicit colliding-square limit",
        )
    field = RealAlgebraicField.sqrt(delta)
    one, zero = field.constant(1), field.constant(0)
    if m12:
        forms_a = (
            (one, (field.constant(m13) + field.generator) / m12),
            (one, (field.constant(m13) - field.generator) / m12),
        )
    else:
        forms_a = ((zero, one), (one, field.constant(m23 / (2 * m13))))
    squares = tuple((u * u, 2 * u * v, v * v) for u, v in forms_a)
    pair = next(
        (i, j)
        for i, j in combinations(range(3), 2)
        if not (squares[0][i] * squares[1][j] - squares[0][j] * squares[1][i]).is_zero()
    )
    i, j = pair
    det = squares[0][i] * squares[1][j] - squares[0][j] * squares[1][i]
    out_a: list[AlgebraicNumber] = []
    for row in c:
        out_a.extend(
            (
                (row[i] * squares[1][j] - row[j] * squares[1][i]) / det,
                (row[j] * squares[0][i] - row[i] * squares[0][j]) / det,
            )
        )
    witness_a = AlgebraicRealizationWitness(
        source.fingerprint, field, tuple(v for f in forms_a for v in f) + tuple(out_a), target
    )
    if not witness_a.verify(source):
        raise ArithmeticError("real algebraic square witness failed")
    return MembershipReport(
        "realizable",
        "binary_quadratic_width2",
        source,
        target,
        witness_a,
        None,
        "two distinct real square directions with Sturm-isolated algebraic parameters",
    )

Related APIsomnibias.core.realization.MembershipReport↗omnibias.core.realization.compile_coefficient_map↗omnibias.core.realization.certify_matrix_rank↗omnibias.core.realization.rank.determinant↗omnibias.core.realization.rank.matrix↗omnibias.core.realization.AlgebraicRealizationWitness↗omnibias.core.realization.LaurentClosureWitness↗omnibias.core.realization.LaurentPolynomial↗

Other public import paths

• omnibias.core.realization.classify_binary_quadratic
• omnibias.core.realization.membership.classify_binary_quadratic

FUNCTION

classify_linear

omnibias.core.realization.classify_linearSource ↗

classify_linear(coefficients: Sequence[Sequence[Rational]], hidden_widths: Sequence[int]=()) -> MembershipReport

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
coefficientspositional-or-keyword	Sequence[Sequence[Rational]]Required	See the operation contract and implementation below.
hidden_widthspositional-or-keyword	Sequence[int]Default: ()	See the operation contract and implementation below.

ReturnsMembershipReport

Executed regression · linear membership arbitrary depth

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_linear_membership_arbitrary_depth(hidden):
    report = classify_linear([[1, 2, 3], [-1, 2, 0]], hidden)
    assert report.status == "realizable" and report.witness.verify(report.source)
    assert not replace(report.witness, target=tuple(t + 1 for t in report.target)).verify(
        report.source
    )
    assert classify_linear([[1, 0], [0, 1]], (1, 3)).status == "excluded"

python -m pytest "packages/omnibias-core/tests/test_realization_algebra.py::test_linear_membership_arbitrary_depth[hidden0]" -q

Regression example · portable rational algebraic and closure witnesses bind source

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_portable_rational_algebraic_and_closure_witnesses_bind_source():
    import json

    for report in (
        classify_linear([[1, 2], [0, 1]], (2,)),
        classify_binary_quadratic([[1, 0, 2], [0, 1, 0]]),
        classify_binary_quadratic([[1, 0, 0], [0, 1, 0]]),
    ):
        witness = report.witness or report.closure_path
        payload = json.loads(json.dumps(witness.to_payload()))
        assert witness_from_payload(payload, report.source).verify(report.source)
        payload["target"][0] = [100, 1]
        with pytest.raises(ValueError):
            witness_from_payload(payload, report.source)

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

Read the implementation

def classify_linear(
    coefficients: Sequence[Sequence[Rational]], hidden_widths: Sequence[int] = ()
) -> MembershipReport:
    a = matrix(coefficients)
    dims = (len(a[0]), *hidden_widths, len(a))
    source = compile_coefficient_map(PolynomialNetworkSpec.monomial(dims, 1))
    indices = [tuple(int(i == j) for i in range(dims[0])) for j in range(dims[0])]
    target = _target(source, a, indices)
    rank = certify_matrix_rank(a)
    if rank.rank > min(dims):
        return MembershipReport(
            "excluded",
            "linear",
            source,
            target,
            None,
            None,
            "target rank exceeds the narrowest layer; the rank-bounded image is closed",
        )
    if not hidden_widths:
        theta = tuple(x for row in a for x in row)
    else:
        weights: list[Fraction] = []
        for layer, (n, m) in enumerate(zip(dims[:-1], dims[1:], strict=True)):
            if layer == 0:
                w = [
                    [rank.right[i][j] if i < rank.rank else Fraction(0) for j in range(n)]
                    for i in range(m)
                ]
            elif layer == len(dims) - 2:
                w = [
                    [rank.left[i][j] if j < rank.rank else Fraction(0) for j in range(n)]
                    for i in range(m)
                ]
            else:
                w = [[Fraction(int(i == j and i < rank.rank)) for j in range(n)] for i in range(m)]
            weights.extend(x for row in w for x in row)
        theta = tuple(weights)
    witness = rational_realization_witness(source, theta, target)
    return MembershipReport(
        "realizable",
        "linear",
        source,
        target,
        witness,
        None,
        "exact rank factorization padded through every layer",
    )

Related APIsomnibias.core.realization.MembershipReport↗omnibias.core.realization.compile_coefficient_map↗omnibias.core.realization.certify_matrix_rank↗omnibias.core.realization.rank.matrix↗omnibias.core.realization.rational_realization_witness↗

Other public import paths

• omnibias.core.realization.classify_linear
• omnibias.core.realization.membership.classify_linear

FUNCTION

classify_scalar_quadratic

omnibias.core.realization.classify_scalar_quadraticSource ↗

classify_scalar_quadratic(coefficients: Sequence[Sequence[Rational]], hidden_width: int) -> MembershipReport

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
coefficientspositional-or-keyword	Sequence[Sequence[Rational]]Required	See the operation contract and implementation below.
hidden_widthpositional-or-keyword	intRequired	See the operation contract and implementation below.

ReturnsMembershipReport

Executed regression · scalar quadratic congruence handles zero diagonal and rank

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_scalar_quadratic_congruence_handles_zero_diagonal_and_rank():
    rng = random.Random(529)
    for n in (2, 3, 4):
        for _ in range(7):
            a = [[Q(rng.randrange(-3, 4)) for _ in range(n)] for _ in range(n)]
            a = [[a[min(i, j)][max(i, j)] for j in range(n)] for i in range(n)]
            report = classify_scalar_quadratic(a, n)
            assert report.status == "realizable" and report.witness.verify(report.source)
    assert classify_scalar_quadratic([[0, 1], [1, 0]], 2).witness is not None
    assert classify_scalar_quadratic([[1, 0], [0, 1]], 1).status == "excluded"

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

Regression example · linear membership arbitrary depth

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_linear_membership_arbitrary_depth(hidden):
    report = classify_linear([[1, 2, 3], [-1, 2, 0]], hidden)
    assert report.status == "realizable" and report.witness.verify(report.source)
    assert not replace(report.witness, target=tuple(t + 1 for t in report.target)).verify(
        report.source
    )
    assert classify_linear([[1, 0], [0, 1]], (1, 3)).status == "excluded"

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

Read the implementation

def classify_scalar_quadratic(
    coefficients: Sequence[Sequence[Rational]], hidden_width: int
) -> MembershipReport:
    a = matrix(coefficients)
    values, forms = _signed_squares(a)
    n = len(a)
    source = compile_coefficient_map(PolynomialNetworkSpec.monomial((n, hidden_width, 1), 2))
    coeffs = {}
    for i in range(n):
        for j in range(i, n):
            idx = tuple(int(k == i) + int(k == j) for k in range(n))
            coeffs[idx] = a[i][j] * (1 if i == j else 2)
    target = tuple(coeffs.get(idx, Fraction(0)) for idx in source.input_indices)
    if len(values) > hidden_width:
        return MembershipReport(
            "excluded",
            "scalar_quadratic",
            source,
            target,
            None,
            None,
            "symmetric rank exceeds hidden width; rank-bounded image is closed",
        )
    theta = tuple(x for form in forms for x in form) + (Fraction(0),) * (
        (hidden_width - len(forms)) * n
    )
    theta += values + (Fraction(0),) * (hidden_width - len(values))
    witness = rational_realization_witness(source, theta, target)
    return MembershipReport(
        "realizable",
        "scalar_quadratic",
        source,
        target,
        witness,
        None,
        "exact rational signed-square congruence",
    )

Related APIsomnibias.core.realization.MembershipReport↗omnibias.core.realization.compile_coefficient_map↗omnibias.core.realization.rank.matrix↗omnibias.core.realization.rational_realization_witness↗

Other public import paths

• omnibias.core.realization.classify_scalar_quadratic
• omnibias.core.realization.membership.classify_scalar_quadratic

← Package overviewRunnable learning examples →