API REFERENCE/omnibias-struct

omnibias.struct.torch.select

0.1.0a2AlphaPython >=3.10AGPL / commercial

Differentiable dynamic programs for sequences and parses, structured distributions, and finite-temperature bounds.

import omnibias.struct.torch.select

Module contract & mathematical conventions

Certified argmax / measure-mode collapse: soft selection + Gibbs moments (torch).

Bit-identical twin of omnibias.struct.jax.select (float64). The Gibbs law p_beta(i) ∝ exp(beta s_i) over N logits collapses onto a Dirac at the mode as beta -> inf; certified_argmax pairs the relaxed selection with a sound, closed-form ~omnibias.struct.SelectionCertificate. The moments reuse the closed-form log-sum-exp tower (omnibias.struct.torch._logsumexp): the Gibbs mean is softmax, the covariance is hessian(lse_beta)/beta, and the higher directional cumulants are the exact log-partition jet kappa_m(v_I) = m! * jet_m / beta^m obtained with omnibias.torch.jet.compose_jet -- no autodiff, no finite differences.

**Two axes, never conflated.** The beta -> inf annealing here is the *feasibility / temperature* sense of collapse (the same axis as omnibias-discrete / omnibias-qubo) -- it is **not** the founding delta -> 0 bias collapse. The founding derivative tower is only the exact engine that differentiates lse_beta (softplus^(n) = sigma^(n-1)); do not conflate the two axes.

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 →

Imports & aliases

These names share a definition with another public module. Follow a name for its full contract, parameters, and examples.

Import from this module	Canonical reference
logsumexp_beta	omnibias.struct.torch.logsumexp_beta
softmax_beta	omnibias.struct.torch.softmax_beta

FUNCTION

certified_argmax

omnibias.struct.torch.certified_argmaxSource ↗

certified_argmax(logits: Tensor, beta: float, *, eps: float | None=None) -> tuple[Tensor, SelectionCertificate]

Relaxed selection softmax(beta * logits) plus its SelectionCertificate.

logits must be 1-D (N choices). Returns (soft_output, certificate) where the certificate bounds the beta -> inf Gibbs-to-Dirac collapse in closed form (value gap log(N)/beta, mode-mass concentration, and -- when eps is given -- L^inf argmax-stability margin > 2 eps). The soft output is differentiable; the certificate is a frozen numpy object suitable for ~omnibias.struct.seal_selection_certificate.

Parameters

Name	Type & default	Contract
logitspositional-or-keyword	TensorRequired	See the operation contract and implementation below.
betapositional-or-keyword	floatRequired	See the operation contract and implementation below.
epskeyword-only	float | NoneDefault: None	See the operation contract and implementation below.

Returnstuple[Tensor, SelectionCertificate]

Explicit validation & failure cases

• When lg.ndim != 1, raises ValueError(f'certified_argmax expects 1-D logits (N choices), got shape {tuple(lg.shape)}').

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

Executed regression · layer certificate matches functional

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_layer_certificate_matches_functional() -> None:
    layer = DecisionLayer(beta=8.0, eps=0.05)
    scores = torch.tensor([1.0, -0.5, 0.3], dtype=torch.float64)
    soft, cert = layer.certified(scores)
    assert torch.allclose(soft, layer.forward(scores))
    ref = certified_decision(scores.numpy(), beta=8.0, eps=0.05)
    assert cert.argmax == ref.argmax
    assert math.isclose(cert.gap_bound, ref.gap_bound, rel_tol=1e-12)
    assert math.isclose(cert.p_max, ref.p_max, rel_tol=1e-9)

python -m pytest "packages/omnibias-struct/tests/test_decision_layer.py::test_layer_certificate_matches_functional" -q

Regression example · certified argmax matches core and rejects batched

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_certified_argmax_matches_core_and_rejects_batched() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.struct.torch import select as ts

    s = np.array([2.0, 0.5, -0.3, 1.1])
    soft, cert = ts.certified_argmax(torch.tensor(s, dtype=torch.float64), beta=4.0, eps=0.1)
    assert float(soft.sum()) == pytest.approx(1.0, abs=1e-12)
    ref = certify_argmax(s, 4.0, eps=0.1)
    assert cert.argmax == ref.argmax
    assert cert.p_max == pytest.approx(ref.p_max, rel=RTOL, abs=ATOL)
    with pytest.raises(ValueError):
        ts.certified_argmax(torch.tensor([[1.0, 2.0], [3.0, 4.0]]), beta=1.0)

python -m pytest packages/omnibias-struct/tests/test_select.py -k test_certified_argmax_matches_core_and_rejects_batched -q

Read the implementation

def certified_argmax(
    logits: Tensor, beta: float, *, eps: float | None = None
) -> tuple[Tensor, SelectionCertificate]:
    r"""Relaxed selection ``softmax(beta * logits)`` plus its :class:`SelectionCertificate`.

    ``logits`` must be 1-D (``N`` choices). Returns ``(soft_output, certificate)`` where the
    certificate bounds the ``beta -> inf`` Gibbs-to-Dirac collapse in closed form (value gap
    ``log(N)/beta``, mode-mass concentration, and -- when ``eps`` is given -- ``L^inf``
    argmax-stability ``margin > 2 eps``). The soft output is differentiable; the certificate is
    a frozen numpy object suitable for :func:`~omnibias.struct.seal_selection_certificate`.
    """
    lg = torch.as_tensor(logits)
    if lg.ndim != 1:
        raise ValueError(f"certified_argmax expects 1-D logits (N choices), got shape {tuple(lg.shape)}")
    soft = softmax_beta(lg, beta, axis=-1)
    cert = certify_argmax(lg.detach().cpu().numpy(), beta, eps=eps)
    return soft, cert

Related APIsomnibias.struct.certify_argmax↗omnibias.struct.torch.softmax_beta↗

Other public import paths

• omnibias.struct.torch.certified_argmax
• omnibias.struct.torch.select.certified_argmax

FUNCTION

gibbs_covariance

omnibias.struct.torch.gibbs_covarianceSource ↗

gibbs_covariance(logits: Tensor, beta: float=1.0, *, axis: int=-1) -> Tensor

The Gibbs one-hot covariance diag(p) - p p^T (= hessian(lse_beta) / beta).

Returns a (..., N, N) tensor; the exact second moment of the categorical indicator, obtained in closed form from logsumexp_beta_hessian (never autodiff).

Parameters

Name	Type & default	Contract
logitspositional-or-keyword	TensorRequired	See the operation contract and implementation below.
betapositional-or-keyword	floatDefault: 1.0	See the operation contract and implementation below.
axiskeyword-only	intDefault: -1	See the operation contract and implementation below.

ReturnsTensor

Executed regression · gibbs moments torch vs reference

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_gibbs_moments_torch_vs_reference() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.struct.torch import (
        gibbs_covariance,
        gibbs_cumulants_directional,
        gibbs_mean,
        soft_argmax,
        soft_max_value,
    )

    rng = np.random.default_rng(11)
    s = rng.standard_normal(6)
    v = rng.standard_normal(6)
    beta = 2.3
    st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
    p = _ref_softmax(s, beta)
    assert np.allclose(gibbs_mean(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert np.allclose(soft_argmax(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert soft_max_value(st, beta).item() == pytest.approx(_ref_lse(s, beta), rel=RTOL, abs=ATOL)
    cov = gibbs_covariance(st, beta).numpy()
    assert np.allclose(cov, np.diag(p) - np.outer(p, p), rtol=RTOL, atol=ATOL)
    kappa = gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
    assert np.allclose(kappa, _ref_cumulants(p, v, 4), rtol=1e-7, atol=1e-9)
    assert kappa[0] == pytest.approx(float(p @ v), rel=RTOL, abs=ATOL)  # mean
    assert kappa[1] == pytest.approx(float(v @ cov @ v), rel=RTOL, abs=ATOL)  # variance

python -m pytest "packages/omnibias-struct/tests/test_select.py::test_gibbs_moments_torch_vs_reference" -q

Regression example · select torch jax parity

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_select_torch_jax_parity() -> None:
    torch = pytest.importorskip("torch")
    jax = pytest.importorskip("jax")
    jax.config.update("jax_enable_x64", True)
    import jax.numpy as jnp
    from omnibias.struct.jax import select as js
    from omnibias.struct.torch import select as ts

    for seed in range(6):
        rng = np.random.default_rng(500 + seed)
        # Well-determined instance: a clear margin so the parity tol is not masking a tie.
        s = np.sort(rng.standard_normal(7))[::-1] + np.linspace(0.0, 0.3, 7)[::-1]
        v = rng.standard_normal(7)
        beta = float(rng.uniform(1.0, 12.0))
        st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
        sj, vj = jnp.asarray(s), jnp.asarray(v)

        def close(a, b) -> bool:  # noqa: ANN001
            return bool(np.max(np.abs(np.asarray(a) - np.asarray(b))) < PARITY_TOL)

        assert close(ts.soft_max_value(st, beta).numpy(), js.soft_max_value(sj, beta))
        assert close(ts.soft_argmax(st, beta).numpy(), js.soft_argmax(sj, beta))
        assert close(ts.gibbs_mean(st, beta).numpy(), js.gibbs_mean(sj, beta))
        assert close(ts.gibbs_covariance(st, beta).numpy(), js.gibbs_covariance(sj, beta))
        kt = ts.gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
        kj = np.asarray(js.gibbs_cumulants_directional(sj, vj, beta, order=4))
        assert close(kt, kj)
        soft_t, cert_t = ts.certified_argmax(st, beta, eps=0.05)
        soft_j, cert_j = js.certified_argmax(sj, beta, eps=0.05)
        assert close(soft_t.numpy(), soft_j)
        assert cert_t.argmax == cert_j.argmax
        assert cert_t.p_max_lower == pytest.approx(cert_j.p_max_lower, rel=RTOL, abs=ATOL)

python -m pytest packages/omnibias-struct/tests/test_select.py -k test_select_torch_jax_parity -q

Read the implementation

def gibbs_covariance(logits: Tensor, beta: float = 1.0, *, axis: int = -1) -> Tensor:
    r"""The Gibbs one-hot covariance ``diag(p) - p p^T`` (``= hessian(lse_beta) / beta``).

    Returns a ``(..., N, N)`` tensor; the exact second moment of the categorical indicator,
    obtained in closed form from :func:`logsumexp_beta_hessian` (never autodiff).
    """
    return logsumexp_beta_hessian(logits, beta, axis=axis) / beta

Related APIsomnibias.struct.torch.logsumexp_beta_hessian↗

Other public import paths

• omnibias.struct.torch.gibbs_covariance
• omnibias.struct.torch.select.gibbs_covariance

FUNCTION

gibbs_cumulants_directional

omnibias.struct.torch.gibbs_cumulants_directionalSource ↗

gibbs_cumulants_directional(logits: Tensor, v: Tensor, beta: float=1.0, order: int=1) -> Tensor

Exact cumulants kappa_1..kappa_order of X = v_I under the Gibbs law I ~ p.

kappa_1 = E_p[v_I] = <p, v> (the directional mean), kappa_2 = Var_p(v_I) (= v^T (diag(p) - p p^T) v), and higher cumulants follow. They are the derivatives of the log-partition phi(t) = lse_beta(logits + t v): writing phi(t) = lse_beta(logits) + beta^-1 log sum_i p_i e^{t beta v_i}, the jet of the inner log-sum is composed from the analytic log derivative tower via omnibias.torch.jet.compose_jet (Faà di Bruno), giving kappa_m = m! * F_jet[m] / beta^m exactly -- no autodiff. Reduces over the last axis; returns a (order, ...) tensor (index m-1 holds kappa_m).

Parameters

Name	Type & default	Contract
logitspositional-or-keyword	TensorRequired	See the operation contract and implementation below.
vpositional-or-keyword	TensorRequired	See the operation contract and implementation below.
betapositional-or-keyword	floatDefault: 1.0	See the operation contract and implementation below.
orderpositional-or-keyword	intDefault: 1	See the operation contract and implementation below.

ReturnsTensor

Explicit validation & failure cases

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

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

Executed regression · gibbs cumulants order validation

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_gibbs_cumulants_order_validation() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.struct.torch import gibbs_cumulants_directional

    with pytest.raises(ValueError):
        gibbs_cumulants_directional(torch.tensor([1.0, 2.0]), torch.tensor([0.0, 1.0]), 1.0, order=0)

python -m pytest "packages/omnibias-struct/tests/test_select.py::test_gibbs_cumulants_order_validation" -q

Regression example · gibbs moments torch vs reference

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_gibbs_moments_torch_vs_reference() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.struct.torch import (
        gibbs_covariance,
        gibbs_cumulants_directional,
        gibbs_mean,
        soft_argmax,
        soft_max_value,
    )

    rng = np.random.default_rng(11)
    s = rng.standard_normal(6)
    v = rng.standard_normal(6)
    beta = 2.3
    st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
    p = _ref_softmax(s, beta)
    assert np.allclose(gibbs_mean(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert np.allclose(soft_argmax(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert soft_max_value(st, beta).item() == pytest.approx(_ref_lse(s, beta), rel=RTOL, abs=ATOL)
    cov = gibbs_covariance(st, beta).numpy()
    assert np.allclose(cov, np.diag(p) - np.outer(p, p), rtol=RTOL, atol=ATOL)
    kappa = gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
    assert np.allclose(kappa, _ref_cumulants(p, v, 4), rtol=1e-7, atol=1e-9)
    assert kappa[0] == pytest.approx(float(p @ v), rel=RTOL, abs=ATOL)  # mean
    assert kappa[1] == pytest.approx(float(v @ cov @ v), rel=RTOL, abs=ATOL)  # variance

python -m pytest packages/omnibias-struct/tests/test_select.py -k test_gibbs_moments_torch_vs_reference -q

Read the implementation

def gibbs_cumulants_directional(
    logits: Tensor, v: Tensor, beta: float = 1.0, order: int = 1
) -> Tensor:
    r"""Exact cumulants ``kappa_1..kappa_order`` of ``X = v_I`` under the Gibbs law ``I ~ p``.

    ``kappa_1 = E_p[v_I] = <p, v>`` (the directional mean), ``kappa_2 = Var_p(v_I)``
    (``= v^T (diag(p) - p p^T) v``), and higher cumulants follow. They are the derivatives of
    the log-partition ``phi(t) = lse_beta(logits + t v)``: writing
    ``phi(t) = lse_beta(logits) + beta^-1 log sum_i p_i e^{t beta v_i}``, the jet of the inner
    ``log-sum`` is composed from the analytic ``log`` derivative tower via
    :func:`omnibias.torch.jet.compose_jet` (Faà di Bruno), giving
    ``kappa_m = m! * F_jet[m] / beta^m`` exactly -- no autodiff. Reduces over the last axis;
    returns a ``(order, ...)`` tensor (index ``m-1`` holds ``kappa_m``).
    """
    if order < 1:
        raise ValueError(f"order must be >= 1, got {order}")
    s = torch.as_tensor(logits)
    vv = torch.as_tensor(v)
    p = softmax_beta(s, beta, axis=-1)
    w = beta * vv
    # Inner jet (coefficient form): S_coeffs[k] = sum_i p_i w_i^k / k!  (S(0) = sum_i p_i = 1).
    s_rows = [p.sum(dim=-1)]
    wk = torch.ones_like(w)
    fact = 1.0
    for k in range(1, order + 1):
        wk = wk * w
        fact *= k
        s_rows.append((p * wk).sum(dim=-1) / fact)
    s_coeffs = torch.stack(s_rows, dim=0)
    s0 = s_coeffs[0]
    # Analytic log derivative tower at S0: f^(k)(S0) = (-1)^(k-1) (k-1)! / S0^k (k >= 1).
    log_rows = [torch.log(s0)]
    for k in range(1, order + 1):
        coef = ((-1.0) ** (k - 1)) * math.factorial(k - 1)
        log_rows.append(coef / (s0**k))
    log_tower = torch.stack(log_rows, dim=0)
    f_jet = compose_jet(s_coeffs, log_tower)
    cumulants = [math.factorial(m) * f_jet[m] / (beta**m) for m in range(1, order + 1)]
    return torch.stack(cumulants, dim=0)

Related APIsomnibias.struct.torch.softmax_beta↗omnibias.torch.compose_jet↗

Other public import paths

• omnibias.struct.torch.gibbs_cumulants_directional
• omnibias.struct.torch.select.gibbs_cumulants_directional

FUNCTION

gibbs_mean

omnibias.struct.torch.gibbs_meanSource ↗

gibbs_mean(logits: Tensor, beta: float=1.0, *, axis: int=-1) -> Tensor

The Gibbs law p_i = softmax(beta * logits)_i -- the mean of the one-hot indicator.

Identical tensor to soft_argmax; named for the measure/moment view (it is the gradient of soft_max_value, i.e. E_p[e_i]).

Parameters

Name	Type & default	Contract
logitspositional-or-keyword	TensorRequired	See the operation contract and implementation below.
betapositional-or-keyword	floatDefault: 1.0	See the operation contract and implementation below.
axiskeyword-only	intDefault: -1	See the operation contract and implementation below.

ReturnsTensor

Executed regression · gibbs moments torch vs reference

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_gibbs_moments_torch_vs_reference() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.struct.torch import (
        gibbs_covariance,
        gibbs_cumulants_directional,
        gibbs_mean,
        soft_argmax,
        soft_max_value,
    )

    rng = np.random.default_rng(11)
    s = rng.standard_normal(6)
    v = rng.standard_normal(6)
    beta = 2.3
    st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
    p = _ref_softmax(s, beta)
    assert np.allclose(gibbs_mean(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert np.allclose(soft_argmax(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert soft_max_value(st, beta).item() == pytest.approx(_ref_lse(s, beta), rel=RTOL, abs=ATOL)
    cov = gibbs_covariance(st, beta).numpy()
    assert np.allclose(cov, np.diag(p) - np.outer(p, p), rtol=RTOL, atol=ATOL)
    kappa = gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
    assert np.allclose(kappa, _ref_cumulants(p, v, 4), rtol=1e-7, atol=1e-9)
    assert kappa[0] == pytest.approx(float(p @ v), rel=RTOL, abs=ATOL)  # mean
    assert kappa[1] == pytest.approx(float(v @ cov @ v), rel=RTOL, abs=ATOL)  # variance

python -m pytest "packages/omnibias-struct/tests/test_select.py::test_gibbs_moments_torch_vs_reference" -q

Regression example · select torch jax parity

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_select_torch_jax_parity() -> None:
    torch = pytest.importorskip("torch")
    jax = pytest.importorskip("jax")
    jax.config.update("jax_enable_x64", True)
    import jax.numpy as jnp
    from omnibias.struct.jax import select as js
    from omnibias.struct.torch import select as ts

    for seed in range(6):
        rng = np.random.default_rng(500 + seed)
        # Well-determined instance: a clear margin so the parity tol is not masking a tie.
        s = np.sort(rng.standard_normal(7))[::-1] + np.linspace(0.0, 0.3, 7)[::-1]
        v = rng.standard_normal(7)
        beta = float(rng.uniform(1.0, 12.0))
        st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
        sj, vj = jnp.asarray(s), jnp.asarray(v)

        def close(a, b) -> bool:  # noqa: ANN001
            return bool(np.max(np.abs(np.asarray(a) - np.asarray(b))) < PARITY_TOL)

        assert close(ts.soft_max_value(st, beta).numpy(), js.soft_max_value(sj, beta))
        assert close(ts.soft_argmax(st, beta).numpy(), js.soft_argmax(sj, beta))
        assert close(ts.gibbs_mean(st, beta).numpy(), js.gibbs_mean(sj, beta))
        assert close(ts.gibbs_covariance(st, beta).numpy(), js.gibbs_covariance(sj, beta))
        kt = ts.gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
        kj = np.asarray(js.gibbs_cumulants_directional(sj, vj, beta, order=4))
        assert close(kt, kj)
        soft_t, cert_t = ts.certified_argmax(st, beta, eps=0.05)
        soft_j, cert_j = js.certified_argmax(sj, beta, eps=0.05)
        assert close(soft_t.numpy(), soft_j)
        assert cert_t.argmax == cert_j.argmax
        assert cert_t.p_max_lower == pytest.approx(cert_j.p_max_lower, rel=RTOL, abs=ATOL)

python -m pytest packages/omnibias-struct/tests/test_select.py -k test_select_torch_jax_parity -q

Read the implementation

def gibbs_mean(logits: Tensor, beta: float = 1.0, *, axis: int = -1) -> Tensor:
    r"""The Gibbs law ``p_i = softmax(beta * logits)_i`` -- the mean of the one-hot indicator.

    Identical tensor to :func:`soft_argmax`; named for the measure/moment view (it is the
    gradient of :func:`soft_max_value`, i.e. ``E_p[e_i]``).
    """
    return softmax_beta(logits, beta, axis=axis)

Related APIsomnibias.struct.torch.softmax_beta↗

Other public import paths

• omnibias.struct.torch.gibbs_mean
• omnibias.struct.torch.select.gibbs_mean

FUNCTION

soft_argmax

omnibias.struct.torch.soft_argmaxSource ↗

soft_argmax(logits: Tensor, beta: float=1.0, *, axis: int=-1) -> Tensor

The relaxed one-hot selection softmax(beta * logits) (-> e_argmax as beta -> inf).

Parameters

Name	Type & default	Contract
logitspositional-or-keyword	TensorRequired	See the operation contract and implementation below.
betapositional-or-keyword	floatDefault: 1.0	See the operation contract and implementation below.
axiskeyword-only	intDefault: -1	See the operation contract and implementation below.

ReturnsTensor

Executed regression · layer certificate matches functional

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_layer_certificate_matches_functional() -> None:
    layer = DecisionLayer(beta=8.0, eps=0.05)
    scores = torch.tensor([1.0, -0.5, 0.3], dtype=torch.float64)
    soft, cert = layer.certified(scores)
    assert torch.allclose(soft, layer.forward(scores))
    ref = certified_decision(scores.numpy(), beta=8.0, eps=0.05)
    assert cert.argmax == ref.argmax
    assert math.isclose(cert.gap_bound, ref.gap_bound, rel_tol=1e-12)
    assert math.isclose(cert.p_max, ref.p_max, rel_tol=1e-9)

python -m pytest "packages/omnibias-struct/tests/test_decision_layer.py::test_layer_certificate_matches_functional" -q

Regression example · gibbs moments torch vs reference

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_gibbs_moments_torch_vs_reference() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.struct.torch import (
        gibbs_covariance,
        gibbs_cumulants_directional,
        gibbs_mean,
        soft_argmax,
        soft_max_value,
    )

    rng = np.random.default_rng(11)
    s = rng.standard_normal(6)
    v = rng.standard_normal(6)
    beta = 2.3
    st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
    p = _ref_softmax(s, beta)
    assert np.allclose(gibbs_mean(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert np.allclose(soft_argmax(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert soft_max_value(st, beta).item() == pytest.approx(_ref_lse(s, beta), rel=RTOL, abs=ATOL)
    cov = gibbs_covariance(st, beta).numpy()
    assert np.allclose(cov, np.diag(p) - np.outer(p, p), rtol=RTOL, atol=ATOL)
    kappa = gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
    assert np.allclose(kappa, _ref_cumulants(p, v, 4), rtol=1e-7, atol=1e-9)
    assert kappa[0] == pytest.approx(float(p @ v), rel=RTOL, abs=ATOL)  # mean
    assert kappa[1] == pytest.approx(float(v @ cov @ v), rel=RTOL, abs=ATOL)  # variance

python -m pytest packages/omnibias-struct/tests/test_select.py -k test_gibbs_moments_torch_vs_reference -q

Read the implementation

def soft_argmax(logits: Tensor, beta: float = 1.0, *, axis: int = -1) -> Tensor:
    r"""The relaxed one-hot selection ``softmax(beta * logits)`` (``-> e_argmax`` as ``beta -> inf``)."""
    return softmax_beta(logits, beta, axis=axis)

Related APIsomnibias.struct.torch.softmax_beta↗

Other public import paths

• omnibias.struct.torch.soft_argmax
• omnibias.struct.torch.select.soft_argmax

FUNCTION

soft_max_value

omnibias.struct.torch.soft_max_valueSource ↗

soft_max_value(logits: Tensor, beta: float=1.0, *, axis: int=-1) -> Tensor

The relaxed max value lse_beta(logits) (>= max, -> max as beta -> inf).

Parameters

Name	Type & default	Contract
logitspositional-or-keyword	TensorRequired	See the operation contract and implementation below.
betapositional-or-keyword	floatDefault: 1.0	See the operation contract and implementation below.
axiskeyword-only	intDefault: -1	See the operation contract and implementation below.

ReturnsTensor

Executed regression · gibbs moments torch vs reference

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_gibbs_moments_torch_vs_reference() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.struct.torch import (
        gibbs_covariance,
        gibbs_cumulants_directional,
        gibbs_mean,
        soft_argmax,
        soft_max_value,
    )

    rng = np.random.default_rng(11)
    s = rng.standard_normal(6)
    v = rng.standard_normal(6)
    beta = 2.3
    st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
    p = _ref_softmax(s, beta)
    assert np.allclose(gibbs_mean(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert np.allclose(soft_argmax(st, beta).numpy(), p, rtol=RTOL, atol=ATOL)
    assert soft_max_value(st, beta).item() == pytest.approx(_ref_lse(s, beta), rel=RTOL, abs=ATOL)
    cov = gibbs_covariance(st, beta).numpy()
    assert np.allclose(cov, np.diag(p) - np.outer(p, p), rtol=RTOL, atol=ATOL)
    kappa = gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
    assert np.allclose(kappa, _ref_cumulants(p, v, 4), rtol=1e-7, atol=1e-9)
    assert kappa[0] == pytest.approx(float(p @ v), rel=RTOL, abs=ATOL)  # mean
    assert kappa[1] == pytest.approx(float(v @ cov @ v), rel=RTOL, abs=ATOL)  # variance

python -m pytest "packages/omnibias-struct/tests/test_select.py::test_gibbs_moments_torch_vs_reference" -q

Regression example · select torch jax parity

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_select_torch_jax_parity() -> None:
    torch = pytest.importorskip("torch")
    jax = pytest.importorskip("jax")
    jax.config.update("jax_enable_x64", True)
    import jax.numpy as jnp
    from omnibias.struct.jax import select as js
    from omnibias.struct.torch import select as ts

    for seed in range(6):
        rng = np.random.default_rng(500 + seed)
        # Well-determined instance: a clear margin so the parity tol is not masking a tie.
        s = np.sort(rng.standard_normal(7))[::-1] + np.linspace(0.0, 0.3, 7)[::-1]
        v = rng.standard_normal(7)
        beta = float(rng.uniform(1.0, 12.0))
        st, vt = torch.tensor(s, dtype=torch.float64), torch.tensor(v, dtype=torch.float64)
        sj, vj = jnp.asarray(s), jnp.asarray(v)

        def close(a, b) -> bool:  # noqa: ANN001
            return bool(np.max(np.abs(np.asarray(a) - np.asarray(b))) < PARITY_TOL)

        assert close(ts.soft_max_value(st, beta).numpy(), js.soft_max_value(sj, beta))
        assert close(ts.soft_argmax(st, beta).numpy(), js.soft_argmax(sj, beta))
        assert close(ts.gibbs_mean(st, beta).numpy(), js.gibbs_mean(sj, beta))
        assert close(ts.gibbs_covariance(st, beta).numpy(), js.gibbs_covariance(sj, beta))
        kt = ts.gibbs_cumulants_directional(st, vt, beta, order=4).numpy()
        kj = np.asarray(js.gibbs_cumulants_directional(sj, vj, beta, order=4))
        assert close(kt, kj)
        soft_t, cert_t = ts.certified_argmax(st, beta, eps=0.05)
        soft_j, cert_j = js.certified_argmax(sj, beta, eps=0.05)
        assert close(soft_t.numpy(), soft_j)
        assert cert_t.argmax == cert_j.argmax
        assert cert_t.p_max_lower == pytest.approx(cert_j.p_max_lower, rel=RTOL, abs=ATOL)

python -m pytest packages/omnibias-struct/tests/test_select.py -k test_select_torch_jax_parity -q

Read the implementation

def soft_max_value(logits: Tensor, beta: float = 1.0, *, axis: int = -1) -> Tensor:
    r"""The relaxed max value ``lse_beta(logits)`` (``>= max``, ``-> max`` as ``beta -> inf``)."""
    return logsumexp_beta(logits, beta, axis=axis)

Related APIsomnibias.struct.torch.logsumexp_beta↗

Other public import paths

• omnibias.struct.torch.soft_max_value
• omnibias.struct.torch.select.soft_max_value

← Package overviewRunnable learning examples →