omnibias.core.frames

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

Module contract & mathematical conventions

OMBU wavelet frames (theory 01-06).

sigma' is **not** admissible (admissibility_constant(..., 1) returns None, never a guess). Frames are not orthonormal and not compactly supported; there is no O(N) fast transform. Pack order remains a band selector (01-07), not a Littlewood-Paley completeness claim.

The atoms come from founding delta -> 0. No temperature collapse. Pure Python: no tensor imports. A FrameSpec compiles to a BankSpec.

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

FrameSpec

omnibias.core.FrameSpecSource ↗

class FrameSpec

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.

Discrete analytic frame: order-n atoms on a scale / offset bank.

Not orthonormal, not compactly supported, no O(N) transform.

Parameters

Name	Type & default	Contract
`base`dataclass field	`str`Required	See the operation contract and implementation below.
`order`dataclass field	`int`Required	See the operation contract and implementation below.
`scales`dataclass field	`tuple[float, ...]`Required	See the operation contract and implementation below.
`offset_spacing`dataclass field	`float`Required	See the operation contract and implementation below.
`n_offsets`dataclass field	`int`Default: 16	See the operation contract and implementation below.

Executed regression · compile bank

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_compile_bank() -> None:
    spec = FrameSpec("sech", 3, scales=(1.0, 2.0), offset_spacing=0.5, n_offsets=8)
    bank = compile_bank(spec)
    assert bank.n_offsets == 8
    assert bank.scales == (1.0, 2.0)
    assert bank.spacing == pytest.approx(0.5)

python -m pytest "packages/omnibias-core/tests/test_frames.py::test_compile_bank" -q

Regression example · g2 lp bounds contain grid and sample

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_lp_bounds_contain_grid_and_sample() -> None:
    spec = FrameSpec("gaussian", 2, scales=(0.5, 1.0, 2.0), offset_spacing=0.25)
    a, b = littlewood_paley_bounds(spec, grid=1024)
    rng = __import__("random").Random(0)
    for xi in [2.0 ** ((i - 200) / 16.0) for i in range(400)] + [
        2.0 ** rng.uniform(-8, 8) for _ in range(40)
    ]:
        acc = 0.0
        for s in spec.scales:
            mag = (abs(s * xi) ** spec.order) * math.sqrt(s) * hat_sigma_magnitude(
                spec.base, s * xi
            )
            acc += mag * mag
        assert a.lo - 1e-12 <= acc <= b.hi + 1e-12

python -m pytest packages/omnibias-core/tests/test_frames.py -k test_g2_lp_bounds_contain_grid_and_sample -q

Fields & methods

basefield

base: str

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

Regression example · g2 lp bounds contain grid and sample

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_lp_bounds_contain_grid_and_sample() -> None:
    spec = FrameSpec("gaussian", 2, scales=(0.5, 1.0, 2.0), offset_spacing=0.25)
    a, b = littlewood_paley_bounds(spec, grid=1024)
    rng = __import__("random").Random(0)
    for xi in [2.0 ** ((i - 200) / 16.0) for i in range(400)] + [
        2.0 ** rng.uniform(-8, 8) for _ in range(40)
    ]:
        acc = 0.0
        for s in spec.scales:
            mag = (abs(s * xi) ** spec.order) * math.sqrt(s) * hat_sigma_magnitude(
                spec.base, s * xi
            )
            acc += mag * mag
        assert a.lo - 1e-12 <= acc <= b.hi + 1e-12

python -m pytest packages/omnibias-core/tests/test_frames.py -k test_g2_lp_bounds_contain_grid_and_sample -q

View source ↗

orderfield

order: int

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

Regression example · g2 lp bounds contain grid and sample

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_lp_bounds_contain_grid_and_sample() -> None:
    spec = FrameSpec("gaussian", 2, scales=(0.5, 1.0, 2.0), offset_spacing=0.25)
    a, b = littlewood_paley_bounds(spec, grid=1024)
    rng = __import__("random").Random(0)
    for xi in [2.0 ** ((i - 200) / 16.0) for i in range(400)] + [
        2.0 ** rng.uniform(-8, 8) for _ in range(40)
    ]:
        acc = 0.0
        for s in spec.scales:
            mag = (abs(s * xi) ** spec.order) * math.sqrt(s) * hat_sigma_magnitude(
                spec.base, s * xi
            )
            acc += mag * mag
        assert a.lo - 1e-12 <= acc <= b.hi + 1e-12

python -m pytest packages/omnibias-core/tests/test_frames.py -k test_g2_lp_bounds_contain_grid_and_sample -q

View source ↗

scalesfield

scales: tuple[float, ...]

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

Regression example · g2 lp bounds contain grid and sample

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_lp_bounds_contain_grid_and_sample() -> None:
    spec = FrameSpec("gaussian", 2, scales=(0.5, 1.0, 2.0), offset_spacing=0.25)
    a, b = littlewood_paley_bounds(spec, grid=1024)
    rng = __import__("random").Random(0)
    for xi in [2.0 ** ((i - 200) / 16.0) for i in range(400)] + [
        2.0 ** rng.uniform(-8, 8) for _ in range(40)
    ]:
        acc = 0.0
        for s in spec.scales:
            mag = (abs(s * xi) ** spec.order) * math.sqrt(s) * hat_sigma_magnitude(
                spec.base, s * xi
            )
            acc += mag * mag
        assert a.lo - 1e-12 <= acc <= b.hi + 1e-12

python -m pytest packages/omnibias-core/tests/test_frames.py -k test_g2_lp_bounds_contain_grid_and_sample -q

View source ↗

offset_spacingfield

offset_spacing: float

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

View source ↗

n_offsetsfield

n_offsets: int = 16

Declared int field on FrameSpec. Default expression: 16.

View source ↗

__post_init__method

__post_init__(self) -> None

See the class contract above and the exact method implementation below.

Returns: None

Validation & failure cases

When name not in _CLOSED, raises ValueError(f'frame base {self.base!r} has no closed-form Fourier; expected one of {sorted(_CLOSED)}').
When self.order < 1, raises ValueError('order must be >= 1').
When self.offset_spacing <= 0.0, raises ValueError('offset_spacing must be positive').
When any((s <= 0.0 for s in self.scales)), raises ValueError('scales must be positive').

Executed regression · compile bank

Full file, imports & fixtures ↗

def test_compile_bank() -> None:
    spec = FrameSpec("sech", 3, scales=(1.0, 2.0), offset_spacing=0.5, n_offsets=8)
    bank = compile_bank(spec)
    assert bank.n_offsets == 8
    assert bank.scales == (1.0, 2.0)
    assert bank.spacing == pytest.approx(0.5)

python -m pytest "packages/omnibias-core/tests/test_frames.py::test_compile_bank" -q

Method implementation

    def __post_init__(self) -> None:
        name = str(self.base).lower().strip()
        if name not in _CLOSED:
            raise ValueError(
                f"frame base {self.base!r} has no closed-form Fourier; "
                f"expected one of {sorted(_CLOSED)}"
            )
        if self.order < 1:
            raise ValueError("order must be >= 1")
        if self.offset_spacing <= 0.0:
            raise ValueError("offset_spacing must be positive")
        if any(s <= 0.0 for s in self.scales):
            raise ValueError("scales must be positive")
        object.__setattr__(self, "base", name)

View source ↗

Read the implementation

class FrameSpec:
    """Discrete analytic frame: order-``n`` atoms on a scale / offset bank.

    Not orthonormal, not compactly supported, no O(N) transform.
    """

    base: str
    order: int
    scales: tuple[float, ...]
    offset_spacing: float
    n_offsets: int = 16

    def __post_init__(self) -> None:
        name = str(self.base).lower().strip()
        if name not in _CLOSED:
            raise ValueError(
                f"frame base {self.base!r} has no closed-form Fourier; "
                f"expected one of {sorted(_CLOSED)}"
            )
        if self.order < 1:
            raise ValueError("order must be >= 1")
        if self.offset_spacing <= 0.0:
            raise ValueError("offset_spacing must be positive")
        if any(s <= 0.0 for s in self.scales):
            raise ValueError("scales must be positive")
        object.__setattr__(self, "base", name)

Other public import paths

omnibias.core.FrameSpec
omnibias.core.frames.FrameSpec

FUNCTION

admissibility_constant

omnibias.core.admissibility_constantSource ↗

admissibility_constant(base: str, order: int) -> Interval | None

Calderón constant. None for n = 1 (sigma' is not admissible).

Parameters

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

ReturnsInterval | None

Executed regression · g1 admissibility none for n1

Full file, imports & fixtures ↗

def test_g1_admissibility_none_for_n1() -> None:
    assert admissibility_constant("gaussian", 1) is None
    assert admissibility_constant("sech", 1) is None
    assert vanishing_moments("gaussian", 1) == 0

python -m pytest "packages/omnibias-core/tests/test_frames.py::test_g1_admissibility_none_for_n1" -q

Regression example · g1 sech matches integral

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_sech_matches_integral() -> None:
    c = admissibility_constant("sech", 2)
    assert c is not None
    acc = 0.0
    dx = 0.002
    x = dx
    while x < 20.0:
        hat = hat_sigma_magnitude("sech", x)
        acc += (x ** (2 * 2 - 1)) * hat * hat * dx
        x += dx
    assert c.lo <= acc <= c.hi

python -m pytest packages/omnibias-core/tests/test_frames.py -k test_g1_sech_matches_integral -q

Read the implementation

def admissibility_constant(base: str, order: int) -> Interval | None:
    """Calderón constant. ``None`` for ``n = 1`` (``sigma'`` is not admissible)."""
    n = int(order)
    if n < 2:
        return None
    name = str(base).lower().strip()
    if name == "gaussian":
        # int_0^inf xi^{2n-1} |hat g|^2 d xi = pi * (n-1)!
        # (hat g = sqrt(2 pi) e^{-xi^2/2}; boundary terms vanish for n >= 2).
        return Interval.point(pi * float(factorial(n - 1)))
    if name == "sech":
        return _sech_admissibility(n)
    return None

Other public import paths

omnibias.core.admissibility_constant
omnibias.core.frames.admissibility_constant

FUNCTION

compile_bank

omnibias.core.compile_bankSource ↗

compile_bank(spec: FrameSpec) -> BankSpec

Thin FrameSpec -> BankSpec compiler for BiasScan.

Parameters

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

ReturnsBankSpec

Explicit validation & failure cases

When n < 2, raises ValueError('n_offsets must be >= 2').

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

Executed regression · compile bank

Full file, imports & fixtures ↗

def test_compile_bank() -> None:
    spec = FrameSpec("sech", 3, scales=(1.0, 2.0), offset_spacing=0.5, n_offsets=8)
    bank = compile_bank(spec)
    assert bank.n_offsets == 8
    assert bank.scales == (1.0, 2.0)
    assert bank.spacing == pytest.approx(0.5)

python -m pytest "packages/omnibias-core/tests/test_frames.py::test_compile_bank" -q

Read the implementation

def compile_bank(spec: FrameSpec) -> BankSpec:
    """Thin ``FrameSpec -> BankSpec`` compiler for ``BiasScan``."""
    n = spec.n_offsets
    if n < 2:
        raise ValueError("n_offsets must be >= 2")
    half = 0.5 * spec.offset_spacing * (n - 1)
    return BankSpec.uniform(-half, half, n, scales=spec.scales)

Other public import paths

omnibias.core.compile_bank
omnibias.core.frames.compile_bank

FUNCTION

dilated_sigma_n

omnibias.core.dilated_sigma_nSource ↗

dilated_sigma_n(base: str, u: float, order: int, alpha: float) -> float

sigma_alpha^(n)(u) = alpha^n sigma^(n)(alpha u).

Parameters

Name	Type & default	Contract
`base`positional-or-keyword	`str`Required	See the operation contract and implementation below.
`u`positional-or-keyword	`float`Required	See the operation contract and implementation below.
`order`positional-or-keyword	`int`Required	See the operation contract and implementation below.
`alpha`positional-or-keyword	`float`Required	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

When alpha <= 0.0, raises ValueError('alpha must be positive').

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

Executed regression · g3 dilation exactness

Full file, imports & fixtures ↗

def test_g3_dilation_exactness() -> None:
    import numpy as np

    eps = np.finfo(np.float64).eps
    for base in ("gaussian", "tanh", "sech"):
        for n in range(0, 8):
            for alpha in (0.7, 1.5):
                u = -0.4
                left = dilated_sigma_n(base, u, n, alpha)
                right = (alpha**n) * dilated_sigma_n(base, alpha * u, n, 1.0)
                scale = max(abs(left), abs(right), 1.0)
                ulp = abs(left - right) / (eps * scale)
                assert ulp <= 4.0

python -m pytest "packages/omnibias-core/tests/test_frames.py::test_g3_dilation_exactness" -q

Read the implementation

def dilated_sigma_n(base: str, u: float, order: int, alpha: float) -> float:
    """``sigma_alpha^(n)(u) = alpha^n sigma^(n)(alpha u)``."""
    if alpha <= 0.0:
        raise ValueError("alpha must be positive")
    z = alpha * u
    if base == "gaussian":
        g = math.exp(-0.5 * z * z)
        he = _horner(hermite_coeffs(order), z)
        sign = 1.0 if order % 2 == 0 else -1.0
        raw = sign * he * g
    elif base in ("tanh", "sech"):
        t = math.tanh(z)
        if base == "tanh":
            raw = _horner(tanh_polynomial_coeffs(order), t)
        else:
            sech = 1.0 / math.cosh(z)
            raw = _horner(sech_polynomial_coeffs(order), t) * sech
    else:
        raise ValueError(f"unsupported frame base {base!r}")
    return (alpha**order) * raw

Other public import paths

omnibias.core.dilated_sigma_n
omnibias.core.frames.dilated_sigma_n

FUNCTION

littlewood_paley_bounds

omnibias.core.frames.littlewood_paley_boundsSource ↗

littlewood_paley_bounds(spec: FrameSpec, *, grid: int=4096) -> tuple[Interval, Interval]

Sound (A, B) enclosure of the LP sum on a log-frequency grid.

Uses an interval sup/inf over neighbouring bins, not a pointwise max. This is not a Littlewood-Paley completeness claim.

Parameters

Name	Type & default	Contract
`spec`positional-or-keyword	`FrameSpec`Required	See the operation contract and implementation below.
`grid`keyword-only	`int`Default: 4096	See the operation contract and implementation below.

Returnstuple[Interval, Interval]

Explicit validation & failure cases

When spec.order < 2, raises ValueError('LP bounds require an admissible atom (order >= 2)').

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

Executed regression · g2 lp bounds contain grid and sample

Full file, imports & fixtures ↗

def test_g2_lp_bounds_contain_grid_and_sample() -> None:
    spec = FrameSpec("gaussian", 2, scales=(0.5, 1.0, 2.0), offset_spacing=0.25)
    a, b = littlewood_paley_bounds(spec, grid=1024)
    rng = __import__("random").Random(0)
    for xi in [2.0 ** ((i - 200) / 16.0) for i in range(400)] + [
        2.0 ** rng.uniform(-8, 8) for _ in range(40)
    ]:
        acc = 0.0
        for s in spec.scales:
            mag = (abs(s * xi) ** spec.order) * math.sqrt(s) * hat_sigma_magnitude(
                spec.base, s * xi
            )
            acc += mag * mag
        assert a.lo - 1e-12 <= acc <= b.hi + 1e-12

python -m pytest "packages/omnibias-core/tests/test_frames.py::test_g2_lp_bounds_contain_grid_and_sample" -q

Read the implementation

def littlewood_paley_bounds(
    spec: FrameSpec, *, grid: int = 4096
) -> tuple[Interval, Interval]:
    """Sound ``(A, B)`` enclosure of the LP sum on a log-frequency grid.

    Uses an interval sup/inf over neighbouring bins, not a pointwise max.
    This is not a Littlewood-Paley completeness claim.
    """
    if spec.order < 2:
        raise ValueError("LP bounds require an admissible atom (order >= 2)")
    xis = [2.0 ** ((i - grid // 2) / 32.0) for i in range(grid)]
    sums: list[float] = []
    for xi in xis:
        acc = 0.0
        for a in spec.scales:
            # hat psi_a (xi) ~ sqrt(a) (i a xi)^n hat_sigma(a xi) / something
            # magnitude^2 ~ a * (a xi)^{2n} |hat_sigma(a xi)|^2
            mag = (abs(a * xi) ** spec.order) * math.sqrt(a) * hat_sigma_magnitude(
                spec.base, a * xi
            )
            acc += mag * mag
        sums.append(acc)
    bins_lo: list[float] = []
    bins_hi: list[float] = []
    for i in range(len(sums) - 1):
        bins_lo.append(min(sums[i], sums[i + 1]))
        bins_hi.append(max(sums[i], sums[i + 1]))
    return Interval(min(bins_lo), min(bins_lo)), Interval(max(bins_hi), max(bins_hi))

FUNCTION

redundancy

omnibias.core.frames.redundancySource ↗

redundancy(spec: FrameSpec) -> Interval

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
`spec`positional-or-keyword	`FrameSpec`Required	See the operation contract and implementation below.

ReturnsInterval

Read the implementation

def redundancy(spec: FrameSpec) -> Interval:
    a, b = littlewood_paley_bounds(spec)
    if a.lo <= 0.0:
        return Interval(float("inf"), float("inf"))
    return b / a

FUNCTION

vanishing_moments

omnibias.core.vanishing_momentsSource ↗

vanishing_moments(base: str, order: int) -> int

sigma^(n) has n vanishing moments for n >= 2; sigma' has none.

Parameters

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

Returnsint

Executed regression · g1 admissibility none for n1

Full file, imports & fixtures ↗

def test_g1_admissibility_none_for_n1() -> None:
    assert admissibility_constant("gaussian", 1) is None
    assert admissibility_constant("sech", 1) is None
    assert vanishing_moments("gaussian", 1) == 0

python -m pytest "packages/omnibias-core/tests/test_frames.py::test_g1_admissibility_none_for_n1" -q

Read the implementation

def vanishing_moments(base: str, order: int) -> int:
    """``sigma^(n)`` has ``n`` vanishing moments for ``n >= 2``; ``sigma'`` has none."""
    n = int(order)
    if n < 2:
        return 0
    _ = str(base)
    return n

Other public import paths

omnibias.core.vanishing_moments
omnibias.core.frames.vanishing_moments

← Package overview Runnable learning examples →

omnibias.core.frames

FrameSpec​

Parameters

Fields & methods

admissibility_constant​

Parameters

compile_bank​

Parameters

dilated_sigma_n​

Parameters

littlewood_paley_bounds​

Parameters

redundancy​

Parameters

vanishing_moments​

Parameters

FrameSpec

admissibility_constant

compile_bank

dilated_sigma_n

littlewood_paley_bounds

redundancy

vanishing_moments