API REFERENCE/omnibias-core

omnibias.core.confluence

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

Module contract & mathematical conventions

Host arithmetic for centered collision coordinates and bounded moment atoms.

Input floats are interpreted as their stored dyadic values. Conversion errors bound conversion to the returned floats; they cannot recover earlier rounding. No finite-spread truncated moment expansion is called an exact coordinate change.

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

Activation

omnibias.core.confluence.ActivationSource ↗

Activation = Literal['sigmoid', 'tanh']

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

Activation = Literal["sigmoid", "tanh"]

CLASS

MomentInitialization

omnibias.core.confluence.MomentInitializationSource ↗

class MomentInitialization

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.

Taylor-normalized moments, exact source arithmetic, and rounding boxes.

Parameters

Name	Type & default	Contract
momentsdataclass field	tuple[float, ...]Required	See the operation contract and implementation below.
exact_momentsdataclass field	tuple[Fraction, ...]Required	See the operation contract and implementation below.
conversion_errorsdataclass field	tuple[Interval, ...]Required	See the operation contract and implementation below.
centerdataclass field	FractionRequired	See the operation contract and implementation below.
offsetsdataclass field	tuple[Fraction, ...]Required	See the operation contract and implementation below.
coefficientsdataclass field	tuple[Fraction, ...]Required	See the operation contract and implementation below.

Fields & methods

momentsfield

moments: tuple[float, ...]

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

View source ↗

exact_momentsfield

exact_moments: tuple[Fraction, ...]

Declared tuple[Fraction, ...] field on MomentInitialization. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

conversion_errorsfield

conversion_errors: tuple[Interval, ...]

Declared tuple[Interval, ...] field on MomentInitialization. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

centerfield

center: Fraction

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

View source ↗

offsetsfield

offsets: tuple[Fraction, ...]

Declared tuple[Fraction, ...] field on MomentInitialization. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

coefficientsfield

coefficients: tuple[Fraction, ...]

Declared tuple[Fraction, ...] field on MomentInitialization. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

View source ↗

Read the implementation

class MomentInitialization:
    """Taylor-normalized moments, exact source arithmetic, and rounding boxes."""

    moments: tuple[float, ...]
    exact_moments: tuple[Fraction, ...]
    conversion_errors: tuple[Interval, ...]
    center: Fraction
    offsets: tuple[Fraction, ...]
    coefficients: tuple[Fraction, ...]

FUNCTION

cluster_remainder

omnibias.core.confluence.cluster_remainderSource ↗

cluster_remainder(initialization: MomentInitialization, *, activation: Activation='sigmoid', spatial_order: int=0, weight: float=1.0) -> Interval

Uniform spatial-derivative error for a common-weight bias cluster.

Includes moment float-conversion error. Spatial derivatives are along a scalar direction with common affine slope weight.

Parameters

Name	Type & default	Contract
initializationpositional-or-keyword	MomentInitializationRequired	See the operation contract and implementation below.
activationkeyword-only	ActivationDefault: 'sigmoid'	See the operation contract and implementation below.
spatial_orderkeyword-only	intDefault: 0	See the operation contract and implementation below.
weightkeyword-only	floatDefault: 1.0	See the operation contract and implementation below.

ReturnsInterval

Explicit validation & failure cases

• When spatial_order < 0, raises ValueError('spatial_order must be nonnegative').

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

Read the implementation

def cluster_remainder(
    initialization: MomentInitialization,
    *,
    activation: Activation = "sigmoid",
    spatial_order: int = 0,
    weight: float = 1.0,
) -> Interval:
    """Uniform spatial-derivative error for a common-weight bias cluster.

    Includes moment float-conversion error. Spatial derivatives are along a
    scalar direction with common affine slope ``weight``.
    """
    if spatial_order < 0:
        raise ValueError("spatial_order must be nonnegative")
    n = len(initialization.moments)
    tail = sum(
        (
            abs(a) * abs(b) ** n
            for a, b in zip(initialization.coefficients, initialization.offsets, strict=True)
        ),
        Fraction(),
    ) / factorial(n)
    error = Interval.from_rational(tail) * derivative_bound(activation, n + spatial_order)
    for k, rounding in enumerate(initialization.conversion_errors):
        error += Interval.point(rounding.mag) * derivative_bound(activation, k + spatial_order)
    error *= Interval.point(abs(weight)) ** spatial_order
    return Interval(0.0, error.hi)

Related APIsomnibias.core.confluence.derivative_bound↗omnibias.core.verified.Interval↗

FUNCTION

derivative_bound

omnibias.core.confluence.derivative_boundSource ↗

derivative_bound(activation: Activation, order: int) -> Interval

Global bound on abs(sigma**(order)) from the shared integer polynomial.

This conservative coefficient bound uses sigmoid in [0,1] and tanh in [-1,1]. It avoids a numerical maximization being mistaken for a proof.

Parameters

Name	Type & default	Contract
activationpositional-or-keyword	ActivationRequired	See the operation contract and implementation below.
orderpositional-or-keyword	intRequired	See the operation contract and implementation below.

ReturnsInterval

Explicit validation & failure cases

• When order < 0, raises ValueError('order must be nonnegative').
• When activation not in ('sigmoid', 'tanh'), raises ValueError('supported analytic bounds are sigmoid and tanh').

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

Read the implementation

def derivative_bound(activation: Activation, order: int) -> Interval:
    """Global bound on ``abs(sigma**(order))`` from the shared integer polynomial.

    This conservative coefficient bound uses sigmoid in [0,1] and tanh in
    [-1,1]. It avoids a numerical maximization being mistaken for a proof.
    """
    if order < 0:
        raise ValueError("order must be nonnegative")
    if activation not in ("sigmoid", "tanh"):
        raise ValueError("supported analytic bounds are sigmoid and tanh")
    coefficients = (
        sigmoid_poly_coeffs_exact(order)
        if activation == "sigmoid"
        else tanh_poly_coeffs_exact(order)
    )
    return Interval.from_rational(sum(abs(c) for c in coefficients))

Related APIsomnibias.core.verified.sigmoid_poly_coeffs_exact↗omnibias.core.verified.tanh_poly_coeffs_exact↗

FUNCTION

initialize_moments

omnibias.core.confluence.initialize_momentsSource ↗

initialize_moments(offsets: tuple[float | Fraction, ...], coefficients: tuple[float | Fraction, ...], *, order: int, center: float | Fraction=0.0) -> MomentInitialization

Compute sum(a_i * (b_i-center)**k)/k! in exact rational arithmetic.

Parameters

Name	Type & default	Contract
offsetspositional-or-keyword	tuple[float | Fraction, ...]Required	See the operation contract and implementation below.
coefficientspositional-or-keyword	tuple[float | Fraction, ...]Required	See the operation contract and implementation below.
orderkeyword-only	intRequired	See the operation contract and implementation below.
centerkeyword-only	float | FractionDefault: 0.0	See the operation contract and implementation below.

ReturnsMomentInitialization

Explicit validation & failure cases

• When order < 0 or not offsets or len(offsets) != len(coefficients), raises ValueError('nonempty matching arrays and nonnegative order are required').

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

Read the implementation

def initialize_moments(
    offsets: tuple[float | Fraction, ...],
    coefficients: tuple[float | Fraction, ...],
    *,
    order: int,
    center: float | Fraction = 0.0,
) -> MomentInitialization:
    """Compute ``sum(a_i * (b_i-center)**k)/k!`` in exact rational arithmetic."""
    if order < 0 or not offsets or len(offsets) != len(coefficients):
        raise ValueError("nonempty matching arrays and nonnegative order are required")
    c = Fraction(center)
    bs = tuple(Fraction(b) - c for b in offsets)
    aa = tuple(Fraction(a) for a in coefficients)
    exact = tuple(
        sum((a * b**k for a, b in zip(aa, bs, strict=True)), Fraction()) / factorial(k)
        for k in range(order + 1)
    )
    rounded = tuple(float(q) for q in exact)
    errors = tuple(
        Interval.from_rational(q - Fraction(f)) for q, f in zip(exact, rounded, strict=True)
    )
    return MomentInitialization(rounded, exact, errors, c, bs, aa)

Related APIsomnibias.core.confluence.MomentInitialization↗

FUNCTION

pair_derivative_error

omnibias.core.confluence.pair_derivative_errorSource ↗

pair_derivative_error(*, rho: Interval, eta: Interval, m0: Interval, m1: Interval, weight: Interval=_ONE, direction: Interval=_ZERO, spatial_order: int=0, activation: Activation='sigmoid') -> Interval

Bound the pair-to-derivative limit error, including affine direction pairs.

z=w*x+b, eta=v*x+c; weight encloses w, direction encloses v, eta encloses its values on the declared domain. Taylor's theorem in h is applied to sigma**(n)(z+h*eta)*(w+h*v)**n. This also handles the product-rule terms in derivatives of eta*sigma'(z).

Parameters

Name	Type & default	Contract
rhokeyword-only	IntervalRequired	See the operation contract and implementation below.
etakeyword-only	IntervalRequired	See the operation contract and implementation below.
m0keyword-only	IntervalRequired	See the operation contract and implementation below.
m1keyword-only	IntervalRequired	See the operation contract and implementation below.
weightkeyword-only	IntervalDefault: _ONE	See the operation contract and implementation below.
directionkeyword-only	IntervalDefault: _ZERO	See the operation contract and implementation below.
spatial_orderkeyword-only	intDefault: 0	See the operation contract and implementation below.
activationkeyword-only	ActivationDefault: 'sigmoid'	See the operation contract and implementation below.

ReturnsInterval

Explicit validation & failure cases

• When rho.lo < 0 or spatial_order < 0, raises ValueError('rho and spatial_order must be nonnegative').

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

Read the implementation

def pair_derivative_error(
    *,
    rho: Interval,
    eta: Interval,
    m0: Interval,
    m1: Interval,
    weight: Interval = _ONE,
    direction: Interval = _ZERO,
    spatial_order: int = 0,
    activation: Activation = "sigmoid",
) -> Interval:
    """Bound the pair-to-derivative limit error, including affine direction pairs.

    ``z=w*x+b``, ``eta=v*x+c``; weight encloses w, direction encloses v,
    eta encloses its values on the declared domain. Taylor's theorem in h
    is applied to ``sigma**(n)(z+h*eta)*(w+h*v)**n``. This also handles the
    product-rule terms in derivatives of ``eta*sigma'(z)``.
    """
    if rho.lo < 0 or spatial_order < 0:
        raise ValueError("rho and spatial_order must be nonnegative")
    if rho.hi == 0:
        return _ZERO
    from math import comb, inf, nextafter, sqrt

    h = Interval(0.0, nextafter(sqrt(rho.hi), inf))
    slope = Interval.point(weight.mag) + h * Interval.point(direction.mag)
    n = spatial_order

    def bound(k: int) -> Interval:
        total = Interval.point(0.0)
        for j in range(min(k, n) + 1):
            coefficient = comb(k, j) * factorial(n) // factorial(n - j)
            total += (
                coefficient
                * Interval.point(direction.mag) ** j
                * slope ** (n - j)
                * Interval.point(eta.mag) ** (k - j)
                * derivative_bound(activation, n + k - j)
            )
        return total

    error = rho * (Interval.point(m0.mag) * bound(2) / 2 + Interval.point(m1.mag) * bound(3) / 6)
    return Interval(0.0, error.hi)

Related APIsomnibias.core.confluence.derivative_bound↗omnibias.core.verified.Interval↗

FUNCTION

pair_moments

omnibias.core.confluence.pair_momentsSource ↗

pair_moments(a_plus: float, a_minus: float, h: float) -> MomentInitialization

Exact stored-operand (m0,m1) for a pair with spread h.

Parameters

Name	Type & default	Contract
a_pluspositional-or-keyword	floatRequired	See the operation contract and implementation below.
a_minuspositional-or-keyword	floatRequired	See the operation contract and implementation below.
hpositional-or-keyword	floatRequired	See the operation contract and implementation below.

ReturnsMomentInitialization

Explicit validation & failure cases

• When h < 0, raises ValueError('h must be nonnegative').

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

Read the implementation

def pair_moments(a_plus: float, a_minus: float, h: float) -> MomentInitialization:
    """Exact stored-operand ``(m0,m1)`` for a pair with spread ``h``."""
    if h < 0:
        raise ValueError("h must be nonnegative")
    return initialize_moments((h, -h), (a_plus, a_minus), order=1)

Related APIsomnibias.core.confluence.initialize_moments↗

FUNCTION

pair_series_error

omnibias.core.confluence.pair_series_errorSource ↗

pair_series_error(*, rho: Interval, eta: Interval, terms: int, activation: Activation='sigmoid', spatial_order: int=0, weight: Interval=_ONE, direction: Interval=_ZERO) -> tuple[Interval, Interval]

Declared truncation error of the even rho series in centered_pair.

These bounds concern the analytic truncation, not backend floating-point evaluation. The rigorous register must also enclose arithmetic rounding.

Parameters

Name	Type & default	Contract
rhokeyword-only	IntervalRequired	See the operation contract and implementation below.
etakeyword-only	IntervalRequired	See the operation contract and implementation below.
termskeyword-only	intRequired	See the operation contract and implementation below.
activationkeyword-only	ActivationDefault: 'sigmoid'	See the operation contract and implementation below.
spatial_orderkeyword-only	intDefault: 0	See the operation contract and implementation below.
weightkeyword-only	IntervalDefault: _ONE	See the operation contract and implementation below.
directionkeyword-only	IntervalDefault: _ZERO	See the operation contract and implementation below.

Returnstuple[Interval, Interval]

Explicit validation & failure cases

• When rho.lo < 0 or terms < 1 or spatial_order < 0, raises ValueError('nonnegative rho/order and positive series terms required').

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

Read the implementation

def pair_series_error(
    *,
    rho: Interval,
    eta: Interval,
    terms: int,
    activation: Activation = "sigmoid",
    spatial_order: int = 0,
    weight: Interval = _ONE,
    direction: Interval = _ZERO,
) -> tuple[Interval, Interval]:
    """Declared truncation error of the even rho series in centered_pair.

    These bounds concern the analytic truncation, not backend floating-point
    evaluation. The rigorous register must also enclose arithmetic rounding.
    """
    if rho.lo < 0 or terms < 1 or spatial_order < 0:
        raise ValueError("nonnegative rho/order and positive series terms required")
    if rho.hi == 0:
        return _ZERO, _ZERO
    from math import comb, inf, nextafter, sqrt

    h = Interval(0.0, nextafter(sqrt(rho.hi), inf))
    slope = Interval.point(weight.mag) + h * Interval.point(direction.mag)
    n = spatial_order

    def bound(k: int) -> Interval:
        total = _ZERO
        for j in range(min(k, n) + 1):
            coefficient = comb(k, j) * factorial(n) // factorial(n - j)
            total += (
                coefficient
                * Interval.point(direction.mag) ** j
                * slope ** (n - j)
                * Interval.point(eta.mag) ** (k - j)
                * derivative_bound(activation, n + k - j)
            )
        return total

    k = 2 * terms
    a = rho**terms * bound(k) / factorial(k)
    b = rho**terms * bound(k + 1) / factorial(k + 1)
    return Interval(0, a.hi), Interval(0, b.hi)

Related APIsomnibias.core.confluence.derivative_bound↗omnibias.core.verified.Interval↗

← Package overviewRunnable learning examples →