API REFERENCE/omnibias-core

omnibias.core.integral_kernel

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

Module contract & mathematical conventions

Integral-kernel operator (theory 09-14).

A volumetric 1-D kernel whose cell **is** the OMBU integral role S(z + b_hi) - S(z + b_lo) with S' = sigma. Not a surface BEM-Net (02-06) and not a Fourier multiplier.

The window is the knob. founding bias collapse (delta -> 0) of that window recovers a sigma kernel and is not the default. Temperature collapse (beta -> inf, feasibility) does not appear. do not conflate the two.

Accuracy depends on the supplied quadrature rule.

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

DEFAULT_CONFIG

omnibias.core.integral_kernel.DEFAULT_CONFIGSource ↗

DEFAULT_CONFIG = IntegralKernelConfig()

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

DEFAULT_CONFIG = IntegralKernelConfig()

Related APIsomnibias.core.integral_kernel.IntegralKernelConfig↗

CONSTANT

DISCLAIMER

omnibias.core.integral_kernel.DISCLAIMERSource ↗

DISCLAIMER = 'Integral-kernel operator: OMBU integral cell, not BEM-Net, not FNO SOTA, with explicit local scope'

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.

Regression example · g3 honesty

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_g3_honesty() -> None:
    payload = honesty_payload()
    assert payload["claimed_bem_net"] is False
    assert payload["claimed_fno_sota"] is False
    assert payload["theorem_prover_verified"] is False
    assert "not BEM-Net" in DISCLAIMER

python -m pytest packages/omnibias-core/tests/test_integral_kernel.py -k test_g3_honesty -q

Read the implementation

DISCLAIMER = (
    "Integral-kernel operator: OMBU integral cell, not BEM-Net, not FNO SOTA, "
    "with explicit local scope"
)

Other public import paths

• omnibias.core.integral_kernel.DISCLAIMER
• omnibias.jax.architectures.integral_kernel.DISCLAIMER
• omnibias.torch.architectures.integral_kernel.DISCLAIMER

CLASS

IntegralKernelConfig

omnibias.core.integral_kernel.IntegralKernelConfigSource ↗

class IntegralKernelConfig

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.

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
n_dirsdataclass field	intDefault: 4	See the operation contract and implementation below.
windowdataclass field	floatDefault: 0.5	See the operation contract and implementation below.
wdataclass field	floatDefault: 1.0	See the operation contract and implementation below.

Fields & methods

n_dirsfield

n_dirs: int = 4

Declared int field on IntegralKernelConfig. Default expression: 4.

View source ↗

windowfield

window: float = 0.5

Declared float field on IntegralKernelConfig. Default expression: 0.5.

View source ↗

wfield

w: float = 1.0

Declared float field on IntegralKernelConfig. Default expression: 1.0.

View source ↗

Read the implementation

class IntegralKernelConfig:
    n_dirs: int = 4
    window: float = 0.5
    w: float = 1.0

Other public import paths

• omnibias.core.integral_kernel.IntegralKernelConfig
• omnibias.jax.architectures.IntegralKernelConfig
• omnibias.torch.architectures.IntegralKernelConfig
• omnibias.jax.architectures.integral_kernel.IntegralKernelConfig
• omnibias.torch.architectures.integral_kernel.IntegralKernelConfig

FUNCTION

antiderivative_skill

omnibias.core.integral_kernel.antiderivative_skillSource ↗

antiderivative_skill(*, seeds: int=5, n: int=33, n_dirs: int=4) -> dict[str, object]

G2: named Volterra int_0^x cos vs a same-width MLP kernel.

Parameters

Name	Type & default	Contract
seedskeyword-only	intDefault: 5	See the operation contract and implementation below.
nkeyword-only	intDefault: 33	See the operation contract and implementation below.
n_dirskeyword-only	intDefault: 4	See the operation contract and implementation below.

Returnsdict[str, object]

Executed regression · g2 antiderivative

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_g2_antiderivative() -> None:
    report = antiderivative_skill()
    assert report["below_1e3"] is True
    assert report["skill_positive"] is True
    assert float(report["skill"]) > 0.0

python -m pytest "packages/omnibias-core/tests/test_integral_kernel.py::test_g2_antiderivative" -q

Read the implementation

def antiderivative_skill(
    *,
    seeds: int = 5,
    n: int = 33,
    n_dirs: int = 4,
) -> dict[str, object]:
    """G2: named Volterra ``int_0^x cos`` vs a same-width MLP kernel."""
    lo = 0.0
    hi = 0.5 * math.pi
    xs = [lo + (hi - lo) * i / (n - 1) for i in range(n)]
    fs = [math.cos(x) for x in xs]
    target = [math.sin(x) for x in xs]
    pred = volterra_apply(fs, xs, nodes=xs)
    max_err = max(abs(a - b) for a, b in zip(pred, target, strict=True))
    skill = 1.0 - _rmse(pred, target) / _rmse([0.0] * n, target)
    mlp_max: list[float] = []
    for seed in range(seeds):
        cols: list[list[float]] = []
        for k in range(n_dirs):
            alpha = 1.0 + 0.7 * float(k) + 0.15 * float(seed)
            bias = -0.4 + 0.2 * float(k) - 0.05 * float(seed)
            col = []
            weights = _trap_weights(xs)
            for x in xs:
                acc = 0.0
                for y, f, weight in zip(xs, fs, weights, strict=True):
                    acc += sigmoid(alpha * (x - y) + bias) * f * weight
                col.append(acc)
            cols.append(col)
        amps = _lstsq(cols, target)
        mlp = [
            sum(a * col[i] for a, col in zip(amps, cols, strict=True)) for i in range(n)
        ]
        mlp_max.append(max(abs(a - b) for a, b in zip(mlp, target, strict=True)))
    mlp_med = sorted(mlp_max)[len(mlp_max) // 2]
    return {
        "max_err": max_err,
        "skill": skill,
        "mlp_median": mlp_med,
        "below_1e3": max_err < 1e-3,
        "skill_positive": skill > 0.0,
        "beats_mlp": max_err < mlp_med,
        "g2_earned": max_err < 1e-3 and skill > 0.0 and max_err < mlp_med,
    }

Related APIsomnibias.core.ftc.sigmoid↗omnibias.core.integral_kernel.volterra_apply↗

FUNCTION

honesty_payload

omnibias.core.integral_kernel.honesty_payloadSource ↗

honesty_payload() -> dict[str, bool]

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Returnsdict[str, bool]

Executed regression · g3 honesty

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_g3_honesty() -> None:
    payload = honesty_payload()
    assert payload["claimed_bem_net"] is False
    assert payload["claimed_fno_sota"] is False
    assert payload["theorem_prover_verified"] is False
    assert "not BEM-Net" in DISCLAIMER

python -m pytest "packages/omnibias-core/tests/test_integral_kernel.py::test_g3_honesty" -q

Read the implementation

def honesty_payload() -> dict[str, bool]:
    return {
        "claimed_bem_net": False,
        "claimed_fno_sota": False,
        "stretch_claim": False,
        "theorem_prover_verified": False,
    }

Other public import paths

• omnibias.core.integral_kernel.honesty_payload
• omnibias.jax.architectures.integral_kernel.honesty_payload
• omnibias.torch.architectures.integral_kernel.honesty_payload

FUNCTION

integral_cell

omnibias.core.integral_kernel.integral_cellSource ↗

integral_cell(z: float, b_lo: float, b_hi: float) -> float

S(z + b_hi) - S(z + b_lo). Matches OperatorBlock(op='integral').

Parameters

Name	Type & default	Contract
zpositional-or-keyword	floatRequired	See the operation contract and implementation below.
b_lopositional-or-keyword	floatRequired	See the operation contract and implementation below.
b_hipositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

• When b_hi == b_lo, raises ValueError('window is degenerate; collapse is a separate head').

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

Executed regression · degenerate window

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_degenerate_window() -> None:
    with pytest.raises(ValueError, match="degenerate"):
        integral_cell(0.0, 0.1, 0.1)

python -m pytest "packages/omnibias-core/tests/test_integral_kernel.py::test_degenerate_window" -q

Regression example · g1

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_g1() -> None:
    ex = worked_example()
    assert ex["g1_err"] < 1e-12
    z = jnp.asarray([0.5])
    cell = float(integral_cell(z, -0.5, 0.5)[0])
    assert abs(cell - core_cell(0.5, -0.5, 0.5)) < 1e-12

python -m pytest packages/omnibias-jax/tests/test_integral_kernel.py -k test_g1 -q

Read the implementation

def integral_cell(z: float, b_lo: float, b_hi: float) -> float:
    """``S(z + b_hi) - S(z + b_lo)``. Matches ``OperatorBlock(op='integral')``."""
    if b_hi == b_lo:
        raise ValueError("window is degenerate; collapse is a separate head")
    return softplus(z + b_hi) - softplus(z + b_lo)

Related APIsomnibias.core.ftc.softplus↗

FUNCTION

integral_kernel_apply

omnibias.core.integral_kernel.integral_kernel_applySource ↗

integral_kernel_apply(source: Sequence[float], coords: Sequence[float], params: Sequence[float] | None=None, *, config: IntegralKernelConfig | None=None, nodes: Sequence[float] | None=None) -> list[float]

Apply (Kf)(x) = sum_j w_j K(x, y_j) f(y_j). Not BEM-Net.

Parameters

Name	Type & default	Contract
sourcepositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
coordspositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
paramspositional-or-keyword	Sequence[float] | NoneDefault: None	See the operation contract and implementation below.
configkeyword-only	IntegralKernelConfig | NoneDefault: None	See the operation contract and implementation below.
nodeskeyword-only	Sequence[float] | NoneDefault: None	See the operation contract and implementation below.

Returnslist[float]

Explicit validation & failure cases

• When len(source) != len(ys), raises ValueError('source and nodes must have the same length').

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

Read the implementation

def integral_kernel_apply(
    source: Sequence[float],
    coords: Sequence[float],
    params: Sequence[float] | None = None,
    *,
    config: IntegralKernelConfig | None = None,
    nodes: Sequence[float] | None = None,
) -> list[float]:
    """Apply ``(Kf)(x) = sum_j w_j K(x, y_j) f(y_j)``. Not BEM-Net."""
    cfg = DEFAULT_CONFIG if config is None else config
    ys = list(nodes) if nodes is not None else list(coords)
    if len(source) != len(ys):
        raise ValueError("source and nodes must have the same length")
    weights = _trap_weights(ys)
    scale = 1.0 if not params else float(params[0])
    out: list[float] = []
    for x in coords:
        acc = 0.0
        for y, f, weight in zip(ys, source, weights, strict=True):
            acc += kernel(x, y, config=cfg) * f * weight
        out.append(scale * acc)
    return out

Related APIsomnibias.core.integral_kernel.kernel↗

FUNCTION

kernel

omnibias.core.integral_kernel.kernelSource ↗

kernel(x: float, y: float, *, config: IntegralKernelConfig | None=None) -> float

Volumetric kernel in z = w (x - y). Not BEM-Net.

Parameters

Name	Type & default	Contract
xpositional-or-keyword	floatRequired	See the operation contract and implementation below.
ypositional-or-keyword	floatRequired	See the operation contract and implementation below.
configkeyword-only	IntegralKernelConfig | NoneDefault: None	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

• When cfg.window <= 0.0, raises ValueError(f'window must be > 0, got {cfg.window}').

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

Read the implementation

def kernel(x: float, y: float, *, config: IntegralKernelConfig | None = None) -> float:
    """Volumetric kernel in ``z = w (x - y)``. Not BEM-Net."""
    cfg = DEFAULT_CONFIG if config is None else config
    if cfg.window <= 0.0:
        raise ValueError(f"window must be > 0, got {cfg.window}")
    half = 0.5 * cfg.window
    return integral_cell(cfg.w * (x - y), -half, half)

Related APIsomnibias.core.integral_kernel.integral_cell↗

FUNCTION

volterra_apply

omnibias.core.integral_kernel.volterra_applySource ↗

volterra_apply(source: Sequence[float], coords: Sequence[float], *, nodes: Sequence[float] | None=None) -> list[float]

Named 1-D antiderivative int_{y0}^x f. Heaviside limit of the kernel.

Parameters

Name	Type & default	Contract
sourcepositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
coordspositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.
nodeskeyword-only	Sequence[float] | NoneDefault: None	See the operation contract and implementation below.

Returnslist[float]

Explicit validation & failure cases

• When len(source) != len(ys), raises ValueError('source and nodes must have the same length').
• When ys != list(coords), raises ValueError('volterra_apply requires coords == nodes').

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

Executed regression · g2 antiderivative

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_g2_antiderivative() -> None:
    report = antiderivative_skill()
    assert report["below_1e3"] is True
    assert report["skill_positive"] is True
    assert float(report["skill"]) > 0.0

python -m pytest "packages/omnibias-core/tests/test_integral_kernel.py::test_g2_antiderivative" -q

Read the implementation

def volterra_apply(
    source: Sequence[float],
    coords: Sequence[float],
    *,
    nodes: Sequence[float] | None = None,
) -> list[float]:
    """Named 1-D antiderivative ``int_{y0}^x f``. Heaviside limit of the kernel."""
    ys = list(nodes) if nodes is not None else list(coords)
    if len(source) != len(ys):
        raise ValueError("source and nodes must have the same length")
    if ys != list(coords):
        raise ValueError("volterra_apply requires coords == nodes")
    out = [0.0]
    for i in range(1, len(ys)):
        out.append(out[-1] + 0.5 * (source[i] + source[i - 1]) * (ys[i] - ys[i - 1]))
    return out

FUNCTION

worked_example

omnibias.core.integral_kernel.worked_exampleSource ↗

worked_example() -> dict[str, float]

Mass of a unit source on [0, 1] at x=0.5, w=1.

softplus(0.5) - softplus(-0.5) is a mass, not ||f||_1.

Returnsdict[str, float]

Executed regression · g1

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_g1() -> None:
    ex = worked_example()
    assert ex["g1_err"] < 1e-12
    z = jnp.asarray([0.5])
    cell = float(integral_cell(z, -0.5, 0.5)[0])
    assert abs(cell - core_cell(0.5, -0.5, 0.5)) < 1e-12

python -m pytest "packages/omnibias-jax/tests/test_integral_kernel.py::test_g1" -q

Regression example · g1 cell

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_g1_cell() -> None:
    ex = worked_example()
    assert ex["g1_err"] < 1e-12
    assert abs(integral_cell(0.5, -0.5, 0.5) - (softplus(1.0) - softplus(0.0))) < 1e-12
    assert abs(ex["mass"] - 0.5) < 1e-12

python -m pytest packages/omnibias-core/tests/test_integral_kernel.py -k test_g1_cell -q

Read the implementation

def worked_example() -> dict[str, float]:
    """Mass of a unit source on ``[0, 1]`` at ``x=0.5``, ``w=1``.

    ``softplus(0.5) - softplus(-0.5)`` is a mass, not ``||f||_1``.
    """
    mass = integral_cell(0.5, -1.0, 0.0)
    expected = softplus(0.5) - softplus(-0.5)
    g1_cell = integral_cell(0.5, -0.5, 0.5)
    g1_ref = softplus(1.0) - softplus(0.0)
    return {
        "mass": mass,
        "mass_expected": expected,
        "mass_err": abs(mass - expected),
        "g1_cell": g1_cell,
        "g1_ref": g1_ref,
        "g1_err": abs(g1_cell - g1_ref),
    }

Related APIsomnibias.core.ftc.softplus↗omnibias.core.integral_kernel.integral_cell↗

← Package overviewRunnable learning examples →