API REFERENCE/omnibias-core

omnibias.core.jets

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

Module contract & mathematical conventions

Jet-bundle vocabulary helpers (theory 01-10).

This is a **reformulation**, not a discovery: a tower of numbers is a jet only when it is holonomic (annihilates the contact ideal). There is no omnibias-jetbundle package.

A 1-D jet at a point is (u, u', ..., u^{(N)}). The contact residual of order k is u^{(k)}(x+h) - u^{(k)}(x) - h u^{(k+1)}(x), which is O(h^2) for a genuine prolongation and O(h) for a corrupted tower.

Founding delta -> 0 produces fiber coordinates. Temperature collapse (beta -> inf) acts on the base stratification, not on the fiber.

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

contact_residual

omnibias.core.contact_residualSource ↗

contact_residual(jet_at_x: Jet1D, jet_at_x_plus_h: Jet1D, *, h: float) -> tuple[float, ...]

Residuals of du^{(k)} - u^{(k+1)} dx for a 1-D jet.

Should be O(h^2) for a holonomic jet (Taylor remainder) and O(h) when a coordinate is overwritten.

Parameters

Name	Type & default	Contract
jet_at_xpositional-or-keyword	Jet1DRequired	See the operation contract and implementation below.
jet_at_x_plus_hpositional-or-keyword	Jet1DRequired	See the operation contract and implementation below.
hkeyword-only	floatRequired	See the operation contract and implementation below.

Returnstuple[float, ...]

Explicit validation & failure cases

• When h == 0.0, raises ValueError('h must be nonzero').
• When len(a) != len(b), raises ValueError('jets must have equal length').
• When len(a) < 2, raises ValueError('contact residual needs order >= 1 (at least two coordinates)').

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

Executed regression · contact residual worked example

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_contact_residual_worked_example() -> None:
    # Spec 01-10 worked example at x=0.5, h=1e-4, tanh.
    x = 0.5
    h = 1e-4
    res = contact_residual(_tanh_jet(x, 2), _tanh_jet(x + h, 2), h=h)
    assert abs(res[0]) < 1e-8
    bad0 = list(_tanh_jet(x, 2))
    badh = list(_tanh_jet(x + h, 2))
    bad0[1] = 0.90
    badh[1] = 0.90
    res_bad = contact_residual(bad0, badh, h=h)
    assert abs(res_bad[0]) > 1e-6

python -m pytest "packages/omnibias-core/tests/test_jets_contact.py::test_contact_residual_worked_example" -q

Read the implementation

def contact_residual(
    jet_at_x: Jet1D,
    jet_at_x_plus_h: Jet1D,
    *,
    h: float,
) -> tuple[float, ...]:
    """Residuals of ``du^{(k)} - u^{(k+1)} dx`` for a 1-D jet.

    Should be ``O(h^2)`` for a holonomic jet (Taylor remainder) and
    ``O(h)`` when a coordinate is overwritten.
    """
    if h == 0.0:
        raise ValueError("h must be nonzero")
    a = tuple(float(v) for v in jet_at_x)
    b = tuple(float(v) for v in jet_at_x_plus_h)
    if len(a) != len(b):
        raise ValueError("jets must have equal length")
    if len(a) < 2:
        raise ValueError("contact residual needs order >= 1 (at least two coordinates)")
    return tuple(b[k] - a[k] - h * a[k + 1] for k in range(len(a) - 1))

Other public import paths

• omnibias.core.contact_residual
• omnibias.core.jets.contact_residual

FUNCTION

is_holonomic

omnibias.core.is_holonomicSource ↗

is_holonomic(section_sampler: SectionSampler, x: float, *, h: float, rtol: float=1e-06) -> bool

Rate test: halve h and check the residual drops by about 4x.

A holonomic 1-D jet has second-order contact remainder, so r(h/2) / r(h) ~ 1/4. Corrupted towers stay near 1/2.

Parameters

Name	Type & default	Contract
section_samplerpositional-or-keyword	SectionSamplerRequired	See the operation contract and implementation below.
xpositional-or-keyword	floatRequired	See the operation contract and implementation below.
hkeyword-only	floatRequired	See the operation contract and implementation below.
rtolkeyword-only	floatDefault: 1e-06	See the operation contract and implementation below.

Returnsbool

Explicit validation & failure cases

• When h == 0.0, raises ValueError('h must be nonzero').

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

Executed regression · g1 holonomic vs corrupted no misclassification

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_holonomic_vs_corrupted_no_misclassification() -> None:
    rng = random.Random(0)
    n_ok = 0
    n_bad = 0
    for i in range(220):
        kind = i % 4
        x = rng.uniform(-1.2, 1.2)
        h = 1e-4
        if kind == 0:
            def sampler(z: float) -> tuple[float, ...]:
                return _tanh_jet(z)
        elif kind == 1:
            def sampler(z: float) -> tuple[float, ...]:
                return _gauss_jet(z)
        elif kind == 2:
            coeffs = tuple(rng.uniform(-1.0, 1.0) for _ in range(5))

            def sampler(z: float, c: tuple[float, ...] = coeffs) -> tuple[float, ...]:
                return _poly_jet(z, c)
        else:
            def sampler(z: float) -> tuple[float, ...]:
                return _exp_jet(z)
        assert is_holonomic(sampler, x, h=h)
        n_ok += 1

        def corrupted(z: float, _s=sampler) -> tuple[float, ...]:
            jet = list(_s(z))
            jet[1] = 0.90
            return tuple(jet)

        assert not is_holonomic(corrupted, x, h=h)
        n_bad += 1
    assert n_ok >= 200 and n_bad >= 200

python -m pytest "packages/omnibias-core/tests/test_jets_contact.py::test_g1_holonomic_vs_corrupted_no_misclassification" -q

Read the implementation

def is_holonomic(
    section_sampler: SectionSampler,
    x: float,
    *,
    h: float,
    rtol: float = 1e-6,
) -> bool:
    """Rate test: halve ``h`` and check the residual drops by about ``4x``.

    A holonomic 1-D jet has second-order contact remainder, so
    ``r(h/2) / r(h) ~ 1/4``. Corrupted towers stay near ``1/2``.
    """
    if h == 0.0:
        raise ValueError("h must be nonzero")
    j0 = section_sampler(x)
    r_h = max_abs_contact_residual(j0, section_sampler(x + h), h=h)
    h2 = 0.5 * h
    r_h2 = max_abs_contact_residual(j0, section_sampler(x + h2), h=h2)
    # Machine-zero remainder is holonomic. Do not scale the floor by |jet|:
    # a corrupted first derivative of size O(1) produces r ~ |h|, which must
    # not be swallowed by rtol * max|jet|.
    floor = 1e-14
    if r_h <= floor and r_h2 <= floor:
        return True
    if r_h <= 0.0:
        return r_h2 <= floor
    ratio = r_h2 / r_h
    # Second-order: ~0.25; first-order: ~0.5. Split at ~0.38.
    return ratio <= 0.38

Related APIsomnibias.core.jets.max_abs_contact_residual↗

Other public import paths

• omnibias.core.is_holonomic
• omnibias.core.jets.is_holonomic

FUNCTION

max_abs_contact_residual

omnibias.core.jets.max_abs_contact_residualSource ↗

max_abs_contact_residual(jet_at_x: Jet1D, jet_at_x_plus_h: Jet1D, *, h: float) -> float

The module contract describes the context for this operation. Its signature, explicit validation, return expressions, and implementation are recorded below.

Parameters

Name	Type & default	Contract
jet_at_xpositional-or-keyword	Jet1DRequired	See the operation contract and implementation below.
jet_at_x_plus_hpositional-or-keyword	Jet1DRequired	See the operation contract and implementation below.
hkeyword-only	floatRequired	See the operation contract and implementation below.

Returnsfloat

Executed regression · g2 rate three halvings

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_g2_rate_three_halvings() -> None:
    x = 0.5
    h0 = 8e-4
    j0 = _tanh_jet(x)

    def holonomic_res(h: float) -> float:
        return max_abs_contact_residual(j0, _tanh_jet(x + h), h=h)

    def corrupted_res(h: float) -> float:
        good = _tanh_jet(x)
        bad_h = list(_tanh_jet(x + h))
        bad0 = list(good)
        bad0[1] = 0.90
        bad_h[1] = 0.90
        return max_abs_contact_residual(bad0, bad_h, h=h)

    hs = [h0 / (2**k) for k in range(4)]
    r_h = [holonomic_res(h) for h in hs]
    r_c = [corrupted_res(h) for h in hs]
    # Three halvings: holonomic ~4x, corrupted ~2x.
    for i in range(3):
        ratio_h = r_h[i + 1] / r_h[i]
        ratio_c = r_c[i + 1] / r_c[i]
        assert 0.15 <= ratio_h <= 0.35, (i, ratio_h, r_h)
        assert 0.40 <= ratio_c <= 0.60, (i, ratio_c, r_c)

python -m pytest "packages/omnibias-core/tests/test_jets_contact.py::test_g2_rate_three_halvings" -q

Read the implementation

def max_abs_contact_residual(
    jet_at_x: Jet1D,
    jet_at_x_plus_h: Jet1D,
    *,
    h: float,
) -> float:
    res = contact_residual(jet_at_x, jet_at_x_plus_h, h=h)
    return max(abs(v) for v in res)

Related APIsomnibias.core.contact_residual↗

← Package overviewRunnable learning examples →