omnibias.core.spec

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

Module contract & mathematical conventions

Backend-agnostic activation specification.

The omnibias framework parameterises every closed-form derivative-tower kernel by an ActivationSpec, a small bundle of metadata describing one base activation (forward, derivative, fastpath, Riccati polynomial, GLM noise model, operator role).

This module defines the *generic* spec that does not bind to any specific tensor library. The omnibias.torch.activations.registry and omnibias.jax.activations modules each instantiate concrete dataclasses that pin TensorT to their respective array type (torch.Tensor and jax.Array).

Keeping the spec definition in omnibias.core guarantees the shape of every backend's registry is identical by construction, which is what the cross-backend parity test (tests/test_cross_backend_parity.py) checks.

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

ActivationSpec

omnibias.core.ActivationSpecSource ↗

class ActivationSpec(Generic[TensorT])

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.

Full description of a base activation, generic over the tensor type.

Attributes

name : str Lookup key (lowercase, no whitespace). forward : Callable[[TensorT], TensorT] sigma(z). derivative : Callable[[TensorT], TensorT], optional First derivative sigma'(z) in closed form. None when not available analytically. fastpath : Callable[[TensorT, int], TensorT], optional Closed-form sigma^(n)(z) for any non-negative integer order n. None when no general derivative formula is known. integral : Callable[[TensorT], TensorT], optional Closed-form antiderivative S(z) with S'(z) = sigma(z). Definite bias-window integrals are evaluated as S(z + b_hi) - S(z + b_lo). None when no stable primitive is provided by the backend. riccati_polynomial : tuple[float, ...], optional Coefficients of the polynomial P such that sigma'(z) = P(sigma(z)) (Riccati class). None for activations not in the Riccati class. noise_model : str GLM family for which sigma is the log-partition function; "none" if the activation does not arise as a log-partition. operator_role : str One-line description of the canonical operator role of the K=2 bias-collapse unit with this activation. aliases : Sequence[str] Additional lookup names (lowercase, no whitespace). limit_pos_inf : float, optional Saturation limit lim_{z->+inf} sigma(z) when it is finite; None when the activation diverges or has no recorded right asymptote. This is the beta->inf saturation reused by the binary surrogates and the jet lim operator. limit_neg_inf : float, optional Saturation limit lim_{z->-inf} sigma(z) when finite; None otherwise. transforms : TransformKernels[TensorT], optional Closed-form Laplace / Fourier / Mellin transforms of sigma. None (the default) means the backend registered no transform at all for this activation, which is distinct from registering a TransformKernels whose individual fields are None.

Parameters

Name	Type & default	Contract
`name`dataclass field	`str`Required	str Lookup key (lowercase, no whitespace).
`forward`dataclass field	`Callable[[TensorT], TensorT]`Required	Callable[[TensorT], TensorT] `sigma(z)`.
`derivative`dataclass field	`Callable[[TensorT], TensorT] \| None`Default: None	Callable[[TensorT], TensorT], optional First derivative `sigma'(z)` in closed form. `None` when not available analytically.
`fastpath`dataclass field	`Callable[[TensorT, int], TensorT] \| None`Default: None	Callable[[TensorT, int], TensorT], optional Closed-form `sigma^(n)(z)` for any non-negative integer order `n`. `None` when no general derivative formula is known.
`integral`dataclass field	`Callable[[TensorT], TensorT] \| None`Default: None	Callable[[TensorT], TensorT], optional Closed-form antiderivative `S(z)` with `S'(z) = sigma(z)`. Definite bias-window integrals are evaluated as `S(z + b_hi) - S(z + b_lo)`. `None` when no stable primitive is provided by the backend.
`riccati_polynomial`dataclass field	`tuple[float, ...] \| None`Default: None	tuple[float, ...], optional Coefficients of the polynomial `P` such that `sigma'(z) = P(sigma(z))` (Riccati class). `None` for activations not in the Riccati class.
`noise_model`dataclass field	`str`Default: 'none'	str GLM family for which `sigma` is the log-partition function; `"none"` if the activation does not arise as a log-partition.
`operator_role`dataclass field	`str`Default: ''	str One-line description of the canonical operator role of the K=2 bias-collapse unit with this activation.
`aliases`dataclass field	`Sequence[str]`Default: field(default_factory=tuple)	Sequence[str] Additional lookup names (lowercase, no whitespace).
`limit_pos_inf`dataclass field	`float \| None`Default: None	float, optional Saturation limit `lim_{z->+inf} sigma(z)` when it is finite; `None` when the activation diverges or has no recorded right asymptote. This is the `beta->inf` saturation reused by the binary surrogates and the jet `lim` operator.
`limit_neg_inf`dataclass field	`float \| None`Default: None	float, optional Saturation limit `lim_{z->-inf} sigma(z)` when finite; `None` otherwise.
`transforms`dataclass field	`TransformKernels[TensorT] \| None`Default: None	TransformKernels[TensorT], optional Closed-form Laplace / Fourier / Mellin transforms of `sigma`. `None` (the default) means the backend registered no transform at all for this activation, which is distinct from registering a `TransformKernels` whose individual fields are `None`.
`tower`dataclass field	`Callable[[TensorT, int], TensorT] \| None`Default: None	See the operation contract and implementation below.

Regression example · tempered requires base fastpath

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_tempered_requires_base_fastpath() -> None:
    with pytest.raises(ValueError, match="fastpath"):
        tempered(ActivationSpec(name="id", forward=_identity), 2.0)

python -m pytest packages/omnibias-core/tests/test_spec.py -k test_tempered_requires_base_fastpath -q

Regression example · grad block requires fastpath

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_grad_block_requires_fastpath() -> None:
    # relu now carries an all-orders a.e. tower; use a fastpath-less spec so the
    # op="laplacian" guard still has something to reject.
    no_fastpath = ActivationSpec(name="_no_fastpath_probe", forward=ops.relu, fastpath=None)
    with pytest.raises(TypeError):
        OperatorBlock(channels=2, op="laplacian", base=no_fastpath)

python -m pytest packages/omnibias-keras/tests/test_blocks.py -k test_grad_block_requires_fastpath -q

Fields & methods

namefield

name: str

Lookup key (lowercase, no whitespace).

Name	Type & default	Contract
`laplace`dataclass field	`Callable[[TensorT], TensorT] \| None`Default: None	Callable[[TensorT], TensorT], optional `L[sigma](s)` for real `s` in the region of convergence.
`fourier`dataclass field	`Callable[[TensorT], TensorT] \| None`Default: None	Callable[[TensorT], TensorT], optional `F[sigma](xi)`. Registered only for `L^1(R)` activations; a saturating or growing activation has a distributional Fourier transform (Dirac deltas, principal values) that no tensor kernel can represent honestly, so it stays `None`.
`mellin`dataclass field	`Callable[[TensorT], TensorT] \| None`Default: None	Callable[[TensorT], TensorT], optional `M[sigma](s)` for real `s` in the region of convergence.

Name	Type & default	Contract
`base_fastpath`positional-or-keyword	`NthDerivativeFn[TensorT]`Required	See the operation contract and implementation below.
`beta`positional-or-keyword	`float \| TensorT`Required	See the operation contract and implementation below.
`scale_power`keyword-only	`int`Default: 0	See the operation contract and implementation below.

Name	Type & default	Contract
`base`positional-or-keyword	`TransformKernels[TensorT]`Required	See the operation contract and implementation below.
`beta`positional-or-keyword	`float \| TensorT`Required	See the operation contract and implementation below.
`scale_power`keyword-only	`int`Default: 0	See the operation contract and implementation below.

Name	Type & default	Contract
`spec`positional-or-keyword	`ActivationSpec[TensorT]`Required	See the operation contract and implementation below.
`sign`positional-or-keyword	`float`Required	See the operation contract and implementation below.

Name	Type & default	Contract
`base`positional-or-keyword	`ActivationSpec[TensorT]`Required	Base `ActivationSpec` with a non-`None` `fastpath`.
`beta`positional-or-keyword	`float \| TensorT`Required	Temperature (float or backend tensor). Larger is sharper.
`scale`keyword-only	`str`Default: 'unit'	`"unit"` for `g(beta z)` or `"one_over_beta"` for `g(beta z) / beta`.
`name`keyword-only	`str \| None`Default: None	Metadata for the produced spec (limits are recorded explicitly rather than auto-derived, so callers stay honest about the surrogate's asymptotes).
`noise_model`keyword-only	`str`Default: 'none'	See the operation contract and implementation below.
`operator_role`keyword-only	`str`Default: ''	See the operation contract and implementation below.
`aliases`keyword-only	`Sequence[str]`Default: ()	See the operation contract and implementation below.
`limit_pos_inf`keyword-only	`float \| None`Default: None	See the operation contract and implementation below.
`limit_neg_inf`keyword-only	`float \| None`Default: None	See the operation contract and implementation below.

omnibias.core.spec

ActivationSpec​

Parameters

Fields & methods

IntegralFn​

NthDerivativeFn​

TensorFn​

TensorT​

TransformFn​

TransformKernels​

Parameters

Fields & methods

make_tempered_fastpath​

Parameters

make_tempered_transforms​

Parameters

saturation_limit​

Parameters

tempered​

Parameters

ActivationSpec

IntegralFn

NthDerivativeFn

TensorFn

TensorT

TransformFn

TransformKernels

make_tempered_fastpath

make_tempered_transforms

saturation_limit

tempered