API REFERENCE/omnibias-qcalculus

omnibias.qcalculus.torch

0.1.0a2AlphaPython >=3.10Apache-2.0

q-numbers, Jackson derivatives and integrals, q-series, and the ordinary-calculus limit as q approaches one.

import omnibias.qcalculus.torch

Module contract & mathematical conventions

PyTorch twin of the Jackson q-derivative of an activation.

q_derivative(name, z, q) is the batched Jackson quotient (sigma(qz) - sigma(z)) / ((q-1)z); q_derivative_limit(name, z) is the closed-form first derivative sigma'(z) from the backend fastpath -- the exact q -> 1 limit. Their residual -> 0 as q -> 1 (the **distinct** q-limit, not the delta -> 0 founding collapse). Bit-identical to the JAX twin up to the base activation's libm.

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 →

hybridModule ↗

Imports & aliases

These names share a definition with another public module. Follow a name for its full contract, parameters, and examples.

Import from this module	Canonical reference
QOMBUConfig	omnibias.qcalculus.QOMBUConfig
q_ombu_forward	omnibias.qcalculus.torch.q_ombu_forward

FUNCTION

q_derivative

omnibias.qcalculus.torch.q_derivativeSource ↗

q_derivative(name: str, z: Tensor, q: float) -> Tensor

Batched Jackson q-derivative (sigma(qz) - sigma(z)) / ((q-1)z) (q != 1).

Evaluated away from z = 0; near z = 0 the quotient is ill-conditioned (the true value is sigma'(0), recovered by q_derivative_limit).

Parameters

Name	Type & default	Contract
namepositional-or-keyword	strRequired	See the operation contract and implementation below.
zpositional-or-keyword	TensorRequired	See the operation contract and implementation below.
qpositional-or-keyword	floatRequired	See the operation contract and implementation below.

ReturnsTensor

Explicit validation & failure cases

• When q == 1.0, raises ValueError('q_derivative needs q != 1 (the q -> 1 limit is q_derivative_limit)').

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

Executed regression · jax twin matches torch twin

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_jax_twin_matches_torch_twin() -> None:
    torch = pytest.importorskip("torch")
    jax = pytest.importorskip("jax")
    jax.config.update("jax_enable_x64", True)
    import jax.numpy as jnp
    from omnibias.qcalculus.jax import q_derivative as jq
    from omnibias.qcalculus.torch import q_derivative as tq

    xs = [0.5, 0.9, 1.4, 1.9]
    q = 0.95
    t = tq("sigmoid", torch.tensor(xs, dtype=torch.float64), q).tolist()
    j = jq("sigmoid", jnp.asarray(xs, dtype=jnp.float64), q).tolist()
    for a, b in zip(t, j, strict=False):
        assert a == pytest.approx(b, rel=1e-10, abs=1e-12)

python -m pytest "packages/omnibias-qcalculus/tests/test_package.py::test_jax_twin_matches_torch_twin" -q

Regression example · torch twin q to one collapse

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_torch_twin_q_to_one_collapse() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.qcalculus.torch import q_derivative, q_derivative_limit, q_derivative_residual

    z = torch.linspace(0.5, 2.0, 16, dtype=torch.float64)
    limit = q_derivative_limit("tanh", z)
    prev = float("inf")
    for q in (0.9, 0.99, 0.999):
        res = q_derivative_residual("tanh", z, q).abs().max().item()
        assert res < prev  # monotone collapse toward sigma'
        prev = res
    assert prev < 1e-2
    # q_derivative is the plain Jackson quotient.
    got = q_derivative("tanh", z, 0.999)
    assert got.shape == z.shape and limit.shape == z.shape

python -m pytest packages/omnibias-qcalculus/tests/test_package.py -k test_torch_twin_q_to_one_collapse -q

Read the implementation

def q_derivative(name: str, z: Tensor, q: float) -> Tensor:
    r"""Batched Jackson q-derivative ``(sigma(qz) - sigma(z)) / ((q-1)z)`` (``q != 1``).

    Evaluated away from ``z = 0``; near ``z = 0`` the quotient is ill-conditioned (the true
    value is ``sigma'(0)``, recovered by :func:`q_derivative_limit`).
    """
    if q == 1.0:
        raise ValueError("q_derivative needs q != 1 (the q -> 1 limit is q_derivative_limit)")
    spec = get_activation(name)
    return (spec.forward(q * z) - spec.forward(z)) / ((q - 1.0) * z)

Related APIsomnibias.torch.get_activation↗

FUNCTION

q_derivative_limit

omnibias.qcalculus.torch.q_derivative_limitSource ↗

q_derivative_limit(name: str, z: Tensor) -> Tensor

Closed-form sigma'(z) via the backend fastpath -- the exact q -> 1 limit.

Parameters

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

ReturnsTensor

Explicit validation & failure cases

• When spec.fastpath is None, raises NotImplementedError(f'activation {name!r} has no closed-form derivative kernel').

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

Executed regression · torch twin q to one collapse

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_torch_twin_q_to_one_collapse() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.qcalculus.torch import q_derivative, q_derivative_limit, q_derivative_residual

    z = torch.linspace(0.5, 2.0, 16, dtype=torch.float64)
    limit = q_derivative_limit("tanh", z)
    prev = float("inf")
    for q in (0.9, 0.99, 0.999):
        res = q_derivative_residual("tanh", z, q).abs().max().item()
        assert res < prev  # monotone collapse toward sigma'
        prev = res
    assert prev < 1e-2
    # q_derivative is the plain Jackson quotient.
    got = q_derivative("tanh", z, 0.999)
    assert got.shape == z.shape and limit.shape == z.shape

python -m pytest "packages/omnibias-qcalculus/tests/test_package.py::test_torch_twin_q_to_one_collapse" -q

Read the implementation

def q_derivative_limit(name: str, z: Tensor) -> Tensor:
    r"""Closed-form ``sigma'(z)`` via the backend fastpath -- the exact ``q -> 1`` limit."""
    spec = get_activation(name)
    if spec.fastpath is None:
        raise NotImplementedError(f"activation {name!r} has no closed-form derivative kernel")
    out: Tensor = spec.fastpath(z, 1)
    return out

Related APIsomnibias.torch.get_activation↗

FUNCTION

q_derivative_residual

omnibias.qcalculus.torch.q_derivative_residualSource ↗

q_derivative_residual(name: str, z: Tensor, q: float) -> Tensor

q_derivative - q_derivative_limit; -> 0 as q -> 1.

Parameters

Name	Type & default	Contract
namepositional-or-keyword	strRequired	See the operation contract and implementation below.
zpositional-or-keyword	TensorRequired	See the operation contract and implementation below.
qpositional-or-keyword	floatRequired	See the operation contract and implementation below.

ReturnsTensor

Executed regression · torch twin q to one collapse

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_torch_twin_q_to_one_collapse() -> None:
    torch = pytest.importorskip("torch")
    from omnibias.qcalculus.torch import q_derivative, q_derivative_limit, q_derivative_residual

    z = torch.linspace(0.5, 2.0, 16, dtype=torch.float64)
    limit = q_derivative_limit("tanh", z)
    prev = float("inf")
    for q in (0.9, 0.99, 0.999):
        res = q_derivative_residual("tanh", z, q).abs().max().item()
        assert res < prev  # monotone collapse toward sigma'
        prev = res
    assert prev < 1e-2
    # q_derivative is the plain Jackson quotient.
    got = q_derivative("tanh", z, 0.999)
    assert got.shape == z.shape and limit.shape == z.shape

python -m pytest "packages/omnibias-qcalculus/tests/test_package.py::test_torch_twin_q_to_one_collapse" -q

Read the implementation

def q_derivative_residual(name: str, z: Tensor, q: float) -> Tensor:
    r"""``q_derivative - q_derivative_limit``; ``-> 0`` as ``q -> 1``."""
    return q_derivative(name, z, q) - q_derivative_limit(name, z)

Related APIsomnibias.qcalculus.torch.q_derivative↗omnibias.qcalculus.torch.q_derivative_limit↗

← Package overviewRunnable learning examples →