API REFERENCE/omnibias-partition

omnibias.partition.certify

0.1.0a2AlphaPython >=3.10AGPL / commercial

Trainable soft partitions of unity, regional experts, temperature hardening, and scoped membership bounds.

import omnibias.partition.certify

Module contract & mathematical conventions

Sound certificate for a soft partition of unity.

certify_partition_gap bundles the certified **soft->hard collapse** guarantees a partition can *earn* (not just assert) as beta -> inf:

• a sound per-sample **L1 membership gap** bound sum_l |w_soft_l - w_hard_l| (via the outward-rounded total-variation argument in omnibias.partition._core.verified), aggregated to its max / mean over a sample set, with the measured value for the is_sound self-check;
• the closed-form log(n_regions)/beta Gibbs-to-Dirac scale as a reference.

Honesty (the discrete consumers' yes-if framing): the bound is a genuine sound enclosure of the collapse gap, never an exact-optimality claim, and the gap is never asserted zero.

Terminology: the beta -> inf gate hardening is the feasibility / temperature sense of "collapse", distinct from the **founding bias collapse** (the multi-bias delta -> 0 limit to sigma^(K-1); see docs/derivatives.md).

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

PartitionGapCertificate

omnibias.partition.PartitionGapCertificateSource ↗

class PartitionGapCertificate

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 bound on the soft->hard partition-of-unity gap as beta -> inf.

Parameters

Name	Type & default	Contract
betadataclass field	floatRequired	See the operation contract and implementation below.
n_regionsdataclass field	intRequired	See the operation contract and implementation below.
max_gapdataclass field	floatRequired	See the operation contract and implementation below.
mean_gapdataclass field	floatRequired	See the operation contract and implementation below.
measured_maxdataclass field	floatRequired	See the operation contract and implementation below.
gibbs_scaledataclass field	floatRequired	See the operation contract and implementation below.

Executed regression · certificate is sound and hardens

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_certificate_is_sound_and_hardens() -> None:
    cfg = PartitionConfig(n_features=3, depth=2, seed=4)
    params = init_params(cfg, rng=2)
    X = np.random.default_rng(5).standard_normal((150, 3))
    lo = certify_partition_gap(params, X, beta=2.0)
    hi = certify_partition_gap(params, X, beta=64.0)
    assert lo.is_sound and hi.is_sound
    assert hi.max_gap <= lo.max_gap + 1e-9  # sharper beta -> smaller certified gap
    assert hi.gibbs_scale < lo.gibbs_scale  # log(n_regions)/beta shrinks with beta

python -m pytest "packages/omnibias-partition/tests/test_certify.py::test_certificate_is_sound_and_hardens" -q

Fields & methods

betafield

beta: float

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

View source ↗

n_regionsfield

n_regions: int

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

View source ↗

max_gapfield

max_gap: float

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

View source ↗

mean_gapfield

mean_gap: float

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

View source ↗

measured_maxfield

measured_max: float

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

View source ↗

gibbs_scalefield

gibbs_scale: float

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

View source ↗

is_soundproperty

is_sound(self) -> bool

The certified bound must dominate the actually-measured L1 gap (self-check).

Returns: bool

Executed regression · certificate is sound and hardens

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_certificate_is_sound_and_hardens() -> None:
    cfg = PartitionConfig(n_features=3, depth=2, seed=4)
    params = init_params(cfg, rng=2)
    X = np.random.default_rng(5).standard_normal((150, 3))
    lo = certify_partition_gap(params, X, beta=2.0)
    hi = certify_partition_gap(params, X, beta=64.0)
    assert lo.is_sound and hi.is_sound
    assert hi.max_gap <= lo.max_gap + 1e-9  # sharper beta -> smaller certified gap
    assert hi.gibbs_scale < lo.gibbs_scale  # log(n_regions)/beta shrinks with beta

python -m pytest "packages/omnibias-partition/tests/test_certify.py::test_certificate_is_sound_and_hardens" -q

Method implementation

    def is_sound(self) -> bool:
        r"""The certified bound must dominate the actually-measured L1 gap (self-check)."""
        return self.max_gap >= self.measured_max - 1e-9

View source ↗

certifiedproperty

certified(self) -> bool

Alias of is_sound (a yes-if verdict: the enclosure holds).

Returns: bool

Method implementation

    def certified(self) -> bool:
        r"""Alias of :attr:`is_sound` (a yes-if verdict: the enclosure holds)."""
        return self.is_sound

View source ↗

Read the implementation

class PartitionGapCertificate:
    r"""A certified bound on the soft->hard partition-of-unity gap as ``beta -> inf``."""

    beta: float
    n_regions: int
    max_gap: float
    mean_gap: float
    measured_max: float
    gibbs_scale: float

    @property
    def is_sound(self) -> bool:
        r"""The certified bound must dominate the actually-measured L1 gap (self-check)."""
        return self.max_gap >= self.measured_max - 1e-9

    @property
    def certified(self) -> bool:
        r"""Alias of :attr:`is_sound` (a yes-if verdict: the enclosure holds)."""
        return self.is_sound

Other public import paths

• omnibias.partition.PartitionGapCertificate
• omnibias.partition.certify.PartitionGapCertificate

FUNCTION

certify_partition_gap

omnibias.partition.certify_partition_gapSource ↗

certify_partition_gap(params: PartitionParams, X: np.ndarray, *, beta: float | None=None) -> PartitionGapCertificate

Certified soft->hard membership gap on the samples X.

Returns a sound per-sample bound on the L1 distance between the soft partition-of-unity weights and their crisp beta -> inf one-hot limit, aggregated to its max / mean over X (with the measured gap for PartitionGapCertificate.is_sound), plus the log(n_regions)/beta Gibbs scale.

Parameters

Name	Type & default	Contract
paramspositional-or-keyword	PartitionParamsRequired	See the operation contract and implementation below.
Xpositional-or-keyword	np.ndarrayRequired	See the operation contract and implementation below.
betakeyword-only	float | NoneDefault: None	See the operation contract and implementation below.

ReturnsPartitionGapCertificate

Executed regression · certificate is sound and hardens

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_certificate_is_sound_and_hardens() -> None:
    cfg = PartitionConfig(n_features=3, depth=2, seed=4)
    params = init_params(cfg, rng=2)
    X = np.random.default_rng(5).standard_normal((150, 3))
    lo = certify_partition_gap(params, X, beta=2.0)
    hi = certify_partition_gap(params, X, beta=64.0)
    assert lo.is_sound and hi.is_sound
    assert hi.max_gap <= lo.max_gap + 1e-9  # sharper beta -> smaller certified gap
    assert hi.gibbs_scale < lo.gibbs_scale  # log(n_regions)/beta shrinks with beta

python -m pytest "packages/omnibias-partition/tests/test_certify.py::test_certificate_is_sound_and_hardens" -q

Read the implementation

def certify_partition_gap(
    params: PartitionParams,
    X: np.ndarray,
    *,
    beta: float | None = None,
) -> PartitionGapCertificate:
    r"""Certified soft->hard membership gap on the samples ``X``.

    Returns a sound per-sample bound on the L1 distance between the soft partition-of-unity
    weights and their crisp ``beta -> inf`` one-hot limit, aggregated to its max / mean over
    ``X`` (with the measured gap for :attr:`PartitionGapCertificate.is_sound`), plus the
    ``log(n_regions)/beta`` Gibbs scale.
    """
    b = float(params.config.beta_final if beta is None else beta)
    bound, measured = weight_rounding_gap(params, X, b)
    return PartitionGapCertificate(
        beta=b,
        n_regions=params.n_regions,
        max_gap=float(bound.max()),
        mean_gap=float(bound.mean()),
        measured_max=float(measured.max()),
        gibbs_scale=gibbs_gap_bound(params.n_regions, b),
    )

Related APIsomnibias.partition.PartitionGapCertificate↗

Other public import paths

• omnibias.partition.certify_partition_gap
• omnibias.partition.certify.certify_partition_gap

← Package overviewRunnable learning examples →