API REFERENCE/omnibias-core

omnibias.core.parameter_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.parameter_jets

Module contract & mathematical conventions

Parameter-space mixed jets (theory 09-27).

Treat a PDE parameter μ as a jet coordinate so one pass yields ∂^{α,β} u / ∂x^α ∂μ^β. founding bias collapse (delta -> 0) supplies sigma^(n) along affine directions in z = (x, μ). Temperature collapse (beta -> inf, feasibility) does not appear. do not conflate the two.

Closed form holds **iff** μ enters a jet trunk / OMBU. A dense pde_params encoder is autodiff and cannot set closed_form. Directional parameter derivatives for the supplied finite network. theorem_prover_verified is not asserted.

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 →

CONSTANT

DEFAULT_SPEC

omnibias.core.parameter_jets.DEFAULT_SPECSource ↗

DEFAULT_SPEC = ParameterJetSpec()

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

DEFAULT_SPEC = ParameterJetSpec()

Related APIsomnibias.core.parameter_jets.ParameterJetSpec↗

CONSTANT

DISCLAIMER

omnibias.core.parameter_jets.DISCLAIMERSource ↗

DISCLAIMER = 'mixed x-mu jets; closed_form iff mu is on the jet trunk; directional parameter derivatives for a finite network'

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.

Regression example · g4 honesty

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_g4_honesty() -> None:
    payload = honesty_payload()
    assert payload["parampinn_package"] is False
    assert payload["global_pde_claim"] is False
    assert payload["stretch_claim"] is False
    assert "finite network" in DISCLAIMER

python -m pytest packages/omnibias-core/tests/test_parameter_jets.py -k test_g4_honesty -q

Read the implementation

DISCLAIMER = (
    "mixed x-mu jets; closed_form iff mu is on the jet trunk; "
    "directional parameter derivatives for a finite network"
)

CLASS

ParameterJetSpec

omnibias.core.parameter_jets.ParameterJetSpecSource ↗

class ParameterJetSpec

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.

One selected physical-parameter mixed partial.

param_order is the actual scalar-parameter derivative order. space_multi_index selects coordinate derivatives; its empty default preserves the legacy pure-parameter partial. space_order caps that index's total degree. General neural-weight subspaces use realization jets.

Parameters

Name	Type & default	Contract
space_orderdataclass field	intDefault: 1	See the operation contract and implementation below.
param_orderdataclass field	intDefault: 1	See the operation contract and implementation below.
methoddataclass field	strDefault: 'closed_form'	See the operation contract and implementation below.
mu_in_jet_trunkdataclass field	boolDefault: True	See the operation contract and implementation below.
space_multi_indexdataclass field	tuple[int, ...]Default: ()	See the operation contract and implementation below.

Executed regression · g3 closed form requires trunk

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_g3_closed_form_requires_trunk() -> None:
    spec = ParameterJetSpec(method="closed_form", mu_in_jet_trunk=False)
    with pytest.raises(ValueError, match="mu_in_jet_trunk"):
        mixed_jet(None, (1.0, 1.0), 1.0, spec=spec)
    ad = ParameterJetSpec(method="autodiff", mu_in_jet_trunk=False)
    assert ad.method != "closed_form"

python -m pytest "packages/omnibias-core/tests/test_parameter_jets.py::test_g3_closed_form_requires_trunk" -q

Regression example · supplied provider is used and no field is silently ignored

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_supplied_provider_is_used_and_no_field_is_silently_ignored() -> None:
    class Provider:
        def mixed_parameter_jet(self, coords: tuple[float, float], parameters: float, *, spec: ParameterJetSpec) -> float:
            return 7.0 * parameters + coords[0] + spec.param_order

    assert mixed_jet(Provider(), (2.0, 3.0), 5.0) == 38.0
    with pytest.raises(TypeError, match="mixed_parameter_jet"):
        mixed_jet(lambda x, p: x[0] * p, (2.0, 3.0), 5.0)
    with pytest.raises(NotImplementedError, match="autodiff"):
        mixed_jet(None, (1.0, 1.0), 1.0, spec=ParameterJetSpec(method="autodiff"))

python -m pytest packages/omnibias-core/tests/test_realization_schema.py -k test_supplied_provider_is_used_and_no_field_is_silently_ignored -q

Fields & methods

space_orderfield

space_order: int = 1

Declared int field on ParameterJetSpec. Default expression: 1.

View source ↗

param_orderfield

param_order: int = 1

Declared int field on ParameterJetSpec. Default expression: 1.

View source ↗

methodfield

method: str = 'closed_form'

Declared str field on ParameterJetSpec. Default expression: 'closed_form'.

Regression example · g3 closed form requires trunk

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_g3_closed_form_requires_trunk() -> None:
    spec = ParameterJetSpec(method="closed_form", mu_in_jet_trunk=False)
    with pytest.raises(ValueError, match="mu_in_jet_trunk"):
        mixed_jet(None, (1.0, 1.0), 1.0, spec=spec)
    ad = ParameterJetSpec(method="autodiff", mu_in_jet_trunk=False)
    assert ad.method != "closed_form"

python -m pytest packages/omnibias-core/tests/test_parameter_jets.py -k test_g3_closed_form_requires_trunk -q

View source ↗

mu_in_jet_trunkfield

mu_in_jet_trunk: bool = True

Declared bool field on ParameterJetSpec. Default expression: True.

View source ↗

space_multi_indexfield

space_multi_index: tuple[int, ...] = ()

Declared tuple[int, ...] field on ParameterJetSpec. Default expression: ().

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.space_order < 0 or self.param_order < 0, raises ValueError('jet orders must be nonnegative').
• When self.method not in {'closed_form', 'autodiff', 'finite_difference'}, raises ValueError('method must be closed_form, autodiff, or finite_difference').
• When any((n < 0 for n in self.space_multi_index)) or sum(self.space_multi_index) > self.space_order, raises ValueError('space_multi_index exceeds the requested space_order').

Executed regression · g3 closed form requires trunk

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_g3_closed_form_requires_trunk() -> None:
    spec = ParameterJetSpec(method="closed_form", mu_in_jet_trunk=False)
    with pytest.raises(ValueError, match="mu_in_jet_trunk"):
        mixed_jet(None, (1.0, 1.0), 1.0, spec=spec)
    ad = ParameterJetSpec(method="autodiff", mu_in_jet_trunk=False)
    assert ad.method != "closed_form"

python -m pytest "packages/omnibias-core/tests/test_parameter_jets.py::test_g3_closed_form_requires_trunk" -q

Method implementation

    def __post_init__(self) -> None:
        if self.space_order < 0 or self.param_order < 0:
            raise ValueError("jet orders must be nonnegative")
        if self.method not in {"closed_form", "autodiff", "finite_difference"}:
            raise ValueError("method must be closed_form, autodiff, or finite_difference")
        object.__setattr__(self, "space_multi_index", tuple(self.space_multi_index))
        if any(n < 0 for n in self.space_multi_index) or sum(self.space_multi_index) > self.space_order:
            raise ValueError("space_multi_index exceeds the requested space_order")

View source ↗

Read the implementation

class ParameterJetSpec:
    """One selected physical-parameter mixed partial.

    ``param_order`` is the actual scalar-parameter derivative order.
    ``space_multi_index`` selects coordinate derivatives; its empty default
    preserves the legacy pure-parameter partial. ``space_order`` caps that
    index's total degree. General neural-weight subspaces use realization jets.
    """

    space_order: int = 1
    param_order: int = 1
    method: str = "closed_form"
    mu_in_jet_trunk: bool = True
    space_multi_index: tuple[int, ...] = ()

    def __post_init__(self) -> None:
        if self.space_order < 0 or self.param_order < 0:
            raise ValueError("jet orders must be nonnegative")
        if self.method not in {"closed_form", "autodiff", "finite_difference"}:
            raise ValueError("method must be closed_form, autodiff, or finite_difference")
        object.__setattr__(self, "space_multi_index", tuple(self.space_multi_index))
        if any(n < 0 for n in self.space_multi_index) or sum(self.space_multi_index) > self.space_order:
            raise ValueError("space_multi_index exceeds the requested space_order")

CLASS

ScalarParameterJetProvider

omnibias.core.parameter_jets.ScalarParameterJetProviderSource ↗

class ScalarParameterJetProvider(Protocol)

An explicit closed-form field provider; plain callables are not relabeled.

Fields & methods

mixed_parameter_jetmethod

mixed_parameter_jet(self, coords: tuple[float, float], parameters: float, *, spec: ParameterJetSpec) -> float

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

Parameters

Name	Type & default	Contract
coordspositional-or-keyword	tuple[float, float]Required	See the operation contract and implementation below.
parameterspositional-or-keyword	floatRequired	See the operation contract and implementation below.
speckeyword-only	ParameterJetSpecRequired	See the operation contract and implementation below.

Returns: float

Method implementation

    def mixed_parameter_jet(
        self, coords: tuple[float, float], parameters: float, *, spec: ParameterJetSpec,
    ) -> float: ...

View source ↗

Read the implementation

class ScalarParameterJetProvider(Protocol):
    """An explicit closed-form field provider; plain callables are not relabeled."""

    def mixed_parameter_jet(
        self, coords: tuple[float, float], parameters: float, *, spec: ParameterJetSpec,
    ) -> float: ...

FUNCTION

fourier_heat

omnibias.core.parameter_jets.fourier_heatSource ↗

fourier_heat(x: float, t: float, mu: float, *, wave: float=1.0) -> float

Exact mode exp(-μ k^2 t) sin(k x).

Parameters

Name	Type & default	Contract
xpositional-or-keyword	floatRequired	See the operation contract and implementation below.
tpositional-or-keyword	floatRequired	See the operation contract and implementation below.
mupositional-or-keyword	floatRequired	See the operation contract and implementation below.
wavekeyword-only	floatDefault: 1.0	See the operation contract and implementation below.

Returnsfloat

Executed regression · g1 fourier heat

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_fourier_heat() -> None:
    ex = worked_example()
    assert ex["abs_sum"] < 1e-8

python -m pytest "packages/omnibias-core/tests/test_parameter_jets.py::test_g1_fourier_heat" -q

Read the implementation

def fourier_heat(x: float, t: float, mu: float, *, wave: float = 1.0) -> float:
    """Exact mode ``exp(-μ k^2 t) sin(k x)``."""
    return math.exp(-float(mu) * wave * wave * float(t)) * math.sin(wave * float(x))

FUNCTION

fourier_heat_du_dmu

omnibias.core.parameter_jets.fourier_heat_du_dmuSource ↗

fourier_heat_du_dmu(x: float, t: float, mu: float, *, wave: float=1.0) -> float

Closed-form ∂u/∂μ = -k^2 t u (μ on the jet trunk).

Parameters

Name	Type & default	Contract
xpositional-or-keyword	floatRequired	See the operation contract and implementation below.
tpositional-or-keyword	floatRequired	See the operation contract and implementation below.
mupositional-or-keyword	floatRequired	See the operation contract and implementation below.
wavekeyword-only	floatDefault: 1.0	See the operation contract and implementation below.

Returnsfloat

Read the implementation

def fourier_heat_du_dmu(x: float, t: float, mu: float, *, wave: float = 1.0) -> float:
    """Closed-form ``∂u/∂μ = -k^2 t u`` (μ on the jet trunk)."""
    return (-wave * wave * float(t)) * fourier_heat(x, t, mu, wave=wave)

Related APIsomnibias.core.parameter_jets.fourier_heat↗

FUNCTION

honesty_payload

omnibias.core.parameter_jets.honesty_payloadSource ↗

honesty_payload() -> dict[str, bool]

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

Returnsdict[str, bool]

Executed regression · g4 honesty

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_g4_honesty() -> None:
    payload = honesty_payload()
    assert payload["parampinn_package"] is False
    assert payload["global_pde_claim"] is False
    assert payload["stretch_claim"] is False
    assert "finite network" in DISCLAIMER

python -m pytest "packages/omnibias-core/tests/test_parameter_jets.py::test_g4_honesty" -q

Read the implementation

def honesty_payload() -> dict[str, bool]:
    return {
        "parampinn_package": False,
        "global_pde_claim": False,
        "stretch_claim": False,
        "continuum_claim": False,
        "theorem_prover_verified": False,
    }

FUNCTION

mixed_jet

omnibias.core.parameter_jets.mixed_jetSource ↗

mixed_jet(field: object | None, coords: tuple[float, float], parameters: float, *, spec: ParameterJetSpec | None=None, wave: float=1.0) -> float

A supplied scalar jet provider, or the named manufactured heat example.

Core has no autodiff backend. Use a tensor backend for method='autodiff'; the old numerical comparison is explicitly named finite_difference.

Parameters

Name	Type & default	Contract
fieldpositional-or-keyword	object | NoneRequired	See the operation contract and implementation below.
coordspositional-or-keyword	tuple[float, float]Required	See the operation contract and implementation below.
parameterspositional-or-keyword	floatRequired	See the operation contract and implementation below.
speckeyword-only	ParameterJetSpec | NoneDefault: None	See the operation contract and implementation below.
wavekeyword-only	floatDefault: 1.0	See the operation contract and implementation below.

Returnsfloat

Explicit validation & failure cases

• When cfg.method == 'autodiff', raises NotImplementedError("core has no autodiff backend; use a tensor mixed_jet or method='finite_difference'").
• When field is not None, raises TypeError('core finite_difference is the manufactured example; use a tensor callable adapter for a field').
• When not cfg.mu_in_jet_trunk, raises ValueError('closed_form requires mu_in_jet_trunk=True').
• When not isinstance(field, ScalarParameterJetProvider), raises TypeError('closed_form field must implement mixed_parameter_jet').
• When not cfg.mu_in_jet_trunk, raises ValueError('closed_form requires mu to enter mlp_jet_mv / OMBU (set mu_in_jet_trunk=True)').
• When len(spatial) != 2, raises ValueError('the heat example needs a two-coordinate space_multi_index').
• When cfg.param_order != 1 or any(cfg.space_multi_index), raises NotImplementedError('the finite-difference example supports the first parameter derivative only').

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

Executed regression · g1 fourier heat

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_fourier_heat() -> None:
    ex = worked_example()
    assert ex["abs_sum"] < 1e-8

python -m pytest "packages/omnibias-core/tests/test_parameter_jets.py::test_g1_fourier_heat" -q

Regression example · g3 closed form requires trunk

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_g3_closed_form_requires_trunk() -> None:
    spec = ParameterJetSpec(method="closed_form", mu_in_jet_trunk=False)
    with pytest.raises(ValueError, match="mu_in_jet_trunk"):
        mixed_jet(None, (1.0, 1.0), 1.0, spec=spec)
    ad = ParameterJetSpec(method="autodiff", mu_in_jet_trunk=False)
    assert ad.method != "closed_form"

python -m pytest packages/omnibias-core/tests/test_parameter_jets.py -k test_g3_closed_form_requires_trunk -q

Read the implementation

def mixed_jet(
    field: object | None,
    coords: tuple[float, float],
    parameters: float,
    *,
    spec: ParameterJetSpec | None = None,
    wave: float = 1.0,
) -> float:
    """A supplied scalar jet provider, or the named manufactured heat example.

    Core has no autodiff backend. Use a tensor backend for ``method='autodiff'``;
    the old numerical comparison is explicitly named ``finite_difference``.
    """
    cfg = DEFAULT_SPEC if spec is None else spec
    if cfg.method == "autodiff":
        raise NotImplementedError("core has no autodiff backend; use a tensor mixed_jet or method='finite_difference'")
    if field is not None:
        if cfg.method == "closed_form":
            if not cfg.mu_in_jet_trunk:
                raise ValueError("closed_form requires mu_in_jet_trunk=True")
            if not isinstance(field, ScalarParameterJetProvider):
                raise TypeError("closed_form field must implement mixed_parameter_jet")
            return field.mixed_parameter_jet(coords, parameters, spec=cfg)
        raise TypeError("core finite_difference is the manufactured example; use a tensor callable adapter for a field")
    if cfg.method == "closed_form":
        if not cfg.mu_in_jet_trunk:
            raise ValueError(
                "closed_form requires mu to enter mlp_jet_mv / OMBU "
                "(set mu_in_jet_trunk=True)"
            )
        x, t = coords
        spatial = cfg.space_multi_index or (0, 0)
        if len(spatial) != 2:
            raise ValueError("the heat example needs a two-coordinate space_multi_index")
        kx, kt = spatial
        n = cfg.param_order
        time_factor = sum(
            math.comb(kt, j) * math.factorial(n) / math.factorial(n - j)
            * t ** (n - j) * (-parameters * wave * wave) ** (kt - j)
            for j in range(min(n, kt) + 1)
        )
        return ((-wave * wave) ** n * time_factor * wave ** kx
                * math.exp(-parameters * wave * wave * t)
                * math.sin(wave * x + kx * math.pi / 2))
    if cfg.method == "finite_difference":
        if cfg.param_order != 1 or any(cfg.space_multi_index):
            raise NotImplementedError("the finite-difference example supports the first parameter derivative only")
        x, t = coords
        return _central_fd(lambda mu: fourier_heat(x, t, mu, wave=wave), parameters, 1e-6)
    raise ValueError(f"unknown method {cfg.method!r}")

Related APIsomnibias.core.parameter_jets.fourier_heat↗

FUNCTION

parameter_jet_skill

omnibias.core.parameter_jets.parameter_jet_skillSource ↗

parameter_jet_skill(*, seeds: int=5) -> dict[str, object]

G2: closed-form ∂u/∂μ beats h=1e-3 central FD vs a 4th-order FD.

Parameters

Name	Type & default	Contract
seedskeyword-only	intDefault: 5	See the operation contract and implementation below.

Returnsdict[str, object]

Executed regression · g2 skill

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_skill() -> None:
    report = parameter_jet_skill()
    assert report["g2_earned"] is True
    assert report["beats_fd"] is True

python -m pytest "packages/omnibias-core/tests/test_parameter_jets.py::test_g2_skill" -q

Read the implementation

def parameter_jet_skill(*, seeds: int = 5) -> dict[str, object]:
    """G2: closed-form ``∂u/∂μ`` beats ``h=1e-3`` central FD vs a 4th-order FD."""
    jet_err = 0.0
    fd_err = 0.0
    zero_err = 0.0
    for seed in range(seeds):
        x = 0.3 + 0.1 * float(seed)
        t = 0.5
        mu = 0.8 + 0.05 * float(seed)

        def _u(m: float, xx: float = x, tt: float = t) -> float:
            return fourier_heat(xx, tt, m)

        jet = mixed_jet(None, (x, t), mu)
        ref = _fd4(_u, mu, 1e-4)
        fd = _central_fd(_u, mu, 1e-3)
        jet_err += abs(jet - ref)
        fd_err += abs(fd - ref)
        zero_err += abs(0.0 - ref)
    jet_mae = jet_err / float(seeds)
    fd_mae = fd_err / float(seeds)
    zero_mae = zero_err / float(seeds)
    return {
        "jet_mae": jet_mae,
        "fd_mae": fd_mae,
        "zero_mae": zero_mae,
        "beats_fd": jet_mae < fd_mae,
        "skill_vs_zero": zero_mae - jet_mae,
        "g2_earned": jet_mae < fd_mae and jet_mae < zero_mae,
    }

Related APIsomnibias.core.parameter_jets.fourier_heat↗omnibias.core.parameter_jets.mixed_jet↗

FUNCTION

worked_example

omnibias.core.parameter_jets.worked_exampleSource ↗

worked_example() -> dict[str, float]

G1: k=1, t=1, μ=1, x=π/2 so ∂u/∂μ + u = 0.

Returnsdict[str, float]

Executed regression · g1 fourier heat

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_fourier_heat() -> None:
    ex = worked_example()
    assert ex["abs_sum"] < 1e-8

python -m pytest "packages/omnibias-core/tests/test_parameter_jets.py::test_g1_fourier_heat" -q

Read the implementation

def worked_example() -> dict[str, float]:
    """G1: ``k=1``, ``t=1``, ``μ=1``, ``x=π/2`` so ``∂u/∂μ + u = 0``."""
    x = 0.5 * math.pi
    t = 1.0
    mu = 1.0
    value = fourier_heat(x, t, mu)
    du = mixed_jet(None, (x, t), mu)
    return {
        "u": value,
        "du_dmu": du,
        "abs_sum": abs(du + value),
        "x": x,
        "t": t,
        "mu": mu,
    }

Related APIsomnibias.core.parameter_jets.fourier_heat↗omnibias.core.parameter_jets.mixed_jet↗

← Package overviewRunnable learning examples →