omnibias.core.polynomials

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

Module contract & mathematical conventions

Pure-Python polynomial-coefficient generators for the closed-form derivative towers (sigmoid, tanh, Gaussian).

The torch and JAX backends both import these. The coefficient sequences are independent of the array library; only the Horner evaluation has to differ across backends (because it touches the tensor type).

Three families:

sigmoid / softplus: sigma^(n)(z) = P_n(sigmoid(z)) where P_n is a polynomial in s = sigmoid(z) whose coefficients are produced by sigmoid_polynomial_coeffs.
tanh: tanh^(n)(z) = T_n(tanh(z)) where T_n is a polynomial in t = tanh(z) produced by tanh_polynomial_coeffs.
Gaussian g(z) = exp(-z^2/2): g^(n)(z) = (-1)^n He_n(z) g(z) with probabilist's Hermite polynomial coefficients hermite_coeffs.

These are the same definitions used by the PyTorch fast paths in omnibias.fastpath.eulerian, omnibias.fastpath.legendre, omnibias.fastpath.hermite. Keeping them in one pure-Python file guarantees backend parity by construction.

Exactness

Every one of these recurrences has **integer** coefficients (signed Eulerian numbers, the tanh / sech Riccati towers, probabilist's Hermite). They are therefore accumulated in Python int -- which is unbounded -- and narrowed to float exactly once, on return. Running the recurrence in float instead would compound rounding at every step and stop matching the correctly-rounded coefficient from order 19 (sigmoid), 20 (sech), 22 (tanh) and 30 (Hermite) onward, because the coefficients outgrow 2**53. Narrowing once means each returned coefficient carries a single rounding, the best a float can do, and the exact int twins in omnibias.core.verified.coeffs agree with these by construction rather than by luck.

The recurrences are also iterative rather than self-recursive, so a large order costs memory but never a RecursionError, and each cache is explicitly bounded (order is often user-controlled, and an unbounded memo keyed on it is a memory exhaustion vector).

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

MAX_ORDER

omnibias.core.polynomials.MAX_ORDERSource ↗

MAX_ORDER: int = 512

Largest derivative order these generators accept. Well past the point where a float coefficient can hold the answer at all (see _narrow), so the binding limit in practice is representability rather than this cap; the cap is here so a hostile or mistyped order cannot allocate unboundedly.

Regression example · order is bounded in both directions

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_order_is_bounded_in_both_directions() -> None:
    import pytest
    from omnibias.core.polynomials import (
        MAX_ORDER,
        hermite_coeffs,
        mish_inner_coeffs,
        sech_polynomial_coeffs,
        sigmoid_polynomial_coeffs,
        tanh_polynomial_coeffs,
    )

    generators = (
        sigmoid_polynomial_coeffs,
        tanh_polynomial_coeffs,
        sech_polynomial_coeffs,
        hermite_coeffs,
        mish_inner_coeffs,
    )
    for fn in generators:
        with pytest.raises(ValueError, match="must be >= 0"):
            fn(-1)
        with pytest.raises(ValueError, match="MAX_ORDER"):
            fn(MAX_ORDER + 1)

python -m pytest packages/omnibias-core/tests/test_polynomials_invariants.py -k test_order_is_bounded_in_both_directions -q

Read the implementation

MAX_ORDER: int = 512

FUNCTION

hermite_coeffs

omnibias.core.hermite_coeffsSource ↗

hermite_coeffs(n: int) -> tuple[float, ...]

Coefficients of the probabilist's Hermite polynomial He_n.

Returns (c_0, ..., c_n) with He_n(z) = sum_k c_k * z^k. Recurrence: He_0 = 1, He_1 = z, He_{n+1} = z He_n - n He_{n-1}.

Parameters

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

Returnstuple[float, ...]

Executed regression · hermite negative order raises

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_hermite_negative_order_raises() -> None:
    with pytest.raises(ValueError, match="order n must be"):
        hermite_coeffs(-1)

python -m pytest "packages/omnibias-core/tests/test_polynomials.py::test_hermite_negative_order_raises" -q

Regression example · hermite he0

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_hermite_he0() -> None:
    # He_0(z) = 1
    assert hermite_coeffs(0) == (1.0,)

python -m pytest packages/omnibias-core/tests/test_polynomials.py -k test_hermite_he0 -q

Read the implementation

def hermite_coeffs(n: int) -> tuple[float, ...]:
    """Coefficients of the probabilist's Hermite polynomial ``He_n``.

    Returns ``(c_0, ..., c_n)`` with ``He_n(z) = sum_k c_k * z^k``.
    Recurrence: ``He_0 = 1, He_1 = z, He_{n+1} = z He_n - n He_{n-1}``.
    """
    _check_order(n)
    return _narrow(_hermite_coeffs_int(n), n, "Hermite")

Other public import paths

omnibias.core.hermite_coeffs
omnibias.core.polynomials.hermite_coeffs
omnibias.keras.fastpath.hermite_coeffs
omnibias.keras.fastpath.hermite.hermite_coeffs
omnibias.torch.fastpath.hermite.hermite_coeffs

FUNCTION

mish_inner_coeffs

omnibias.core.mish_inner_coeffsSource ↗

mish_inner_coeffs(n: int) -> tuple[tuple[int, int, float], ...]

Coefficients of the n-th derivative of g(z) = tanh(softplus(z)).

g is the inner factor of Mish (mish(z) = z * g(z)). With t = tanh(softplus(z)) and s = sigmoid(z) = softplus'(z) the two Riccati rules

dt/dz = (1 - t^2) s, ds/dz = s - s^2

close the whole derivative tower on polynomials in (t, s):

g^(n)(z) = sum_{i,j} c_{ij} t^i s^j.

Returns the nonzero (i, j, c_{ij}) triples, sorted. g^(0) = t so mish_inner_coeffs(0) == ((1, 0, 1.0),). Backends evaluate the tower with one softplus + one tanh + one sigmoid call, giving Mish a closed-form all-orders fast path that is bit-identical by construction.

Parameters

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

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

Executed regression · order is bounded in both directions

Full file, imports & fixtures ↗

def test_order_is_bounded_in_both_directions() -> None:
    import pytest
    from omnibias.core.polynomials import (
        MAX_ORDER,
        hermite_coeffs,
        mish_inner_coeffs,
        sech_polynomial_coeffs,
        sigmoid_polynomial_coeffs,
        tanh_polynomial_coeffs,
    )

    generators = (
        sigmoid_polynomial_coeffs,
        tanh_polynomial_coeffs,
        sech_polynomial_coeffs,
        hermite_coeffs,
        mish_inner_coeffs,
    )
    for fn in generators:
        with pytest.raises(ValueError, match="must be >= 0"):
            fn(-1)
        with pytest.raises(ValueError, match="MAX_ORDER"):
            fn(MAX_ORDER + 1)

python -m pytest "packages/omnibias-core/tests/test_polynomials_invariants.py::test_order_is_bounded_in_both_directions" -q

Regression example · coefficient caches are bounded

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_coefficient_caches_are_bounded() -> None:
    """An unbounded memo keyed on a caller-supplied order is a DoS vector."""
    from omnibias.core import bell, multi_index, polynomials
    from omnibias.core.verified import coeffs

    cached = [
        polynomials.sigmoid_polynomial_coeffs,
        polynomials.tanh_polynomial_coeffs,
        polynomials.sech_polynomial_coeffs,
        polynomials.hermite_coeffs,
        polynomials.mish_inner_coeffs,
        bell.bell_number,
        multi_index._multi_indices,
        multi_index._multiply_table,
        coeffs.sigmoid_poly_coeffs_exact,
        coeffs.tanh_poly_coeffs_exact,
        coeffs.hermite_coeffs_exact,
        coeffs.sech_poly_coeffs_exact,
    ]
    for fn in cached:
        info = fn.cache_info()
        assert info.maxsize is not None, f"{fn.__name__} has an unbounded cache"
        assert info.maxsize > 0

python -m pytest packages/omnibias-core/tests/test_polynomials_invariants.py -k test_coefficient_caches_are_bounded -q

Read the implementation

def mish_inner_coeffs(n: int) -> tuple[tuple[int, int, float], ...]:
    r"""Coefficients of the ``n``-th derivative of ``g(z) = tanh(softplus(z))``.

    ``g`` is the inner factor of Mish (``mish(z) = z * g(z)``). With
    ``t = tanh(softplus(z))`` and ``s = sigmoid(z) = softplus'(z)`` the two
    Riccati rules

        dt/dz = (1 - t^2) s,      ds/dz = s - s^2

    close the whole derivative tower on polynomials in ``(t, s)``:

        g^(n)(z) = sum_{i,j} c_{ij} t^i s^j.

    Returns the nonzero ``(i, j, c_{ij})`` triples, sorted. ``g^(0) = t`` so
    ``mish_inner_coeffs(0) == ((1, 0, 1.0),)``. Backends evaluate the tower with
    one ``softplus`` + one ``tanh`` + one ``sigmoid`` call, giving Mish a
    closed-form all-orders fast path that is bit-identical by construction.
    """
    _check_order(n)
    poly: dict[tuple[int, int], int] = {(1, 0): 1}
    for _ in range(n):
        nxt: dict[tuple[int, int], int] = {}
        for (i, j), c in poly.items():
            if i >= 1:  # d/dt * (1 - t^2) s
                nxt[(i - 1, j + 1)] = nxt.get((i - 1, j + 1), 0) + i * c
                nxt[(i + 1, j + 1)] = nxt.get((i + 1, j + 1), 0) - i * c
            if j >= 1:  # d/ds * (s - s^2)
                nxt[(i, j)] = nxt.get((i, j), 0) + j * c
                nxt[(i, j + 1)] = nxt.get((i, j + 1), 0) - j * c
        poly = nxt
    return tuple(sorted((i, j, float(c)) for (i, j), c in poly.items() if c != 0))

Other public import paths

omnibias.core.mish_inner_coeffs
omnibias.core.polynomials.mish_inner_coeffs

FUNCTION

sech_polynomial_coeffs

omnibias.core.polynomials.sech_polynomial_coeffsSource ↗

sech_polynomial_coeffs(n: int) -> tuple[float, ...]

Coefficients of Q_n(t) with sech^(n)(z) = Q_n(t) * sech(z), t = tanh(z).

Returns a tuple (c_0, ..., c_n) with Q_n(t) = sum_k c_k * t^k. sech closes its whole derivative tower on poly(t) * sech via the two Riccati rules d/dz sech = -t sech and d/dz t = 1 - t^2, giving the recurrence Q_0 = 1, Q_{n+1}(t) = (1 - t^2) Q_n'(t) - t Q_n(t).

The constant term Q_n(0) = sech^(n)(0) is the n-th **Euler (secant) number** E_n (E_0 = 1, E_2 = -1, E_4 = 5, E_6 = -61, ...); omnibias.difference reads them straight off this tower. This is a coefficient generator (and its verified twin in omnibias.core.verified); no per-backend sech activation fastpath is provided.

Parameters

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

Returnstuple[float, ...]

Executed regression · sech exact coeffs match float

Full file, imports & fixtures ↗

def test_sech_exact_coeffs_match_float(n: int) -> None:
    exact = sech_poly_coeffs_exact(n)
    flt = sech_polynomial_coeffs(n)
    assert len(exact) == len(flt)
    for ce, cf in zip(exact, flt, strict=True):
        assert float(ce) == cf  # still exact as double at these orders

python -m pytest "packages/omnibias-core/tests/verified/test_sigma_and_jet.py::test_sech_exact_coeffs_match_float[10]" -q

Regression example · hermite coeffs is cached

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_hermite_coeffs_is_cached() -> None:
    a = hermite_coeffs(5)
    b = hermite_coeffs(5)
    assert a is b

python -m pytest packages/omnibias-core/tests/test_polynomials_invariants.py -k test_hermite_coeffs_is_cached -q

Read the implementation

def sech_polynomial_coeffs(n: int) -> tuple[float, ...]:
    r"""Coefficients of ``Q_n(t)`` with ``sech^(n)(z) = Q_n(t) * sech(z)``,
    ``t = tanh(z)``.

    Returns a tuple ``(c_0, ..., c_n)`` with ``Q_n(t) = sum_k c_k * t^k``.
    ``sech`` closes its whole derivative tower on ``poly(t) * sech`` via the two
    Riccati rules ``d/dz sech = -t sech`` and ``d/dz t = 1 - t^2``, giving the
    recurrence ``Q_0 = 1``, ``Q_{n+1}(t) = (1 - t^2) Q_n'(t) - t Q_n(t)``.

    The constant term ``Q_n(0) = sech^(n)(0)`` is the ``n``-th **Euler (secant)
    number** ``E_n`` (``E_0 = 1``, ``E_2 = -1``, ``E_4 = 5``, ``E_6 = -61``, ...);
    :mod:`omnibias.difference` reads them straight off this tower. This is a
    coefficient generator (and its verified twin in
    :mod:`omnibias.core.verified`); no per-backend ``sech`` activation fastpath is
    provided.
    """
    _check_order(n)
    return _narrow(_sech_coeffs_int(n), n, "sech")

FUNCTION

sigmoid_polynomial_coeffs

omnibias.core.sigmoid_polynomial_coeffsSource ↗

sigmoid_polynomial_coeffs(n: int) -> tuple[float, ...]

Coefficients of P_n(s) = sigma^(n)(z) as a polynomial in s = sigmoid(z).

Returns a tuple (c_0, c_1, ..., c_{n+1}) with P_n(s) = sum_k c_k * s^k. P_0(s) = s; the recurrence is P_{n+1}(s) = s (1 - s) * P_n'(s) and the coefficients are (signed) Eulerian numbers.

Parameters

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

Returnstuple[float, ...]

Executed regression · sigmoid p0

Full file, imports & fixtures ↗

def test_sigmoid_p0() -> None:
    # P_0(s) = s
    assert sigmoid_polynomial_coeffs(0) == (0.0, 1.0)

python -m pytest "packages/omnibias-core/tests/test_polynomials.py::test_sigmoid_p0" -q

Regression example · sigmoid p1

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_sigmoid_p1() -> None:
    # P_1(s) = s - s^2
    assert sigmoid_polynomial_coeffs(1) == (0.0, 1.0, -1.0)

python -m pytest packages/omnibias-core/tests/test_polynomials.py -k test_sigmoid_p1 -q

Read the implementation

def sigmoid_polynomial_coeffs(n: int) -> tuple[float, ...]:
    """Coefficients of ``P_n(s) = sigma^(n)(z)`` as a polynomial in
    ``s = sigmoid(z)``.

    Returns a tuple ``(c_0, c_1, ..., c_{n+1})`` with
    ``P_n(s) = sum_k c_k * s^k``. ``P_0(s) = s``; the recurrence is
    ``P_{n+1}(s) = s (1 - s) * P_n'(s)`` and the coefficients are
    (signed) Eulerian numbers.
    """
    _check_order(n)
    return _narrow(_sigmoid_coeffs_int(n), n, "sigmoid")

Other public import paths

omnibias.core.sigmoid_polynomial_coeffs
omnibias.core.polynomials.sigmoid_polynomial_coeffs
omnibias.keras.fastpath.sigmoid_polynomial_coeffs
omnibias.keras.fastpath.eulerian.sigmoid_polynomial_coeffs
omnibias.torch.fastpath.eulerian.sigmoid_polynomial_coeffs

FUNCTION

tanh_polynomial_coeffs

omnibias.core.tanh_polynomial_coeffsSource ↗

tanh_polynomial_coeffs(n: int) -> tuple[float, ...]

Coefficients of T_n(t) = tanh^(n)(z) as a polynomial in t = tanh(z).

Returns a tuple (c_0, ..., c_{n+1}) with T_n(t) = sum_k c_k * t^k. T_0(t) = t; recurrence T_{n+1}(t) = (1 - t^2) * T_n'(t).

Parameters

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

Returnstuple[float, ...]

Executed regression · tanh negative order raises

Full file, imports & fixtures ↗

def test_tanh_negative_order_raises() -> None:
    with pytest.raises(ValueError, match="order n must be"):
        tanh_polynomial_coeffs(-1)

python -m pytest "packages/omnibias-core/tests/test_polynomials.py::test_tanh_negative_order_raises" -q

Regression example · tanh t0

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_tanh_t0() -> None:
    # T_0(t) = t
    assert tanh_polynomial_coeffs(0) == (0.0, 1.0)

python -m pytest packages/omnibias-core/tests/test_polynomials.py -k test_tanh_t0 -q

Read the implementation

def tanh_polynomial_coeffs(n: int) -> tuple[float, ...]:
    """Coefficients of ``T_n(t) = tanh^(n)(z)`` as a polynomial in
    ``t = tanh(z)``.

    Returns a tuple ``(c_0, ..., c_{n+1})`` with
    ``T_n(t) = sum_k c_k * t^k``. ``T_0(t) = t``; recurrence
    ``T_{n+1}(t) = (1 - t^2) * T_n'(t)``.
    """
    _check_order(n)
    return _narrow(_tanh_coeffs_int(n), n, "tanh")

Other public import paths

omnibias.core.tanh_polynomial_coeffs
omnibias.core.polynomials.tanh_polynomial_coeffs
omnibias.keras.fastpath.tanh_polynomial_coeffs
omnibias.keras.fastpath.legendre.tanh_polynomial_coeffs
omnibias.torch.fastpath.legendre.tanh_polynomial_coeffs

← Package overview Runnable learning examples →

omnibias.core.polynomials

MAX_ORDER​

hermite_coeffs​

Parameters

mish_inner_coeffs​

Parameters

sech_polynomial_coeffs​

Parameters

sigmoid_polynomial_coeffs​

Parameters

tanh_polynomial_coeffs​

Parameters

MAX_ORDER

hermite_coeffs

mish_inner_coeffs

sech_polynomial_coeffs

sigmoid_polynomial_coeffs

tanh_polynomial_coeffs