API REFERENCE/omnibias-core

omnibias.core.spectral_design

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

Module contract & mathematical conventions

Order-as-frequency band algebra (theory 01-07).

Differentiation multiplies the Fourier transform by (i xi)^n, so pack order is a frequency-band selector. This module is a **design calculator**: it reports which band a channel (n, alpha) sees. It is not a wavelet frame (theory 01-06 stays concept) and it does not claim Littlewood-Paley completeness.

Closed-form hat_sigma is supplied by the caller (gaussian and sech). tanh is not in L^1, so it is not a supported transform base here.

The tower is founding bias collapse (delta -> 0). No temperature collapse appears.

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

BandPlan

omnibias.core.BandPlanSource ↗

class BandPlan

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 budget of (order, scale) channels covering a target band.

flatness is max/min of the summed response on the design interval. A large value is a spectral hole (G4), not a frame-completeness claim.

Parameters

Name	Type & default	Contract
basedataclass field	strRequired	See the operation contract and implementation below.
ordersdataclass field	tuple[int, ...]Required	See the operation contract and implementation below.
scalesdataclass field	tuple[float, ...]Required	See the operation contract and implementation below.
xi_lodataclass field	floatRequired	See the operation contract and implementation below.
xi_hidataclass field	floatRequired	See the operation contract and implementation below.
flatnessdataclass field	floatRequired	See the operation contract and implementation below.

Executed regression · worked example peaks

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_worked_example_peaks() -> None:
    plan = design_band_plan("sech", xi_lo=1.0, xi_hi=32.0, channels=4, order=2)
    peaks = tuple(
        peak_frequency("sech", n, a) for n, a in zip(plan.orders, plan.scales, strict=True)
    )
    assert peaks == pytest.approx((2.0, 4.0, 8.0, 16.0), rel=1e-12)
    assert plan.flatness < 3.0
    assert plan.has_spectral_hole() is False

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_worked_example_peaks" -q

Fields & methods

basefield

base: str

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

View source ↗

ordersfield

orders: tuple[int, ...]

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

View source ↗

scalesfield

scales: tuple[float, ...]

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

View source ↗

xi_lofield

xi_lo: float

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

View source ↗

xi_hifield

xi_hi: float

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

View source ↗

flatnessfield

flatness: float

Declared float field on BandPlan. 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 len(self.orders) != len(self.scales), raises ValueError('orders and scales must have the same length').
• When not self.orders, raises ValueError('BandPlan requires at least one channel').

Executed regression · worked example peaks

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_worked_example_peaks() -> None:
    plan = design_band_plan("sech", xi_lo=1.0, xi_hi=32.0, channels=4, order=2)
    peaks = tuple(
        peak_frequency("sech", n, a) for n, a in zip(plan.orders, plan.scales, strict=True)
    )
    assert peaks == pytest.approx((2.0, 4.0, 8.0, 16.0), rel=1e-12)
    assert plan.flatness < 3.0
    assert plan.has_spectral_hole() is False

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_worked_example_peaks" -q

Method implementation

    def __post_init__(self) -> None:
        if len(self.orders) != len(self.scales):
            raise ValueError("orders and scales must have the same length")
        if not self.orders:
            raise ValueError("BandPlan requires at least one channel")

View source ↗

n_channelsproperty

n_channels(self) -> int

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

Returns: int

Executed regression · jetkan from band plan pack count

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_jetkan_from_band_plan_pack_count() -> None:
    from omnibias.core.spectral_design import design_band_plan
    from omnibias.torch.architectures.jetkan import jetkan_from_band_plan

    plan = design_band_plan("sech", xi_lo=1.0, xi_hi=16.0, channels=3, order=1)
    cfg = jetkan_from_band_plan(plan, (2, 1))
    assert cfg.packs_per_edge == 3
    net = JetKAN(cfg, dtype=torch.float64)
    out = net(torch.zeros(2, 2, dtype=torch.float64))
    assert out.shape == (2, 1)

python -m pytest "packages/omnibias-torch/tests/test_jetkan.py::test_jetkan_from_band_plan_pack_count" -q

Method implementation

    def n_channels(self) -> int:
        return len(self.orders)

View source ↗

has_spectral_holemethod

has_spectral_hole(self, *, max_flatness: float=1.7) -> bool

True when peak-normalized covering on the peak span varies too much.

Default 1.7 separates the spec's four-channel covering (~1.53) from the deliberate two-peak hole at (2, 16) (~1.85). This is a diagnostic, not a wavelet-frame test.

Parameters

Name	Type & default	Contract
max_flatnesskeyword-only	floatDefault: 1.7	See the operation contract and implementation below.

Returns: bool

Executed regression · worked example peaks

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_worked_example_peaks() -> None:
    plan = design_band_plan("sech", xi_lo=1.0, xi_hi=32.0, channels=4, order=2)
    peaks = tuple(
        peak_frequency("sech", n, a) for n, a in zip(plan.orders, plan.scales, strict=True)
    )
    assert peaks == pytest.approx((2.0, 4.0, 8.0, 16.0), rel=1e-12)
    assert plan.flatness < 3.0
    assert plan.has_spectral_hole() is False

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_worked_example_peaks" -q

Method implementation

    def has_spectral_hole(self, *, max_flatness: float = 1.7) -> bool:
        """``True`` when peak-normalized covering on the peak span varies too much.

        Default ``1.7`` separates the spec's four-channel covering (~1.53)
        from the deliberate two-peak hole at ``(2, 16)`` (~1.85). This is a
        diagnostic, not a wavelet-frame test.
        """
        return self.flatness > float(max_flatness)

View source ↗

Read the implementation

class BandPlan:
    """A budget of ``(order, scale)`` channels covering a target band.

    ``flatness`` is ``max/min`` of the summed response on the design interval.
    A large value is a spectral hole (G4), not a frame-completeness claim.
    """

    base: str
    orders: tuple[int, ...]
    scales: tuple[float, ...]
    xi_lo: float
    xi_hi: float
    flatness: float

    def __post_init__(self) -> None:
        if len(self.orders) != len(self.scales):
            raise ValueError("orders and scales must have the same length")
        if not self.orders:
            raise ValueError("BandPlan requires at least one channel")

    @property
    def n_channels(self) -> int:
        return len(self.orders)

    def has_spectral_hole(self, *, max_flatness: float = 1.7) -> bool:
        """``True`` when peak-normalized covering on the peak span varies too much.

        Default ``1.7`` separates the spec's four-channel covering (~1.53)
        from the deliberate two-peak hole at ``(2, 16)`` (~1.85). This is a
        diagnostic, not a wavelet-frame test.
        """
        return self.flatness > float(max_flatness)

Other public import paths

• omnibias.core.BandPlan
• omnibias.core.spectral_design.BandPlan

CONSTANT

SECH_DECAY

omnibias.core.spectral_design.SECH_DECAYSource ↗

SECH_DECAY: float = pi / 2.0

Fourier decay constant for sech: hat sech(xi) = pi sech(pi xi / 2) so the exponential tail is exp(- (pi/2) |xi|).

Read the implementation

SECH_DECAY: float = pi / 2.0

FUNCTION

alpha_for_peak

omnibias.core.alpha_for_peakSource ↗

alpha_for_peak(base: str, order: int, xi_peak: float) -> float

Invert peak_frequency for the temper scale.

Parameters

Name	Type & default	Contract
basepositional-or-keyword	strRequired	See the operation contract and implementation below.
orderpositional-or-keyword	intRequired	See the operation contract and implementation below.
xi_peakpositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

• When n < 1, raises ValueError(f'alpha_for_peak requires order >= 1, got {order}').
• When not peak > 0.0 or peak != peak, raises ValueError(f'xi_peak must be finite and positive, got {xi_peak}').

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

Executed regression · schedule tracks target band

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_schedule_tracks_target_band() -> None:
    def band(t: float) -> float:
        return 2.0 + 14.0 * t

    alphas = scale_schedule(target_band=band, steps=5, base="gaussian", order=1)
    assert len(alphas) == 5
    for t, a in zip(np.linspace(0.0, 1.0, 5), alphas, strict=True):
        assert abs(peak_frequency("gaussian", 1, a) - band(float(t))) <= 1e-12

python -m pytest "packages/omnibias-fields/tests/test_scale.py::test_schedule_tracks_target_band" -q

Regression example · peak matches numerical argmax

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_peak_matches_numerical_argmax(base: str, order: int) -> None:
    """G1: closed-form peak vs argmax of R, relative <= 1e-6."""
    alpha = 1.7
    pred = peak_frequency(base, order, alpha)
    found = locate_peak_numerically(base, order, alpha)
    rel = abs(pred - found) / pred
    assert rel <= 1e-6
    # Inverse is consistent.
    a2 = alpha_for_peak(base, order, pred)
    assert a2 == pytest.approx(alpha, rel=1e-12)

python -m pytest packages/omnibias-core/tests/test_spectral_design.py -k test_peak_matches_numerical_argmax -q

Read the implementation

def alpha_for_peak(base: str, order: int, xi_peak: float) -> float:
    """Invert :func:`peak_frequency` for the temper scale."""
    name = _canonical_base(base)
    n = int(order)
    if n < 1:
        raise ValueError(f"alpha_for_peak requires order >= 1, got {order}")
    peak = float(xi_peak)
    if not (peak > 0.0) or peak != peak:
        raise ValueError(f"xi_peak must be finite and positive, got {xi_peak}")
    if name == "gaussian":
        return peak / sqrt(float(n))
    u = _sech_stationary_u(n)
    return peak * SECH_DECAY / u

Other public import paths

• omnibias.core.alpha_for_peak
• omnibias.core.spectral_design.alpha_for_peak

FUNCTION

band_plan_from_peaks

omnibias.core.spectral_design.band_plan_from_peaksSource ↗

band_plan_from_peaks(base: str, *, peaks: Sequence[float], order: int | Sequence[int]=2, xi_lo: float, xi_hi: float) -> BandPlan

Build a plan from explicit peak frequencies (used for hole diagnostics).

Parameters

Name	Type & default	Contract
basepositional-or-keyword	strRequired	See the operation contract and implementation below.
peakskeyword-only	Sequence[float]Required	See the operation contract and implementation below.
orderkeyword-only	int | Sequence[int]Default: 2	See the operation contract and implementation below.
xi_lokeyword-only	floatRequired	See the operation contract and implementation below.
xi_hikeyword-only	floatRequired	See the operation contract and implementation below.

ReturnsBandPlan

Explicit validation & failure cases

• When any((p <= 0.0 for p in peak_t)), raises ValueError('peaks must be positive').
• When len(orders) != len(peak_t), raises ValueError('order sequence must match peaks').

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

Executed regression · holed plan is flagged

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_holed_plan_is_flagged() -> None:
    """G4: two far peaks leave a hole; four-channel plan does not."""
    from omnibias.core.spectral_design import band_plan_from_peaks

    hole = band_plan_from_peaks(
        "sech", peaks=(2.0, 16.0), order=2, xi_lo=1.0, xi_hi=32.0
    )
    dense = design_band_plan("sech", xi_lo=1.0, xi_hi=32.0, channels=4, order=2)
    assert hole.has_spectral_hole() is True
    assert hole.flatness > dense.flatness
    assert dense.has_spectral_hole() is False

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_holed_plan_is_flagged" -q

Read the implementation

def band_plan_from_peaks(
    base: str,
    *,
    peaks: Sequence[float],
    order: int | Sequence[int] = 2,
    xi_lo: float,
    xi_hi: float,
) -> BandPlan:
    """Build a plan from explicit peak frequencies (used for hole diagnostics)."""
    name = _canonical_base(base)
    peak_t = tuple(float(p) for p in peaks)
    if any(p <= 0.0 for p in peak_t):
        raise ValueError("peaks must be positive")
    if isinstance(order, int):
        orders = tuple(int(order) for _ in peak_t)
    else:
        orders = tuple(int(o) for o in order)
        if len(orders) != len(peak_t):
            raise ValueError("order sequence must match peaks")
    scales = tuple(
        alpha_for_peak(name, n, peak) for n, peak in zip(orders, peak_t, strict=True)
    )
    n_grid = 256
    cover_lo = min(peak_t)
    cover_hi = max(peak_t)
    log_lo = log(cover_lo)
    log_hi = log(cover_hi) if cover_hi > cover_lo else log(cover_lo * 1.0001)
    grid = tuple(
        exp(log_lo + (log_hi - log_lo) * i / float(n_grid - 1)) for i in range(n_grid)
    )
    summed = _summed_normalized_response(name, orders, scales, grid)
    return BandPlan(
        base=name,
        orders=orders,
        scales=scales,
        xi_lo=float(xi_lo),
        xi_hi=float(xi_hi),
        flatness=float(_flatness(summed)),
    )

Related APIsomnibias.core.BandPlan↗omnibias.core.alpha_for_peak↗

FUNCTION

design_band_plan

omnibias.core.design_band_planSource ↗

design_band_plan(base: str, *, xi_lo: float, xi_hi: float, channels: int, order: int | Sequence[int]=2, overlap: float=0.5) -> BandPlan

Place channels peaks geometrically across [xi_lo, xi_hi].

Interior geometric nodes (drop the endpoints of an channels + 2 sequence) recover the spec's worked example: [1, 32] with 4 channels peaks at 2, 4, 8, 16. overlap is recorded for callers; spacing is geometric rather than a solved LP. 01-06 frames stay concept.

Parameters

Name	Type & default	Contract
basepositional-or-keyword	strRequired	See the operation contract and implementation below.
xi_lokeyword-only	floatRequired	See the operation contract and implementation below.
xi_hikeyword-only	floatRequired	See the operation contract and implementation below.
channelskeyword-only	intRequired	See the operation contract and implementation below.
orderkeyword-only	int | Sequence[int]Default: 2	See the operation contract and implementation below.
overlapkeyword-only	floatDefault: 0.5	See the operation contract and implementation below.

ReturnsBandPlan

Explicit validation & failure cases

• When int(channels) < 1, raises ValueError(f'channels must be >= 1, got {channels}').
• When not (xi_lo > 0.0 and xi_hi > xi_lo), raises ValueError('need 0 < xi_lo < xi_hi').
• When len(orders) != len(peaks), raises ValueError('order sequence must match channel count').

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

Executed regression · worked example peaks

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_worked_example_peaks() -> None:
    plan = design_band_plan("sech", xi_lo=1.0, xi_hi=32.0, channels=4, order=2)
    peaks = tuple(
        peak_frequency("sech", n, a) for n, a in zip(plan.orders, plan.scales, strict=True)
    )
    assert peaks == pytest.approx((2.0, 4.0, 8.0, 16.0), rel=1e-12)
    assert plan.flatness < 3.0
    assert plan.has_spectral_hole() is False

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_worked_example_peaks" -q

Regression example · jetkan from band plan pack count

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_jetkan_from_band_plan_pack_count() -> None:
    from omnibias.core.spectral_design import design_band_plan
    from omnibias.torch.architectures.jetkan import jetkan_from_band_plan

    plan = design_band_plan("sech", xi_lo=1.0, xi_hi=16.0, channels=3, order=1)
    cfg = jetkan_from_band_plan(plan, (2, 1))
    assert cfg.packs_per_edge == 3
    net = JetKAN(cfg, dtype=torch.float64)
    out = net(torch.zeros(2, 2, dtype=torch.float64))
    assert out.shape == (2, 1)

python -m pytest packages/omnibias-torch/tests/test_jetkan.py -k test_jetkan_from_band_plan_pack_count -q

Read the implementation

def design_band_plan(
    base: str,
    *,
    xi_lo: float,
    xi_hi: float,
    channels: int,
    order: int | Sequence[int] = 2,
    overlap: float = 0.5,
) -> BandPlan:
    """Place ``channels`` peaks geometrically across ``[xi_lo, xi_hi]``.

    Interior geometric nodes (drop the endpoints of an ``channels + 2``
    sequence) recover the spec's worked example: ``[1, 32]`` with 4 channels
    peaks at ``2, 4, 8, 16``. ``overlap`` is recorded for callers; spacing is
    geometric rather than a solved LP. 01-06 frames stay concept.
    """
    name = _canonical_base(base)
    if int(channels) < 1:
        raise ValueError(f"channels must be >= 1, got {channels}")
    if not (xi_lo > 0.0 and xi_hi > xi_lo):
        raise ValueError("need 0 < xi_lo < xi_hi")
    _ = float(overlap)
    nodes = _geomspace(float(xi_lo), float(xi_hi), int(channels) + 2)
    peaks = nodes[1:-1]
    if isinstance(order, int):
        orders = tuple(int(order) for _ in peaks)
    else:
        orders = tuple(int(o) for o in order)
        if len(orders) != len(peaks):
            raise ValueError("order sequence must match channel count")
    scales = tuple(
        alpha_for_peak(name, n, peak) for n, peak in zip(orders, peaks, strict=True)
    )
    n_grid = 256
    peak_vals = tuple(
        peak_frequency(name, n, a) for n, a in zip(orders, scales, strict=True)
    )
    cover_lo = min(peak_vals)
    cover_hi = max(peak_vals)
    log_lo = log(cover_lo)
    log_hi = log(cover_hi) if cover_hi > cover_lo else log(cover_lo * 1.0001)
    grid = tuple(
        exp(log_lo + (log_hi - log_lo) * i / float(n_grid - 1)) for i in range(n_grid)
    )
    summed = _summed_normalized_response(name, orders, scales, grid)
    return BandPlan(
        base=name,
        orders=orders,
        scales=scales,
        xi_lo=float(xi_lo),
        xi_hi=float(xi_hi),
        flatness=float(_flatness(summed)),
    )

Related APIsomnibias.core.BandPlan↗omnibias.core.alpha_for_peak↗omnibias.core.peak_frequency↗

Other public import paths

• omnibias.core.design_band_plan
• omnibias.core.spectral_design.design_band_plan

FUNCTION

hat_sigma_magnitude

omnibias.core.spectral_design.hat_sigma_magnitudeSource ↗

hat_sigma_magnitude(base: str, xi: float) -> float

|hat_sigma(xi)| in the angular-frequency convention of transforms.py.

Parameters

Name	Type & default	Contract
basepositional-or-keyword	strRequired	See the operation contract and implementation below.
xipositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · g1 sech matches integral

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_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::test_g1_sech_matches_integral" -q

Regression example · g1 gaussian closed form vs 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_gaussian_closed_form_vs_integral() -> None:
    for n in range(2, 7):
        c = admissibility_constant("gaussian", n)
        assert c is not None
        # Numerical Calderón integral int_0^inf xi^{2n-1} |hat g|^2 d xi
        acc = 0.0
        dx = 0.002
        x = dx
        while x < 12.0:
            hat = hat_sigma_magnitude("gaussian", x)
            acc += (x ** (2 * n - 1)) * hat * hat * dx
            x += dx
        rel = abs(c.mid - acc) / c.mid
        assert rel <= 1e-10

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

Read the implementation

def hat_sigma_magnitude(base: str, xi: float) -> float:
    """``|hat_sigma(xi)|`` in the angular-frequency convention of ``transforms.py``."""
    name = _canonical_base(base)
    x = abs(float(xi))
    if name == "gaussian":
        return sqrt(2.0 * pi) * exp(-0.5 * x * x)
    # sech: pi sech(pi xi / 2)
    arg = SECH_DECAY * x
    # sech(arg) = 2 e^{-arg} / (1 + e^{-2 arg}) for stability at large arg.
    e = exp(-arg)
    sech = 2.0 * e / (1.0 + e * e)
    return pi * sech

FUNCTION

locate_peak_numerically

omnibias.core.spectral_design.locate_peak_numericallySource ↗

locate_peak_numerically(base: str, order: int, alpha: float, *, n_grid: int=80) -> float

Argmax of response_profile by golden-section search on log xi.

Parameters

Name	Type & default	Contract
basepositional-or-keyword	strRequired	See the operation contract and implementation below.
orderpositional-or-keyword	intRequired	See the operation contract and implementation below.
alphapositional-or-keyword	floatRequired	See the operation contract and implementation below.
n_gridkeyword-only	intDefault: 80	See the operation contract and implementation below.

Returnsfloat

Executed regression · peak matches numerical argmax

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_peak_matches_numerical_argmax(base: str, order: int) -> None:
    """G1: closed-form peak vs argmax of R, relative <= 1e-6."""
    alpha = 1.7
    pred = peak_frequency(base, order, alpha)
    found = locate_peak_numerically(base, order, alpha)
    rel = abs(pred - found) / pred
    assert rel <= 1e-6
    # Inverse is consistent.
    a2 = alpha_for_peak(base, order, pred)
    assert a2 == pytest.approx(alpha, rel=1e-12)

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_peak_matches_numerical_argmax[1-gaussian]" -q

Read the implementation

def locate_peak_numerically(
    base: str,
    order: int,
    alpha: float,
    *,
    n_grid: int = 80,
) -> float:
    """Argmax of :func:`response_profile` by golden-section search on ``log xi``."""
    pred = peak_frequency(base, order, alpha)
    lo = log(pred / 4.0)
    hi = log(pred * 4.0)
    phi = (sqrt(5.0) - 1.0) / 2.0
    c = hi - phi * (hi - lo)
    d = lo + phi * (hi - lo)

    def _r(log_xi: float) -> float:
        return response_profile(base, order, alpha, (exp(log_xi),))[0]

    yc = _r(c)
    yd = _r(d)
    for _ in range(n_grid):
        if yc > yd:
            hi = d
            d = c
            yd = yc
            c = hi - phi * (hi - lo)
            yc = _r(c)
        else:
            lo = c
            c = d
            yc = yd
            d = lo + phi * (hi - lo)
            yd = _r(d)
    return exp(0.5 * (lo + hi))

Related APIsomnibias.core.peak_frequency↗omnibias.core.response_profile↗

FUNCTION

peak_frequency

omnibias.core.peak_frequencySource ↗

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

Peak of response_profile.

Gaussian: exact alpha * sqrt(n). Sech: exact root of d log R / d xi = 0, which is tanh(k xi) = n / (k xi) with k = (pi/2) / alpha. The Laplace form n alpha / (pi/2) is the large-n limit and is not used for G1.

Parameters

Name	Type & default	Contract
basepositional-or-keyword	strRequired	See the operation contract and implementation below.
orderpositional-or-keyword	intRequired	See the operation contract and implementation below.
alphapositional-or-keyword	floatRequired	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

• When n < 1, raises ValueError(f'peak_frequency requires order >= 1, got {order}').
• When not a > 0.0 or a != a, raises ValueError(f'alpha must be finite and positive, got {alpha}').

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

Executed regression · rejects tanh and bad inputs

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_rejects_tanh_and_bad_inputs() -> None:
    with pytest.raises(ValueError, match="L1"):
        response_profile("tanh", 1, 1.0, (1.0,))
    with pytest.raises(ValueError, match="order"):
        peak_frequency("sech", 0, 1.0)

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_rejects_tanh_and_bad_inputs" -q

Regression example · schedule tracks target band

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_schedule_tracks_target_band() -> None:
    def band(t: float) -> float:
        return 2.0 + 14.0 * t

    alphas = scale_schedule(target_band=band, steps=5, base="gaussian", order=1)
    assert len(alphas) == 5
    for t, a in zip(np.linspace(0.0, 1.0, 5), alphas, strict=True):
        assert abs(peak_frequency("gaussian", 1, a) - band(float(t))) <= 1e-12

python -m pytest packages/omnibias-fields/tests/test_scale.py -k test_schedule_tracks_target_band -q

Read the implementation

def peak_frequency(base: str, order: int, alpha: float) -> float:
    """Peak of :func:`response_profile`.

    Gaussian: exact ``alpha * sqrt(n)``. Sech: exact root of
    ``d log R / d xi = 0``, which is ``tanh(k xi) = n / (k xi)`` with
    ``k = (pi/2) / alpha``. The Laplace form ``n alpha / (pi/2)`` is the
    large-``n`` limit and is not used for G1.
    """
    name = _canonical_base(base)
    n = int(order)
    if n < 1:
        raise ValueError(f"peak_frequency requires order >= 1, got {order}")
    a = float(alpha)
    if not (a > 0.0) or a != a:
        raise ValueError(f"alpha must be finite and positive, got {alpha}")
    if name == "gaussian":
        return a * sqrt(float(n))
    u = _sech_stationary_u(n)
    return u * a / SECH_DECAY

Other public import paths

• omnibias.core.peak_frequency
• omnibias.core.spectral_design.peak_frequency

FUNCTION

relative_bandwidth

omnibias.core.relative_bandwidthSource ↗

relative_bandwidth(base: str, order: int) -> float

Quadratic (Laplace) relative half-width Delta xi / xi_peak.

Sech (exponential Fourier tail): 1/sqrt(n). Gaussian: 1/sqrt(2 n). For small n this is crude; callers should also measure half-power width.

Parameters

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

Returnsfloat

Explicit validation & failure cases

• When n < 1, raises ValueError(f'relative_bandwidth requires order >= 1, got {order}').

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

Executed regression · relative bandwidth shrinks with order

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_relative_bandwidth_shrinks_with_order() -> None:
    assert relative_bandwidth("sech", 4) < relative_bandwidth("sech", 1)
    assert relative_bandwidth("gaussian", 4) == pytest.approx(1.0 / math.sqrt(8.0))

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_relative_bandwidth_shrinks_with_order" -q

Read the implementation

def relative_bandwidth(base: str, order: int) -> float:
    """Quadratic (Laplace) relative half-width ``Delta xi / xi_peak``.

    Sech (exponential Fourier tail): ``1/sqrt(n)``. Gaussian: ``1/sqrt(2 n)``.
    For small ``n`` this is crude; callers should also measure half-power width.
    """
    name = _canonical_base(base)
    n = int(order)
    if n < 1:
        raise ValueError(f"relative_bandwidth requires order >= 1, got {order}")
    if name == "gaussian":
        return 1.0 / sqrt(2.0 * float(n))
    return 1.0 / sqrt(float(n))

Other public import paths

• omnibias.core.relative_bandwidth
• omnibias.core.spectral_design.relative_bandwidth

FUNCTION

response_profile

omnibias.core.response_profileSource ↗

response_profile(base: str, order: int, alpha: float, xi: Sequence[float]) -> tuple[float, ...]

Band-pass magnitude |xi|^n alpha^{n-1} |hat_sigma(xi / alpha)|.

Closed form for gaussian and sech. Returns a parallel tuple to xi.

Parameters

Name	Type & default	Contract
basepositional-or-keyword	strRequired	See the operation contract and implementation below.
orderpositional-or-keyword	intRequired	See the operation contract and implementation below.
alphapositional-or-keyword	floatRequired	See the operation contract and implementation below.
xipositional-or-keyword	Sequence[float]Required	See the operation contract and implementation below.

Returnstuple[float, ...]

Explicit validation & failure cases

• When n < 0, raises ValueError(f'order must be >= 0, got {order}').
• When not a > 0.0 or a != a, raises ValueError(f'alpha must be finite and positive, got {alpha}').

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

Executed regression · rejects tanh and bad inputs

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_rejects_tanh_and_bad_inputs() -> None:
    with pytest.raises(ValueError, match="L1"):
        response_profile("tanh", 1, 1.0, (1.0,))
    with pytest.raises(ValueError, match="order"):
        peak_frequency("sech", 0, 1.0)

python -m pytest "packages/omnibias-core/tests/test_spectral_design.py::test_rejects_tanh_and_bad_inputs" -q

Read the implementation

def response_profile(
    base: str,
    order: int,
    alpha: float,
    xi: Sequence[float],
) -> tuple[float, ...]:
    """Band-pass magnitude ``|xi|^n alpha^{n-1} |hat_sigma(xi / alpha)|``.

    Closed form for gaussian and sech. Returns a parallel tuple to ``xi``.
    """
    _canonical_base(base)
    n = int(order)
    if n < 0:
        raise ValueError(f"order must be >= 0, got {order}")
    a = float(alpha)
    if not (a > 0.0) or a != a:
        raise ValueError(f"alpha must be finite and positive, got {alpha}")
    out: list[float] = []
    pow_a = a ** (n - 1) if n > 0 else 1.0 / a
    for raw in xi:
        x = float(raw)
        mag_xi = abs(x) ** n
        hat = hat_sigma_magnitude(base, x / a)
        out.append(mag_xi * pow_a * hat)
    return tuple(out)

Related APIsomnibias.core.spectral_design.hat_sigma_magnitude↗

Other public import paths

• omnibias.core.response_profile
• omnibias.core.spectral_design.response_profile

← Package overviewRunnable learning examples →