omnibias.core.band_embed

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

Module contract & mathematical conventions

Vectorized soft-binning band / integral embedding (theory 05-03).

Batched lift of the omnibias.core.ftc.ftc_block / OperatorBlock(op="band"|"integral") closed-form window over a *grid* of J interior thresholds t_1 < ... < t_J, padded with t_0 = -inf and t_{J+1} = +inf, giving J + 1 soft bins for one numeric feature:

\mathrm{band}(x, t)_j = \sigma(\beta (x - t_j)) - \sigma(\beta (x - t_{j+1})), \quad j = 0..J

Each pairwise difference is exactly the OperatorBlock(op="band") window sigma(z + b_hi) - sigma(z + b_lo) with z = beta * x, b_hi = -beta t_j, b_lo = -beta t_{j+1} -- this module reuses that formula rather than forking it, batched over the threshold grid instead of a single learned window (spec section 4(e)). The two open bins are finite, closed-form limits of that same substitution (sigma(+-inf) = 1, 0), not literal infinities in the implementation.

Two identities hold **exactly** (not just as beta -> inf), verified as unit tests:

**Telescoping sum**: sum_j band_embed(x, t)_j == 1 for every finite beta > 0 -- a genuine soft partition of unity, not merely a large-beta approximation.
**FTC**: d/dx integral_embed(x, t) == beta * band_embed(x, t) elementwise, since integral_embed is band_embed's closed-form antiderivative (S' = sigma, S = softplus), with an integration constant per open tail chosen so every bin stays finite for finite x (see the module-level derivation in the theory spec, section 4(e)/5(iii)).

beta -> inf hardens each soft bin into a crisp 0/1 indicator of t_j <= x < t_{j+1} -- **temperature collapse** (feasibility sense), not the founding delta -> 0 bias collapse. No founding collapse limit appears in this module.

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 →

CONSTANT

FloatArray

omnibias.core.band_embed.FloatArraySource ↗

FloatArray: TypeAlias = NDArray[np.float64]

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

FloatArray: TypeAlias = NDArray[np.float64]

FUNCTION

band_embed

omnibias.core.band_embed.band_embedSource ↗

band_embed(x: ArrayLike, t: ArrayLike, *, beta: float=1.0) -> FloatArray

Open-tail soft-histogram band embedding over a threshold grid.

band_embed(x, t)[..., j] = sigma(beta*(x - t_j)) - sigma(beta*(x - t_{j+1})), j = 0..J, with t_0 := -inf and t_{J+1} := +inf folded in as the exact limits sigma(+inf) = 1 / sigma(-inf) = 0 (never computed as literal infinities).

Parameters

x : array_like Feature values, any shape. t : array_like Sorted interior thresholds, shape (..., J) with J >= 1 and strictly increasing along the last axis (checked). A shared (J,) grid broadcasts against every entry of x; a (n_features, J) grid broadcasts against x of shape (n, n_features) for a per-feature grid. beta : float, default 1.0 Sharpness. beta -> inf hardens each bin into a crisp indicator of t_j <= x < t_{j+1} (temperature collapse, not founding bias collapse).

Returns

FloatArray Shape x.shape + (J+1,) (broadcast). Each entry lies in (0, 1) and **every row sums to exactly 1** (telescoping; see module docstring), for any beta > 0 -- a genuine soft partition of unity, unlike a finite-window-only band.

Parameters

Name	Type & default	Contract
`x`positional-or-keyword	`ArrayLike`Required	array_like Feature values, any shape.
`t`positional-or-keyword	`ArrayLike`Required	array_like Sorted interior thresholds, shape `(..., J)` with `J >= 1` and strictly increasing along the last axis (checked). A shared `(J,)` grid broadcasts against every entry of `x`; a `(n_features, J)` grid broadcasts against `x` of shape `(n, n_features)` for a per-feature grid.
`beta`keyword-only	`float`Default: 1.0	float, default 1.0 Sharpness. `beta -> inf` hardens each bin into a crisp indicator of `t_j <= x < t_{j+1}` (temperature collapse, not founding bias collapse).

ReturnsFloatArray

Executed regression · band embed rejects empty t

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_band_embed_rejects_empty_t() -> None:
    with pytest.raises(ValueError, match="at least 1 interior threshold"):
        band_embed(np.array([0.0]), np.array([]))

python -m pytest "packages/omnibias-core/tests/test_band_embed.py::test_band_embed_rejects_empty_t" -q

Regression example · band embed rejects non increasing t

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_band_embed_rejects_non_increasing_t() -> None:
    with pytest.raises(ValueError, match="strictly increasing"):
        band_embed(np.array([0.0]), np.array([1.0, 0.5]))

python -m pytest packages/omnibias-core/tests/test_band_embed.py -k test_band_embed_rejects_non_increasing_t -q

Read the implementation

def band_embed(x: ArrayLike, t: ArrayLike, *, beta: float = 1.0) -> FloatArray:
    r"""Open-tail soft-histogram band embedding over a threshold grid.

    ``band_embed(x, t)[..., j] = sigma(beta*(x - t_j)) - sigma(beta*(x - t_{j+1}))``,
    ``j = 0..J``, with ``t_0 := -inf`` and ``t_{J+1} := +inf`` folded in as the
    exact limits ``sigma(+inf) = 1`` / ``sigma(-inf) = 0`` (never computed as
    literal infinities).

    Parameters
    ----------
    x : array_like
        Feature values, any shape.
    t : array_like
        Sorted interior thresholds, shape ``(..., J)`` with ``J >= 1`` and
        strictly increasing along the last axis (checked). A shared
        ``(J,)`` grid broadcasts against every entry of ``x``; a
        ``(n_features, J)`` grid broadcasts against ``x`` of shape
        ``(n, n_features)`` for a per-feature grid.
    beta : float, default 1.0
        Sharpness. ``beta -> inf`` hardens each bin into a crisp indicator of
        ``t_j <= x < t_{j+1}`` (temperature collapse, not founding bias
        collapse).

    Returns
    -------
    FloatArray
        Shape ``x.shape + (J+1,)`` (broadcast). Each entry lies in ``(0, 1)``
        and **every row sums to exactly 1** (telescoping; see module
        docstring), for any ``beta > 0`` -- a genuine soft partition of
        unity, unlike a finite-window-only band.
    """
    xv, tv = _prepare(x, t)
    b = float(beta)
    z = b * (xv[..., np.newaxis] - tv)
    sig = _sigmoid(z)
    lead = np.broadcast_shapes(xv.shape, tv.shape[:-1])
    ones = np.ones(lead + (1,), dtype=np.float64)
    zeros = np.zeros(lead + (1,), dtype=np.float64)
    sig = np.broadcast_to(sig, lead + (tv.shape[-1],))
    padded = np.concatenate([ones, sig, zeros], axis=-1)
    return cast(FloatArray, padded[..., :-1] - padded[..., 1:])

FUNCTION

integral_embed

omnibias.core.band_embed.integral_embedSource ↗

integral_embed(x: ArrayLike, t: ArrayLike, *, beta: float=1.0) -> FloatArray

Closed-form antiderivative twin of band_embed.

d/dx integral_embed(x, t) == beta * band_embed(x, t) exactly (a unit test, not an approximation): each of the J-1 interior bins is the usual finite-window antiderivative S(beta*(x-t_j)) - S(beta*(x-t_{j+1})) (S = softplus, S' = sigma); the two open bins use the integration constant that keeps them finite for finite x -- beta*(x-t_1) - S(beta*(x-t_1)) on the left (matching S(-z) = S(z) - z) and plain S(beta*(x-t_J)) on the right, which is exactly the t_0 -> -inf / t_{J+1} -> +inf limit of the finite window formula, taken without ever evaluating S at infinity.

A second exact identity (telescoping, like band_embed's): sum_j integral_embed(x, t)[..., j] == beta * (x - t_1).

Parameters and shapes match band_embed.

Parameters

Name	Type & default	Contract
`x`positional-or-keyword	`ArrayLike`Required	See the operation contract and implementation below.
`t`positional-or-keyword	`ArrayLike`Required	See the operation contract and implementation below.
`beta`keyword-only	`float`Default: 1.0	See the operation contract and implementation below.

ReturnsFloatArray

Executed regression · integral embed telescoping sum

Full file, imports & fixtures ↗

def test_integral_embed_telescoping_sum() -> None:
    """``sum_j integral_embed(x, t)[j] == beta * (x - t[0])`` exactly."""
    rng = np.random.default_rng(2)
    x = rng.uniform(-5.0, 5.0, size=30)
    t = np.array([-1.5, 0.3, 1.1])
    beta = 2.2
    total = integral_embed(x, t, beta=beta).sum(axis=-1)
    expected = beta * (x - t[0])
    assert np.max(np.abs(total - expected)) < 1e-9

python -m pytest "packages/omnibias-core/tests/test_band_embed.py::test_integral_embed_telescoping_sum" -q

Regression example · integral embed interior bin matches ftc block

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_integral_embed_interior_bin_matches_ftc_block() -> None:
    """The one finite bin of a 2-threshold grid's integral_embed == ftc_block's integral."""
    t_lo, t_hi, beta, x = 0.05, 1.3, 0.8, -1.1
    interior = integral_embed(np.array([x]), np.array([t_lo, t_hi]), beta=beta)[0, 1]
    b_hi = -beta * t_lo
    b_lo = -beta * t_hi
    integral, _deriv, _collapse = ftc_block(beta * x, 1.0, b_lo, b_hi)
    assert abs(float(interior) - integral) < 1e-12

python -m pytest packages/omnibias-core/tests/test_band_embed.py -k test_integral_embed_interior_bin_matches_ftc_block -q

Read the implementation

def integral_embed(x: ArrayLike, t: ArrayLike, *, beta: float = 1.0) -> FloatArray:
    r"""Closed-form antiderivative twin of :func:`band_embed`.

    ``d/dx integral_embed(x, t) == beta * band_embed(x, t)`` exactly
    (a unit test, not an approximation): each of the ``J-1`` interior bins is
    the usual finite-window antiderivative ``S(beta*(x-t_j)) -
    S(beta*(x-t_{j+1}))`` (``S`` = softplus, ``S' = sigma``); the two open
    bins use the integration constant that keeps them finite for finite
    ``x`` -- ``beta*(x-t_1) - S(beta*(x-t_1))`` on the left (matching
    ``S(-z) = S(z) - z``) and plain ``S(beta*(x-t_J))`` on the right, which
    is exactly the ``t_0 -> -inf`` / ``t_{J+1} -> +inf`` limit of the finite
    window formula, taken without ever evaluating ``S`` at infinity.

    A second exact identity (telescoping, like :func:`band_embed`'s):
    ``sum_j integral_embed(x, t)[..., j] == beta * (x - t_1)``.

    Parameters and shapes match :func:`band_embed`.
    """
    xv, tv = _prepare(x, t)
    b = float(beta)
    z = b * (xv[..., np.newaxis] - tv)
    sp = _softplus(z)
    lead = np.broadcast_shapes(xv.shape, tv.shape[:-1])
    sp = np.broadcast_to(sp, lead + (tv.shape[-1],))
    t0 = np.broadcast_to(tv[..., 0], lead)
    bin0 = (b * (xv - t0) - sp[..., 0])[..., np.newaxis]
    zeros = np.zeros(lead + (1,), dtype=np.float64)
    padded = np.concatenate([sp, zeros], axis=-1)
    tail = padded[..., :-1] - padded[..., 1:]
    return cast(FloatArray, np.concatenate([bin0, tail], axis=-1))

FUNCTION

quantile_thresholds

omnibias.core.band_embed.quantile_thresholdsSource ↗

quantile_thresholds(x_ref: ArrayLike, n_bins: int) -> FloatArray

Quantile-spaced interior thresholds from a reference sample.

Returns n_bins - 1 thresholds, the empirical quantiles of x_ref at 1/n_bins, 2/n_bins, ..., (n_bins-1)/n_bins, for the "quantile init" convention used by BandFeatureEmbedder (omnibias.tab.torch.embed) -- feeding these into band_embed gives n_bins open-tail soft bins each holding (at beta -> inf) about 1/n_bins of the reference mass. Degenerate quantile ties (e.g. from a constant or heavily-duplicated reference column) are nudged strictly increasing so every bin stays non-empty.

Parameters

Name	Type & default	Contract
`x_ref`positional-or-keyword	`ArrayLike`Required	See the operation contract and implementation below.
`n_bins`positional-or-keyword	`int`Required	See the operation contract and implementation below.

ReturnsFloatArray

Explicit validation & failure cases

When n_bins < 2, raises ValueError(f'n_bins must be >= 2 (>= 1 interior threshold), got {n_bins}').
When xv.size < 2, raises ValueError('quantile_thresholds needs at least 2 reference points').

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

Executed regression · quantile thresholds rejects bad input

Full file, imports & fixtures ↗

def test_quantile_thresholds_rejects_bad_input() -> None:
    with pytest.raises(ValueError, match="n_bins"):
        quantile_thresholds(np.array([0.0, 1.0]), n_bins=1)
    with pytest.raises(ValueError, match="at least 2"):
        quantile_thresholds(np.array([1.0]), n_bins=3)

python -m pytest "packages/omnibias-core/tests/test_band_embed.py::test_quantile_thresholds_rejects_bad_input" -q

Regression example · band embed range and shape

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_band_embed_range_and_shape() -> None:
    x = np.linspace(-5.0, 5.0, 17)
    t = np.array([-3.0, -1.0, 1.0, 3.0])
    out = band_embed(x, t, beta=1.5)
    assert out.shape == (17, 5)
    assert np.all(out > 0.0) and np.all(out < 1.0)

python -m pytest packages/omnibias-core/tests/test_band_embed.py -k test_band_embed_range_and_shape -q

Read the implementation

def quantile_thresholds(x_ref: ArrayLike, n_bins: int) -> FloatArray:
    """Quantile-spaced interior thresholds from a reference sample.

    Returns ``n_bins - 1`` thresholds, the empirical quantiles of ``x_ref``
    at ``1/n_bins, 2/n_bins, ..., (n_bins-1)/n_bins``, for the "quantile
    init" convention used by ``BandFeatureEmbedder``
    (:mod:`omnibias.tab.torch.embed`) -- feeding these into :func:`band_embed`
    gives ``n_bins`` open-tail soft bins each holding (at ``beta -> inf``)
    about ``1/n_bins`` of the reference mass. Degenerate quantile ties (e.g.
    from a constant or heavily-duplicated reference column) are nudged
    strictly increasing so every bin stays non-empty.
    """
    if n_bins < 2:
        raise ValueError(f"n_bins must be >= 2 (>= 1 interior threshold), got {n_bins}")
    xv = np.asarray(x_ref, dtype=np.float64).reshape(-1)
    if xv.size < 2:
        raise ValueError("quantile_thresholds needs at least 2 reference points")
    qs = np.linspace(0.0, 1.0, n_bins + 1)[1:-1]
    edges = np.quantile(xv, qs)
    eps = 1e-6 * (float(np.max(np.abs(xv))) + 1.0)
    for i in range(1, edges.size):
        if edges[i] <= edges[i - 1]:
            edges[i] = edges[i - 1] + eps
    return edges

← Package overview Runnable learning examples →

omnibias.core.band_embed

FloatArray​

band_embed​

Parameters

integral_embed​

Parameters

quantile_thresholds​

Parameters

FloatArray

band_embed

integral_embed

quantile_thresholds