omnibias.qcalculus
q-numbers, Jackson derivatives and integrals, q-series, and the ordinary-calculus limit as q approaches one.
import omnibias.qcalculusUse qcalculus for multiplicative q-shifts and q-deformed algebra. Its q approaching one limit is different from the additive bias-gap limit in difference and the temperature-hardening limit in decision models. Keep those parameters and their normalizations separate.
Check the accepted q domain, singular cases, truncation count, and convergence assumptions for each q-series or integral. Some formulas have removable limits that require a dedicated stable path; substituting q=1 directly into a quotient can be undefined. A certified geometric tail applies only when its stated convergence condition holds.
For Torch and JAX wrappers, verify dtype, gradient support, and how the ordinary-derivative limit is obtained. A mathematically exact symbolic coefficient and a truncated floating-point series have different accuracy contracts.
Module contract & mathematical conventions
omnibias-qcalculus: quantum / q-calculus on the omnibias tower.
Exact q-combinatorics ([n]_q, [n]_q!, Gaussian binomial, (a;q)_n), the Jackson
q-derivative / q-integral, the two q-exponentials, q-deformed Bernoulli / Euler numbers,
and basic hypergeometric series _r phi_s with certified geometric tails.
The **q -> 1 limit** recovers ordinary calculus ([n]_q -> n, D_q f -> f'). This
is a **distinct** limit from the delta -> 0 founding bias-collapse of
omnibias.difference and the beta -> inf **temperature collapse** feasibility penalty elsewhere -- same
spirit, different parameter, never conflated.
Backend twins (omnibias.qcalculus.torch, omnibias.qcalculus.jax) provide the
algebraically corresponding Jackson q-derivative of the activation dictionary; import them explicitly.
important:
**Bit-parity with the PyTorch twin requires 64-bit JAX** -- jax.config.update("jax_enable_x64", True) before the first JAX array is created (or JAX_ENABLE_X64=1). JAX otherwise truncates to float32 while PyTorch uses float64, so the twins stay internally consistent but agree only to float32 tolerance. Where a value feeds a threshold, a rounding step or an argmax, that is enough to change the decision rather than just the last digits. See omnibias.jax.precision.
Numerical scope: shared coefficients and formulas do not establish universal floating-point identity across backends, devices, compiler transforms, or reduction orders. Compare the chosen path with dtype-appropriate tolerances; even float64 is not a general bitwise-equality guarantee. Algebraic initialization identities likewise need a numerical check for the selected coefficients and reduction order.
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.
QOMBUConfig
omnibias.qcalculus.QOMBUConfigSource ↗class QOMBUConfigDataclass 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.
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 |
|---|---|---|
qdataclass field | floatDefault: 1.01 | See the operation contract and implementation below. |
n_q_layersdataclass field | intDefault: 1 | See the operation contract and implementation below. |
n_sigma_layersdataclass field | intDefault: 1 | See the operation contract and implementation below. |
Regression example · q one uses limit
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.
def test_q_one_uses_limit() -> None:
with pytest.raises(ValueError, match="named limit"):
q_ombu_forward(2.0, config=QOMBUConfig(q=1.0))
assert q_ombu_limit(2.0) == 4.0python -m pytest packages/omnibias-qcalculus/tests/test_hybrid.py -k test_q_one_uses_limit -qFields & methods
n_q_layersfield
n_q_layers: int = 1Declared int field on QOMBUConfig. Default expression: 1.
n_sigma_layersfield
n_sigma_layers: int = 1Declared int field on QOMBUConfig. Default expression: 1.
Read the implementation
class QOMBUConfig:
q: float = 1.01
n_q_layers: int = 1
n_sigma_layers: int = 1Other public import paths
omnibias.qcalculus.QOMBUConfigomnibias.qcalculus.jax.QOMBUConfigomnibias.qcalculus.torch.QOMBUConfigomnibias.qcalculus.jax.hybrid.QOMBUConfigomnibias.qcalculus.torch.hybrid.QOMBUConfig
q_ombu_forward
omnibias.qcalculus.q_ombu_forwardSource ↗q_ombu_forward(x: float, params: Sequence[float] | None=None, *, config: QOMBUConfig | None=None, f: Callable[[float], float] | None=None, fprime: Callable[[float], float] | None=None) -> tuple[float, float]Returns (y, limit_residual). y is D_q of the source.
Parameters
| Name | Type & default | Contract |
|---|---|---|
xpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
paramspositional-or-keyword | Sequence[float] | NoneDefault: None | See the operation contract and implementation below. |
configkeyword-only | QOMBUConfig | NoneDefault: None | See the operation contract and implementation below. |
fkeyword-only | Callable[[float], float] | NoneDefault: None | See the operation contract and implementation below. |
fprimekeyword-only | Callable[[float], float] | NoneDefault: None | See the operation contract and implementation below. |
tuple[float, float]Explicit validation & failure cases
- When
cfg.q == 1.0, raisesValueError('q == 1 is the named limit; use q_ombu_limit'). - When
cfg.n_q_layers < 1, raisesValueError(f'n_q_layers must be >= 1, got {cfg.n_q_layers}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · g2 monotone q limit
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.
def test_g2_monotone_q_limit() -> None:
report = q_limit_skill()
assert report["monotone"] is True
assert report["g2_earned"] is Truepython -m pytest "packages/omnibias-qcalculus/tests/test_hybrid.py::test_g2_monotone_q_limit" -qRegression example · q one uses limit
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.
def test_q_one_uses_limit() -> None:
with pytest.raises(ValueError, match="named limit"):
q_ombu_forward(2.0, config=QOMBUConfig(q=1.0))
assert q_ombu_limit(2.0) == 4.0python -m pytest packages/omnibias-qcalculus/tests/test_hybrid.py -k test_q_one_uses_limit -qRead the implementation
def q_ombu_forward(
x: float,
params: Sequence[float] | None = None,
*,
config: QOMBUConfig | None = None,
f: Callable[[float], float] | None = None,
fprime: Callable[[float], float] | None = None,
) -> tuple[float, float]:
"""Returns ``(y, limit_residual)``. ``y`` is ``D_q`` of the source."""
cfg = DEFAULT_CONFIG if config is None else config
if cfg.q == 1.0:
raise ValueError("q == 1 is the named limit; use q_ombu_limit")
if cfg.n_q_layers < 1:
raise ValueError(f"n_q_layers must be >= 1, got {cfg.n_q_layers}")
func = _square if f is None else f
y = q_derivative(func, x, cfg.q)
_ = (params, cfg.n_sigma_layers)
residual = y - q_ombu_limit(x, config=cfg, fprime=fprime)
return y, residualq_ombu_limit
omnibias.qcalculus.q_ombu_limitSource ↗q_ombu_limit(x: float, params: Sequence[float] | None=None, *, config: QOMBUConfig | None=None, fprime: Callable[[float], float] | None=None) -> floatOrdinary derivative of the source. The named q -> 1 limit.
Parameters
| Name | Type & default | Contract |
|---|---|---|
xpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
paramspositional-or-keyword | Sequence[float] | NoneDefault: None | See the operation contract and implementation below. |
configkeyword-only | QOMBUConfig | NoneDefault: None | See the operation contract and implementation below. |
fprimekeyword-only | Callable[[float], float] | NoneDefault: None | See the operation contract and implementation below. |
floatExecuted regression · g2 monotone q limit
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.
def test_g2_monotone_q_limit() -> None:
report = q_limit_skill()
assert report["monotone"] is True
assert report["g2_earned"] is Truepython -m pytest "packages/omnibias-qcalculus/tests/test_hybrid.py::test_g2_monotone_q_limit" -qRegression example · q one uses limit
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.
def test_q_one_uses_limit() -> None:
with pytest.raises(ValueError, match="named limit"):
q_ombu_forward(2.0, config=QOMBUConfig(q=1.0))
assert q_ombu_limit(2.0) == 4.0python -m pytest packages/omnibias-qcalculus/tests/test_hybrid.py -k test_q_one_uses_limit -qRead the implementation
def q_ombu_limit(
x: float,
params: Sequence[float] | None = None,
*,
config: QOMBUConfig | None = None,
fprime: Callable[[float], float] | None = None,
) -> float:
"""Ordinary derivative of the source. The named ``q -> 1`` limit."""
del params, config
if fprime is None:
return 2.0 * x
return float(fprime(x))q_antiderivative_poly
omnibias.qcalculus.q_antiderivative_polySource ↗q_antiderivative_poly(coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]Exact q-antiderivative of sum_i c_i x^i: \int x^i d_q x = x^{i+1}/[i+1]_q.
Returns the ascending coefficients (constant term 0); the exact inverse of
q_derivative_poly up to the integration constant.
Parameters
| Name | Type & default | Contract |
|---|---|---|
coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · antiderivative is left inverse of derivative
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.
def test_antiderivative_is_left_inverse_of_derivative() -> None:
q = Fraction(1, 3)
coeffs = [Fraction(1), Fraction(2), Fraction(3), Fraction(4)]
back = q_derivative_poly(q_antiderivative_poly(coeffs, q), q)
assert tuple(back) == tuple(Fraction(c) for c in coeffs)python -m pytest "packages/omnibias-qcalculus/tests/test_qderiv.py::test_antiderivative_is_left_inverse_of_derivative" -qRead the implementation
def q_antiderivative_poly(coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]:
r"""Exact q-antiderivative of ``sum_i c_i x^i``: ``\int x^i d_q x = x^{i+1}/[i+1]_q``.
Returns the ascending coefficients (constant term ``0``); the exact inverse of
:func:`q_derivative_poly` up to the integration constant.
"""
c = [_frac(v) for v in coeffs]
out = [Fraction(0)]
for i, ci in enumerate(c):
out.append(ci / q_bracket(i + 1, q))
return tuple(out)q_derivative
omnibias.qcalculus.q_derivativeSource ↗q_derivative(f: Callable[[float], float], x: float, q: float) -> floatNumerical Jackson q-derivative (f(qx) - f(x)) / ((q-1)x) (x != 0, q != 1).
At x = 0 the q-derivative is the ordinary f'(0), which a difference quotient
cannot form from one sample -- pass a non-zero x (or use the polynomial operator).
Parameters
| Name | Type & default | Contract |
|---|---|---|
fpositional-or-keyword | Callable[[float], float]Required | See the operation contract and implementation below. |
xpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
qpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
floatExplicit validation & failure cases
- When
q == 1.0, raisesValueError('q_derivative needs q != 1 (the q -> 1 limit is the ordinary derivative)'). - When
x == 0.0, raisesValueError('numerical q_derivative is undefined at x = 0; use q_derivative_poly').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · g2 monotone q limit
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.
def test_g2_monotone_q_limit() -> None:
report = q_limit_skill()
assert report["monotone"] is True
assert report["g2_earned"] is Truepython -m pytest "packages/omnibias-qcalculus/tests/test_hybrid.py::test_g2_monotone_q_limit" -qRegression example · errors
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.
def test_errors() -> None:
with pytest.raises(ValueError):
q_derivative(lambda x: x, 1.0, 1.0) # q == 1
with pytest.raises(ValueError):
q_derivative(lambda x: x, 0.0, 0.5) # x == 0
with pytest.raises(ValueError):
q_integral(lambda x: x, 0.0, 1.0, 1.5) # q not in (0, 1)python -m pytest packages/omnibias-qcalculus/tests/test_qderiv.py -k test_errors -qRead the implementation
def q_derivative(f: Callable[[float], float], x: float, q: float) -> float:
r"""Numerical Jackson q-derivative ``(f(qx) - f(x)) / ((q-1)x)`` (``x != 0``, ``q != 1``).
At ``x = 0`` the q-derivative is the ordinary ``f'(0)``, which a difference quotient
cannot form from one sample -- pass a non-zero ``x`` (or use the polynomial operator).
"""
if q == 1.0:
raise ValueError("q_derivative needs q != 1 (the q -> 1 limit is the ordinary derivative)")
if x == 0.0:
raise ValueError("numerical q_derivative is undefined at x = 0; use q_derivative_poly")
return (f(q * x) - f(x)) / ((q - 1.0) * x)q_derivative_poly
omnibias.qcalculus.q_derivative_polySource ↗q_derivative_poly(coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]Exact q-derivative of a polynomial sum_i c_i x^i: D_q x^i = [i]_q x^{i-1}.
Returns the ascending coefficients of the degree-lowered polynomial (empty for a constant). Exact rational arithmetic.
Parameters
| Name | Type & default | Contract |
|---|---|---|
coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q pincherle reduces to classical
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.
def test_q_pincherle_reduces_to_classical() -> None:
assert q_pincherle_derivative(_F, ONE) == pincherle_derivative(_F)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_pincherle_reduces_to_classical" -qRegression example · q delta operator of t is q derivative
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.
def test_q_delta_operator_of_t_is_q_derivative(q: Fraction) -> None:
poly = (Fraction(2), Fraction(-1), Fraction(3), Fraction(1), Fraction(-2))
assert _same_poly(q_delta_operator_apply((0, 1), poly, q), q_derivative_poly(poly, q))python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_delta_operator_of_t_is_q_derivative -qRead the implementation
def q_derivative_poly(coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]:
r"""Exact q-derivative of a polynomial ``sum_i c_i x^i``: ``D_q x^i = [i]_q x^{i-1}``.
Returns the ascending coefficients of the degree-lowered polynomial (empty for a
constant). Exact rational arithmetic.
"""
c = [_frac(v) for v in coeffs]
if len(c) <= 1:
return ()
return tuple(c[i] * q_bracket(i, q) for i in range(1, len(c)))q_integral
omnibias.qcalculus.q_integralSource ↗q_integral(f: Callable[[float], float], a: float, b: float, q: float, *, terms: int=200) -> floatNumerical Jackson q-integral \int_a^b f(x) d_q x for 0 < q < 1.
Uses \int_0^c f d_q x = (1 - q) c sum_{k>=0} q^k f(c q^k) (a geometric point set
c q^k -> 0) and \int_a^b = \int_0^b - \int_0^a. terms truncates the sum;
for a bounded f the omitted tail is O(q^{terms}).
Parameters
| Name | Type & default | Contract |
|---|---|---|
fpositional-or-keyword | Callable[[float], float]Required | See the operation contract and implementation below. |
apositional-or-keyword | floatRequired | See the operation contract and implementation below. |
bpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
qpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
termskeyword-only | intDefault: 200 | See the operation contract and implementation below. |
floatExplicit validation & failure cases
- When
not 0.0 < q < 1.0, raisesValueError(f'numerical q_integral needs 0 < q < 1, got q={q}'). - When
terms < 1, raisesValueError(f'terms must be >= 1, got {terms}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q integral of monomial
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.
def test_q_integral_of_monomial() -> None:
# int_0^1 x^n d_q x = 1 / [n+1]_q.
q = 0.5
for n in range(5):
got = q_integral(lambda x, n=n: x**n, 0.0, 1.0, q, terms=400)
expected = 1.0 / float(q_bracket(n + 1, Fraction(1, 2)))
assert got == pytest.approx(expected, rel=1e-9)python -m pytest "packages/omnibias-qcalculus/tests/test_qderiv.py::test_q_integral_of_monomial" -qRegression example · errors
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.
def test_errors() -> None:
with pytest.raises(ValueError):
q_derivative(lambda x: x, 1.0, 1.0) # q == 1
with pytest.raises(ValueError):
q_derivative(lambda x: x, 0.0, 0.5) # x == 0
with pytest.raises(ValueError):
q_integral(lambda x: x, 0.0, 1.0, 1.5) # q not in (0, 1)python -m pytest packages/omnibias-qcalculus/tests/test_qderiv.py -k test_errors -qRead the implementation
def q_integral(
f: Callable[[float], float], a: float, b: float, q: float, *, terms: int = 200
) -> float:
r"""Numerical Jackson q-integral ``\int_a^b f(x) d_q x`` for ``0 < q < 1``.
Uses ``\int_0^c f d_q x = (1 - q) c sum_{k>=0} q^k f(c q^k)`` (a geometric point set
``c q^k -> 0``) and ``\int_a^b = \int_0^b - \int_0^a``. ``terms`` truncates the sum;
for a bounded ``f`` the omitted tail is ``O(q^{terms})``.
"""
if not 0.0 < q < 1.0:
raise ValueError(f"numerical q_integral needs 0 < q < 1, got q={q}")
if terms < 1:
raise ValueError(f"terms must be >= 1, got {terms}")
def jackson_0(c: float) -> float:
if c == 0.0:
return 0.0
total = 0.0
power = 1.0 # q^k
for _ in range(terms):
total += power * f(c * power)
power *= q
return (1.0 - q) * c * total
return jackson_0(b) - jackson_0(a)basic_hypergeometric
omnibias.qcalculus.basic_hypergeometricSource ↗basic_hypergeometric(a: Sequence[float], b: Sequence[float], q: float, z: float, *, terms: int=64) -> floatNumerical _r phi_s by direct truncated summation (the baseline).
Parameters
| Name | Type & default | Contract |
|---|---|---|
apositional-or-keyword | Sequence[float]Required | See the operation contract and implementation below. |
bpositional-or-keyword | Sequence[float]Required | See the operation contract and implementation below. |
qpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
zpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
termskeyword-only | intDefault: 64 | See the operation contract and implementation below. |
floatExplicit validation & failure cases
- When
not 0.0 < q < 1.0, raisesValueError(f'basic_hypergeometric needs 0 < q < 1, got q={q}'). - When
terms < 1, raisesValueError(f'terms must be >= 1, got {terms}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · e q as 1phi0
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.
def test_e_q_as_1phi0() -> None:
# e_q(z) = _1phi_0(0; ; q, (1-q) z).
for q in (0.3, 0.5, 0.7):
for z in (0.2, 0.5, 1.0):
viaphi = basic_hypergeometric([0.0], [], q, (1 - q) * z, terms=120)
assert viaphi == pytest.approx(q_exp(z, q), rel=1e-9, abs=1e-12)python -m pytest "packages/omnibias-qcalculus/tests/test_qhyper.py::test_e_q_as_1phi0" -qRegression example · enclosure contains float baseline
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.
def test_enclosure_contains_float_baseline() -> None:
a = [Fraction(1, 4)]
b = [Fraction(3, 5)]
q, z = Fraction(1, 2), Fraction(1, 10)
iv = basic_hypergeometric_enclosure(a, b, q, z, terms=40)
base = basic_hypergeometric([0.25], [0.6], 0.5, 0.1, terms=200)
assert iv.lo <= base <= iv.hipython -m pytest packages/omnibias-qcalculus/tests/test_qhyper.py -k test_enclosure_contains_float_baseline -qRead the implementation
def basic_hypergeometric(
a: Sequence[float],
b: Sequence[float],
q: float,
z: float,
*,
terms: int = 64,
) -> float:
r"""Numerical ``_r phi_s`` by direct truncated summation (the baseline)."""
if not 0.0 < q < 1.0:
raise ValueError(f"basic_hypergeometric needs 0 < q < 1, got q={q}")
if terms < 1:
raise ValueError(f"terms must be >= 1, got {terms}")
exponent = 1 + len(b) - len(a)
total = 0.0
for n in range(terms):
num = 1.0
for ai in a:
num *= _poch_float(ai, q, n)
den = 1.0
for bj in b:
den *= _poch_float(bj, q, n)
den *= _poch_float(q, q, n) # (q; q)_n
sign_pow = ((-1.0) ** n * q ** (n * (n - 1) / 2.0)) ** exponent
total += (num / den) * sign_pow * z**n
return totalbasic_hypergeometric_enclosure
omnibias.qcalculus.basic_hypergeometric_enclosureSource ↗basic_hypergeometric_enclosure(a: Sequence[Rational], b: Sequence[Rational], q: Rational, z: Rational, *, terms: int=32) -> IntervalCertified Interval enclosure of _r phi_s (0 < q < 1, r <= s+1).
Sums terms exact-rational retained terms and majorises the omitted tail by a
rigorous geometric bound on the consecutive term ratio. Raises ValueError if the
ratio cannot be certified < 1 at this truncation (raise terms and retry) or if
the parameters place the series outside the convergent regime.
Parameters
| Name | Type & default | Contract |
|---|---|---|
apositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
bpositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
zpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
termskeyword-only | intDefault: 32 | See the operation contract and implementation below. |
IntervalExplicit validation & failure cases
- When
not 0 < qf < 1, raisesValueError(f'enclosure needs 0 < q < 1, got q={qf}'). - When
terms < 1, raisesValueError(f'terms must be >= 1, got {terms}'). - When
exponent < 0, raisesValueError(f'r <= s+1 required for a convergent enclosure (r={len(af)}, s={len(bf)})'). - When
not ratio < 1, raisesValueError(f'could not certify ratio < 1 at terms={terms} (got {float(ratio):.4g}); increase terms').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · divergent regime raises
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.
def test_divergent_regime_raises() -> None:
# r > s + 1 (here r = 2, s = 0) is not enclosable: must refuse, not fake a bound.
with pytest.raises(ValueError):
basic_hypergeometric_enclosure([Fraction(1, 5), Fraction(1, 4)], [], Fraction(1, 2), Fraction(1, 10))python -m pytest "packages/omnibias-qcalculus/tests/test_qhyper.py::test_divergent_regime_raises" -qRegression example · enclosure contains float baseline
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.
def test_enclosure_contains_float_baseline() -> None:
a = [Fraction(1, 4)]
b = [Fraction(3, 5)]
q, z = Fraction(1, 2), Fraction(1, 10)
iv = basic_hypergeometric_enclosure(a, b, q, z, terms=40)
base = basic_hypergeometric([0.25], [0.6], 0.5, 0.1, terms=200)
assert iv.lo <= base <= iv.hipython -m pytest packages/omnibias-qcalculus/tests/test_qhyper.py -k test_enclosure_contains_float_baseline -qRead the implementation
def basic_hypergeometric_enclosure(
a: Sequence[Rational],
b: Sequence[Rational],
q: Rational,
z: Rational,
*,
terms: int = 32,
) -> Interval:
r"""Certified :class:`Interval` enclosure of ``_r phi_s`` (``0 < q < 1``, ``r <= s+1``).
Sums ``terms`` exact-rational retained terms and majorises the omitted tail by a
rigorous geometric bound on the consecutive term ratio. Raises ``ValueError`` if the
ratio cannot be certified ``< 1`` at this truncation (raise ``terms`` and retry) or if
the parameters place the series outside the convergent regime.
"""
af = [_frac(x) for x in a]
bf = [_frac(x) for x in b]
qf, zf = _frac(q), _frac(z)
if not 0 < qf < 1:
raise ValueError(f"enclosure needs 0 < q < 1, got q={qf}")
if terms < 1:
raise ValueError(f"terms must be >= 1, got {terms}")
exponent = 1 + len(bf) - len(af)
if exponent < 0:
raise ValueError(
f"r <= s+1 required for a convergent enclosure (r={len(af)}, s={len(bf)})"
)
ratio = _ratio_bound(af, bf, qf, zf, exponent, terms)
if not ratio < 1:
raise ValueError(
f"could not certify ratio < 1 at terms={terms} (got {float(ratio):.4g}); "
"increase terms"
)
def term(k: int) -> Interval:
return Interval.from_rational(_term_exact(af, bf, qf, zf, exponent, k))
return certified_ratio_series_sum(term, ratio, num_terms=terms)q_exp_enclosure
omnibias.qcalculus.q_exp_enclosureSource ↗q_exp_enclosure(z: Rational, q: Rational, *, terms: int=32) -> IntervalCertified Interval enclosure of e_q(z) = sum_n z^n / [n]_q!.
Exact retained terms with a geometric tail bounded by |z| / [terms]_q (the q-number
[n+1]_q is increasing, so |t_{n+1}/t_n| = |z|/[n+1]_q <= |z|/[terms]_q).
Parameters
| Name | Type & default | Contract |
|---|---|---|
zpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
termskeyword-only | intDefault: 32 | See the operation contract and implementation below. |
IntervalExplicit validation & failure cases
- When
not 0 < qf < 1, raisesValueError(f'q_exp_enclosure needs 0 < q < 1, got q={qf}'). - When
terms < 1, raisesValueError(f'terms must be >= 1, got {terms}'). - When
not ratio < 1, raisesValueError(f'could not certify ratio < 1 at terms={terms} (got {float(ratio):.4g}); increase terms').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · uncertifiable ratio raises
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.
def test_uncertifiable_ratio_raises() -> None:
# |z| too large for the retained-term count -> ratio not provably < 1.
with pytest.raises(ValueError):
q_exp_enclosure(Fraction(5), Fraction(1, 2), terms=2)python -m pytest "packages/omnibias-qcalculus/tests/test_qhyper.py::test_uncertifiable_ratio_raises" -qRegression example · enclosure contains float baseline
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.
def test_enclosure_contains_float_baseline() -> None:
a = [Fraction(1, 4)]
b = [Fraction(3, 5)]
q, z = Fraction(1, 2), Fraction(1, 10)
iv = basic_hypergeometric_enclosure(a, b, q, z, terms=40)
base = basic_hypergeometric([0.25], [0.6], 0.5, 0.1, terms=200)
assert iv.lo <= base <= iv.hipython -m pytest packages/omnibias-qcalculus/tests/test_qhyper.py -k test_enclosure_contains_float_baseline -qRead the implementation
def q_exp_enclosure(z: Rational, q: Rational, *, terms: int = 32) -> Interval:
r"""Certified :class:`Interval` enclosure of ``e_q(z) = sum_n z^n / [n]_q!``.
Exact retained terms with a geometric tail bounded by ``|z| / [terms]_q`` (the q-number
``[n+1]_q`` is increasing, so ``|t_{n+1}/t_n| = |z|/[n+1]_q <= |z|/[terms]_q``).
"""
zf, qf = _frac(z), _frac(q)
if not 0 < qf < 1:
raise ValueError(f"q_exp_enclosure needs 0 < q < 1, got q={qf}")
if terms < 1:
raise ValueError(f"terms must be >= 1, got {terms}")
ratio = abs(zf) / q_bracket(terms, qf)
if not ratio < 1:
raise ValueError(
f"could not certify ratio < 1 at terms={terms} (got {float(ratio):.4g}); "
"increase terms"
)
def term(k: int) -> Interval:
return Interval.from_rational(zf**k / q_factorial(k, qf))
return certified_ratio_series_sum(term, ratio, num_terms=terms)q_binomial
omnibias.qcalculus.q_binomialSource ↗q_binomial(n: int, k: int, q: Rational) -> FractionThe Gaussian / q-binomial [n choose k]_q = [n]!/([k]![n-k]!) (exact).
Zero for k < 0 or k > n. At q = 1 this is the ordinary C(n, k).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
kpositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExecuted regression · q euler reduces to classical
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.
def test_q_euler_reduces_to_classical(n: int) -> None:
assert q_euler(n, 1) == _EULER[n]python -m pytest "packages/omnibias-qcalculus/tests/test_qspecial.py::test_q_euler_reduces_to_classical[2]" -qRegression example · q binomial reduces to binomial
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.
def test_q_binomial_reduces_to_binomial(n: int) -> None:
for k in range(-1, n + 2):
expected = math.comb(n, k) if 0 <= k <= n else 0
assert q_binomial(n, k, 1) == expectedpython -m pytest packages/omnibias-qcalculus/tests/test_qnumbers.py -k test_q_binomial_reduces_to_binomial -qRead the implementation
def q_binomial(n: int, k: int, q: Rational) -> Fraction:
r"""The Gaussian / q-binomial ``[n choose k]_q = [n]!/([k]![n-k]!)`` (exact).
Zero for ``k < 0`` or ``k > n``. At ``q = 1`` this is the ordinary ``C(n, k)``.
"""
if k < 0 or k > n:
return Fraction(0)
return q_factorial(n, q) / (q_factorial(k, q) * q_factorial(n - k, q))q_binomial_poly
omnibias.qcalculus.q_binomial_polySource ↗q_binomial_poly(n: int, k: int) -> tuple[int, ...]The Gaussian binomial [n choose k]_q as an integer polynomial in q.
Computed by the q-Pascal recurrence [n,k]_q = [n-1,k-1]_q + q^k [n-1,k]_q (so the
coefficients are the *non-negative* integers counting subspaces / inversions), which
avoids any division. Returns the ascending coefficient tuple.
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
kpositional-or-keyword | intRequired | See the operation contract and implementation below. |
tuple[int, ...]Executed regression · q binomial poly known value
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.
def test_q_binomial_poly_known_value() -> None:
# [4 choose 2]_q = 1 + q + 2 q^2 + q^3 + q^4 (a textbook Gaussian polynomial).
assert q_binomial_poly(4, 2) == (1, 1, 2, 1, 1)python -m pytest "packages/omnibias-qcalculus/tests/test_qnumbers.py::test_q_binomial_poly_known_value" -qRegression example · gaussian binomial polynomial is exact object
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.
def test_gaussian_binomial_polynomial_is_exact_object() -> None:
# Exposed as an exact integer-polynomial (closed-form), not a float.
poly = qc.q_binomial_poly(6, 3)
assert all(isinstance(c, int) for c in poly)
assert qc.q_binomial(6, 3, Fraction(1)) == sum(poly)python -m pytest packages/omnibias-qcalculus/tests/test_package.py -k test_gaussian_binomial_polynomial_is_exact_object -qRead the implementation
def q_binomial_poly(n: int, k: int) -> tuple[int, ...]:
r"""The Gaussian binomial ``[n choose k]_q`` as an integer polynomial in ``q``.
Computed by the q-Pascal recurrence ``[n,k]_q = [n-1,k-1]_q + q^k [n-1,k]_q`` (so the
coefficients are the *non-negative* integers counting subspaces / inversions), which
avoids any division. Returns the ascending coefficient tuple.
"""
if k < 0 or k > n:
return ()
if k == 0 or k == n:
return (1,)
below = q_binomial_poly(n - 1, k - 1) # [n-1, k-1]
right = q_binomial_poly(n - 1, k) # q^k * [n-1, k]
size = max(len(below), k + len(right))
coeffs = [0] * size
for i, c in enumerate(below):
coeffs[i] += c
for i, c in enumerate(right):
coeffs[i + k] += c
while len(coeffs) > 1 and coeffs[-1] == 0:
coeffs.pop()
return tuple(coeffs)q_bracket
omnibias.qcalculus.q_bracketSource ↗q_bracket(n: int, q: Rational) -> FractionThe q-number [n]_q = (1 - q^n)/(1 - q) = 1 + q + ... + q^{n-1} (exact, n >= 0).
The summation form is used so q = 1 gives n with no division by zero.
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExplicit validation & failure cases
- When
n < 0, raisesValueError(f'q_bracket needs n >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q euler reduces to classical
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.
def test_q_euler_reduces_to_classical(n: int) -> None:
assert q_euler(n, 1) == _EULER[n]python -m pytest "packages/omnibias-qcalculus/tests/test_qspecial.py::test_q_euler_reduces_to_classical[2]" -qRegression example · q bracket reduces to n at q one
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.
def test_q_bracket_reduces_to_n_at_q_one(n: int) -> None:
assert q_bracket(n, 1) == n
assert q_bracket(n, Fraction(1)) == npython -m pytest packages/omnibias-qcalculus/tests/test_qnumbers.py -k test_q_bracket_reduces_to_n_at_q_one -qRead the implementation
def q_bracket(n: int, q: Rational) -> Fraction:
r"""The q-number ``[n]_q = (1 - q^n)/(1 - q) = 1 + q + ... + q^{n-1}`` (exact, ``n >= 0``).
The summation form is used so ``q = 1`` gives ``n`` with no division by zero.
"""
if n < 0:
raise ValueError(f"q_bracket needs n >= 0, got {n}")
qq = _frac(q)
total = Fraction(0)
power = Fraction(1)
for _ in range(n):
total += power
power *= qq
return totalq_bracket_poly
omnibias.qcalculus.q_bracket_polySource ↗q_bracket_poly(n: int) -> tuple[int, ...]The q-number [n]_q as an integer polynomial in q (1, 1, ..., 1; n ones).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
tuple[int, ...]Explicit validation & failure cases
- When
n < 0, raisesValueError(f'q_bracket_poly needs n >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q bracket poly is ones and evaluates
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.
def test_q_bracket_poly_is_ones_and_evaluates() -> None:
for n in range(7):
assert q_bracket_poly(n) == tuple(1 for _ in range(n))
assert _poly_eval(q_bracket_poly(n), Fraction(2, 5)) == q_bracket(n, Fraction(2, 5))python -m pytest "packages/omnibias-qcalculus/tests/test_qnumbers.py::test_q_bracket_poly_is_ones_and_evaluates" -qRead the implementation
def q_bracket_poly(n: int) -> tuple[int, ...]:
r"""The q-number ``[n]_q`` as an integer polynomial in ``q`` (``1, 1, ..., 1``; ``n`` ones)."""
if n < 0:
raise ValueError(f"q_bracket_poly needs n >= 0, got {n}")
return tuple(1 for _ in range(n))q_factorial
omnibias.qcalculus.q_factorialSource ↗q_factorial(n: int, q: Rational) -> FractionThe q-factorial [n]_q! = prod_{k=1}^{n} [k]_q (exact, n >= 0).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExplicit validation & failure cases
- When
n < 0, raisesValueError(f'q_factorial needs n >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q euler reduces to classical
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.
def test_q_euler_reduces_to_classical(n: int) -> None:
assert q_euler(n, 1) == _EULER[n]python -m pytest "packages/omnibias-qcalculus/tests/test_qspecial.py::test_q_euler_reduces_to_classical[2]" -qRegression example · q factorial reduces to factorial
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.
def test_q_factorial_reduces_to_factorial(n: int) -> None:
assert q_factorial(n, 1) == math.factorial(n)python -m pytest packages/omnibias-qcalculus/tests/test_qnumbers.py -k test_q_factorial_reduces_to_factorial -qRead the implementation
def q_factorial(n: int, q: Rational) -> Fraction:
r"""The q-factorial ``[n]_q! = prod_{k=1}^{n} [k]_q`` (exact, ``n >= 0``)."""
if n < 0:
raise ValueError(f"q_factorial needs n >= 0, got {n}")
result = Fraction(1)
for k in range(1, n + 1):
result *= q_bracket(k, q)
return resultq_pochhammer
omnibias.qcalculus.q_pochhammerSource ↗q_pochhammer(a: Rational, q: Rational, n: int) -> FractionThe finite q-Pochhammer symbol (a; q)_n = prod_{k=0}^{n-1} (1 - a q^k) (exact).
Parameters
| Name | Type & default | Contract |
|---|---|---|
apositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
FractionExplicit validation & failure cases
- When
n < 0, raisesValueError(f'q_pochhammer needs n >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · negative orders raise
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.
def test_negative_orders_raise() -> None:
with pytest.raises(ValueError):
q_bracket(-1, Fraction(1, 2))
with pytest.raises(ValueError):
q_factorial(-1, Fraction(1, 2))
with pytest.raises(ValueError):
q_pochhammer(1, Fraction(1, 2), -1)python -m pytest "packages/omnibias-qcalculus/tests/test_qnumbers.py::test_negative_orders_raise" -qRegression example · q pochhammer values
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.
def test_q_pochhammer_values() -> None:
# (q; q)_n = prod_{k=1}^n (1 - q^k); (2; 1/3)_3 = -7/27.
q = Fraction(1, 3)
for n in range(6):
expected = math.prod(1 - q**k for k in range(1, n + 1))
assert q_pochhammer(q, q, n) == expected
assert q_pochhammer(2, Fraction(1, 3), 3) == Fraction(-7, 27)python -m pytest packages/omnibias-qcalculus/tests/test_qnumbers.py -k test_q_pochhammer_values -qRead the implementation
def q_pochhammer(a: Rational, q: Rational, n: int) -> Fraction:
r"""The finite q-Pochhammer symbol ``(a; q)_n = prod_{k=0}^{n-1} (1 - a q^k)`` (exact)."""
if n < 0:
raise ValueError(f"q_pochhammer needs n >= 0, got {n}")
af, qf = _frac(a), _frac(q)
result = Fraction(1)
power = Fraction(1) # q^k
for _ in range(n):
result *= 1 - af * power
power *= qf
return resultq_bernoulli
omnibias.qcalculus.q_bernoulliSource ↗q_bernoulli(n: int, q: Rational) -> FractionThe q-Bernoulli number B_n(q) (exact; -> B_n as q -> 1).
From sum_{k=0}^{n} [n+1 choose k]_q B_k(q) = 0 (B_0 = 1), i.e.
B_n(q) = -(1/[n+1]_q) sum_{k=0}^{n-1} [n+1 choose k]_q B_k(q).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExplicit validation & failure cases
- When
n < 0, raisesValueError(f'q_bernoulli needs n >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q bernoulli reduces to classical
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.
def test_q_bernoulli_reduces_to_classical(n: int) -> None:
assert q_bernoulli(n, 1) == _BERNOULLI[n]python -m pytest "packages/omnibias-qcalculus/tests/test_qspecial.py::test_q_bernoulli_reduces_to_classical[0]" -qRegression example · q bernoulli is rational at generic q
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.
def test_q_bernoulli_is_rational_at_generic_q() -> None:
# Away from q = 1 the numbers are still exact rationals (closed-form).
q = Fraction(1, 2)
assert q_bernoulli(1, q) == -1 / (1 + q) # -1/[2]_q
assert isinstance(q_bernoulli(4, q), Fraction)python -m pytest packages/omnibias-qcalculus/tests/test_qspecial.py -k test_q_bernoulli_is_rational_at_generic_q -qRead the implementation
def q_bernoulli(n: int, q: Rational) -> Fraction:
r"""The q-Bernoulli number ``B_n(q)`` (exact; ``-> B_n`` as ``q -> 1``).
From ``sum_{k=0}^{n} [n+1 choose k]_q B_k(q) = 0`` (``B_0 = 1``), i.e.
``B_n(q) = -(1/[n+1]_q) sum_{k=0}^{n-1} [n+1 choose k]_q B_k(q)``.
"""
if n < 0:
raise ValueError(f"q_bernoulli needs n >= 0, got {n}")
bern = [Fraction(1)] # B_0
for m in range(1, n + 1):
s = sum((q_binomial(m + 1, k, q) * bern[k] for k in range(m)), Fraction(0))
bern.append(-s / q_bracket(m + 1, q))
return bern[n]q_euler
omnibias.qcalculus.q_eulerSource ↗q_euler(n: int, q: Rational) -> FractionThe q-Euler (secant) number E_n(q) (exact; 0 for odd n; -> E_n as q -> 1).
From sum_{k=0}^{m} [2m choose 2k]_q E_{2k}(q) = 0 (E_0 = 1), i.e.
E_{2m}(q) = -sum_{k=0}^{m-1} [2m choose 2k]_q E_{2k}(q).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExplicit validation & failure cases
- When
n < 0, raisesValueError(f'q_euler needs n >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q euler reduces to classical
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.
def test_q_euler_reduces_to_classical(n: int) -> None:
assert q_euler(n, 1) == _EULER[n]python -m pytest "packages/omnibias-qcalculus/tests/test_qspecial.py::test_q_euler_reduces_to_classical[0]" -qRegression example · q euler odd is zero
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.
def test_q_euler_odd_is_zero() -> None:
for n in (1, 3, 5, 7):
assert q_euler(n, Fraction(1, 3)) == 0python -m pytest packages/omnibias-qcalculus/tests/test_qspecial.py -k test_q_euler_odd_is_zero -qRead the implementation
def q_euler(n: int, q: Rational) -> Fraction:
r"""The q-Euler (secant) number ``E_n(q)`` (exact; ``0`` for odd ``n``; ``-> E_n`` as ``q -> 1``).
From ``sum_{k=0}^{m} [2m choose 2k]_q E_{2k}(q) = 0`` (``E_0 = 1``), i.e.
``E_{2m}(q) = -sum_{k=0}^{m-1} [2m choose 2k]_q E_{2k}(q)``.
"""
if n < 0:
raise ValueError(f"q_euler needs n >= 0, got {n}")
if n % 2 == 1:
return Fraction(0)
evens = [Fraction(1)] # E_0
for m in range(1, n // 2 + 1):
s = sum((q_binomial(2 * m, 2 * k, q) * evens[k] for k in range(m)), Fraction(0))
evens.append(-s)
return evens[n // 2]q_exp
omnibias.qcalculus.q_expSource ↗q_exp(z: float, q: float, *, terms: int=128) -> floatThe q-exponential e_q(z) = sum_{n>=0} z^n / [n]_q! (numerical, 0 < q < 1).
Converges for |z| < 1/(1-q). terms truncates the series; evaluated in float via
the recurrence t_n = t_{n-1} z / [n]_q (no exact-Fraction factorial blow-up).
Parameters
| Name | Type & default | Contract |
|---|---|---|
zpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
qpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
termskeyword-only | intDefault: 128 | See the operation contract and implementation below. |
floatExplicit validation & failure cases
- When
not 0.0 < q < 1.0, raisesValueError(f'q_exp needs 0 < q < 1, got q={q}'). - When
terms < 1, raisesValueError(f'terms must be >= 1, got {terms}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q exp approaches exp as q to one
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.
def test_q_exp_approaches_exp_as_q_to_one() -> None:
z = 0.4
errs = [abs(q_exp(z, q) - math.exp(z)) for q in (0.9, 0.99, 0.999)]
assert errs == sorted(errs, reverse=True)
assert errs[-1] < 1e-2python -m pytest "packages/omnibias-qcalculus/tests/test_qspecial.py::test_q_exp_approaches_exp_as_q_to_one" -qRegression example · q exponential reciprocal identity
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.
def test_q_exponential_reciprocal_identity() -> None:
# e_q(z) E_q(-z) = 1.
for q in (0.3, 0.5, 0.7):
for z in (0.1, 0.25, -0.2):
assert q_exp(z, q) * q_exp_big(-z, q) == pytest.approx(1.0, rel=1e-9, abs=1e-9)python -m pytest packages/omnibias-qcalculus/tests/test_qspecial.py -k test_q_exponential_reciprocal_identity -qRead the implementation
def q_exp(z: float, q: float, *, terms: int = 128) -> float:
r"""The q-exponential ``e_q(z) = sum_{n>=0} z^n / [n]_q!`` (numerical, ``0 < q < 1``).
Converges for ``|z| < 1/(1-q)``. ``terms`` truncates the series; evaluated in float via
the recurrence ``t_n = t_{n-1} z / [n]_q`` (no exact-Fraction factorial blow-up).
"""
if not 0.0 < q < 1.0:
raise ValueError(f"q_exp needs 0 < q < 1, got q={q}")
if terms < 1:
raise ValueError(f"terms must be >= 1, got {terms}")
total = 0.0
term = 1.0 # z^n / [n]_q!
for n in range(terms):
total += term
term *= z / _q_bracket_float(n + 1, q)
return totalq_exp_big
omnibias.qcalculus.q_exp_bigSource ↗q_exp_big(z: float, q: float, *, terms: int=128) -> floatThe entire q-exponential E_q(z) = sum_{n>=0} q^{n(n-1)/2} z^n / [n]_q! (numerical).
Uses t_n = t_{n-1} (q^{n-1} z) / [n]_q since q^{C(n,2)}/q^{C(n-1,2)} = q^{n-1}.
Parameters
| Name | Type & default | Contract |
|---|---|---|
zpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
qpositional-or-keyword | floatRequired | See the operation contract and implementation below. |
termskeyword-only | intDefault: 128 | See the operation contract and implementation below. |
floatExplicit validation & failure cases
- When
not 0.0 < q < 1.0, raisesValueError(f'q_exp_big needs 0 < q < 1, got q={q}'). - When
terms < 1, raisesValueError(f'terms must be >= 1, got {terms}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q exponential reciprocal identity
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.
def test_q_exponential_reciprocal_identity() -> None:
# e_q(z) E_q(-z) = 1.
for q in (0.3, 0.5, 0.7):
for z in (0.1, 0.25, -0.2):
assert q_exp(z, q) * q_exp_big(-z, q) == pytest.approx(1.0, rel=1e-9, abs=1e-9)python -m pytest "packages/omnibias-qcalculus/tests/test_qspecial.py::test_q_exponential_reciprocal_identity" -qRegression example · errors
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.
def test_errors() -> None:
with pytest.raises(ValueError):
q_exp(0.1, 1.5)
with pytest.raises(ValueError):
q_exp_big(0.1, 0.0)
with pytest.raises(ValueError):
q_bernoulli(-1, Fraction(1, 2))
with pytest.raises(ValueError):
q_euler(-1, Fraction(1, 2))python -m pytest packages/omnibias-qcalculus/tests/test_qspecial.py -k test_errors -qRead the implementation
def q_exp_big(z: float, q: float, *, terms: int = 128) -> float:
r"""The entire q-exponential ``E_q(z) = sum_{n>=0} q^{n(n-1)/2} z^n / [n]_q!`` (numerical).
Uses ``t_n = t_{n-1} (q^{n-1} z) / [n]_q`` since ``q^{C(n,2)}/q^{C(n-1,2)} = q^{n-1}``.
"""
if not 0.0 < q < 1.0:
raise ValueError(f"q_exp_big needs 0 < q < 1, got q={q}")
if terms < 1:
raise ValueError(f"terms must be >= 1, got {terms}")
total = 0.0
term = 1.0 # q^{C(n,2)} z^n / [n]_q!
for n in range(terms):
total += term
term *= (q**n * z) / _q_bracket_float(n + 1, q)
return totalq_falling_factorial_coeffs
omnibias.qcalculus.q_falling_factorial_coeffsSource ↗q_falling_factorial_coeffs(n: int, q: Rational) -> tuple[Fraction, ...]Coefficients of the q-falling factorial [x]_{n,q} = prod_{i=0}^{n-1}(x - [i]_q) (exact).
Returns (c_0, ..., c_n) with [x]_{n,q} = sum_k c_k x^k. Computed directly by the
product (an independent cross-check of q_stirling_first_signed_row); at q -> 1
this is the ordinary falling factorial (x)_n.
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Explicit validation & failure cases
- When
n < 0, raisesValueError(f'n must be >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q falling factorial is signed first kind
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.
def test_q_falling_factorial_is_signed_first_kind(q: Fraction) -> None:
for n in range(N + 1):
assert q_falling_factorial_coeffs(n, q) == q_stirling_first_signed_row(n, q)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_falling_factorial_is_signed_first_kind[q0]" -qRegression example · q stirling reduces to classical
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.
def test_q_stirling_reduces_to_classical(n: int) -> None:
assert tuple(int(x) for x in q_stirling_second_row(n, ONE)) == stirling_second_row(n)
assert tuple(int(x) for x in q_stirling_first_signed_row(n, ONE)) == stirling_first_signed_row(n)
assert tuple(int(x) for x in q_falling_factorial_coeffs(n, ONE)) == falling_factorial_coeffs(n)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_stirling_reduces_to_classical -qRead the implementation
def q_falling_factorial_coeffs(n: int, q: Rational) -> tuple[Fraction, ...]:
r"""Coefficients of the q-falling factorial ``[x]_{n,q} = prod_{i=0}^{n-1}(x - [i]_q)`` (exact).
Returns ``(c_0, ..., c_n)`` with ``[x]_{n,q} = sum_k c_k x^k``. Computed directly by the
product (an independent cross-check of :func:`q_stirling_first_signed_row`); at ``q -> 1``
this is the ordinary falling factorial ``(x)_n``.
"""
if n < 0:
raise ValueError(f"n must be >= 0, got {n}")
qq = Fraction(q)
poly = [Fraction(1)]
for i in range(n):
bracket = q_bracket(i, qq)
nxt = [Fraction(0)] * (len(poly) + 1)
for k, c in enumerate(poly):
nxt[k + 1] += c
nxt[k] -= bracket * c
poly = nxt
return tuple(poly)Other public import paths
omnibias.qcalculus.q_falling_factorial_coeffsomnibias.qcalculus.umbral.q_falling_factorial_coeffs
q_rising_factorial_coeffs
omnibias.qcalculus.q_rising_factorial_coeffsSource ↗q_rising_factorial_coeffs(n: int, q: Rational) -> tuple[Fraction, ...]Coefficients of the q-rising factorial prod_{i=0}^{n-1}(x + [i]_q) (exact).
Returns (c_0, ..., c_n); these are the unsigned q-Stirling first-kind row
c_q(n, .). At q -> 1 this is the ordinary rising factorial x^(n).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Explicit validation & failure cases
- When
n < 0, raisesValueError(f'n must be >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Read the implementation
def q_rising_factorial_coeffs(n: int, q: Rational) -> tuple[Fraction, ...]:
r"""Coefficients of the q-rising factorial ``prod_{i=0}^{n-1}(x + [i]_q)`` (exact).
Returns ``(c_0, ..., c_n)``; these are the unsigned q-Stirling first-kind row
``c_q(n, .)``. At ``q -> 1`` this is the ordinary rising factorial ``x^(n)``.
"""
if n < 0:
raise ValueError(f"n must be >= 0, got {n}")
qq = Fraction(q)
poly = [Fraction(1)]
for i in range(n):
bracket = q_bracket(i, qq)
nxt = [Fraction(0)] * (len(poly) + 1)
for k, c in enumerate(poly):
nxt[k + 1] += c
nxt[k] += bracket * c
poly = nxt
return tuple(poly)Other public import paths
omnibias.qcalculus.q_rising_factorial_coeffsomnibias.qcalculus.umbral.q_rising_factorial_coeffs
q_stirling_first_signed
omnibias.qcalculus.q_stirling_first_signedSource ↗q_stirling_first_signed(n: int, k: int, q: Rational) -> FractionSigned q-Stirling number of the first kind s_q(n, k) = (-1)^{n-k} c_q(n, k) (exact).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
kpositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExecuted regression · q stirling transforms are inverse
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.
def test_q_stirling_transforms_are_inverse(q: Fraction) -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_falling_to_monomial(q_monomial_to_falling(coeffs, q), q) == tuple(coeffs)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_stirling_transforms_are_inverse[q0]" -qRegression example · q stirling kinds are inverse
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.
def test_q_stirling_kinds_are_inverse(q: Fraction) -> None:
# sum_j s_q(n, j) S_q(j, m) = delta_{n, m}.
for n in range(N + 1):
for m in range(n + 1):
total = sum(
(q_stirling_first_signed(n, j, q) * q_stirling_second(j, m, q) for j in range(n + 1)),
Fraction(0),
)
assert total == (Fraction(1) if n == m else Fraction(0))python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_stirling_kinds_are_inverse -qRead the implementation
def q_stirling_first_signed(n: int, k: int, q: Rational) -> Fraction:
r"""Signed q-Stirling number of the first kind ``s_q(n, k) = (-1)^{n-k} c_q(n, k)`` (exact)."""
return Fraction((-1) ** (n - k)) * q_stirling_first_unsigned(n, k, q)Other public import paths
omnibias.qcalculus.q_stirling_first_signedomnibias.qcalculus.umbral.q_stirling_first_signed
q_stirling_first_signed_row
omnibias.qcalculus.q_stirling_first_signed_rowSource ↗q_stirling_first_signed_row(n: int, q: Rational) -> tuple[Fraction, ...]The row (s_q(n, 0), ..., s_q(n, n)) (signed q-Stirling first kind).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Explicit validation & failure cases
- When
n < 0, raisesValueError(f'n must be >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q falling factorial is signed first kind
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.
def test_q_falling_factorial_is_signed_first_kind(q: Fraction) -> None:
for n in range(N + 1):
assert q_falling_factorial_coeffs(n, q) == q_stirling_first_signed_row(n, q)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_falling_factorial_is_signed_first_kind[q0]" -qRegression example · q stirling reduces to classical
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.
def test_q_stirling_reduces_to_classical(n: int) -> None:
assert tuple(int(x) for x in q_stirling_second_row(n, ONE)) == stirling_second_row(n)
assert tuple(int(x) for x in q_stirling_first_signed_row(n, ONE)) == stirling_first_signed_row(n)
assert tuple(int(x) for x in q_falling_factorial_coeffs(n, ONE)) == falling_factorial_coeffs(n)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_stirling_reduces_to_classical -qRead the implementation
def q_stirling_first_signed_row(n: int, q: Rational) -> tuple[Fraction, ...]:
r"""The row ``(s_q(n, 0), ..., s_q(n, n))`` (signed q-Stirling first kind)."""
if n < 0:
raise ValueError(f"n must be >= 0, got {n}")
row = _first_unsigned_table(n, Fraction(q))[n]
return tuple(Fraction((-1) ** (n - k)) * c for k, c in enumerate(row))Other public import paths
omnibias.qcalculus.q_stirling_first_signed_rowomnibias.qcalculus.umbral.q_stirling_first_signed_row
q_stirling_first_unsigned
omnibias.qcalculus.q_stirling_first_unsignedSource ↗q_stirling_first_unsigned(n: int, k: int, q: Rational) -> FractionUnsigned q-Stirling number of the first kind c_q(n, k) (exact; -> c(n, k) at q=1).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
kpositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExplicit validation & failure cases
- When
n < 0 or k < 0, raisesValueError(f'n, k must be >= 0, got n={n}, k={k}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q stirling transforms are inverse
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.
def test_q_stirling_transforms_are_inverse(q: Fraction) -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_falling_to_monomial(q_monomial_to_falling(coeffs, q), q) == tuple(coeffs)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_stirling_transforms_are_inverse[q0]" -qRead the implementation
def q_stirling_first_unsigned(n: int, k: int, q: Rational) -> Fraction:
r"""Unsigned q-Stirling number of the first kind ``c_q(n, k)`` (exact; ``-> c(n, k)`` at ``q=1``)."""
if n < 0 or k < 0:
raise ValueError(f"n, k must be >= 0, got n={n}, k={k}")
if k > n:
return Fraction(0)
return _first_unsigned_table(n, Fraction(q))[n][k]Other public import paths
omnibias.qcalculus.q_stirling_first_unsignedomnibias.qcalculus.umbral.q_stirling_first_unsigned
q_stirling_second
omnibias.qcalculus.q_stirling_secondSource ↗q_stirling_second(n: int, k: int, q: Rational) -> Fractionq-Stirling number of the second kind S_q(n, k) (exact; -> S(n, k) as q -> 1).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
kpositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExplicit validation & failure cases
- When
n < 0 or k < 0, raisesValueError(f'n, k must be >= 0, got n={n}, k={k}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q stirling transforms are inverse
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.
def test_q_stirling_transforms_are_inverse(q: Fraction) -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_falling_to_monomial(q_monomial_to_falling(coeffs, q), q) == tuple(coeffs)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_stirling_transforms_are_inverse[q0]" -qRegression example · q stirling second recurrence
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.
def test_q_stirling_second_recurrence(q: Fraction) -> None:
for n in range(1, N + 1):
for k in range(1, n + 1):
expected = q_stirling_second(n - 1, k - 1, q) + q_bracket(k, q) * q_stirling_second(
n - 1, k, q
)
assert q_stirling_second(n, k, q) == expectedpython -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_stirling_second_recurrence -qRead the implementation
def q_stirling_second(n: int, k: int, q: Rational) -> Fraction:
r"""q-Stirling number of the second kind ``S_q(n, k)`` (exact; ``-> S(n, k)`` as ``q -> 1``)."""
if n < 0 or k < 0:
raise ValueError(f"n, k must be >= 0, got n={n}, k={k}")
if k > n:
return Fraction(0)
return _second_table(n, Fraction(q))[n][k]Other public import paths
omnibias.qcalculus.q_stirling_secondomnibias.qcalculus.umbral.q_stirling_second
q_stirling_second_row
omnibias.qcalculus.q_stirling_second_rowSource ↗q_stirling_second_row(n: int, q: Rational) -> tuple[Fraction, ...]The row (S_q(n, 0), ..., S_q(n, n)) (q-Stirling second kind).
Parameters
| Name | Type & default | Contract |
|---|---|---|
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Explicit validation & failure cases
- When
n < 0, raisesValueError(f'n must be >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q stirling reduces to classical
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.
def test_q_stirling_reduces_to_classical(n: int) -> None:
assert tuple(int(x) for x in q_stirling_second_row(n, ONE)) == stirling_second_row(n)
assert tuple(int(x) for x in q_stirling_first_signed_row(n, ONE)) == stirling_first_signed_row(n)
assert tuple(int(x) for x in q_falling_factorial_coeffs(n, ONE)) == falling_factorial_coeffs(n)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_stirling_reduces_to_classical[0]" -qRegression example · q to one collapse matches classical umbral
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.
def test_q_to_one_collapse_matches_classical_umbral() -> None:
# q-Stirling rows.
for n in range(N + 1):
assert tuple(int(x) for x in q_stirling_second_row(n, ONE)) == stirling_second_row(n)
# transforms.
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_monomial_to_falling(coeffs, ONE) == monomial_to_falling(coeffs)
assert q_falling_to_monomial(coeffs, ONE) == falling_to_monomial(coeffs)
# q-Appell -> Appell.
constants = [Fraction(1), Fraction(-3), Fraction(2), Fraction(5)]
assert [tuple(p) for p in q_appell_sequence(constants, ONE)] == [
tuple(p) for p in appell_sequence(constants)
]
# q-Sheffer -> Sheffer, q-Pincherle -> Pincherle.
assert [tuple(p) for p in q_sheffer_sequence(_G, _F, 5, ONE)] == [
tuple(p) for p in sheffer_sequence(_G, _F, 5)
]
assert q_pincherle_derivative(_F, ONE) == pincherle_derivative(_F)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_to_one_collapse_matches_classical_umbral -qRead the implementation
def q_stirling_second_row(n: int, q: Rational) -> tuple[Fraction, ...]:
r"""The row ``(S_q(n, 0), ..., S_q(n, n))`` (q-Stirling second kind)."""
if n < 0:
raise ValueError(f"n must be >= 0, got {n}")
return tuple(_second_table(n, Fraction(q))[n])Other public import paths
omnibias.qcalculus.q_stirling_second_rowomnibias.qcalculus.umbral.q_stirling_second_row
QShefferClass
omnibias.qcalculus.QShefferClassSource ↗class QShefferClassDataclass 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.
Classification of a q-Sheffer sequence from its pair (g, f) (structural).
Parameters
| Name | Type & default | Contract |
|---|---|---|
kinddataclass field | strRequired | See the operation contract and implementation below. |
is_appelldataclass field | boolRequired | See the operation contract and implementation below. |
is_associateddataclass field | boolRequired | See the operation contract and implementation below. |
Fields & methods
is_appellfield
is_appell: boolDeclared bool field on QShefferClass. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.
View source ↗is_associatedfield
is_associated: boolDeclared bool field on QShefferClass. A value must be provided when constructing the configuration, unless an inherited constructor supplies it.
View source ↗Read the implementation
class QShefferClass:
"""Classification of a q-Sheffer sequence from its pair ``(g, f)`` (structural)."""
kind: str # "appell" | "associated" | "sheffer"
is_appell: bool
is_associated: boolOther public import paths
omnibias.qcalculus.QShefferClassomnibias.qcalculus.umbral.QShefferClass
q_appell_sequence
omnibias.qcalculus.q_appell_sequenceSource ↗q_appell_sequence(constants: Sequence[Rational], q: Rational) -> list[tuple[Fraction, ...]]The q-Appell sequence p_n(x) = sum_k [n,k]_q a_{n-k} x^k (exact).
constants are a_j = p_j(0). Satisfies the q-Appell property
D_q p_n = [n]_q p_{n-1} (the f = t q-Sheffer case). At q -> 1 this is the
classical omnibias.difference.appell_sequence.
Parameters
| Name | Type & default | Contract |
|---|---|---|
constantspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
list[tuple[Fraction, ...]]Executed regression · q appell reduces to classical
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.
def test_q_appell_reduces_to_classical() -> None:
constants = [Fraction(1), Fraction(2), Fraction(-1), Fraction(3), Fraction(0), Fraction(-2)]
q_seq = [tuple(p) for p in q_appell_sequence(constants, ONE)]
classical = [tuple(p) for p in appell_sequence(constants)]
assert q_seq == classicalpython -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_appell_reduces_to_classical" -qRegression example · q bernoulli polynomials reduce to classical
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.
def test_q_bernoulli_polynomials_reduce_to_classical() -> None:
from omnibias.qcalculus import q_bernoulli
constants = [q_bernoulli(j, ONE) for j in range(N + 1)]
assert constants == [bernoulli_number(j) for j in range(N + 1)]
seq = q_appell_sequence(constants, ONE)
for n in range(N + 1):
assert tuple(seq[n]) == bernoulli_polynomial(n)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_bernoulli_polynomials_reduce_to_classical -qRead the implementation
def q_appell_sequence(
constants: Sequence[Rational], q: Rational
) -> list[tuple[Fraction, ...]]:
r"""The q-Appell sequence ``p_n(x) = sum_k [n,k]_q a_{n-k} x^k`` (exact).
``constants`` are ``a_j = p_j(0)``. Satisfies the q-Appell property
``D_q p_n = [n]_q p_{n-1}`` (the ``f = t`` q-Sheffer case). At ``q -> 1`` this is the
classical :func:`omnibias.difference.appell_sequence`.
"""
a = [_frac(v) for v in constants]
return [
tuple(q_binomial(n, k, q) * a[n - k] for k in range(n + 1)) for n in range(len(a))
]Other public import paths
omnibias.qcalculus.q_appell_sequenceomnibias.qcalculus.umbral.q_appell_sequence
q_associated_sequence
omnibias.qcalculus.q_associated_sequenceSource ↗q_associated_sequence(f_coeffs: Sequence[Rational], n: int, q: Rational) -> list[tuple[Fraction, ...]]The q-associated (binomial-type) sequence of the delta series f (g = 1, exact).
f = t gives the monomials x^n; general f gives the q-analog of the associated
sequence, satisfying f(D_q) p_n = [n]_q p_{n-1}.
Parameters
| Name | Type & default | Contract |
|---|---|---|
f_coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
list[tuple[Fraction, ...]]Executed regression · q associated of t are monomials
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.
def test_q_associated_of_t_are_monomials(q: Fraction) -> None:
seq = q_associated_sequence((0, 1), N, q)
for n in range(N + 1):
assert tuple(seq[n]) == tuple([Fraction(0)] * n + [Fraction(1)])python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_associated_of_t_are_monomials[q0]" -qRegression example · q binomial transform inverse
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.
def test_q_binomial_transform_inverse(q: Fraction) -> None:
rng = random.Random(int(q.numerator) * 7 + int(q.denominator))
seq = [Fraction(rng.randint(-6, 6)) for _ in range(7)]
assert q_inverse_binomial_transform(q_binomial_transform(seq, q), q) == tuple(seq)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_binomial_transform_inverse -qRead the implementation
def q_associated_sequence(
f_coeffs: Sequence[Rational], n: int, q: Rational
) -> list[tuple[Fraction, ...]]:
r"""The q-associated (binomial-type) sequence of the delta series ``f`` (``g = 1``, exact).
``f = t`` gives the monomials ``x^n``; general ``f`` gives the q-analog of the associated
sequence, satisfying ``f(D_q) p_n = [n]_q p_{n-1}``.
"""
return q_sheffer_sequence((1,), f_coeffs, n, q)Other public import paths
omnibias.qcalculus.q_associated_sequenceomnibias.qcalculus.umbral.q_associated_sequence
q_binomial_transform
omnibias.qcalculus.q_binomial_transformSource ↗q_binomial_transform(seq: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]The q-binomial transform b_n = sum_k [n,k]_q a_k (exact).
Parameters
| Name | Type & default | Contract |
|---|---|---|
seqpositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q binomial transform inverse
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.
def test_q_binomial_transform_inverse(q: Fraction) -> None:
rng = random.Random(int(q.numerator) * 7 + int(q.denominator))
seq = [Fraction(rng.randint(-6, 6)) for _ in range(7)]
assert q_inverse_binomial_transform(q_binomial_transform(seq, q), q) == tuple(seq)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_binomial_transform_inverse[q0]" -qRegression example · q transforms reduce to classical
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.
def test_q_transforms_reduce_to_classical() -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_monomial_to_falling(coeffs, ONE) == monomial_to_falling(coeffs)
assert q_falling_to_monomial(coeffs, ONE) == falling_to_monomial(coeffs)
seq = [Fraction(1), Fraction(3), Fraction(-2), Fraction(5), Fraction(0), Fraction(-1)]
assert q_binomial_transform(seq, ONE) == binomial_transform(seq)
assert q_inverse_binomial_transform(seq, ONE) == inverse_binomial_transform(seq)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_transforms_reduce_to_classical -qRead the implementation
def q_binomial_transform(seq: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]:
r"""The q-binomial transform ``b_n = sum_k [n,k]_q a_k`` (exact)."""
a = [_frac(v) for v in seq]
return tuple(
sum((q_binomial(n, k, q) * a[k] for k in range(n + 1)), Fraction(0))
for n in range(len(a))
)Other public import paths
omnibias.qcalculus.q_binomial_transformomnibias.qcalculus.umbral.q_binomial_transform
q_delta_operator_apply
omnibias.qcalculus.q_delta_operator_applySource ↗q_delta_operator_apply(f_coeffs: Sequence[Rational], coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]Apply the q-delta operator Q = f(D_q) = sum_k f_k D_q^k to a polynomial (exact).
D_q is the Jackson q-derivative (omnibias.qcalculus.q_derivative_poly). With
f = t this is D_q itself; for the q-associated sequence p_n of f it realises
the exact recurrence Q p_n = [n]_q p_{n-1}.
Parameters
| Name | Type & default | Contract |
|---|---|---|
f_coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q delta operator of t is q derivative
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.
def test_q_delta_operator_of_t_is_q_derivative(q: Fraction) -> None:
poly = (Fraction(2), Fraction(-1), Fraction(3), Fraction(1), Fraction(-2))
assert _same_poly(q_delta_operator_apply((0, 1), poly, q), q_derivative_poly(poly, q))python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_delta_operator_of_t_is_q_derivative[q0]" -qRegression example · q sheffer recurrence
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.
def test_q_sheffer_recurrence(q: Fraction) -> None:
# The exact q-Sheffer recurrence Q s_n = [n]_q s_{n-1} with Q = f(D_q).
seq = q_sheffer_sequence(_G, _F, N, q)
for n in range(1, N + 1):
lhs = q_delta_operator_apply(_F, seq[n], q)
rhs = tuple(q_bracket(n, q) * c for c in seq[n - 1])
assert _same_poly(lhs, rhs)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_sheffer_recurrence -qRead the implementation
def q_delta_operator_apply(
f_coeffs: Sequence[Rational], coeffs: Sequence[Rational], q: Rational
) -> tuple[Fraction, ...]:
r"""Apply the q-delta operator ``Q = f(D_q) = sum_k f_k D_q^k`` to a polynomial (exact).
``D_q`` is the Jackson q-derivative (:func:`omnibias.qcalculus.q_derivative_poly`). With
``f = t`` this is ``D_q`` itself; for the q-associated sequence ``p_n`` of ``f`` it realises
the exact recurrence ``Q p_n = [n]_q p_{n-1}``.
"""
f = [_frac(v) for v in f_coeffs]
qq = _frac(q)
result = [Fraction(0)] * len(coeffs)
deriv = [_frac(v) for v in coeffs] # D_q^0 p
for fk in f:
if fk and deriv:
for j, c in enumerate(deriv):
result[j] += fk * c
deriv = list(q_derivative_poly(deriv, qq))
return _trim(result)Other public import paths
omnibias.qcalculus.q_delta_operator_applyomnibias.qcalculus.umbral.q_delta_operator_apply
q_falling_to_monomial
omnibias.qcalculus.q_falling_to_monomialSource ↗q_falling_to_monomial(coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]Inverse q-Stirling transform: q-falling-factorial coordinates back to monomials.
c_j = sum_k a_k s_q(k, j) (signed q-Stirling first kind); the inverse of
q_monomial_to_falling. At q -> 1 this is the classical
omnibias.difference.falling_to_monomial.
Parameters
| Name | Type & default | Contract |
|---|---|---|
coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q stirling transforms are inverse
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.
def test_q_stirling_transforms_are_inverse(q: Fraction) -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_falling_to_monomial(q_monomial_to_falling(coeffs, q), q) == tuple(coeffs)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_stirling_transforms_are_inverse[q0]" -qRegression example · q transforms reduce to classical
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.
def test_q_transforms_reduce_to_classical() -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_monomial_to_falling(coeffs, ONE) == monomial_to_falling(coeffs)
assert q_falling_to_monomial(coeffs, ONE) == falling_to_monomial(coeffs)
seq = [Fraction(1), Fraction(3), Fraction(-2), Fraction(5), Fraction(0), Fraction(-1)]
assert q_binomial_transform(seq, ONE) == binomial_transform(seq)
assert q_inverse_binomial_transform(seq, ONE) == inverse_binomial_transform(seq)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_transforms_reduce_to_classical -qRead the implementation
def q_falling_to_monomial(
coeffs: Sequence[Rational], q: Rational
) -> tuple[Fraction, ...]:
r"""Inverse q-Stirling transform: q-falling-factorial coordinates back to monomials.
``c_j = sum_k a_k s_q(k, j)`` (signed q-Stirling first kind); the inverse of
:func:`q_monomial_to_falling`. At ``q -> 1`` this is the classical
:func:`omnibias.difference.falling_to_monomial`.
"""
a = [_frac(v) for v in coeffs]
n = len(a)
return tuple(
sum((a[k] * q_stirling_first_signed(k, j, q) for k in range(n)), Fraction(0))
for j in range(n)
)Other public import paths
omnibias.qcalculus.q_falling_to_monomialomnibias.qcalculus.umbral.q_falling_to_monomial
q_inverse_binomial_transform
omnibias.qcalculus.q_inverse_binomial_transformSource ↗q_inverse_binomial_transform(seq: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]The inverse q-binomial transform a_n = sum_k (-1)^{n-k} q^{C(n-k,2)} [n,k]_q b_k (exact).
Parameters
| Name | Type & default | Contract |
|---|---|---|
seqpositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q binomial transform inverse
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.
def test_q_binomial_transform_inverse(q: Fraction) -> None:
rng = random.Random(int(q.numerator) * 7 + int(q.denominator))
seq = [Fraction(rng.randint(-6, 6)) for _ in range(7)]
assert q_inverse_binomial_transform(q_binomial_transform(seq, q), q) == tuple(seq)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_binomial_transform_inverse[q0]" -qRegression example · q transforms reduce to classical
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.
def test_q_transforms_reduce_to_classical() -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_monomial_to_falling(coeffs, ONE) == monomial_to_falling(coeffs)
assert q_falling_to_monomial(coeffs, ONE) == falling_to_monomial(coeffs)
seq = [Fraction(1), Fraction(3), Fraction(-2), Fraction(5), Fraction(0), Fraction(-1)]
assert q_binomial_transform(seq, ONE) == binomial_transform(seq)
assert q_inverse_binomial_transform(seq, ONE) == inverse_binomial_transform(seq)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_transforms_reduce_to_classical -qRead the implementation
def q_inverse_binomial_transform(
seq: Sequence[Rational], q: Rational
) -> tuple[Fraction, ...]:
r"""The inverse q-binomial transform ``a_n = sum_k (-1)^{n-k} q^{C(n-k,2)} [n,k]_q b_k`` (exact)."""
b = [_frac(v) for v in seq]
qq = _frac(q)
out: list[Fraction] = []
for n in range(len(b)):
acc = Fraction(0)
for k in range(n + 1):
sign = Fraction((-1) ** (n - k))
acc += sign * qq ** comb(n - k, 2) * q_binomial(n, k, q) * b[k]
out.append(acc)
return tuple(out)Other public import paths
omnibias.qcalculus.q_inverse_binomial_transformomnibias.qcalculus.umbral.q_inverse_binomial_transform
q_monomial_to_falling
omnibias.qcalculus.q_monomial_to_fallingSource ↗q_monomial_to_falling(coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]q-Stirling transform: coefficients of a polynomial in the q-falling-factorial basis.
a_k = sum_j c_j S_q(j, k) where c are the monomial coefficients; the inverse of
q_falling_to_monomial. At q -> 1 this is the classical
omnibias.difference.monomial_to_falling.
Parameters
| Name | Type & default | Contract |
|---|---|---|
coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q stirling transforms are inverse
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.
def test_q_stirling_transforms_are_inverse(q: Fraction) -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_falling_to_monomial(q_monomial_to_falling(coeffs, q), q) == tuple(coeffs)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_stirling_transforms_are_inverse[q0]" -qRegression example · q transforms reduce to classical
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.
def test_q_transforms_reduce_to_classical() -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_monomial_to_falling(coeffs, ONE) == monomial_to_falling(coeffs)
assert q_falling_to_monomial(coeffs, ONE) == falling_to_monomial(coeffs)
seq = [Fraction(1), Fraction(3), Fraction(-2), Fraction(5), Fraction(0), Fraction(-1)]
assert q_binomial_transform(seq, ONE) == binomial_transform(seq)
assert q_inverse_binomial_transform(seq, ONE) == inverse_binomial_transform(seq)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_transforms_reduce_to_classical -qRead the implementation
def q_monomial_to_falling(
coeffs: Sequence[Rational], q: Rational
) -> tuple[Fraction, ...]:
r"""q-Stirling transform: coefficients of a polynomial in the q-falling-factorial basis.
``a_k = sum_j c_j S_q(j, k)`` where ``c`` are the monomial coefficients; the inverse of
:func:`q_falling_to_monomial`. At ``q -> 1`` this is the classical
:func:`omnibias.difference.monomial_to_falling`.
"""
c = [_frac(v) for v in coeffs]
n = len(c)
return tuple(
sum((c[j] * q_stirling_second(j, k, q) for j in range(n)), Fraction(0))
for k in range(n)
)Other public import paths
omnibias.qcalculus.q_monomial_to_fallingomnibias.qcalculus.umbral.q_monomial_to_falling
q_newton_forward_coeffs
omnibias.qcalculus.q_newton_forward_coeffsSource ↗q_newton_forward_coeffs(samples: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]q-Gregory-Newton forward coefficients from samples at the q-integer nodes [j]_q.
samples[j] are f([0]_q), f([1]_q), ...; returns the coefficients b_k of the
interpolant f(x) = sum_k b_k [x]_{k,q}/[k]_q! (a triangular solve on the nodes, exact).
At q -> 1 the nodes become 0, 1, 2, ... and b_k -> Delta^k f(0), recovering the
classical omnibias.difference.newton_forward_coeffs.
Parameters
| Name | Type & default | Contract |
|---|---|---|
samplespositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q newton reduces to classical
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.
def test_q_newton_reduces_to_classical() -> None:
poly = (Fraction(2), Fraction(-1), Fraction(3), Fraction(1))
samples = [_eval(poly, Fraction(j)) for j in range(len(poly))]
assert q_newton_forward_coeffs(samples, ONE) == newton_forward_coeffs(samples)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_newton_reduces_to_classical" -qRegression example · q stirling transforms are inverse
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.
def test_q_stirling_transforms_are_inverse(q: Fraction) -> None:
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_falling_to_monomial(q_monomial_to_falling(coeffs, q), q) == tuple(coeffs)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_stirling_transforms_are_inverse -qRead the implementation
def q_newton_forward_coeffs(
samples: Sequence[Rational], q: Rational
) -> tuple[Fraction, ...]:
r"""q-Gregory-Newton forward coefficients from samples at the q-integer nodes ``[j]_q``.
``samples[j]`` are ``f([0]_q), f([1]_q), ...``; returns the coefficients ``b_k`` of the
interpolant ``f(x) = sum_k b_k [x]_{k,q}/[k]_q!`` (a triangular solve on the nodes, exact).
At ``q -> 1`` the nodes become ``0, 1, 2, ...`` and ``b_k -> Delta^k f(0)``, recovering the
classical :func:`omnibias.difference.newton_forward_coeffs`.
"""
y = [_frac(v) for v in samples]
qq = _frac(q)
b: list[Fraction] = []
for k in range(len(y)):
node = q_bracket(k, qq)
acc = sum((b[j] * _phi(j, node, qq) for j in range(k)), Fraction(0))
b.append((y[k] - acc) / _phi(k, node, qq))
return tuple(b)Other public import paths
omnibias.qcalculus.q_newton_forward_coeffsomnibias.qcalculus.umbral.q_newton_forward_coeffs
q_newton_forward_value
omnibias.qcalculus.q_newton_forward_valueSource ↗q_newton_forward_value(coeffs: Sequence[Rational], x: Rational, q: Rational) -> FractionEvaluate the q-Newton interpolation sum_k coeffs[k] [x]_{k,q}/[k]_q! at x (exact).
Parameters
| Name | Type & default | Contract |
|---|---|---|
coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
xpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
FractionExecuted regression · q newton reproduces polynomial
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.
def test_q_newton_reproduces_polynomial(q: Fraction) -> None:
poly = (Fraction(2), Fraction(-1), Fraction(3), Fraction(1), Fraction(-2))
samples = [_eval(poly, q_bracket(j, q)) for j in range(len(poly))]
coeffs = q_newton_forward_coeffs(samples, q)
for x in (Fraction(-2), Fraction(0), Fraction(1), Fraction(5, 3), Fraction(7)):
assert q_newton_forward_value(coeffs, x, q) == _eval(poly, x)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_newton_reproduces_polynomial[q0]" -qRead the implementation
def q_newton_forward_value(
coeffs: Sequence[Rational], x: Rational, q: Rational
) -> Fraction:
r"""Evaluate the q-Newton interpolation ``sum_k coeffs[k] [x]_{k,q}/[k]_q!`` at ``x`` (exact)."""
qq = _frac(q)
xf = _frac(x)
return sum(
(_frac(c) * _phi(k, xf, qq) for k, c in enumerate(coeffs)), Fraction(0)
)Other public import paths
omnibias.qcalculus.q_newton_forward_valueomnibias.qcalculus.umbral.q_newton_forward_value
q_pincherle_derivative
omnibias.qcalculus.q_pincherle_derivativeSource ↗q_pincherle_derivative(f_coeffs: Sequence[Rational], q: Rational) -> tuple[Fraction, ...]The (series-level) q-Pincherle derivative of Q = f(D_q): the q-derivative of f.
Returns D_q f (as a coefficient series). This is the q-analog of the Pincherle
derivative; it reduces to the classical f' as q -> 1. Because [D_q, X] = M_q
(the q-dilation) the classical operator commutator identity is q-deformed, so this is the
honest series-level object rather than a claimed QX - XQ operator equality.
Parameters
| Name | Type & default | Contract |
|---|---|---|
f_coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
tuple[Fraction, ...]Executed regression · q pincherle reduces to classical
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.
def test_q_pincherle_reduces_to_classical() -> None:
assert q_pincherle_derivative(_F, ONE) == pincherle_derivative(_F)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_pincherle_reduces_to_classical" -qRegression example · q to one collapse matches classical umbral
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.
def test_q_to_one_collapse_matches_classical_umbral() -> None:
# q-Stirling rows.
for n in range(N + 1):
assert tuple(int(x) for x in q_stirling_second_row(n, ONE)) == stirling_second_row(n)
# transforms.
coeffs = [Fraction(1), Fraction(-2), Fraction(3), Fraction(0), Fraction(4)]
assert q_monomial_to_falling(coeffs, ONE) == monomial_to_falling(coeffs)
assert q_falling_to_monomial(coeffs, ONE) == falling_to_monomial(coeffs)
# q-Appell -> Appell.
constants = [Fraction(1), Fraction(-3), Fraction(2), Fraction(5)]
assert [tuple(p) for p in q_appell_sequence(constants, ONE)] == [
tuple(p) for p in appell_sequence(constants)
]
# q-Sheffer -> Sheffer, q-Pincherle -> Pincherle.
assert [tuple(p) for p in q_sheffer_sequence(_G, _F, 5, ONE)] == [
tuple(p) for p in sheffer_sequence(_G, _F, 5)
]
assert q_pincherle_derivative(_F, ONE) == pincherle_derivative(_F)python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_to_one_collapse_matches_classical_umbral -qRead the implementation
def q_pincherle_derivative(
f_coeffs: Sequence[Rational], q: Rational
) -> tuple[Fraction, ...]:
r"""The (series-level) q-Pincherle derivative of ``Q = f(D_q)``: the q-derivative of ``f``.
Returns ``D_q f`` (as a coefficient series). This is the q-analog of the Pincherle
derivative; it reduces to the classical ``f'`` as ``q -> 1``. Because ``[D_q, X] = M_q``
(the q-dilation) the classical operator commutator identity is q-deformed, so this is the
honest series-level object rather than a claimed ``QX - XQ`` operator equality.
"""
return tuple(q_derivative_poly([_frac(v) for v in f_coeffs], _frac(q)))Other public import paths
omnibias.qcalculus.q_pincherle_derivativeomnibias.qcalculus.umbral.q_pincherle_derivative
q_sheffer_classify
omnibias.qcalculus.q_sheffer_classifySource ↗q_sheffer_classify(g_coeffs: Sequence[Rational], f_coeffs: Sequence[Rational]) -> QShefferClassClassify the q-Sheffer pair (g, f) (appell / associated / sheffer).
g must be invertible (g(0) != 0) and f a delta series (f(0) = 0,
f'(0) != 0). The classification is *structural* -- identical to the classical
omnibias.difference.sheffer_classify, since it does not depend on q.
Parameters
| Name | Type & default | Contract |
|---|---|---|
g_coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
f_coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
QShefferClassExplicit validation & failure cases
- When
not g or g[0] == 0, raisesValueError('g must be invertible: g(0) != 0'). - When
len(f) < 2 or f[0] != 0 or f[1] == 0, raisesValueError("f must be a delta series: f(0) = 0 and f'(0) != 0").
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q associated of t are monomials
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.
def test_q_associated_of_t_are_monomials(q: Fraction) -> None:
seq = q_associated_sequence((0, 1), N, q)
for n in range(N + 1):
assert tuple(seq[n]) == tuple([Fraction(0)] * n + [Fraction(1)])python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_associated_of_t_are_monomials[q0]" -qRegression example · q sheffer classify
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.
def test_q_sheffer_classify() -> None:
assert q_sheffer_classify((1,), (0, 1)).kind == "appell"
assert q_sheffer_classify((1,), (0, 1, 1)).kind == "associated"
assert q_sheffer_classify((1, 2), (0, 1, 1)).kind == "sheffer"python -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_sheffer_classify -qRead the implementation
def q_sheffer_classify(
g_coeffs: Sequence[Rational], f_coeffs: Sequence[Rational]
) -> QShefferClass:
r"""Classify the q-Sheffer pair ``(g, f)`` (appell / associated / sheffer).
``g`` must be invertible (``g(0) != 0``) and ``f`` a delta series (``f(0) = 0``,
``f'(0) != 0``). The classification is *structural* -- identical to the classical
:func:`omnibias.difference.sheffer_classify`, since it does not depend on ``q``.
"""
g = [_frac(v) for v in g_coeffs]
f = [_frac(v) for v in f_coeffs]
if not g or g[0] == 0:
raise ValueError("g must be invertible: g(0) != 0")
if len(f) < 2 or f[0] != 0 or f[1] == 0:
raise ValueError("f must be a delta series: f(0) = 0 and f'(0) != 0")
is_appell = _is_identity_delta(f)
is_associated = _is_unit_constant(g)
kind = "appell" if is_appell else "associated" if is_associated else "sheffer"
return QShefferClass(kind=kind, is_appell=is_appell, is_associated=is_associated)Other public import paths
omnibias.qcalculus.q_sheffer_classifyomnibias.qcalculus.umbral.q_sheffer_classify
q_sheffer_sequence
omnibias.qcalculus.q_sheffer_sequenceSource ↗q_sheffer_sequence(g_coeffs: Sequence[Rational], f_coeffs: Sequence[Rational], n: int, q: Rational) -> list[tuple[Fraction, ...]]The q-Sheffer sequence s_0(x) .. s_n(x) for the pair (g, f) (exact).
Read off the q-exponential generating function
\sum_{n\ge 0} s_n(x)\,\frac{t^n}{[n]_q!} = \frac{1}{g(\bar f(t))}\, e_q\!\big(x\,\bar f(t)\big), \qquad e_q(u) = \sum_m \frac{u^m}{[m]_q!},
with fbar the (ordinary) compositional inverse of the delta series f. Carries the
exact q-Sheffer recurrence Q s_n = [n]_q s_{n-1} with Q = f(D_q)
(q_delta_operator_apply). At q -> 1 this is the classical
omnibias.difference.sheffer_sequence.
Parameters
| Name | Type & default | Contract |
|---|---|---|
g_coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
f_coeffspositional-or-keyword | Sequence[Rational]Required | See the operation contract and implementation below. |
npositional-or-keyword | intRequired | See the operation contract and implementation below. |
qpositional-or-keyword | RationalRequired | See the operation contract and implementation below. |
list[tuple[Fraction, ...]]Explicit validation & failure cases
- When
n < 0, raisesValueError(f'n must be >= 0, got {n}').
These are explicit source guards. Backend operations may also raise for invalid shapes, dtypes, or unsupported devices.
Executed regression · q associated of t are monomials
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.
def test_q_associated_of_t_are_monomials(q: Fraction) -> None:
seq = q_associated_sequence((0, 1), N, q)
for n in range(N + 1):
assert tuple(seq[n]) == tuple([Fraction(0)] * n + [Fraction(1)])python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_associated_of_t_are_monomials[q0]" -qRegression example · q sheffer reduces to classical
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.
def test_q_sheffer_reduces_to_classical() -> None:
q_seq = [tuple(p) for p in q_sheffer_sequence(_G, _F, 5, ONE)]
classical = [tuple(p) for p in sheffer_sequence(_G, _F, 5)]
assert q_seq == classicalpython -m pytest packages/omnibias-qcalculus/tests/test_qumbral.py -k test_q_sheffer_reduces_to_classical -qRead the implementation
def q_sheffer_sequence(
g_coeffs: Sequence[Rational], f_coeffs: Sequence[Rational], n: int, q: Rational
) -> list[tuple[Fraction, ...]]:
r"""The q-Sheffer sequence ``s_0(x) .. s_n(x)`` for the pair ``(g, f)`` (exact).
Read off the q-exponential generating function
.. math::
\sum_{n\ge 0} s_n(x)\,\frac{t^n}{[n]_q!}
= \frac{1}{g(\bar f(t))}\, e_q\!\big(x\,\bar f(t)\big),
\qquad e_q(u) = \sum_m \frac{u^m}{[m]_q!},
with ``fbar`` the (ordinary) compositional inverse of the delta series ``f``. Carries the
exact q-Sheffer recurrence ``Q s_n = [n]_q s_{n-1}`` with ``Q = f(D_q)``
(:func:`q_delta_operator_apply`). At ``q -> 1`` this is the classical
:func:`omnibias.difference.sheffer_sequence`.
"""
if n < 0:
raise ValueError(f"n must be >= 0, got {n}")
q_sheffer_classify(g_coeffs, f_coeffs) # validates the (g, f) pair
qq = _frac(q)
fbar = compositional_inverse(f_coeffs, n)
a_series = series_reciprocal(compose_series(g_coeffs, fbar, n), n) # 1 / g(fbar)
a_coeffs = [a_series[j] if j < len(a_series) else Fraction(0) for j in range(n + 1)]
fbar_pow = _series_powers(fbar, n)
result: list[tuple[Fraction, ...]] = []
for degree in range(n + 1):
poly = [Fraction(0)] * (degree + 1)
for m in range(degree + 1):
acc = Fraction(0)
for j in range(degree - m + 1):
aj = a_coeffs[j]
if aj:
acc += aj * fbar_pow[m][degree - j]
poly[m] = acc / q_factorial(m, qq)
fact = q_factorial(degree, qq)
result.append(tuple(fact * c for c in poly))
return resultOther public import paths
omnibias.qcalculus.q_sheffer_sequenceomnibias.qcalculus.umbral.q_sheffer_sequence
q_umbral_composition
omnibias.qcalculus.q_umbral_compositionSource ↗q_umbral_composition(s_seq: Sequence[Sequence[Rational]], r_seq: Sequence[Sequence[Rational]]) -> list[tuple[Fraction, ...]]Umbral composition (s # r)_n(x) = sum_k s_{n,k} r_k(x) (exact, q-independent).
The polynomial-level umbral composition does not depend on q, so it delegates to the
classical omnibias.difference.umbral_composition.
Parameters
| Name | Type & default | Contract |
|---|---|---|
s_seqpositional-or-keyword | Sequence[Sequence[Rational]]Required | See the operation contract and implementation below. |
r_seqpositional-or-keyword | Sequence[Sequence[Rational]]Required | See the operation contract and implementation below. |
list[tuple[Fraction, ...]]Executed regression · q umbral composition is q independent
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.
def test_q_umbral_composition_is_q_independent() -> None:
# Delegates to the classical (q-independent) umbral composition.
ff = q_associated_sequence([Fraction(0), Fraction(1), Fraction(1, 2), Fraction(1, 6)], 4, Fraction(2, 3))
bell = q_associated_sequence([Fraction(0), Fraction(1), Fraction(-1, 2), Fraction(1, 3)], 4, Fraction(2, 3))
assert q_umbral_composition(ff, bell) == umbral_composition(ff, bell)python -m pytest "packages/omnibias-qcalculus/tests/test_qumbral.py::test_q_umbral_composition_is_q_independent" -qRead the implementation
def q_umbral_composition(
s_seq: Sequence[Sequence[Rational]], r_seq: Sequence[Sequence[Rational]]
) -> list[tuple[Fraction, ...]]:
r"""Umbral composition ``(s # r)_n(x) = sum_k s_{n,k} r_k(x)`` (exact, q-independent).
The polynomial-level umbral composition does not depend on ``q``, so it delegates to the
classical :func:`omnibias.difference.umbral_composition`.
"""
return umbral_composition(s_seq, r_seq)Other public import paths
omnibias.qcalculus.q_umbral_compositionomnibias.qcalculus.umbral.q_umbral_composition