API REFERENCE/omnibias-core

omnibias.core.verified.sqg

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

Module contract & mathematical conventions

Verified 2-D SQG substrate: the single Riesz transform on a Poisson-blob basis.

The companion omnibias.core.verified.riesz module makes the *second-order* Riesz composite R_iR_k elementary on the basis f_a = a^2/(\pi D^2) -- which is exactly what the Leray projection (2-D Euler) needs -- but the **single** Riesz transform R_j (Fourier multiplier -i\xi_j/|\xi|, a *half*-Laplacian |\xi|^{-1}) is *not* elementary on that basis. Genuine **surface quasi-geostrophic (SQG)** flow needs precisely that single Riesz transform:

u = R^\perp\theta = \nabla^\perp(-\Delta)^{-1/2}\theta = (-R_2\theta,\; R_1\theta).

The unlock is to change the blob basis to the one on which the half-Laplacian is *itself* diagonal in closed form: the **2-D Poisson kernel**. For a scale a > 0 set D = x^2 + y^2 + a^2 and

\theta_a(x) = \frac{1}{2\pi}\,\frac{a}{D^{3/2}}, \qquad \hat\theta_a(\xi) = e^{-a|\xi|}.

Because the symbol is e^{-a|\xi|}, every (half-)power of -\Delta acts by a plain multiplication and stays elementary. In particular the **stream function**

\psi_a = (-\Delta)^{-1/2}\theta_a,\qquad \hat\psi_a(\xi) = \frac{e^{-a|\xi|}}{|\xi|},\qquad \psi_a(x) = \frac{1}{2\pi}\,\frac{1}{D^{1/2}},

is in closed form (the radial inverse transform \int_0^\infty e^{-a\rho}J_0(r\rho)\,d\rho = (r^2+a^2)^{-1/2}), and so is the **single Riesz transform**

(R_j\theta_a)(x) = \partial_j\psi_a(x) = -\frac{1}{2\pi}\,\frac{x_j}{D^{3/2}}, \qquad u = \nabla^\perp\psi_a = \frac{1}{2\pi}\,\frac{(y, -x)}{D^{3/2}}.

This is the verified half-Laplacian substrate recorded as the open obligation of the 2-D Euler certificate. A *radial* \theta = \sum_i c_i\theta_{a_i} makes u tangential (\parallel (y,-x)) while \nabla\theta is radial (\parallel (x,y)), so u\cdot\nabla\theta \equiv 0 -- an **exact SQG steady state**, the genuine-SQG analogue of the Euler vortex.

Every quantity is an outward-rounded Interval; the half-power D^{1/2} uses the rigorous Interval.sqrt. The closed forms are *proved* (Fourier multipliers) and *checked* in the tests against an independent mpmath Hankel transform of the symbol and mpmath derivatives of \psi_a.

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 →

FUNCTION

sqg_blob

omnibias.core.verified.sqg_blobSource ↗

sqg_blob(x: float, y: float, a: float) -> Interval

Verified SQG temperature blob \theta_a = a/(2\pi D^{3/2}) (> 0).

The 2-D Poisson kernel; its Fourier symbol is e^{-a|\xi|} (checked in the tests via the Hankel transform), which is what makes the half-Laplacian elementary on this basis.

Parameters

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

ReturnsInterval

Explicit validation & failure cases

• When a == 0.0, raises ValueError('blob scale a must be non-zero').

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

Executed regression · blob is positive and decays

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_blob_is_positive_and_decays() -> None:
    near = sqg_blob(0.0, 0.0, _A)
    far = sqg_blob(5.0, 0.0, _A)
    assert near.lo > 0.0
    assert far.hi < near.lo  # monotone radial decay

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_blob_is_positive_and_decays" -q

Regression example · input validation

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_input_validation() -> None:
    with pytest.raises(ValueError):
        sqg_blob(0.1, 0.2, 0.0)  # zero scale
    with pytest.raises(ValueError):
        sqg_riesz(2, 0.1, 0.2, 0.7)  # bad axis
    with pytest.raises(ValueError):
        sqg_velocity(0.1, 0.2, 0.0)  # zero scale
    assert isinstance(sqg_stream(0.1, 0.2, 0.7), Interval)

python -m pytest packages/omnibias-core/tests/verified/test_sqg.py -k test_input_validation -q

Read the implementation

def sqg_blob(x: float, y: float, a: float) -> Interval:
    r"""Verified SQG temperature blob ``\theta_a = a/(2\pi D^{3/2})`` (``> 0``).

    The 2-D Poisson kernel; its Fourier symbol is ``e^{-a|\xi|}`` (checked in the
    tests via the Hankel transform), which is what makes the half-Laplacian
    elementary on this basis.
    """
    if a == 0.0:
        raise ValueError("blob scale a must be non-zero")
    return Interval.point(a) * (_TWO_PI.reciprocal()) * _inv_pow_three_half(_denom(x, y, a))

Other public import paths

• omnibias.core.verified.sqg_blob
• omnibias.core.verified.sqg.sqg_blob

FUNCTION

sqg_blob_gradient

omnibias.core.verified.sqg_blob_gradientSource ↗

sqg_blob_gradient(x: float, y: float, a: float) -> tuple[Interval, Interval]

Verified \nabla\theta_a = -(3a/2\pi)(x, y)/D^{5/2} (purely radial).

Paired with the tangential velocity u \parallel (y, -x) it makes the SQG advection residual u\cdot\nabla\theta vanish by exact perpendicularity.

Parameters

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

Returnstuple[Interval, Interval]

Explicit validation & failure cases

• When a == 0.0, raises ValueError('blob scale a must be non-zero').

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

Executed regression · blob gradient matches mpmath

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_blob_gradient_matches_mpmath() -> None:
    for x, y in _PTS:
        tx = float(mp.diff(lambda t: _theta(t, y, _A), x))  # noqa: B023
        ty = float(mp.diff(lambda t: _theta(x, t, _A), y))  # noqa: B023
        gx, gy = sqg_blob_gradient(x, y, _A)
        assert gx.lo <= tx <= gx.hi
        assert gy.lo <= ty <= gy.hi

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_blob_gradient_matches_mpmath" -q

Regression example · velocity perp to blob gradient exact steady state

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_velocity_perp_to_blob_gradient_exact_steady_state() -> None:
    # u ~ (y, -x) tangential, nabla theta ~ (x, y) radial: u . nabla theta == 0.
    for x, y in _PTS:
        ux, uy = sqg_velocity(x, y, _A)
        gx, gy = sqg_blob_gradient(x, y, _A)
        res = ux * gx + uy * gy
        assert res.lo <= 0.0 <= res.hi
        assert res.abs().hi < 1e-12

python -m pytest packages/omnibias-core/tests/verified/test_sqg.py -k test_velocity_perp_to_blob_gradient_exact_steady_state -q

Read the implementation

def sqg_blob_gradient(x: float, y: float, a: float) -> tuple[Interval, Interval]:
    r"""Verified ``\nabla\theta_a = -(3a/2\pi)(x, y)/D^{5/2}`` (purely radial).

    Paired with the tangential velocity ``u \parallel (y, -x)`` it makes the SQG
    advection residual ``u\cdot\nabla\theta`` vanish by exact perpendicularity.
    """
    if a == 0.0:
        raise ValueError("blob scale a must be non-zero")
    fac = Interval.point(-3.0 * a) * _TWO_PI.reciprocal() * _inv_pow_five_half(_denom(x, y, a))
    return Interval.point(x) * fac, Interval.point(y) * fac

Other public import paths

• omnibias.core.verified.sqg_blob_gradient
• omnibias.core.verified.sqg.sqg_blob_gradient

FUNCTION

sqg_blob_l2_inner

omnibias.core.verified.sqg_blob_l2_innerSource ↗

sqg_blob_l2_inner(a: float, b: float) -> Interval

Verified \langle\theta_a,\theta_b\rangle_{L^2(\mathbb R^2)} = 1/(2\pi(a+b)^2).

The exact whole-plane inner product of two Poisson-kernel temperature blobs. With \theta_a = a/(2\pi D^{3/2}) the radial integral is elementary,

\int_0^\infty \frac{r\,dr}{(r^2+a^2)^{3/2}(r^2+b^2)^{3/2}} = \frac{1}{(a+b)^2\,ab}, \qquad \langle\theta_a,\theta_b\rangle = \frac{1}{2\pi(a+b)^2},

so the squared L^2 norm of a radial profile \theta=\sum_i c_i\theta_{a_i} *diagonalises* to \sum_{ij} c_i c_j/(2\pi(a_i+a_j)^2). This is the engine of the self-similar **obstruction** certificate (the residual lower bound \lVert(y+R^\perp\theta)\cdot\nabla\theta\rVert_2 \ge \lVert\theta\rVert_2). The endpoints are outward rounded; requires a, b > 0.

Parameters

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

ReturnsInterval

Explicit validation & failure cases

• When a <= 0.0 or b <= 0.0, raises ValueError('blob scales a, b must be positive').

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

Executed regression · blob l2 inner is symmetric and positive

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_blob_l2_inner_is_symmetric_and_positive() -> None:
    ab = sqg_blob_l2_inner(0.6, 1.4)
    ba = sqg_blob_l2_inner(1.4, 0.6)
    assert ab.lo == ba.lo and ab.hi == ba.hi
    assert ab.lo > 0.0

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_blob_l2_inner_is_symmetric_and_positive" -q

Regression example · blob l2 inner rejects nonpositive scale

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_blob_l2_inner_rejects_nonpositive_scale() -> None:
    with pytest.raises(ValueError):
        sqg_blob_l2_inner(0.0, 1.0)
    with pytest.raises(ValueError):
        sqg_blob_l2_inner(1.0, -0.3)

python -m pytest packages/omnibias-core/tests/verified/test_sqg.py -k test_blob_l2_inner_rejects_nonpositive_scale -q

Read the implementation

def sqg_blob_l2_inner(a: float, b: float) -> Interval:
    r"""Verified ``\langle\theta_a,\theta_b\rangle_{L^2(\mathbb R^2)} = 1/(2\pi(a+b)^2)``.

    The exact whole-plane inner product of two Poisson-kernel temperature blobs.
    With ``\theta_a = a/(2\pi D^{3/2})`` the radial integral is elementary,

    .. math::

        \int_0^\infty \frac{r\,dr}{(r^2+a^2)^{3/2}(r^2+b^2)^{3/2}}
        = \frac{1}{(a+b)^2\,ab},
        \qquad
        \langle\theta_a,\theta_b\rangle = \frac{1}{2\pi(a+b)^2},

    so the squared ``L^2`` norm of a radial profile ``\theta=\sum_i c_i\theta_{a_i}``
    *diagonalises* to ``\sum_{ij} c_i c_j/(2\pi(a_i+a_j)^2)``.  This is the engine of
    the self-similar **obstruction** certificate (the residual lower bound
    ``\lVert(y+R^\perp\theta)\cdot\nabla\theta\rVert_2 \ge \lVert\theta\rVert_2``).
    The endpoints are outward rounded; requires ``a, b > 0``.
    """
    if a <= 0.0 or b <= 0.0:
        raise ValueError("blob scales a, b must be positive")
    ab = Interval.point(a) + Interval.point(b)
    return (_TWO_PI * ab.pow_int(2)).reciprocal()

Other public import paths

• omnibias.core.verified.sqg_blob_l2_inner
• omnibias.core.verified.sqg.sqg_blob_l2_inner

FUNCTION

sqg_riesz

omnibias.core.verified.sqg_rieszSource ↗

sqg_riesz(j: int, x: float, y: float, a: float) -> Interval

Verified **single** Riesz transform (R_j\theta_a)(x) = -x_j/(2\pi D^{3/2}).

This is the half-Laplacian piece R_j = \partial_j(-\Delta)^{-1/2} that is *not* elementary on the Euler f_a basis but **is** elementary here (R_j\theta_a = \partial_j\psi_a); j indexes the axis (0 = x, 1 = y). It is the closed-form engine of the SQG velocity u = R^\perp\theta.

Parameters

Name	Type & default	Contract
jpositional-or-keyword	intRequired	See the operation contract and implementation below.
xpositional-or-keyword	floatRequired	See the operation contract and implementation below.
ypositional-or-keyword	floatRequired	See the operation contract and implementation below.
apositional-or-keyword	floatRequired	See the operation contract and implementation below.

ReturnsInterval

Explicit validation & failure cases

• When a == 0.0, raises ValueError('blob scale a must be non-zero').

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

Executed regression · input validation

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_input_validation() -> None:
    with pytest.raises(ValueError):
        sqg_blob(0.1, 0.2, 0.0)  # zero scale
    with pytest.raises(ValueError):
        sqg_riesz(2, 0.1, 0.2, 0.7)  # bad axis
    with pytest.raises(ValueError):
        sqg_velocity(0.1, 0.2, 0.0)  # zero scale
    assert isinstance(sqg_stream(0.1, 0.2, 0.7), Interval)

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_input_validation" -q

Regression example · riesz equals gradient of stream

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_riesz_equals_gradient_of_stream() -> None:
    # The single Riesz transform R_j theta_a = d_j psi_a (definition of psi as the
    # half-inverse): checked against an mpmath derivative of the closed-form psi.
    for x, y in _PTS:
        px = float(mp.diff(lambda t: _psi(t, y, _A), x))  # noqa: B023
        py = float(mp.diff(lambda t: _psi(x, t, _A), y))  # noqa: B023
        r0 = sqg_riesz(0, x, y, _A)
        r1 = sqg_riesz(1, x, y, _A)
        assert r0.lo <= px <= r0.hi
        assert r1.lo <= py <= r1.hi

python -m pytest packages/omnibias-core/tests/verified/test_sqg.py -k test_riesz_equals_gradient_of_stream -q

Read the implementation

def sqg_riesz(j: int, x: float, y: float, a: float) -> Interval:
    r"""Verified **single** Riesz transform ``(R_j\theta_a)(x) = -x_j/(2\pi D^{3/2})``.

    This is the half-Laplacian piece ``R_j = \partial_j(-\Delta)^{-1/2}`` that is
    *not* elementary on the Euler ``f_a`` basis but **is** elementary here
    (``R_j\theta_a = \partial_j\psi_a``); ``j`` indexes the axis (``0`` = x,
    ``1`` = y).  It is the closed-form engine of the SQG velocity ``u = R^\perp\theta``.
    """
    _require_axis("j", j)
    if a == 0.0:
        raise ValueError("blob scale a must be non-zero")
    comp = (x, y)
    inv = _TWO_PI.reciprocal() * _inv_pow_three_half(_denom(x, y, a))
    return Interval.point(-comp[j]) * inv

Other public import paths

• omnibias.core.verified.sqg_riesz
• omnibias.core.verified.sqg.sqg_riesz

FUNCTION

sqg_stream

omnibias.core.verified.sqg_streamSource ↗

sqg_stream(x: float, y: float, a: float) -> Interval

Verified SQG stream function \psi_a = (-\Delta)^{-1/2}\theta_a = 1/(2\pi D^{1/2}).

Parameters

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

ReturnsInterval

Explicit validation & failure cases

• When a == 0.0, raises ValueError('blob scale a must be non-zero').

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

Executed regression · input validation

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_input_validation() -> None:
    with pytest.raises(ValueError):
        sqg_blob(0.1, 0.2, 0.0)  # zero scale
    with pytest.raises(ValueError):
        sqg_riesz(2, 0.1, 0.2, 0.7)  # bad axis
    with pytest.raises(ValueError):
        sqg_velocity(0.1, 0.2, 0.0)  # zero scale
    assert isinstance(sqg_stream(0.1, 0.2, 0.7), Interval)

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_input_validation" -q

Regression example · stream is half inverse laplacian via hankel

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_stream_is_half_inverse_laplacian_via_hankel() -> None:
    # psi_a = (-Delta)^{-1/2} theta_a has symbol e^{-a|xi|}/|xi|; the inverse
    # transform is the closed form 1/(2pi D^{1/2}).
    for x, y in _PTS:
        r = (x * x + y * y) ** 0.5
        truth = float(_hankel(lambda rho: mp.e ** (-_A * rho) / rho, r))
        enc = sqg_stream(x, y, _A)
        assert enc.lo <= truth <= enc.hi

python -m pytest packages/omnibias-core/tests/verified/test_sqg.py -k test_stream_is_half_inverse_laplacian_via_hankel -q

Read the implementation

def sqg_stream(x: float, y: float, a: float) -> Interval:
    r"""Verified SQG stream function ``\psi_a = (-\Delta)^{-1/2}\theta_a = 1/(2\pi D^{1/2})``."""
    if a == 0.0:
        raise ValueError("blob scale a must be non-zero")
    return (_TWO_PI * _denom(x, y, a).sqrt()).reciprocal()

Other public import paths

• omnibias.core.verified.sqg_stream
• omnibias.core.verified.sqg.sqg_stream

FUNCTION

sqg_stream_gradient

omnibias.core.verified.sqg_stream_gradientSource ↗

sqg_stream_gradient(x: float, y: float, a: float) -> tuple[Interval, Interval]

Verified \nabla\psi_a = -(1/2\pi)(x, y)/D^{3/2}.

Parameters

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

Returnstuple[Interval, Interval]

Explicit validation & failure cases

• When a == 0.0, raises ValueError('blob scale a must be non-zero').

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

Executed regression · stream gradient matches mpmath

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_stream_gradient_matches_mpmath() -> None:
    for x, y in _PTS:
        px = float(mp.diff(lambda t: _psi(t, y, _A), x))  # noqa: B023
        py = float(mp.diff(lambda t: _psi(x, t, _A), y))  # noqa: B023
        gx, gy = sqg_stream_gradient(x, y, _A)
        assert gx.lo <= px <= gx.hi
        assert gy.lo <= py <= gy.hi

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_stream_gradient_matches_mpmath" -q

Read the implementation

def sqg_stream_gradient(x: float, y: float, a: float) -> tuple[Interval, Interval]:
    r"""Verified ``\nabla\psi_a = -(1/2\pi)(x, y)/D^{3/2}``."""
    if a == 0.0:
        raise ValueError("blob scale a must be non-zero")
    inv = _TWO_PI.reciprocal() * _inv_pow_three_half(_denom(x, y, a))
    return Interval.point(-x) * inv, Interval.point(-y) * inv

Other public import paths

• omnibias.core.verified.sqg_stream_gradient
• omnibias.core.verified.sqg.sqg_stream_gradient

FUNCTION

sqg_velocity

omnibias.core.verified.sqg_velocitySource ↗

sqg_velocity(x: float, y: float, a: float) -> tuple[Interval, Interval]

Verified SQG velocity u = R^\perp\theta_a = (1/2\pi)(y, -x)/D^{3/2}.

The tangential field u = \nabla^\perp\psi_a = (-\partial_y\psi_a, \partial_x\psi_a); computed here directly so the certificate can cross-check it against the independent (-R_2\theta_a, R_1\theta_a) Riesz route.

Parameters

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

Returnstuple[Interval, Interval]

Explicit validation & failure cases

• When a == 0.0, raises ValueError('blob scale a must be non-zero').

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

Executed regression · input validation

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_input_validation() -> None:
    with pytest.raises(ValueError):
        sqg_blob(0.1, 0.2, 0.0)  # zero scale
    with pytest.raises(ValueError):
        sqg_riesz(2, 0.1, 0.2, 0.7)  # bad axis
    with pytest.raises(ValueError):
        sqg_velocity(0.1, 0.2, 0.0)  # zero scale
    assert isinstance(sqg_stream(0.1, 0.2, 0.7), Interval)

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_input_validation" -q

Regression example · velocity perp to blob gradient exact steady state

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_velocity_perp_to_blob_gradient_exact_steady_state() -> None:
    # u ~ (y, -x) tangential, nabla theta ~ (x, y) radial: u . nabla theta == 0.
    for x, y in _PTS:
        ux, uy = sqg_velocity(x, y, _A)
        gx, gy = sqg_blob_gradient(x, y, _A)
        res = ux * gx + uy * gy
        assert res.lo <= 0.0 <= res.hi
        assert res.abs().hi < 1e-12

python -m pytest packages/omnibias-core/tests/verified/test_sqg.py -k test_velocity_perp_to_blob_gradient_exact_steady_state -q

Read the implementation

def sqg_velocity(x: float, y: float, a: float) -> tuple[Interval, Interval]:
    r"""Verified SQG velocity ``u = R^\perp\theta_a = (1/2\pi)(y, -x)/D^{3/2}``.

    The tangential field ``u = \nabla^\perp\psi_a = (-\partial_y\psi_a,
    \partial_x\psi_a)``; computed here directly so the certificate can cross-check
    it against the independent ``(-R_2\theta_a, R_1\theta_a)`` Riesz route.
    """
    if a == 0.0:
        raise ValueError("blob scale a must be non-zero")
    inv = _TWO_PI.reciprocal() * _inv_pow_three_half(_denom(x, y, a))
    return Interval.point(y) * inv, Interval.point(-x) * inv

Other public import paths

• omnibias.core.verified.sqg_velocity
• omnibias.core.verified.sqg.sqg_velocity

FUNCTION

sqg_velocity_divergence_residual

omnibias.core.verified.sqg_velocity_divergence_residualSource ↗

sqg_velocity_divergence_residual(x: float, y: float, a: float) -> Interval

Closed-form enclosure of \nabla\cdot u for one velocity blob.

Computes \partial_x u_1 + \partial_y u_2 from the two *separate* component derivatives \partial_x u_1 = -(3/2\pi) x y D^{-5/2} and \partial_y u_2 = +(3/2\pi) x y D^{-5/2}); the sum is analytically 0 (u = \nabla^\perp\psi is divergence-free), so the returned interval is a certificate that the two non-trivial rationals cancel.

Parameters

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

ReturnsInterval

Explicit validation & failure cases

• When a == 0.0, raises ValueError('blob scale a must be non-zero').

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

Executed regression · velocity divergence residual encloses zero

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_velocity_divergence_residual_encloses_zero() -> None:
    for x, y in _PTS:
        res = sqg_velocity_divergence_residual(x, y, _A)
        assert res.lo <= 0.0 <= res.hi
        assert res.width < 1e-10

python -m pytest "packages/omnibias-core/tests/verified/test_sqg.py::test_velocity_divergence_residual_encloses_zero" -q

Regression example · velocity perp to blob gradient exact steady state

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_velocity_perp_to_blob_gradient_exact_steady_state() -> None:
    # u ~ (y, -x) tangential, nabla theta ~ (x, y) radial: u . nabla theta == 0.
    for x, y in _PTS:
        ux, uy = sqg_velocity(x, y, _A)
        gx, gy = sqg_blob_gradient(x, y, _A)
        res = ux * gx + uy * gy
        assert res.lo <= 0.0 <= res.hi
        assert res.abs().hi < 1e-12

python -m pytest packages/omnibias-core/tests/verified/test_sqg.py -k test_velocity_perp_to_blob_gradient_exact_steady_state -q

Read the implementation

def sqg_velocity_divergence_residual(x: float, y: float, a: float) -> Interval:
    r"""Closed-form enclosure of ``\nabla\cdot u`` for one velocity blob.

    Computes ``\partial_x u_1 + \partial_y u_2`` from the two *separate* component
    derivatives ``\partial_x u_1 = -(3/2\pi) x y D^{-5/2}`` and
    ``\partial_y u_2 = +(3/2\pi) x y D^{-5/2})``; the sum is analytically ``0``
    (``u = \nabla^\perp\psi`` is divergence-free), so the returned interval is a
    certificate that the two non-trivial rationals cancel.
    """
    if a == 0.0:
        raise ValueError("blob scale a must be non-zero")
    inv5 = _inv_pow_five_half(_denom(x, y, a))
    xy = Interval.point(x) * Interval.point(y)
    base = Interval.point(3.0) * _TWO_PI.reciprocal() * xy * inv5
    dxux = -base
    dyuy = base
    return dxux + dyuy

Other public import paths

• omnibias.core.verified.sqg_velocity_divergence_residual
• omnibias.core.verified.sqg.sqg_velocity_divergence_residual

← Package overviewRunnable learning examples →