API REFERENCE/omnibias-fields

omnibias.fields.jax.ops.integral

0.2.0rc1Release candidatePython >=3.10Apache-2.0

Structured scalar, vector, and tensor fields with derivative caches, calculus operators, and coordinate conventions.

import omnibias.fields.jax.ops.integral

Module contract & mathematical conventions

Definite integration of a field component over a box domain (jax).

Bit-identical twin of omnibias.fields.torch.ops.integral.

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

integrate

omnibias.fields.jax.ops.integrateSource ↗

integrate(state: FieldState, name: str, *, rule: QuadratureSpec) -> Array

Definite integral \int_\Omega u\,dx via the quadrature rule.

state must have been evaluated at rule's nodes.

Parameters

Name	Type & default	Contract
statepositional-or-keyword	FieldStateRequired	See the operation contract and implementation below.
namepositional-or-keyword	strRequired	See the operation contract and implementation below.
rulekeyword-only	QuadratureSpecRequired	See the operation contract and implementation below.

ReturnsArray

Explicit validation & failure cases

• When vals.shape[0] != rule.n_nodes, raises ValueError(f'integrate: state has {vals.shape[0]} points but rule has {rule.n_nodes} nodes; evaluate the field at quadrature_nodes(rule)').

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

Executed regression · integrate cross backend

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_integrate_cross_backend(make_torch_field, make_jax_field):  # type: ignore[no-untyped-def]
    rule = _rule()
    tf, jf = make_torch_field(), make_jax_field()
    ts = tf(torch.as_tensor(rule.nodes, dtype=torch.float64))
    js = jf(jnp.asarray(rule.nodes, dtype=jnp.float64))
    for name in ("u", "v"):
        t = _np(ts[name].integrate(rule=rule))
        j = _np(js[name].integrate(rule=rule))
        assert np.allclose(t, j, rtol=1e-12, atol=1e-12), name

python -m pytest "packages/omnibias-fields/tests/test_integration_norms.py::test_integrate_cross_backend" -q

Read the implementation

def integrate(state: FieldState, name: str, *, rule: QuadratureSpec) -> Array:
    r"""Definite integral :math:`\int_\Omega u\,dx` via the quadrature ``rule``.

    ``state`` must have been evaluated at ``rule``'s nodes.
    """
    vals = value(state, name)
    if vals.shape[0] != rule.n_nodes:
        raise ValueError(
            f"integrate: state has {vals.shape[0]} points but rule has "
            f"{rule.n_nodes} nodes; evaluate the field at quadrature_nodes(rule)"
        )
    w = _weights(rule, vals)
    return jnp.tensordot(w, vals, axes=([0], [0]))

Related APIsomnibias.fields.jax.ops.value↗

Other public import paths

• omnibias.fields.jax.ops.integrate
• omnibias.fields.jax.ops.integral.integrate

FUNCTION

line_integral

omnibias.fields.jax.ops.line_integralSource ↗

line_integral(state: FieldState, name: str, curve: Callable[[Array], Array], *, rule: QuadratureSpec) -> Array

Gradient-theorem line integral \int_C \nabla u \cdot d\mathbf r.

mathematically equivalent twin of omnibias.fields.torch.ops.integral.line_integral; see that docstring for the full contract. Evaluates \int_{t_0}^{t_1} \nabla u(r(t))\cdot r'(t)\,dt, which by the gradient theorem equals u(r(t_1)) - u(r(t_0)). state must hold name evaluated at curve(quadrature_nodes(rule)); the gradient is closed form, the tangent is exact autodiff, and the integral is Gauss-Legendre quadrature.

Backend scope: this identifies the corresponding mathematical construction. It does not guarantee bitwise-equal floating-point results across devices, compilers, dtypes, or backend versions. Validate the selected path with an appropriate absolute and relative tolerance.

Parameters

Name	Type & default	Contract
statepositional-or-keyword	FieldStateRequired	See the operation contract and implementation below.
namepositional-or-keyword	strRequired	See the operation contract and implementation below.
curvepositional-or-keyword	Callable[[Array], Array]Required	See the operation contract and implementation below.
rulekeyword-only	QuadratureSpecRequired	See the operation contract and implementation below.

ReturnsArray

Explicit validation & failure cases

• When g.shape[0] != rule.n_nodes, raises ValueError(f'line_integral: state has {g.shape[0]} points but rule has {rule.n_nodes} nodes; evaluate the field at curve(quadrature_nodes(rule))').
• When x.shape[-1] != 1, raises ValueError(f'line_integral requires a 1-D parameter rule (a curve); got a {x.shape[-1]}-D rule').
• When tangent.shape[-1] != g.shape[-1], raises ValueError(f"line_integral: curve maps to {tangent.shape[-1]} ambient dims but the field gradient spans {g.shape[-1]}; the curve must land in the field's gradient axes").

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

Executed regression · gradient theorem jax

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_gradient_theorem_jax(make_jax_field):  # type: ignore[no-untyped-def]
    field = make_jax_field()
    curve = _jax_linear(_P0, _P1)
    rule = gauss_legendre([(0.0, 1.0)], 8)
    state = _jax_curve_points(field, curve, rule)
    got = float(_np(state.u.line_integral(curve, rule=rule)))
    exp = _endpoint_difference(field, _P0, _P1, "jax")
    assert np.isclose(got, exp, rtol=1e-12, atol=1e-12)

python -m pytest "packages/omnibias-fields/tests/test_line_integral.py::test_gradient_theorem_jax" -q

Read the implementation

def line_integral(
    state: FieldState,
    name: str,
    curve: Callable[[Array], Array],
    *,
    rule: QuadratureSpec,
) -> Array:
    r"""Gradient-theorem line integral :math:`\int_C \nabla u \cdot d\mathbf r`.

    Bit-identical twin of :func:`omnibias.fields.torch.ops.integral.line_integral`;
    see that docstring for the full contract. Evaluates
    :math:`\int_{t_0}^{t_1} \nabla u(r(t))\cdot r'(t)\,dt`, which by the gradient
    theorem equals ``u(r(t_1)) - u(r(t_0))``. ``state`` must hold ``name``
    evaluated at ``curve(quadrature_nodes(rule))``; the gradient is closed form,
    the tangent is exact autodiff, and the integral is Gauss-Legendre quadrature.
    """
    g = gradient(state, name)  # (Q, dim)
    if g.shape[0] != rule.n_nodes:
        raise ValueError(
            f"line_integral: state has {g.shape[0]} points but rule has "
            f"{rule.n_nodes} nodes; evaluate the field at "
            "curve(quadrature_nodes(rule))"
        )
    x = quadrature_nodes(rule, like=g)  # (Q, param_dim) parameter nodes
    if x.shape[-1] != 1:
        raise ValueError(
            "line_integral requires a 1-D parameter rule (a curve); got a "
            f"{x.shape[-1]}-D rule"
        )
    tangent = _tangent(curve, x)  # (Q, dim)
    if tangent.shape[-1] != g.shape[-1]:
        raise ValueError(
            f"line_integral: curve maps to {tangent.shape[-1]} ambient dims but "
            f"the field gradient spans {g.shape[-1]}; the curve must land in the "
            "field's gradient axes"
        )
    integrand = (g * tangent).sum(axis=-1)  # (Q,)
    w = _weights(rule, integrand)
    return jnp.tensordot(w, integrand, axes=([0], [0]))

Related APIsomnibias.fields.jax.ops.gradient↗omnibias.fields.jax.ops.quadrature_nodes↗

Other public import paths

• omnibias.fields.jax.ops.line_integral
• omnibias.fields.jax.ops.integral.line_integral

FUNCTION

quadrature_nodes

omnibias.fields.jax.ops.quadrature_nodesSource ↗

quadrature_nodes(rule: QuadratureSpec, *, like: Array) -> Array

Return the rule's nodes as a (n_nodes, dim) array matching like.

Parameters

Name	Type & default	Contract
rulepositional-or-keyword	QuadratureSpecRequired	See the operation contract and implementation below.
likekeyword-only	ArrayRequired	See the operation contract and implementation below.

ReturnsArray

Executed regression · gradient theorem jax

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_gradient_theorem_jax(make_jax_field):  # type: ignore[no-untyped-def]
    field = make_jax_field()
    curve = _jax_linear(_P0, _P1)
    rule = gauss_legendre([(0.0, 1.0)], 8)
    state = _jax_curve_points(field, curve, rule)
    got = float(_np(state.u.line_integral(curve, rule=rule)))
    exp = _endpoint_difference(field, _P0, _P1, "jax")
    assert np.isclose(got, exp, rtol=1e-12, atol=1e-12)

python -m pytest "packages/omnibias-fields/tests/test_line_integral.py::test_gradient_theorem_jax" -q

Read the implementation

def quadrature_nodes(rule: QuadratureSpec, *, like: Array) -> Array:
    """Return the rule's nodes as a ``(n_nodes, dim)`` array matching ``like``."""
    return jnp.asarray(rule.nodes, dtype=like.dtype)

Other public import paths

• omnibias.fields.jax.ops.quadrature_nodes
• omnibias.fields.jax.ops.integral.quadrature_nodes

← Package overviewRunnable learning examples →