API REFERENCE/omnibias-core

omnibias.core.multipack

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

Module contract & mathematical conventions

Heterogeneous multi-pack Birkhoff support algebra (theory 01-01).

A pack of size K = order + 1 at mean mu collapses under the founding bias collapse delta -> 0 to sigma^(order)(z + mu). Several packs at distinct means give a scattered Birkhoff sample of sigma along one transverse coordinate:

F(z) -> sum_g c_g * sigma^(n_g)(z + mu_g)

This module is pure Python: specs, the Polya screen, the incidence matrix, and a numerical rank test for poisedness. Tensor evaluation lives in the torch / jax twins.

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

MultiPackSpec

omnibias.core.MultiPackSpecSource ↗

class MultiPackSpec

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.

An unordered collection of packs forming a Birkhoff support.

Parameters

Name	Type & default	Contract
packsdataclass field	tuple[PackSpec, ...]Required	See the operation contract and implementation below.

Executed regression · polya failure is not poised

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_polya_failure_is_not_poised() -> None:
    spec = MultiPackSpec.from_packs((PackSpec(order=2, mean=0.0),))
    obl = poisedness_obligation(spec)
    assert obl.holds is False
    assert obl.payload["type"] == PAYLOAD_POISEDNESS

python -m pytest "packages/omnibias-core/tests/test_rational_stencil.py::test_polya_failure_is_not_poised" -q

Regression example · unpoised gap returns false

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_unpoised_gap_returns_false() -> None:
    """Orders {0, 2} at one node: Polya fails -> is_poised is False (G5)."""
    spec = MultiPackSpec((PackSpec(0, 0.0), PackSpec(2, 0.0)))
    assert polya_condition(spec) is False
    assert is_poised(spec) is False

python -m pytest packages/omnibias-core/tests/test_multipack.py -k test_unpoised_gap_returns_false -q

Fields & methods

packsfield

packs: tuple[PackSpec, ...]

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

Regression example · g2 collapse no closed form growth

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_g2_collapse_no_closed_form_growth() -> None:
    """Closed form stable as delta shrinks; FD error grows then breaks."""
    from omnibias.torch.multipack import MultiPackUnit

    torch.set_default_dtype(torch.float64)
    spec = MultiPackSpec((PackSpec(1, -0.5, 1.0), PackSpec(2, 0.5, 0.25)))
    unit = MultiPackUnit(
        1, spec, base="tanh", learnable_means=False, learnable_weights=False
    )
    z0 = 0.0
    closed = float(unit(torch.tensor([[z0]], dtype=torch.float64)).item())
    deltas = [1e-2, 1e-3, 1e-4, 1e-5, 1e-6]
    fd_errs = []
    for delta in deltas:
        acc = 0.0
        for p in spec.packs:
            offsets, signs = central_stencil_weights(p.order, delta)
            for off, s in zip(offsets, signs, strict=True):
                acc += p.weight * s * math.tanh(z0 + p.mean + off)
        fd_errs.append(abs(acc - closed))
    assert fd_errs[0] > fd_errs[2] or fd_errs[2] < 1e-8
    closed2 = float(unit(torch.tensor([[z0]], dtype=torch.float64)).item())
    assert closed2 == closed
    assert fd_errs[-1] > fd_errs[2]

python -m pytest tests/test_multipack_parity.py -k test_g2_collapse_no_closed_form_growth -q

View source ↗

__post_init__method

__post_init__(self) -> None

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

Returns: None

Validation & failure cases

• When not packs, raises ValueError('MultiPackSpec requires at least one pack').

Executed regression · polya failure is not poised

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_polya_failure_is_not_poised() -> None:
    spec = MultiPackSpec.from_packs((PackSpec(order=2, mean=0.0),))
    obl = poisedness_obligation(spec)
    assert obl.holds is False
    assert obl.payload["type"] == PAYLOAD_POISEDNESS

python -m pytest "packages/omnibias-core/tests/test_rational_stencil.py::test_polya_failure_is_not_poised" -q

Method implementation

    def __post_init__(self) -> None:
        packs = tuple(self.packs)
        if not packs:
            raise ValueError("MultiPackSpec requires at least one pack")
        object.__setattr__(self, "packs", packs)

View source ↗

from_packsmethod

from_packs(cls, packs: Sequence[PackSpec]) -> MultiPackSpec

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

Parameters

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

Returns: MultiPackSpec

Executed regression · polya failure is not poised

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_polya_failure_is_not_poised() -> None:
    spec = MultiPackSpec.from_packs((PackSpec(order=2, mean=0.0),))
    obl = poisedness_obligation(spec)
    assert obl.holds is False
    assert obl.payload["type"] == PAYLOAD_POISEDNESS

python -m pytest "packages/omnibias-core/tests/test_rational_stencil.py::test_polya_failure_is_not_poised" -q

Method implementation

    def from_packs(cls, packs: Sequence[PackSpec]) -> MultiPackSpec:
        return cls(tuple(packs))

View source ↗

distinct_meansproperty

distinct_means(self) -> tuple[float, ...]

Means in first-appearance order (exact float identity).

Returns: tuple[float, ...]

Executed regression · polya failure is not poised

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_polya_failure_is_not_poised() -> None:
    spec = MultiPackSpec.from_packs((PackSpec(order=2, mean=0.0),))
    obl = poisedness_obligation(spec)
    assert obl.holds is False
    assert obl.payload["type"] == PAYLOAD_POISEDNESS

python -m pytest "packages/omnibias-core/tests/test_rational_stencil.py::test_polya_failure_is_not_poised" -q

Method implementation

    def distinct_means(self) -> tuple[float, ...]:
        """Means in first-appearance order (exact float identity)."""
        seen: list[float] = []
        for p in self.packs:
            if p.mean not in seen:
                seen.append(p.mean)
        return tuple(seen)

View source ↗

max_orderproperty

max_order(self) -> int

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

Returns: int

Executed regression · polya failure is not poised

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_polya_failure_is_not_poised() -> None:
    spec = MultiPackSpec.from_packs((PackSpec(order=2, mean=0.0),))
    obl = poisedness_obligation(spec)
    assert obl.holds is False
    assert obl.payload["type"] == PAYLOAD_POISEDNESS

python -m pytest "packages/omnibias-core/tests/test_rational_stencil.py::test_polya_failure_is_not_poised" -q

Method implementation

    def max_order(self) -> int:
        return max(p.order for p in self.packs)

View source ↗

n_conditionsproperty

n_conditions(self) -> int

Number of (mean, order) incidence ones (duplicate pairs count once).

Returns: int

Method implementation

    def n_conditions(self) -> int:
        """Number of (mean, order) incidence ones (duplicate pairs count once)."""
        return sum(sum(row) for row in incidence_matrix(self))

View source ↗

Read the implementation

class MultiPackSpec:
    """An unordered collection of packs forming a Birkhoff support."""

    packs: tuple[PackSpec, ...]

    def __post_init__(self) -> None:
        packs = tuple(self.packs)
        if not packs:
            raise ValueError("MultiPackSpec requires at least one pack")
        object.__setattr__(self, "packs", packs)

    @classmethod
    def from_packs(cls, packs: Sequence[PackSpec]) -> MultiPackSpec:
        return cls(tuple(packs))

    @property
    def distinct_means(self) -> tuple[float, ...]:
        """Means in first-appearance order (exact float identity)."""
        seen: list[float] = []
        for p in self.packs:
            if p.mean not in seen:
                seen.append(p.mean)
        return tuple(seen)

    @property
    def max_order(self) -> int:
        return max(p.order for p in self.packs)

    @property
    def n_conditions(self) -> int:
        """Number of (mean, order) incidence ones (duplicate pairs count once)."""
        return sum(sum(row) for row in incidence_matrix(self))

Related APIsomnibias.core.incidence_matrix↗

Other public import paths

• omnibias.core.MultiPackSpec
• omnibias.core.multipack.MultiPackSpec
• omnibias.jax.multipack.MultiPackSpec
• omnibias.torch.multipack.MultiPackSpec

CLASS

PackSpec

omnibias.core.PackSpecSource ↗

class PackSpec

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.

One pack: derivative order n, mean mu, outer weight c.

Parameters

Name	Type & default	Contract
orderdataclass field	intRequired	See the operation contract and implementation below.
meandataclass field	floatRequired	See the operation contract and implementation below.
weightdataclass field	floatDefault: 1.0	See the operation contract and implementation below.

Executed regression · pack rejects negative order

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_pack_rejects_negative_order() -> None:
    with pytest.raises(ValueError, match="order"):
        PackSpec(order=-1, mean=0.0)

python -m pytest "packages/omnibias-core/tests/test_multipack.py::test_pack_rejects_negative_order" -q

Regression example · negative order raises

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_negative_order_raises() -> None:
    with pytest.raises(ValueError):
        PackSpec(-1, 0.0)

python -m pytest tests/test_multipack_parity.py -k test_negative_order_raises -q

Fields & methods

orderfield

order: int

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

Regression example · pack spec roundtrip

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_pack_spec_roundtrip() -> None:
    spec = PackSpec(order=2, mean=-0.25, weight=0.5)
    pack = RefinedPack.from_pack_spec(spec, scale=3.0)
    assert pack.center == pytest.approx(0.25)
    assert pack.to_pack_spec().mean == pytest.approx(spec.mean)
    assert pack.to_pack_spec().order == spec.order

python -m pytest packages/omnibias-core/tests/test_refine.py -k test_pack_spec_roundtrip -q

View source ↗

meanfield

mean: float

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

Regression example · pack spec roundtrip

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_pack_spec_roundtrip() -> None:
    spec = PackSpec(order=2, mean=-0.25, weight=0.5)
    pack = RefinedPack.from_pack_spec(spec, scale=3.0)
    assert pack.center == pytest.approx(0.25)
    assert pack.to_pack_spec().mean == pytest.approx(spec.mean)
    assert pack.to_pack_spec().order == spec.order

python -m pytest packages/omnibias-core/tests/test_refine.py -k test_pack_spec_roundtrip -q

View source ↗

weightfield

weight: float = 1.0

Declared float field on PackSpec. Default expression: 1.0.

View source ↗

__post_init__method

__post_init__(self) -> None

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

Returns: None

Validation & failure cases

• When int(self.order) < 0, raises ValueError(f'order must be >= 0, got {self.order}').
• When not np.isfinite(self.mean), raises ValueError(f'mean must be finite, got {self.mean}').
• When not np.isfinite(self.weight), raises ValueError(f'weight must be finite, got {self.weight}').

Executed regression · pack rejects negative order

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_pack_rejects_negative_order() -> None:
    with pytest.raises(ValueError, match="order"):
        PackSpec(order=-1, mean=0.0)

python -m pytest "packages/omnibias-core/tests/test_multipack.py::test_pack_rejects_negative_order" -q

Method implementation

    def __post_init__(self) -> None:
        if int(self.order) < 0:
            raise ValueError(f"order must be >= 0, got {self.order}")
        if not np.isfinite(self.mean):
            raise ValueError(f"mean must be finite, got {self.mean}")
        if not np.isfinite(self.weight):
            raise ValueError(f"weight must be finite, got {self.weight}")
        object.__setattr__(self, "order", int(self.order))
        object.__setattr__(self, "mean", float(self.mean))
        object.__setattr__(self, "weight", float(self.weight))

View source ↗

arityproperty

arity(self) -> int

Number of biases in the pack: K = order + 1.

Returns: int

Method implementation

    def arity(self) -> int:
        """Number of biases in the pack: ``K = order + 1``."""
        return self.order + 1

View source ↗

Read the implementation

class PackSpec:
    """One pack: derivative order ``n``, mean ``mu``, outer weight ``c``."""

    order: int
    mean: float
    weight: float = 1.0

    def __post_init__(self) -> None:
        if int(self.order) < 0:
            raise ValueError(f"order must be >= 0, got {self.order}")
        if not np.isfinite(self.mean):
            raise ValueError(f"mean must be finite, got {self.mean}")
        if not np.isfinite(self.weight):
            raise ValueError(f"weight must be finite, got {self.weight}")
        object.__setattr__(self, "order", int(self.order))
        object.__setattr__(self, "mean", float(self.mean))
        object.__setattr__(self, "weight", float(self.weight))

    @property
    def arity(self) -> int:
        """Number of biases in the pack: ``K = order + 1``."""
        return self.order + 1

Other public import paths

• omnibias.core.PackSpec
• omnibias.core.multipack.PackSpec
• omnibias.jax.multipack.PackSpec
• omnibias.torch.multipack.PackSpec

FUNCTION

central_stencil_weights

omnibias.core.central_stencil_weightsSource ↗

central_stencil_weights(order: int, delta: float) -> tuple[tuple[float, ...], tuple[float, ...]]

Central finite-difference biases and signs for a single pack.

Biases: mu-relative offsets (k - (K+1)/2) * delta for k = 1..K. Signs: (-1)^{K-k} C(K-1, k-1) / delta^{K-1} with K = order + 1.

Returns offsets (add mu for absolute biases) and signs. Used by the G2 collapse check; the closed-form path never divides by delta.

Parameters

Name	Type & default	Contract
orderpositional-or-keyword	intRequired	See the operation contract and implementation below.
deltapositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnstuple[tuple[float, ...], tuple[float, ...]]

Explicit validation & failure cases

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

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

Executed regression · central stencil k2

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_central_stencil_k2() -> None:
    offsets, signs = central_stencil_weights(1, 1e-3)
    assert len(offsets) == 2
    assert offsets[0] == pytest.approx(-5e-4)
    assert offsets[1] == pytest.approx(5e-4)
    assert signs[0] == pytest.approx(-1.0 / 1e-3)
    assert signs[1] == pytest.approx(1.0 / 1e-3)

python -m pytest "packages/omnibias-core/tests/test_multipack.py::test_central_stencil_k2" -q

Regression example · g2 collapse no closed form growth

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_g2_collapse_no_closed_form_growth() -> None:
    """Closed form stable as delta shrinks; FD error grows then breaks."""
    from omnibias.torch.multipack import MultiPackUnit

    torch.set_default_dtype(torch.float64)
    spec = MultiPackSpec((PackSpec(1, -0.5, 1.0), PackSpec(2, 0.5, 0.25)))
    unit = MultiPackUnit(
        1, spec, base="tanh", learnable_means=False, learnable_weights=False
    )
    z0 = 0.0
    closed = float(unit(torch.tensor([[z0]], dtype=torch.float64)).item())
    deltas = [1e-2, 1e-3, 1e-4, 1e-5, 1e-6]
    fd_errs = []
    for delta in deltas:
        acc = 0.0
        for p in spec.packs:
            offsets, signs = central_stencil_weights(p.order, delta)
            for off, s in zip(offsets, signs, strict=True):
                acc += p.weight * s * math.tanh(z0 + p.mean + off)
        fd_errs.append(abs(acc - closed))
    assert fd_errs[0] > fd_errs[2] or fd_errs[2] < 1e-8
    closed2 = float(unit(torch.tensor([[z0]], dtype=torch.float64)).item())
    assert closed2 == closed
    assert fd_errs[-1] > fd_errs[2]

python -m pytest tests/test_multipack_parity.py -k test_g2_collapse_no_closed_form_growth -q

Read the implementation

def central_stencil_weights(order: int, delta: float) -> tuple[tuple[float, ...], tuple[float, ...]]:
    """Central finite-difference biases and signs for a single pack.

    Biases: ``mu``-relative offsets ``(k - (K+1)/2) * delta`` for ``k = 1..K``.
    Signs: ``(-1)^{K-k} C(K-1, k-1) / delta^{K-1}`` with ``K = order + 1``.

    Returns offsets (add ``mu`` for absolute biases) and signs. Used by the
    G2 collapse check; the closed-form path never divides by ``delta``.
    """
    if order < 0:
        raise ValueError(f"order must be >= 0, got {order}")
    if delta <= 0.0:
        raise ValueError(f"delta must be > 0, got {delta}")
    K = order + 1
    offsets = tuple((k - (K + 1) / 2.0) * float(delta) for k in range(1, K + 1))
    scale = float(delta) ** (K - 1)
    signs = tuple(
        ((-1.0) ** (K - k)) * float(comb(K - 1, k - 1)) / scale for k in range(1, K + 1)
    )
    return offsets, signs

Other public import paths

• omnibias.core.central_stencil_weights
• omnibias.core.multipack.central_stencil_weights

FUNCTION

incidence_matrix

omnibias.core.incidence_matrixSource ↗

incidence_matrix(spec: MultiPackSpec) -> tuple[tuple[int, ...], ...]

Incidence matrix E: rows = distinct means, columns = orders.

E[i][j] = 1 iff some pack at mean i requests derivative order j. Column count is max_order + 1.

Parameters

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

Returnstuple[tuple[int, ...], ...]

Executed regression · polya failure is not poised

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_polya_failure_is_not_poised() -> None:
    spec = MultiPackSpec.from_packs((PackSpec(order=2, mean=0.0),))
    obl = poisedness_obligation(spec)
    assert obl.holds is False
    assert obl.payload["type"] == PAYLOAD_POISEDNESS

python -m pytest "packages/omnibias-core/tests/test_rational_stencil.py::test_polya_failure_is_not_poised" -q

Regression example · polya and incidence taylor

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_polya_and_incidence_taylor() -> None:
    spec = MultiPackSpec(
        (PackSpec(0, 0.0), PackSpec(1, 0.0), PackSpec(2, 0.0))
    )
    assert incidence_matrix(spec) == ((1, 1, 1),)
    assert polya_condition(spec) is True
    assert is_poised(spec) is True

python -m pytest packages/omnibias-core/tests/test_multipack.py -k test_polya_and_incidence_taylor -q

Read the implementation

def incidence_matrix(spec: MultiPackSpec) -> tuple[tuple[int, ...], ...]:
    """Incidence matrix ``E``: rows = distinct means, columns = orders.

    ``E[i][j] = 1`` iff some pack at mean ``i`` requests derivative order ``j``.
    Column count is ``max_order + 1``.
    """
    means = spec.distinct_means
    n_cols = spec.max_order + 1
    mean_index = {m: i for i, m in enumerate(means)}
    rows = [[0] * n_cols for _ in means]
    for p in spec.packs:
        rows[mean_index[p.mean]][p.order] = 1
    return tuple(tuple(r) for r in rows)

Other public import paths

• omnibias.core.incidence_matrix
• omnibias.core.multipack.incidence_matrix

FUNCTION

is_poised

omnibias.core.is_poisedSource ↗

is_poised(spec: MultiPackSpec, *, tol: float=1e-10) -> bool | None

Numerical poisedness test for the Birkhoff support.

Returns

bool | None False if Polya fails or the Vandermonde is clearly rank-deficient. True if the matrix is clearly full rank. None when the rank test is inconclusive (singular value near tol); callers must not read None as True.

Parameters

Name	Type & default	Contract
specpositional-or-keyword	MultiPackSpecRequired	See the operation contract and implementation below.
tolkeyword-only	floatDefault: 1e-10	See the operation contract and implementation below.

Returnsbool | None

Executed regression · unpoised gap returns false

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_unpoised_gap_returns_false() -> None:
    """Orders {0, 2} at one node: Polya fails -> is_poised is False (G5)."""
    spec = MultiPackSpec((PackSpec(0, 0.0), PackSpec(2, 0.0)))
    assert polya_condition(spec) is False
    assert is_poised(spec) is False

python -m pytest "packages/omnibias-core/tests/test_multipack.py::test_unpoised_gap_returns_false" -q

Regression example · polya and incidence taylor

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_polya_and_incidence_taylor() -> None:
    spec = MultiPackSpec(
        (PackSpec(0, 0.0), PackSpec(1, 0.0), PackSpec(2, 0.0))
    )
    assert incidence_matrix(spec) == ((1, 1, 1),)
    assert polya_condition(spec) is True
    assert is_poised(spec) is True

python -m pytest packages/omnibias-core/tests/test_multipack.py -k test_polya_and_incidence_taylor -q

Read the implementation

def is_poised(spec: MultiPackSpec, *, tol: float = 1e-10) -> bool | None:
    """Numerical poisedness test for the Birkhoff support.

    Returns
    -------
    bool | None
        ``False`` if Polya fails or the Vandermonde is clearly rank-deficient.
        ``True`` if the matrix is clearly full rank.
        ``None`` when the rank test is inconclusive (singular value near
        ``tol``); callers must not read ``None`` as ``True``.
    """
    if not polya_condition(spec):
        return False
    A = _birkhoff_vandermonde(spec)
    m = A.shape[0]
    if m == 0:
        return False
    # Exact 1x1 nonzero is poised; empty already handled.
    try:
        s = np.linalg.svd(A, compute_uv=False)
    except np.linalg.LinAlgError:
        return None
    if s.size == 0:
        return False
    smax = float(s[0])
    smin = float(s[-1])
    if smax == 0.0:
        return False
    # Clear full rank.
    if smin > float(tol) * max(smax, 1.0):
        return True
    # Clear deficiency.
    if smin < float(tol) * float(tol) * max(smax, 1.0):
        return False
    # Near the threshold: inconclusive.
    return None

Related APIsomnibias.core.polya_condition↗

Other public import paths

• omnibias.core.is_poised
• omnibias.core.multipack.is_poised

FUNCTION

polya_condition

omnibias.core.polya_conditionSource ↗

polya_condition(spec: MultiPackSpec) -> bool

Necessary Polya screen on the incidence matrix.

For every j, the sum over the first j + 1 columns is at least j + 1. Failure implies the scheme cannot be poised.

Parameters

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

Returnsbool

Executed regression · unpoised gap returns false

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_unpoised_gap_returns_false() -> None:
    """Orders {0, 2} at one node: Polya fails -> is_poised is False (G5)."""
    spec = MultiPackSpec((PackSpec(0, 0.0), PackSpec(2, 0.0)))
    assert polya_condition(spec) is False
    assert is_poised(spec) is False

python -m pytest "packages/omnibias-core/tests/test_multipack.py::test_unpoised_gap_returns_false" -q

Regression example · polya and incidence taylor

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_polya_and_incidence_taylor() -> None:
    spec = MultiPackSpec(
        (PackSpec(0, 0.0), PackSpec(1, 0.0), PackSpec(2, 0.0))
    )
    assert incidence_matrix(spec) == ((1, 1, 1),)
    assert polya_condition(spec) is True
    assert is_poised(spec) is True

python -m pytest packages/omnibias-core/tests/test_multipack.py -k test_polya_and_incidence_taylor -q

Read the implementation

def polya_condition(spec: MultiPackSpec) -> bool:
    """Necessary Polya screen on the incidence matrix.

    For every ``j``, the sum over the first ``j + 1`` columns is at least
    ``j + 1``. Failure implies the scheme cannot be poised.
    """
    E = incidence_matrix(spec)
    if not E:
        return False
    n_cols = len(E[0])
    for j in range(n_cols):
        total = sum(E[i][k] for i in range(len(E)) for k in range(j + 1))
        if total < j + 1:
            return False
    return True

Related APIsomnibias.core.incidence_matrix↗

Other public import paths

• omnibias.core.polya_condition
• omnibias.core.multipack.polya_condition

← Package overviewRunnable learning examples →