Metadata-Version: 2.4
Name: qseries-sage
Version: 1.3.0
Summary: Python/SageMath port of Garvan's Maple qseries package v1.3
Home-page: https://github.com/gerardgarvan/qSage
Author: Gerard Garvan
License: GPL-2.0-or-later
Project-URL: Source, https://github.com/gerardgarvan/qSage
Project-URL: Tutorial, https://github.com/gerardgarvan/qSage/blob/main/docs/tutorial.md
Project-URL: Maple parity report, https://github.com/gerardgarvan/qSage/blob/main/parity/parity_report.md
Project-URL: Garvan's qseries package, https://qseries.org/fgarvan/qmaple/qseries/
Keywords: q-series,partitions,theta functions,eta products,modular forms,SageMath,Maple
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: passagemath
Requires-Dist: passagemath-standard; extra == "passagemath"
Dynamic: license-file

# qseries-sage

[![tests](https://github.com/gerardgarvan/qSage/actions/workflows/tests.yml/badge.svg)](https://github.com/gerardgarvan/qSage/actions/workflows/tests.yml)

A Python/SageMath port of Frank Garvan's Maple **qseries** package (version 1.3): q-products,
theta functions, product conversion (Andrews' algorithm, eta-products, Jacobi products) and
the search for polynomial relations and congruences between q-series — without Maple.

It is a reimplementation written from Garvan's public documentation and tutorial, and checked
function by function against the real Maple package (see [Agreement with Maple](#agreement-with-maple)).
The qseries package and its documentation are by Frank Garvan:
<https://qseries.org/fgarvan/qmaple/qseries/>.

## Install

qseries-sage needs SageMath. Pick one:

**With an existing SageMath** (Sage 9.5 or later):

```bash
sage -pip install qseries-sage
```

**Without SageMath, from pip alone** (Linux and macOS, Python 3.10-3.13), using the
[passagemath](https://github.com/passagemath/passagemath) wheels. This downloads a full Sage
library, roughly 1 GB:

```bash
python -m pip install --upgrade pip
python -m pip install --only-binary=:all: "qseries-sage[passagemath]"
```

Upgrading pip first matters: the older pip that comes with some systems (e.g. Ubuntu 22.04)
does not recognise passagemath's prebuilt wheels and tries to compile parts of Sage from
source, which usually fails. `--only-binary=:all:` makes sure nothing is compiled.

**Windows:** passagemath supports Linux and macOS only, so install inside WSL (Windows
Subsystem for Linux) with the commands above.

Check it works:

```bash
python -c "from qseries import *; print(packageversion())"   # 1.3.0
```

The distribution is called `qseries-sage`; the import name is `qseries`. To install from a
clone of the repository instead, run `pip install .` in it.

## Example

```python
from sage.all import LaurentSeriesRing, QQ
from qseries import etaq, theta3, theta4, prodmake, findhom, findcong, QSeries

R = LaurentSeriesRing(QQ, 'q', default_prec=110)
q = R.gen()

# Quadratic relations among theta functions (Garvan tutorial, section 4.1)
findhom([theta3(q, 100), theta4(q, 100), theta3(q**2, 100), theta4(q**2, 100)], q, 2, 0)
# -> {X1^2 + X2^2 - 2*X3^2, X1*X2 - X4^2}

# Ramanujan's partition congruences
P = QSeries(etaq(q, 1, 1001).series.__invert__(), 1001)
findcong(P, 1000)
# -> {(4, 5, 5), (5, 7, 7), (6, 11, 11), (24, 25, 25)}
```

Series are `QSeries` objects: a Sage Laurent series with an explicit truncation order `T`
and a rational q-power shift `r` (so `theta2` can carry its `q^(1/4)` factor).

## Functions (41)

| Group | Functions |
|---|---|
| Building blocks | `aqprod`, `qbin`, `etaq`, `jacprod`, `theta`, `theta2`, `theta3`, `theta4`, `tripleprod`, `quinprod`, `winquist` |
| Utilities | `sift`, `qdegree`, `lqdegree`, `lqdegree0`, `checkmult`, `checkprod`, `packageversion`, `changes` |
| Product conversion | `prodmake`, `etamake`, `qetamake`, `jacprodmake`, `jac2prod`, `jac2series`, `mprodmake`, `qfactor`, `zqfactor`, `qs2jaccombo`, `findprod` |
| Relations (exact) | `findhom`, `findhomcombo`, `findnonhom`, `findnonhomcombo`, `findlincombo`, `findmaxind`, `findpoly`, `findcong` |
| Relations (mod p) | `findhommodp`, `findhomcombomodp`, `findlincombomodp` |

Output types: `QSeries`, `QProduct`, `EtaProduct`, `EProduct`, `JacProduct`, `PochProduct`,
`MProduct`, `QFactorResult`, `ZQProduct`.

### Differences from the Maple package

- Relations are returned as Sage polynomials in `X1..Xk` (or `X, Y` for `findpoly`) instead of
  Maple's global `X[i]`; the `SL` name lists of `findlincombo*` are accepted but not used.
- `findcong` returns a set of `(B, A, M)` tuples.
- `zqfactor` returns a `ZQProduct` of factors `(1 - a z^i q^j)^e`. Like Maple's version it is
  best-effort: when it cannot find such a product it warns and returns `None`.
- `findhommodp` uses every coefficient, including q^0. Maple 2026 + qseries 1.3 skips the q^0
  coefficient, so it reports `{X[1], X[2]}` for `findhommodp([1+5*q, 1], 5, q, 1, 0)` (claiming
  1 = 0 mod 5); qseries-sage gives the correct `X1 - X2`.
- `qfactor(f, T)`: Maple 2026 + qseries 1.3 returns `1` for quotients such as
  `q^4(1-q^6)(1-q^7)/((1-q^3)(1-q^12))` when `T` is given (20 or 40), but factors them
  correctly, expanded or not, when `T` is left out. qseries-sage factors them either way.


## Agreement with Maple

A battery of 130 cases covering every function was run in Maple 2026.2 with qseries 1.3 and
compared with this package ([`parity/`](https://github.com/gerardgarvan/qSage/tree/main/parity),
[latest report](https://github.com/gerardgarvan/qSage/blob/main/parity/parity_report.md)): 124 agree exactly, 1 agrees in
value (we return an extra valid answer), and the other 5 are the Maple problems listed under
[Differences from the Maple package](#differences-from-the-maple-package).

## Tests

```bash
sage -python -m pytest -q
```

Expected values in the tests come from Garvan's documentation and tutorial, or from stated
mathematical identities — never from this package's own output.

## License and credits

qseries-sage is free software: you can redistribute it and/or modify it under the terms of the
GNU General Public License as published by the Free Software Foundation, either version 2 of the
License, or (at your option) any later version. See [LICENSE](https://github.com/gerardgarvan/qSage/blob/main/LICENSE).

The qseries package for Maple, its function set and its documentation are the work of
Frank Garvan (University of Florida): <https://qseries.org/fgarvan/qmaple/qseries/>.
This port is an independent reimplementation in Python/SageMath written from that public
documentation and the tutorial

> F. G. Garvan, *A q-product tutorial for a q-series MAPLE package*,
> Séminaire Lotharingien de Combinatoire 42 (1999), Article B42d. arXiv:math/9812092.

One function, `zqfactor`, follows the algorithm of the Maple procedure as printed by Maple when
the package is loaded. If you use this package in research, please cite Garvan's qseries
package and tutorial.
