API REFERENCE/omnibias-core

omnibias.core.scan

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

Module contract & mathematical conventions

Bias-scan bank algebra (theory 01-02).

A scan shares one pack template across a bank of bias offsets. Offsets live on the transverse coordinate z = w . x; there is no pixel grid. Pure Python -- tensor evaluation is in the torch / jax twins.

The template's internal limit is founding bias collapse (delta -> 0). The soft-argmax sharpness gamma is a softmax readout; driving it to infinity would be temperature collapse (beta -> inf), a different limit.

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

BankSpec

omnibias.core.BankSpecSource ↗

class BankSpec

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 1-D offset bank, optionally with a scale (tempering) axis.

Parameters

Name	Type & default	Contract
offsetsdataclass field	tuple[float, ...]Required	See the operation contract and implementation below.
scalesdataclass field	tuple[float, ...]Default: (1.0,)	See the operation contract and implementation below.

Executed regression · single offset spacing none

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_single_offset_spacing_none() -> None:
    bank = BankSpec(offsets=(0.25,))
    assert bank.spacing is None
    assert math.isinf(bank.min_separation())

python -m pytest "packages/omnibias-core/tests/test_scan.py::test_single_offset_spacing_none" -q

Regression example · non uniform spacing is none

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_non_uniform_spacing_is_none() -> None:
    bank = BankSpec(offsets=(0.0, 0.1, 0.4))
    assert bank.spacing is None
    assert bank.min_separation() == pytest.approx(0.1)

python -m pytest packages/omnibias-core/tests/test_scan.py -k test_non_uniform_spacing_is_none -q

Fields & methods

offsetsfield

offsets: tuple[float, ...]

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

Regression example · uniform spacing

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_uniform_spacing() -> None:
    bank = BankSpec.uniform(-1.0, 1.0, 5)
    assert bank.offsets == pytest.approx((-1.0, -0.5, 0.0, 0.5, 1.0))
    assert bank.spacing == pytest.approx(0.5)
    assert bank.n_offsets == 5
    assert bank.n_scales == 1
    assert bank.scales == (1.0,)
    assert bank.min_separation() == pytest.approx(0.5)

python -m pytest packages/omnibias-core/tests/test_scan.py -k test_uniform_spacing -q

View source ↗

scalesfield

scales: tuple[float, ...] = (1.0,)

Declared tuple[float, ...] field on BankSpec. Default expression: (1.0,).

Regression example · uniform spacing

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_uniform_spacing() -> None:
    bank = BankSpec.uniform(-1.0, 1.0, 5)
    assert bank.offsets == pytest.approx((-1.0, -0.5, 0.0, 0.5, 1.0))
    assert bank.spacing == pytest.approx(0.5)
    assert bank.n_offsets == 5
    assert bank.n_scales == 1
    assert bank.scales == (1.0,)
    assert bank.min_separation() == pytest.approx(0.5)

python -m pytest packages/omnibias-core/tests/test_scan.py -k test_uniform_spacing -q

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 any((s <= 0.0 for s in scales)), raises ValueError('scales must be positive').

Executed regression · single offset spacing none

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_single_offset_spacing_none() -> None:
    bank = BankSpec(offsets=(0.25,))
    assert bank.spacing is None
    assert math.isinf(bank.min_separation())

python -m pytest "packages/omnibias-core/tests/test_scan.py::test_single_offset_spacing_none" -q

Method implementation

    def __post_init__(self) -> None:
        offsets = _as_float_tuple(self.offsets, name="offsets")
        scales = _as_float_tuple(self.scales, name="scales")
        if any(s <= 0.0 for s in scales):
            raise ValueError("scales must be positive")
        object.__setattr__(self, "offsets", offsets)
        object.__setattr__(self, "scales", scales)

View source ↗

uniformmethod

uniform(cls, lo: float, hi: float, n: int, *, scales: Sequence[float]=(1.0,)) -> BankSpec

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

Parameters

Name	Type & default	Contract
lopositional-or-keyword	floatRequired	See the operation contract and implementation below.
hipositional-or-keyword	floatRequired	See the operation contract and implementation below.
npositional-or-keyword	intRequired	See the operation contract and implementation below.
scaleskeyword-only	Sequence[float]Default: (1.0,)	See the operation contract and implementation below.

Returns: BankSpec

Validation & failure cases

• When n < 2, raises ValueError(f'uniform bank needs n >= 2, got {n}').
• When not (math.isfinite(lo) and math.isfinite(hi)), raises ValueError('lo and hi must be finite').
• When hi == lo, raises ValueError('lo and hi must differ').

Executed regression · uniform rejects degenerate

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_uniform_rejects_degenerate() -> None:
    with pytest.raises(ValueError, match="n >= 2"):
        BankSpec.uniform(-1.0, 1.0, 1)
    with pytest.raises(ValueError, match="differ"):
        BankSpec.uniform(0.0, 0.0, 3)

python -m pytest "packages/omnibias-core/tests/test_scan.py::test_uniform_rejects_degenerate" -q

Method implementation

    def uniform(cls, lo: float, hi: float, n: int, *, scales: Sequence[float] = (1.0,)) -> BankSpec:
        if n < 2:
            raise ValueError(f"uniform bank needs n >= 2, got {n}")
        if not (math.isfinite(lo) and math.isfinite(hi)):
            raise ValueError("lo and hi must be finite")
        if hi == lo:
            raise ValueError("lo and hi must differ")
        step = (hi - lo) / (n - 1)
        offsets = tuple(lo + i * step for i in range(n))
        return cls(offsets, tuple(float(s) for s in scales))

View source ↗

n_offsetsproperty

n_offsets(self) -> int

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

Returns: int

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

Method implementation

    def n_offsets(self) -> int:
        return len(self.offsets)

View source ↗

n_scalesproperty

n_scales(self) -> int

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

Returns: int

Executed regression · uniform spacing

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_uniform_spacing() -> None:
    bank = BankSpec.uniform(-1.0, 1.0, 5)
    assert bank.offsets == pytest.approx((-1.0, -0.5, 0.0, 0.5, 1.0))
    assert bank.spacing == pytest.approx(0.5)
    assert bank.n_offsets == 5
    assert bank.n_scales == 1
    assert bank.scales == (1.0,)
    assert bank.min_separation() == pytest.approx(0.5)

python -m pytest "packages/omnibias-core/tests/test_scan.py::test_uniform_spacing" -q

Method implementation

    def n_scales(self) -> int:
        return len(self.scales)

View source ↗

spacingproperty

spacing(self) -> float | None

Uniform spacing, or None when the bank is irregular.

Returns: float | None

Executed regression · single offset spacing none

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_single_offset_spacing_none() -> None:
    bank = BankSpec(offsets=(0.25,))
    assert bank.spacing is None
    assert math.isinf(bank.min_separation())

python -m pytest "packages/omnibias-core/tests/test_scan.py::test_single_offset_spacing_none" -q

Method implementation

    def spacing(self) -> float | None:
        """Uniform spacing, or ``None`` when the bank is irregular."""
        if len(self.offsets) < 2:
            return None
        diffs = [self.offsets[i + 1] - self.offsets[i] for i in range(len(self.offsets) - 1)]
        ref = diffs[0]
        if ref == 0.0:
            return None
        if any(abs(d - ref) > 1e-12 * max(abs(ref), 1.0) for d in diffs[1:]):
            return None
        return float(ref)

View source ↗

min_separationmethod

min_separation(self) -> float

Minimum adjacent spacing after sorting (collapse diagnostic).

Returns: float

Executed regression · single offset spacing none

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_single_offset_spacing_none() -> None:
    bank = BankSpec(offsets=(0.25,))
    assert bank.spacing is None
    assert math.isinf(bank.min_separation())

python -m pytest "packages/omnibias-core/tests/test_scan.py::test_single_offset_spacing_none" -q

Method implementation

    def min_separation(self) -> float:
        """Minimum adjacent spacing after sorting (collapse diagnostic)."""
        ordered = sorted(self.offsets)
        if len(ordered) < 2:
            return float("inf")
        return min(ordered[i + 1] - ordered[i] for i in range(len(ordered) - 1))

View source ↗

Read the implementation

class BankSpec:
    """A 1-D offset bank, optionally with a scale (tempering) axis."""

    offsets: tuple[float, ...]
    scales: tuple[float, ...] = (1.0,)

    def __post_init__(self) -> None:
        offsets = _as_float_tuple(self.offsets, name="offsets")
        scales = _as_float_tuple(self.scales, name="scales")
        if any(s <= 0.0 for s in scales):
            raise ValueError("scales must be positive")
        object.__setattr__(self, "offsets", offsets)
        object.__setattr__(self, "scales", scales)

    @classmethod
    def uniform(cls, lo: float, hi: float, n: int, *, scales: Sequence[float] = (1.0,)) -> BankSpec:
        if n < 2:
            raise ValueError(f"uniform bank needs n >= 2, got {n}")
        if not (math.isfinite(lo) and math.isfinite(hi)):
            raise ValueError("lo and hi must be finite")
        if hi == lo:
            raise ValueError("lo and hi must differ")
        step = (hi - lo) / (n - 1)
        offsets = tuple(lo + i * step for i in range(n))
        return cls(offsets, tuple(float(s) for s in scales))

    @property
    def n_offsets(self) -> int:
        return len(self.offsets)

    @property
    def n_scales(self) -> int:
        return len(self.scales)

    @property
    def spacing(self) -> float | None:
        """Uniform spacing, or ``None`` when the bank is irregular."""
        if len(self.offsets) < 2:
            return None
        diffs = [self.offsets[i + 1] - self.offsets[i] for i in range(len(self.offsets) - 1)]
        ref = diffs[0]
        if ref == 0.0:
            return None
        if any(abs(d - ref) > 1e-12 * max(abs(ref), 1.0) for d in diffs[1:]):
            return None
        return float(ref)

    def min_separation(self) -> float:
        """Minimum adjacent spacing after sorting (collapse diagnostic)."""
        ordered = sorted(self.offsets)
        if len(ordered) < 2:
            return float("inf")
        return min(ordered[i + 1] - ordered[i] for i in range(len(ordered) - 1))

Other public import paths

• omnibias.core.BankSpec
• omnibias.jax.BankSpec
• omnibias.torch.BankSpec
• omnibias.core.scan.BankSpec
• omnibias.jax.scan.BankSpec
• omnibias.torch.scan.BankSpec

FUNCTION

resolve_scan_role

omnibias.core.scan.resolve_scan_roleSource ↗

resolve_scan_role(template: str | None=None, op: str | None=None, *, default: str='grad') -> str

Select the BiasScan role name.

op is the 01-13 catalog alias for template. They name the same six-role family, not a seventh OperatorBlock role. Passing both raises; passing neither returns default. A MultiPackSpec stays on the template= path in the twins and never enters this helper.

Parameters

Name	Type & default	Contract
templatepositional-or-keyword	str | NoneDefault: None	See the operation contract and implementation below.
oppositional-or-keyword	str | NoneDefault: None	See the operation contract and implementation below.
defaultkeyword-only	strDefault: 'grad'	See the operation contract and implementation below.

Returnsstr

Explicit validation & failure cases

• When template is not None and op is not None, raises ValueError('pass only one of template= or op=; they name the same role').

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

Executed regression · dtype none uses framework default

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_dtype_none_uses_framework_default() -> None:
    prev = torch.get_default_dtype()
    try:
        torch.set_default_dtype(torch.float64)
        scan = BiasScan(1, BankSpec.uniform(-1.0, 1.0, 3), dtype=None)
        assert scan.offsets.dtype == torch.float64
    finally:
        torch.set_default_dtype(prev)

python -m pytest "packages/omnibias-torch/tests/test_scan.py::test_dtype_none_uses_framework_default" -q

Regression example · resolve scan role op is template alias

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_resolve_scan_role_op_is_template_alias() -> None:
    assert resolve_scan_role() == "grad"
    assert resolve_scan_role(op="integral", default="grad") == "integral"
    assert resolve_scan_role(template="band", default="grad") == "band"
    with pytest.raises(ValueError, match="only one of template= or op="):
        resolve_scan_role(template="grad", op="integral", default="grad")

python -m pytest packages/omnibias-core/tests/test_scan.py -k test_resolve_scan_role_op_is_template_alias -q

Read the implementation

def resolve_scan_role(
    template: str | None = None,
    op: str | None = None,
    *,
    default: str = "grad",
) -> str:
    """Select the BiasScan role name.

    ``op`` is the 01-13 catalog alias for ``template``. They name the same
    six-role family, not a seventh ``OperatorBlock`` role. Passing both
    raises; passing neither returns ``default``. A ``MultiPackSpec`` stays
    on the ``template=`` path in the twins and never enters this helper.
    """
    if template is not None and op is not None:
        raise ValueError("pass only one of template= or op=; they name the same role")
    if template is not None:
        return template
    if op is not None:
        return op
    return default

← Package overviewRunnable learning examples →