omnibias.core.verified.laguerre_basis

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.verified.laguerre_basis

Module contract & mathematical conventions

Verified Laguerre-function basis on [0, inf) -- sibling of Hermite.

Convention

This module fixes the **standard Laguerre polynomials** L_n = L_n^{(0)},

L_0(x) = 1,\quad L_1(x) = 1 - x, \quad L_{n+1}(x) = \frac{(2n+1-x)\,L_n(x) - n\,L_{n-1}(x)}{n+1},

with **exact rational** coefficients (the recurrence introduces a division by n+1, so the coefficients live in Q, not Z). The (unnormalized) **Laguerre function** used here is

\ell_n(x) = L_n(x)\, e^{-x/2}, \qquad x \ge 0,

evaluated as an interval Horner scheme over ~fractions.Fraction coefficients times a rigorous enclosure of exp(-x/2).

This is a **sibling** of omnibias.core.verified.hermite_basis, not a drop-in Fourier eigenbasis: Laguerre functions are orthogonal on [0, inf) with weight e^{-x}, and they are **not** self-dual under the Fourier transform (there is no analogue of the exact (-i)^n multiplier). A tail bound is still available under a caller-supplied uniform |ell_n(x)| hypothesis, via the same geometric-decay contract as ~omnibias.core.verified.hermite_basis.HermiteExpansion.

Scope. This module never claims a continuum spectral theorem, a Cohn-Elkies packing bound, or a Fourier inversion identity.

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

LaguerreExpansion

omnibias.core.verified.LaguerreExpansionSource ↗

class LaguerreExpansion

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.

A finite Laguerre-function expansion f = sum_{n=0}^{N} c_n ell_n.

No stored tail radius: as with ~omnibias.core.verified.hermite_basis.HermiteExpansion, the tail depends on the evaluation point through |ell_n(x)|.

Parameters

Name	Type & default	Contract
`coeffs`dataclass field	`list[ComplexInterval]`Required	See the operation contract and implementation below.

Executed regression · laguerre expansion tail contains kept

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_laguerre_expansion_tail_contains_kept() -> None:
    expansion = LaguerreExpansion.from_coeffs([1.0, -0.1])
    kept = expansion.evaluate_kept(0.25)
    full = expansion.evaluate(0.25, coeff_bound=1.0, ratio=0.4, psi_bound=2.0)
    assert full.re.lo <= kept.re.lo and full.re.hi >= kept.re.hi

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_expansion_tail_contains_kept" -q

Fields & methods

coeffsfield

coeffs: list[ComplexInterval]

Declared list[ComplexInterval] field on LaguerreExpansion. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.

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 not self.coeffs, raises ValueError('LaguerreExpansion needs at least one coefficient').

Executed regression · laguerre expansion tail contains kept

Full file, imports & fixtures ↗

def test_laguerre_expansion_tail_contains_kept() -> None:
    expansion = LaguerreExpansion.from_coeffs([1.0, -0.1])
    kept = expansion.evaluate_kept(0.25)
    full = expansion.evaluate(0.25, coeff_bound=1.0, ratio=0.4, psi_bound=2.0)
    assert full.re.lo <= kept.re.lo and full.re.hi >= kept.re.hi

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_expansion_tail_contains_kept" -q

Method implementation

    def __post_init__(self) -> None:
        if not self.coeffs:
            raise ValueError("LaguerreExpansion needs at least one coefficient")

View source ↗

orderproperty

order(self) -> int

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

Returns: int

Executed regression · laguerre expansion tail contains kept

Full file, imports & fixtures ↗

def test_laguerre_expansion_tail_contains_kept() -> None:
    expansion = LaguerreExpansion.from_coeffs([1.0, -0.1])
    kept = expansion.evaluate_kept(0.25)
    full = expansion.evaluate(0.25, coeff_bound=1.0, ratio=0.4, psi_bound=2.0)
    assert full.re.lo <= kept.re.lo and full.re.hi >= kept.re.hi

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_expansion_tail_contains_kept" -q

Method implementation

    def order(self) -> int:
        return len(self.coeffs) - 1

View source ↗

from_coeffsmethod

from_coeffs(cls, coeffs: Sequence[ComplexLike]) -> LaguerreExpansion

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

Parameters

Name	Type & default	Contract
`coeffs`positional-or-keyword	`Sequence[ComplexLike]`Required	See the operation contract and implementation below.

Returns: LaguerreExpansion

Executed regression · laguerre expansion tail contains kept

Full file, imports & fixtures ↗

def test_laguerre_expansion_tail_contains_kept() -> None:
    expansion = LaguerreExpansion.from_coeffs([1.0, -0.1])
    kept = expansion.evaluate_kept(0.25)
    full = expansion.evaluate(0.25, coeff_bound=1.0, ratio=0.4, psi_bound=2.0)
    assert full.re.lo <= kept.re.lo and full.re.hi >= kept.re.hi

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_expansion_tail_contains_kept" -q

Method implementation

    def from_coeffs(cls, coeffs: Sequence[ComplexLike]) -> LaguerreExpansion:
        return cls([ComplexInterval.from_value(c) for c in coeffs])

View source ↗

evaluate_keptmethod

evaluate_kept(self, x: IntervalLike) -> ComplexInterval

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

Parameters

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

Returns: ComplexInterval

Executed regression · laguerre expansion tail contains kept

Full file, imports & fixtures ↗

def test_laguerre_expansion_tail_contains_kept() -> None:
    expansion = LaguerreExpansion.from_coeffs([1.0, -0.1])
    kept = expansion.evaluate_kept(0.25)
    full = expansion.evaluate(0.25, coeff_bound=1.0, ratio=0.4, psi_bound=2.0)
    assert full.re.lo <= kept.re.lo and full.re.hi >= kept.re.hi

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_expansion_tail_contains_kept" -q

Method implementation

    def evaluate_kept(self, x: IntervalLike) -> ComplexInterval:
        xi = Interval.from_value(x)
        acc = ComplexInterval.zero()
        for n, coeff in enumerate(self.coeffs):
            acc = acc + coeff * ComplexInterval.from_value(laguerre_function(n, xi))
        return acc

View source ↗

tail_boundmethod

tail_bound(self, x: IntervalLike, *, coeff_bound: float, ratio: float, psi_bound: float) -> Interval

Geometric tail sum_{n>N} |c_n ell_n(x)| under a uniform psi_bound.

Requires |c_n| <= coeff_bound * ratio^n past the truncation and |ell_n(x)| <= psi_bound for those n. The weight nu of ~omnibias.core.verified.sequence_space.geometric_tail_bound is 1 (unweighted coefficient decay).

Parameters

Name	Type & default	Contract
`x`positional-or-keyword	`IntervalLike`Required	See the operation contract and implementation below.
`coeff_bound`keyword-only	`float`Required	See the operation contract and implementation below.
`ratio`keyword-only	`float`Required	See the operation contract and implementation below.
`psi_bound`keyword-only	`float`Required	See the operation contract and implementation below.

Returns: Interval

Validation & failure cases

When psi_bound < 0.0, raises ValueError(f'psi_bound must be >= 0, got {psi_bound!r}').

Executed regression · laguerre expansion tail contains kept

Full file, imports & fixtures ↗

def test_laguerre_expansion_tail_contains_kept() -> None:
    expansion = LaguerreExpansion.from_coeffs([1.0, -0.1])
    kept = expansion.evaluate_kept(0.25)
    full = expansion.evaluate(0.25, coeff_bound=1.0, ratio=0.4, psi_bound=2.0)
    assert full.re.lo <= kept.re.lo and full.re.hi >= kept.re.hi

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_expansion_tail_contains_kept" -q

Method implementation

    def tail_bound(
        self,
        x: IntervalLike,
        *,
        coeff_bound: float,
        ratio: float,
        psi_bound: float,
    ) -> Interval:
        r"""Geometric tail ``sum_{n>N} |c_n ell_n(x)|`` under a uniform ``psi_bound``.

        Requires ``|c_n| <= coeff_bound * ratio^n`` past the truncation and
        ``|ell_n(x)| <= psi_bound`` for those ``n``.  The weight ``nu`` of
        :func:`~omnibias.core.verified.sequence_space.geometric_tail_bound` is
        ``1`` (unweighted coefficient decay).
        """
        del x  # bound is uniform in x by hypothesis on psi_bound
        if psi_bound < 0.0:
            raise ValueError(f"psi_bound must be >= 0, got {psi_bound!r}")
        return geometric_tail_bound(coeff_bound, ratio, 1.0, self.order) * Interval.point(
            psi_bound
        )

View source ↗

evaluatemethod

evaluate(self, x: IntervalLike, *, coeff_bound: float, ratio: float, psi_bound: float) -> ComplexInterval

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

Parameters

Name	Type & default	Contract
`x`positional-or-keyword	`IntervalLike`Required	See the operation contract and implementation below.
`coeff_bound`keyword-only	`float`Required	See the operation contract and implementation below.
`ratio`keyword-only	`float`Required	See the operation contract and implementation below.
`psi_bound`keyword-only	`float`Required	See the operation contract and implementation below.

Returns: ComplexInterval

Executed regression · laguerre expansion tail contains kept

Full file, imports & fixtures ↗

def test_laguerre_expansion_tail_contains_kept() -> None:
    expansion = LaguerreExpansion.from_coeffs([1.0, -0.1])
    kept = expansion.evaluate_kept(0.25)
    full = expansion.evaluate(0.25, coeff_bound=1.0, ratio=0.4, psi_bound=2.0)
    assert full.re.lo <= kept.re.lo and full.re.hi >= kept.re.hi

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_expansion_tail_contains_kept" -q

Method implementation

    def evaluate(
        self,
        x: IntervalLike,
        *,
        coeff_bound: float,
        ratio: float,
        psi_bound: float,
    ) -> ComplexInterval:
        kept = self.evaluate_kept(x)
        tail = self.tail_bound(x, coeff_bound=coeff_bound, ratio=ratio, psi_bound=psi_bound)
        pad = Interval(-tail.hi, tail.hi)
        return ComplexInterval(kept.re + pad, kept.im + pad)

View source ↗

Read the implementation

class LaguerreExpansion:
    """A finite Laguerre-function expansion ``f = sum_{n=0}^{N} c_n ell_n``.

    No stored tail radius: as with :class:`~omnibias.core.verified.hermite_basis.HermiteExpansion`,
    the tail depends on the evaluation point through ``|ell_n(x)|``.
    """

    coeffs: list[ComplexInterval]

    def __post_init__(self) -> None:
        if not self.coeffs:
            raise ValueError("LaguerreExpansion needs at least one coefficient")

    @property
    def order(self) -> int:
        return len(self.coeffs) - 1

    @classmethod
    def from_coeffs(cls, coeffs: Sequence[ComplexLike]) -> LaguerreExpansion:
        return cls([ComplexInterval.from_value(c) for c in coeffs])

    def evaluate_kept(self, x: IntervalLike) -> ComplexInterval:
        xi = Interval.from_value(x)
        acc = ComplexInterval.zero()
        for n, coeff in enumerate(self.coeffs):
            acc = acc + coeff * ComplexInterval.from_value(laguerre_function(n, xi))
        return acc

    def tail_bound(
        self,
        x: IntervalLike,
        *,
        coeff_bound: float,
        ratio: float,
        psi_bound: float,
    ) -> Interval:
        r"""Geometric tail ``sum_{n>N} |c_n ell_n(x)|`` under a uniform ``psi_bound``.

        Requires ``|c_n| <= coeff_bound * ratio^n`` past the truncation and
        ``|ell_n(x)| <= psi_bound`` for those ``n``.  The weight ``nu`` of
        :func:`~omnibias.core.verified.sequence_space.geometric_tail_bound` is
        ``1`` (unweighted coefficient decay).
        """
        del x  # bound is uniform in x by hypothesis on psi_bound
        if psi_bound < 0.0:
            raise ValueError(f"psi_bound must be >= 0, got {psi_bound!r}")
        return geometric_tail_bound(coeff_bound, ratio, 1.0, self.order) * Interval.point(
            psi_bound
        )

    def evaluate(
        self,
        x: IntervalLike,
        *,
        coeff_bound: float,
        ratio: float,
        psi_bound: float,
    ) -> ComplexInterval:
        kept = self.evaluate_kept(x)
        tail = self.tail_bound(x, coeff_bound=coeff_bound, ratio=ratio, psi_bound=psi_bound)
        pad = Interval(-tail.hi, tail.hi)
        return ComplexInterval(kept.re + pad, kept.im + pad)

Other public import paths

omnibias.core.verified.LaguerreExpansion
omnibias.core.verified.laguerre_basis.LaguerreExpansion

FUNCTION

laguerre_function

omnibias.core.verified.laguerre_functionSource ↗

laguerre_function(n: int, x: IntervalLike) -> Interval

Rigorous enclosure of ell_n(x) = L_n(x) exp(-x/2) for x >= 0.

Parameters

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

ReturnsInterval

Executed regression · laguerre function contains reference

Full file, imports & fixtures ↗

def test_laguerre_function_contains_reference() -> None:
    x = 0.5
    l0 = laguerre_function(0, x)
    l1 = laguerre_function(1, x)
    weight = float(laguerre_weight(x).mid)
    assert l0.contains(weight)
    assert l1.contains((1.0 - x) * weight)

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_function_contains_reference" -q

Read the implementation

def laguerre_function(n: int, x: IntervalLike) -> Interval:
    r"""Rigorous enclosure of ``ell_n(x) = L_n(x) exp(-x/2)`` for ``x >= 0``."""
    xi = Interval.from_value(x)
    return _horner_rational(laguerre_poly_coeffs_exact(n), xi) * laguerre_weight(xi)

Other public import paths

omnibias.core.verified.laguerre_function
omnibias.core.verified.laguerre_basis.laguerre_function

FUNCTION

laguerre_poly_coeffs_exact

omnibias.core.verified.laguerre_poly_coeffs_exactSource ↗

laguerre_poly_coeffs_exact(n: int) -> tuple[Fraction, ...]

Exact rational coefficients of L_n, low-degree first.

L_n(x) = sum_{k=0}^n c_k x^k with each c_k a ~fractions.Fraction.

Parameters

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

Returnstuple[Fraction, ...]

Explicit validation & failure cases

When n < 0, raises ValueError(f'order n must be >= 0, got {n}').

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

Executed regression · laguerre low order coeffs

Full file, imports & fixtures ↗

def test_laguerre_low_order_coeffs() -> None:
    assert laguerre_poly_coeffs_exact(0) == (Fraction(1),)
    assert laguerre_poly_coeffs_exact(1) == (Fraction(1), Fraction(-1))
    # L_2 = (2 - 4x + x^2) / 2 = 1 - 2x + x^2/2
    assert laguerre_poly_coeffs_exact(2) == (Fraction(1), Fraction(-2), Fraction(1, 2))

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_low_order_coeffs" -q

Read the implementation

def laguerre_poly_coeffs_exact(n: int) -> tuple[Fraction, ...]:
    """Exact rational coefficients of ``L_n``, low-degree first.

    ``L_n(x) = sum_{k=0}^n c_k x^k`` with each ``c_k`` a
    :class:`~fractions.Fraction`.
    """
    if n < 0:
        raise ValueError(f"order n must be >= 0, got {n}")
    if n == 0:
        return (Fraction(1),)
    if n == 1:
        return (Fraction(1), Fraction(-1))
    prev2: tuple[Fraction, ...] = (Fraction(1),)
    prev1: tuple[Fraction, ...] = (Fraction(1), Fraction(-1))
    for m in range(1, n):
        # L_{m+1} = ((2m+1) L_m - x L_m - m L_{m-1}) / (m+1)
        scale = Fraction(2 * m + 1)
        denom = Fraction(m + 1)
        shifted = (Fraction(0),) + prev1  # x * L_m
        length = max(len(prev1), len(shifted), len(prev2))
        out = [Fraction(0)] * length
        for k, c in enumerate(prev1):
            out[k] += scale * c
        for k, c in enumerate(shifted):
            out[k] -= c
        for k, c in enumerate(prev2):
            out[k] -= Fraction(m) * c
        prev2, prev1 = prev1, tuple(c / denom for c in out)
    return prev1

Other public import paths

omnibias.core.verified.laguerre_poly_coeffs_exact
omnibias.core.verified.laguerre_basis.laguerre_poly_coeffs_exact

FUNCTION

laguerre_weight

omnibias.core.verified.laguerre_weightSource ↗

laguerre_weight(x: IntervalLike) -> Interval

Rigorous enclosure of exp(-x/2) for x >= 0.

Parameters

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

ReturnsInterval

Explicit validation & failure cases

When xi.lo < 0.0, raises ValueError(f'Laguerre weight requires x >= 0, got x.lo={xi.lo!r}').

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

Executed regression · laguerre refuses negative x

Full file, imports & fixtures ↗

def test_laguerre_refuses_negative_x() -> None:
    import pytest

    with pytest.raises(ValueError, match="x >= 0"):
        laguerre_weight(Interval(-0.1, 0.1))

python -m pytest "packages/omnibias-core/tests/verified/test_laguerre_basis.py::test_laguerre_refuses_negative_x" -q

Regression example · laguerre function contains reference

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_laguerre_function_contains_reference() -> None:
    x = 0.5
    l0 = laguerre_function(0, x)
    l1 = laguerre_function(1, x)
    weight = float(laguerre_weight(x).mid)
    assert l0.contains(weight)
    assert l1.contains((1.0 - x) * weight)

python -m pytest packages/omnibias-core/tests/verified/test_laguerre_basis.py -k test_laguerre_function_contains_reference -q

Read the implementation

def laguerre_weight(x: IntervalLike) -> Interval:
    """Rigorous enclosure of ``exp(-x/2)`` for ``x >= 0``."""
    xi = Interval.from_value(x)
    if xi.lo < 0.0:
        raise ValueError(f"Laguerre weight requires x >= 0, got x.lo={xi.lo!r}")
    return exp_iv(Interval.point(-0.5) * xi)

Other public import paths

omnibias.core.verified.laguerre_weight
omnibias.core.verified.laguerre_basis.laguerre_weight

← Package overview Runnable learning examples →

omnibias.core.verified.laguerre_basis

LaguerreExpansion​

Parameters

Fields & methods

Parameters

Parameters

Parameters

Parameters

laguerre_function​

Parameters

laguerre_poly_coeffs_exact​

Parameters

laguerre_weight​

Parameters

LaguerreExpansion

laguerre_function

laguerre_poly_coeffs_exact

laguerre_weight