API REFERENCE/omnibias-core

omnibias.core.implicit

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

Module contract & mathematical conventions

Implicit / DEQ algebra (theory 08-08).

An equilibrium u = sigma(W u + x) is a root of F(u) = u - sigma(W u + x). The implicit-function theorem differentiates the root with exact sigma' from the founding bias collapse (delta -> 0): one linear solve against I - diag(sigma'(z)) W replaces unrolled backprop through a fixed-point iteration.

This module is backend-free: config, the contraction raise, and the infinity-norm spectral-radius bound. Tensor Newton / Banach iteration and the IFT VJP live in omnibias.{torch,jax}.implicit.

No temperature collapse. Not a global min, and not a continuum PDE existence claim. IFT is the chain rule at a fixed point, not an absence of the chain rule.

Shared formulas do not imply universal floating-point identity. Verify dtype, shape, derivative-order support, and the stated numerical assumptions for the path you use.

Module source ↗Source revision 9a2d73df0573Running reference examples →

CLASS

DEQConfig

omnibias.core.DEQConfigSource ↗

class DEQConfig

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.

Fixed-point solver budget and contraction policy.

newton is the gated method. iterate is Banach iteration. anderson is recorded extra and raises DEQSolverUnknown until it earns a gate.

Parameters

Name	Type & default	Contract
solverdataclass field	DEQSolverDefault: 'newton'	See the operation contract and implementation below.
max_iterdataclass field	intDefault: 50	See the operation contract and implementation below.
toldataclass field	floatDefault: 1e-10	See the operation contract and implementation below.
require_contractiondataclass field	boolDefault: False	See the operation contract and implementation below.

Executed regression · contraction raises

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_contraction_raises() -> None:
    cfg = DEQConfig(require_contraction=True, max_iter=2)
    with pytest.raises(DEQNotContractive, match="unroll"):
        deq_solve(jnp.asarray([[3.0]]), jnp.asarray([0.1]), "tanh", config=cfg)

python -m pytest "packages/omnibias-jax/tests/test_implicit.py::test_contraction_raises" -q

Regression example · anderson raises

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_anderson_raises() -> None:
    with pytest.raises(DEQSolverUnknown, match="newton"):
        deq_solve(
            jnp.asarray([[0.2]]),
            jnp.asarray([0.5]),
            "tanh",
            config=DEQConfig(solver="anderson"),
        )

python -m pytest packages/omnibias-jax/tests/test_implicit.py -k test_anderson_raises -q

Fields & methods

solverfield

solver: DEQSolver = 'newton'

Declared DEQSolver field on DEQConfig. Default expression: 'newton'.

View source ↗

max_iterfield

max_iter: int = 50

Declared int field on DEQConfig. Default expression: 50.

View source ↗

tolfield

tol: float = 1e-10

Declared float field on DEQConfig. Default expression: 1e-10.

View source ↗

require_contractionfield

require_contraction: bool = False

Declared bool field on DEQConfig. Default expression: False.

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 self.solver not in ('newton', 'iterate', 'anderson'), raises ValueError(f"solver must be 'newton', 'iterate', or 'anderson', got {self.solver!r}").
• When self.max_iter < 1, raises ValueError(f'max_iter must be >= 1, got {self.max_iter}').
• When self.tol <= 0.0 or not math.isfinite(self.tol), raises ValueError(f'tol must be a finite number > 0, got {self.tol}').

Executed regression · contraction raises

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_contraction_raises() -> None:
    cfg = DEQConfig(require_contraction=True, max_iter=2)
    with pytest.raises(DEQNotContractive, match="unroll"):
        deq_solve(jnp.asarray([[3.0]]), jnp.asarray([0.1]), "tanh", config=cfg)

python -m pytest "packages/omnibias-jax/tests/test_implicit.py::test_contraction_raises" -q

Method implementation

    def __post_init__(self) -> None:
        if self.solver not in ("newton", "iterate", "anderson"):
            raise ValueError(
                f"solver must be 'newton', 'iterate', or 'anderson', "
                f"got {self.solver!r}"
            )
        if self.max_iter < 1:
            raise ValueError(f"max_iter must be >= 1, got {self.max_iter}")
        if self.tol <= 0.0 or not math.isfinite(self.tol):
            raise ValueError(f"tol must be a finite number > 0, got {self.tol}")

View source ↗

Read the implementation

class DEQConfig:
    """Fixed-point solver budget and contraction policy.

    ``newton`` is the gated method. ``iterate`` is Banach iteration.
    ``anderson`` is recorded extra and raises
    :class:`DEQSolverUnknown` until it earns a gate.
    """

    solver: DEQSolver = "newton"
    max_iter: int = 50
    tol: float = 1e-10
    require_contraction: bool = False

    def __post_init__(self) -> None:
        if self.solver not in ("newton", "iterate", "anderson"):
            raise ValueError(
                f"solver must be 'newton', 'iterate', or 'anderson', "
                f"got {self.solver!r}"
            )
        if self.max_iter < 1:
            raise ValueError(f"max_iter must be >= 1, got {self.max_iter}")
        if self.tol <= 0.0 or not math.isfinite(self.tol):
            raise ValueError(f"tol must be a finite number > 0, got {self.tol}")

Other public import paths

• omnibias.core.DEQConfig
• omnibias.jax.DEQConfig
• omnibias.torch.DEQConfig
• omnibias.core.implicit.DEQConfig
• omnibias.jax.implicit.DEQConfig
• omnibias.torch.implicit.DEQConfig

CLASS

DEQNotContractive

omnibias.core.DEQNotContractiveSource ↗

class DEQNotContractive(ValueError)

Raised when require_contraction=True and the bound is >= 1.

Regression example · contraction raises

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_contraction_raises() -> None:
    cfg = DEQConfig(require_contraction=True, max_iter=2)
    with pytest.raises(DEQNotContractive, match="unroll"):
        deq_solve(jnp.asarray([[3.0]]), jnp.asarray([0.1]), "tanh", config=cfg)

python -m pytest packages/omnibias-jax/tests/test_implicit.py -k test_contraction_raises -q

Regression example · contraction raise

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_contraction_raise() -> None:
    reject_deq_contraction(0.5, require=True)
    with pytest.raises(DEQNotContractive, match="unroll"):
        reject_deq_contraction(1.0, require=True)
    reject_deq_contraction(1.5, require=False)

python -m pytest packages/omnibias-core/tests/test_implicit.py -k test_contraction_raise -q

Read the implementation

class DEQNotContractive(ValueError):
    """Raised when ``require_contraction=True`` and the bound is ``>= 1``."""

Other public import paths

• omnibias.core.DEQNotContractive
• omnibias.jax.DEQNotContractive
• omnibias.torch.DEQNotContractive
• omnibias.core.implicit.DEQNotContractive
• omnibias.jax.implicit.DEQNotContractive
• omnibias.torch.implicit.DEQNotContractive

CONSTANT

DEQSolver

omnibias.core.implicit.DEQSolverSource ↗

DEQSolver = Literal['newton', 'iterate', 'anderson']

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

DEQSolver = Literal["newton", "iterate", "anderson"]

CLASS

DEQSolverUnknown

omnibias.core.DEQSolverUnknownSource ↗

class DEQSolverUnknown(ValueError)

Raised when the solver name is not implemented.

Regression example · anderson is extra

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_anderson_is_extra() -> None:
    with pytest.raises(DEQSolverUnknown, match="newton"):
        reject_anderson("anderson")
    reject_anderson("newton")

python -m pytest packages/omnibias-core/tests/test_implicit.py -k test_anderson_is_extra -q

Regression example · anderson raises

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_anderson_raises() -> None:
    with pytest.raises(DEQSolverUnknown, match="newton"):
        deq_solve(
            jnp.asarray([[0.2]]),
            jnp.asarray([0.5]),
            "tanh",
            config=DEQConfig(solver="anderson"),
        )

python -m pytest packages/omnibias-jax/tests/test_implicit.py -k test_anderson_raises -q

Read the implementation

class DEQSolverUnknown(ValueError):
    """Raised when the solver name is not implemented."""

Other public import paths

• omnibias.core.DEQSolverUnknown
• omnibias.jax.DEQSolverUnknown
• omnibias.torch.DEQSolverUnknown
• omnibias.core.implicit.DEQSolverUnknown
• omnibias.jax.implicit.DEQSolverUnknown
• omnibias.torch.implicit.DEQSolverUnknown

CONSTANT

HONESTY

omnibias.core.implicit.HONESTYSource ↗

HONESTY: dict[str, bool] = {'global_convergence_claim': False, 'global_min_claim': False, 'unrolled_bptt_claim': False, 'greedy_only_claimed_optimal': False}

This exported constant is defined by the expression above. Its exact value and annotation come from the pinned source; use it with the module contract.

Read the implementation

HONESTY: dict[str, bool] = {
    "global_convergence_claim": False,
    "global_min_claim": False,
    "unrolled_bptt_claim": False,
    "greedy_only_claimed_optimal": False,
}

FUNCTION

honesty_payload

omnibias.core.honesty_payloadSource ↗

honesty_payload() -> dict[str, bool]

Sealed artifact keys. Values are copies.

Returnsdict[str, bool]

Executed regression · honesty sealed

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_honesty_sealed() -> None:
    payload = honesty_payload()
    assert payload["global_convergence_claim"] is False
    assert payload["unrolled_bptt_claim"] is False
    payload["global_convergence_claim"] = True
    assert honesty_payload()["global_convergence_claim"] is False

python -m pytest "packages/omnibias-core/tests/test_implicit.py::test_honesty_sealed" -q

Read the implementation

def honesty_payload() -> dict[str, bool]:
    """Sealed artifact keys. Values are copies."""
    return dict(HONESTY)

Other public import paths

• omnibias.core.honesty_payload
• omnibias.core.implicit.honesty_payload
• omnibias.jax.implicit.honesty_payload
• omnibias.torch.implicit.honesty_payload

FUNCTION

reject_anderson

omnibias.core.reject_andersonSource ↗

reject_anderson(solver: str) -> None

Anderson is extra; the gate uses Newton.

Parameters

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

ReturnsNone

Explicit validation & failure cases

• When solver == 'anderson', raises DEQSolverUnknown("anderson acceleration is extra and is not the gated solver; use solver='newton' or solver='iterate'").

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

Executed regression · anderson is extra

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_anderson_is_extra() -> None:
    with pytest.raises(DEQSolverUnknown, match="newton"):
        reject_anderson("anderson")
    reject_anderson("newton")

python -m pytest "packages/omnibias-core/tests/test_implicit.py::test_anderson_is_extra" -q

Read the implementation

def reject_anderson(solver: str) -> None:
    """Anderson is extra; the gate uses Newton."""
    if solver == "anderson":
        raise DEQSolverUnknown(
            "anderson acceleration is extra and is not the gated solver; "
            "use solver='newton' or solver='iterate'"
        )

Related APIsomnibias.core.DEQSolverUnknown↗

Other public import paths

• omnibias.core.reject_anderson
• omnibias.core.implicit.reject_anderson

FUNCTION

reject_deq_contraction

omnibias.core.reject_deq_contractionSource ↗

reject_deq_contraction(bound: float, *, require: bool) -> None

G11: raise rather than silently unroll when the bound is >= 1.

Parameters

Name	Type & default	Contract
boundpositional-or-keyword	floatRequired	See the operation contract and implementation below.
requirekeyword-only	boolRequired	See the operation contract and implementation below.

ReturnsNone

Explicit validation & failure cases

• When require and radius >= 1.0, raises DEQNotContractive(f'spectral_radius_bound={radius} >= 1; refuse to unroll. Pass require_contraction=False to attempt Newton without a Banach certificate').

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

Executed regression · contraction raises

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_contraction_raises() -> None:
    cfg = DEQConfig(require_contraction=True, max_iter=2)
    with pytest.raises(DEQNotContractive, match="unroll"):
        deq_solve(jnp.asarray([[3.0]]), jnp.asarray([0.1]), "tanh", config=cfg)

python -m pytest "packages/omnibias-jax/tests/test_implicit.py::test_contraction_raises" -q

Regression example · contraction raise

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_contraction_raise() -> None:
    reject_deq_contraction(0.5, require=True)
    with pytest.raises(DEQNotContractive, match="unroll"):
        reject_deq_contraction(1.0, require=True)
    reject_deq_contraction(1.5, require=False)

python -m pytest packages/omnibias-core/tests/test_implicit.py -k test_contraction_raise -q

Read the implementation

def reject_deq_contraction(bound: float, *, require: bool) -> None:
    """G11: raise rather than silently unroll when the bound is ``>= 1``."""
    radius = spectral_radius_inf_bound(bound)
    if require and radius >= 1.0:
        raise DEQNotContractive(
            f"spectral_radius_bound={radius} >= 1; refuse to unroll. "
            "Pass require_contraction=False to attempt Newton without "
            "a Banach certificate"
        )

Related APIsomnibias.core.DEQNotContractive↗omnibias.core.spectral_radius_inf_bound↗

Other public import paths

• omnibias.core.reject_deq_contraction
• omnibias.core.implicit.reject_deq_contraction

FUNCTION

spectral_radius_inf_bound

omnibias.core.spectral_radius_inf_boundSource ↗

spectral_radius_inf_bound(abs_sigma_prime_times_row_l1: float) -> float

Infinity-norm bound on diag(sigma') W.

max_i |sigma'_i| ||W_{i,:}||_1 is enough for the gate. A value < 1 is a sufficient Banach contraction test, not a necessary one.

Parameters

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

Returnsfloat

Explicit validation & failure cases

• When bound < 0.0 or not math.isfinite(bound), raises ValueError(f'spectral-radius bound must be a finite number >= 0, got {bound}').

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

Executed regression · inf bound

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_inf_bound() -> None:
    assert spectral_radius_inf_bound(0.141) == pytest.approx(0.141)
    with pytest.raises(ValueError):
        spectral_radius_inf_bound(-0.1)

python -m pytest "packages/omnibias-core/tests/test_implicit.py::test_inf_bound" -q

Read the implementation

def spectral_radius_inf_bound(
    abs_sigma_prime_times_row_l1: float,
) -> float:
    """Infinity-norm bound on ``diag(sigma') W``.

    ``max_i |sigma'_i| ||W_{i,:}||_1`` is enough for the gate. A value
    ``< 1`` is a sufficient Banach contraction test, not a necessary one.
    """
    bound = float(abs_sigma_prime_times_row_l1)
    if bound < 0.0 or not math.isfinite(bound):
        raise ValueError(
            f"spectral-radius bound must be a finite number >= 0, got {bound}"
        )
    return bound

Other public import paths

• omnibias.core.spectral_radius_inf_bound
• omnibias.core.implicit.spectral_radius_inf_bound

← Package overviewRunnable learning examples →