schubmult 5.3.0__tar.gz → 5.4.0__tar.gz

{schubmult-5.3.0 → schubmult-5.4.0}/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 5.4.0
+
+New quantum double Grothendieck and change-of-variables APIs, custom quantum alphabets,
+multiplicative equivariant variables, on-demand generating-set growth, and Python 3.15 wheel support.
+
+### Added
+
+- **Change of variables** (#45). `ChangeOfVariables(source, target, rule)` provides lazy indexed
+  images of a generating set, with labels inherited from the target alphabet.
+  For example, `ChangeOfVariables(x, t, lambda i, target: 1 - 1 / target[i])` represents
+  $x_i \mapsto 1 - 1/t_i$. Indexing computes individual images on demand, and `.subs(expr)`
+  substitutes source variables in an expression. Exported from `schubmult`.
+- **Quantum double Grothendieck ring** (#44). `QDGx` and `QuantumDoubleGrothendieckRing`
+  provide stable elements supporting linear combinations, multiplication through the conjectural
+  equivariant quantum K-Pieri kernel, coefficient simplification, and explicit Lenart--Maeno
+  quantum polynomial expansion. Beta is symbolic by default; `QDGx(w, beta=-1)` specializes it,
+  mixed coefficient alphabets are supported, and `QDGx(w, "0")` uses the zero alphabet.
+  Arbitrary x-polynomial conversion and coproducts are not implemented. Products retain
+  permutations outside any chosen finite symmetric group; finite-flag comparisons must handle
+  those separately.
+- **`--beta EXPR` on all four `grothmult_*` commands** (#44). Accepts a sympified expression,
+  such as `--beta=-1`, `--beta 0`, or `--beta "1/2"`; omitting it keeps beta symbolic.
+  `grothmult_double --mixed-var --display-positive` constructs the positive representation with
+  symbolic beta before specialization. For the quantum commands, `--parabolic --beta 0` defers
+  specialization until after Kato projection so inverse powers of beta can cancel.
+- **Custom quantum alphabets** (#52). `QuantumDoubleSchubertRing`, `QuantumSingleSchubertRing`,
+  and `QDSx(w, genset, q_var=...)` accept a `q_var` generating set in place of the default
+  `GeneratingSet("q")`, including a finite `CustomGeneratingSet` with entries such as `t[i]**2`.
+  Products, positive products, quantum elementary and factorial elementary symmetric functions, and
+  polynomial expansion use the ring's quantum alphabet. Rings with different quantum alphabets
+  compare and hash as distinct, so their products are cached separately.
+- **`--multiplicative-variables` for `grothmult_double` and `grothmult_q_double`** (#51).
+  Calculates at `beta=-1` with coefficient coordinates `1-1/y_i` (also `1-1/z_i` with
+  `--mixed-var`) through `ChangeOfVariables`, matching the multiplicative equivariant-character
+  convention. An explicit `--beta=-1` is allowed; other beta values and `--display-positive`
+  are rejected. Combine with `--simplify` to cancel the resulting rational coefficients. Quantum
+  parameters are unchanged, and the quantum command supports `--parabolic`.
+- **Multiplicative variables in the web widget** (#51). A *Multiplicative variables* checkbox
+  (`"multiplicative_variables"` in the JSON API) is available for the double Grothendieck
+  flavors, including mixed variables, simplification, parabolic projection, and downloads.
+  Non-boolean values are rejected, and the option is ignored for other flavors.
+- **Duan--Khlaif--Zou equivariant quantum K-theory examples** (#51).
+  `examples/duan_khlaif_zou_qk.py` computes 156 distinct explicit products listed in
+  [arXiv:2606.15261v2](https://arxiv.org/abs/2606.15261v2), with page references, `--list`,
+  `--example`, and `--section` selection, and optional standalone TeX output (`--tex`). It
+  computes new answers rather than automatically checking the paper's right-hand sides. Regression
+  tests cover the inventory, finite-flag projections, and selected coefficient identities.
+- **Citation metadata** (#53). `CITATION.cff` enables GitHub's *Cite this repository*, and the
+  README and documentation explain how to cite `schubmult`, including the version or commit used.
+
+### Changed
+
+- **Generating sets grow on demand** (#46). `GeneratingSet` starts with 10 cached symbols and
+  grows geometrically for nonnegative indexing and explicitly bounded slices, removing the
+  previous fixed index limit. `len()`, iteration, negative indexing, and open-ended slices
+  describe only the currently cached prefix; use explicit slice bounds when a computation needs
+  a particular number of variables. Masked sets and polynomial consumers follow the growing
+  alphabet. `CustomGeneratingSet` remains finite.
+- **Experimental combinatorics modules moved** (#54). The `chute_move_element`, `hecke_plactic`,
+  `hpd`, `inversions_tableau`, `quasi_crystal_graph`, and `root_tableau` modules now live in
+  `schubmult.combinatorics.experimental`. Their former module paths and top-level `schubmult`
+  exports are no longer available. Pickles referencing the former module paths will not load
+  without migration.
+- **CPython 3.15 wheels** (#49). The release workflow upgrades cibuildwheel to v4.3.4 and targets
+  CPython 3.10-3.15 on Linux (x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows
+  (x86_64). Package metadata also lists Python 3.15. Pull requests changing the wheel workflow
+  build and smoke-test wheels; publishing remains restricted to release tags.
+
+## 5.3.0
+
+The `5.3.0` and `5.2.0` tags have identical source trees. Their published source distributions
+contain the same code, with only generated version and commit metadata differing. Features
+previously listed as 5.3.0 are included in 5.4.0 above.
+
 ## 5.2.0
 
 Final release of 5.2.0, including the changes in 5.2.0b2 and 5.2.0b3.

schubmult-5.4.0/CITATION.cff

@@ -0,0 +1,30 @@
+cff-version: 1.2.0
+message: "If you use schubmult in your research, please cite it as below and include the version or Git commit you used."
+title: schubmult
+abstract: "Fast Schubert calculus in Python: Littlewood-Richardson coefficients, Schubert/Grothendieck rings, and the combinatorics behind them."
+type: software
+authors:
+  - family-names: Samuel
+    given-names: Matt
+repository-code: "https://github.com/matthematics/schubmult"
+url: "https://matthematics.github.io/schubmult/"
+license: GPL-3.0-or-later
+keywords:
+  - Schubert calculus
+  - Schubert polynomials
+  - Grothendieck polynomials
+  - Littlewood-Richardson coefficients
+  - algebraic combinatorics
+
+# arXiv preprint template: replace every XXXX.XXXXX, <PAPER_TITLE>, and <YEAR>, then uncomment.
+# GitHub's "Cite this repository" button will then show the preprint as the preferred citation.
+# preferred-citation:
+#   type: article
+#   authors:
+#     - family-names: Samuel
+#       given-names: Matt
+#   title: "<PAPER_TITLE>"
+#   year: <YEAR>
+#   journal: "arXiv preprint arXiv:XXXX.XXXXX"
+#   doi: 10.48550/arXiv.XXXX.XXXXX
+#   url: "https://arxiv.org/abs/XXXX.XXXXX"

{schubmult-5.3.0/src/schubmult.egg-info → schubmult-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: schubmult
-Version: 5.3.0
+Version: 5.4.0
 Summary: Package for algebraic computation with single, double, and quantum Schubert polynomials
 Author-email: Matt Samuel <schubmult@gmail.com>
 Maintainer-email: Matt Samuel <schubmult@gmail.com>
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: C++
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
@@ -53,6 +54,8 @@ Dynamic: license-file
 
 **Documentation:** <https://matthematics.github.io/schubmult/>
 
+**Citation:** [How to cite](#how-to-cite)
+
 ---
 
 ## Installation
@@ -74,7 +77,7 @@ Requires Python 3.10+. To build the documentation locally, install the `docs` ex
 ### Python
 
 ```python
-from schubmult import Sx, DSx, QSx, QDSx, Gx, DGx, Permutation
+from schubmult import Sx, DSx, QSx, QDSx, Gx, DGx, QDGx, Permutation
 from schubmult.abc import x, y, z
 
 # Ordinary Schubert polynomials: S_312 * S_132 = S_321 + S_4123
@@ -111,6 +114,13 @@ Gx([2, 1, 3]) * Gx([2, 1, 3])                # 𝔊_(3, 1, 2)(x)
 # -------------------------- + -----------------------------
 #         y_2*β + 1                      y_2*β + 1
 
+# Quantum double Grothendieck polynomials (conjectural equivariant quantum K-Pieri rule)
+g = QDGx([1, 3, 2], beta=-1)
+h = QDGx([2, 1, 3], beta=-1)
+product = (g * h).simplify()                 # multiplication uses the combinatorial kernel
+product.expand()                           # explicit Lenart--Maeno quantum polynomials
+g * QDGx([2, 1, 3], "z", beta=-1)           # mixed coefficient alphabets
+
 # Permutations use one-line notation; Lehmer codes are available too
 w = Permutation([3, 1, 4, 2])
 w.code, w.inv, w.descents()                  # ([2, 0, 1], 3, {0, 2})
@@ -118,6 +128,55 @@ w.code, w.inv, w.descents()                  # ([2, 0, 1], 3, {0, 2})
 
 Ring objects: `Sx` (single), `DSx` (double), `QSx`/`QDSx` (quantum, quantum double), `QPSx`/`QPDSx` (parabolic quantum), `Gx`/`DGx` (single/double Grothendieck). Elements are dictionaries `{Permutation: coefficient}` with `*`, `+`, `.expand()`, `.coproduct()`, and change of basis between them. The underlying multiplication kernels live in `schubmult.mult` (`single`, `double`, `quantum`, `quantum_double`, `groth`, `groth_double`).
 
+`QDGx` constructs stable quantum double Grothendieck elements, with symbolic beta by default.
+It supports linear combinations, kernel multiplication, coefficient simplification, and explicit
+polynomial expansion; `QDGx(w, "0")` uses the zero coefficient alphabet. The ring class is
+`QuantumDoubleGrothendieckRing(x_alphabet, y_alphabet, beta=None)`. Arbitrary x-polynomial
+conversion and coproducts are not implemented. Products retain permutations outside any chosen
+finite symmetric group; a finite-flag comparison must handle those separately.
+
+### Paper examples: equivariant quantum K-theory
+
+[examples/duan_khlaif_zou_qk.py](examples/duan_khlaif_zou_qk.py) computes all 156 distinct
+explicit equivariant Schubert-class products in [Duan--Khlaif--Zou, arXiv:2606.15261v2](https://arxiv.org/abs/2606.15261v2):
+Table 3.2 (Fl(3)), Appendix A.1 (Fl(4)), Appendix A.2 (Fl(1,3;4)), and Appendix A.3 (Fl(1,2;4)).
+The script records printed page references and notes the repeated product in A.2 and the
+omitted equivariant square in A.3. It generates new answers, rather than automatically comparing
+against the paper's printed right-hand sides.
+
+```bash
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --list
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --example fl4-04
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --section fl134
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --tex --output products.tex
+```
+
+It uses `QuantumDoubleGrothendieckRing` at `beta=-1` with `ChangeOfVariables` implementing
+`z_i -> 1-1/y_i`, the paper's multiplicative equivariant-character convention. Finite-flag
+projection removes stable terms outside `S_n`; partial flags additionally use the existing
+Kato projection, with consecutive quantum-parameter indices. TeX output is a standalone
+document using `\widetilde{\mathfrak{G}}_w(x;y)`. Add `--non-equivariant` to specialize the
+selected products at `y_i=1`. The underlying equivariant quantum K-Pieri multiplication
+rule remains conjectural.
+
+### Generating sets
+
+`GeneratingSet("x")` supports any nonnegative index, including indices above 100.
+It starts with 10 cached symbols and grows geometrically on demand. Bounded slices
+such as `x[1:151]` also generate the requested variables. `len(x)`, iteration,
+negative indexing, and open-ended slices describe only the currently cached prefix;
+use explicit slice bounds when a computation needs a particular number of variables.
+`CustomGeneratingSet` remains a finite sequence.
+
+```python
+from schubmult import ChangeOfVariables, GeneratingSet
+
+x, t = GeneratingSet("x"), GeneratingSet("t")
+change = ChangeOfVariables(x, t, lambda i, target: 1 - 1 / target[i])
+change[150]                     # 1 - 1/t_150
+change.subs(x[150] + x[1]**2)   # simultaneous substitution of source variables
+```
+
 ### Command line
 
 Each ring has a CLI. Permutations are space-separated, factors are separated by `-`:
@@ -132,10 +191,22 @@ grothmult_py 2 1 3 - 2 1 3                         # Grothendieck
 grothmult_double 2 1 3 - 2 1 3                     # double Grothendieck (coefficients in y and β)
 grothmult_q 2 1 - 2 1                              # quantum Grothendieck (conjectural quantum K-Pieri rule; coefficients in q and β)
 grothmult_q_double 2 1 - 2 1 --mixed-var           # quantum double Grothendieck (coefficients in y, z, q and β)
+grothmult_q_double 2 1 - 2 1 --multiplicative-variables --simplify  # beta=-1, coordinates 1-1/y_i
 ```
 
+Both `grothmult_double` and `grothmult_q_double` support
+`--multiplicative-variables`: this uses `ChangeOfVariables` to calculate with
+`1-1/y_i` coefficient coordinates and fixes `beta=-1`. With `--mixed-var`, the
+second coefficient alphabet is also changed to `1-1/z_i`. Explicit
+`--beta=-1` is allowed; other beta values and `--display-positive` conflict
+with this mode and are rejected. Add `--simplify` to cancel the rational
+coefficients. Without the flag, the existing conventions are unchanged.
+
 `--display-positive` writes double and quantum double coefficients as manifestly positive expressions in the differences `y_i - z_j` (Graham positivity), using integer programming to find a positive representative. Run any script with `--help` for the full option list.
 
+All four `grothmult_*` scripts accept `--beta EXPR` to use a sympified expression as beta in the multiplication, for example `--beta=-1`, `--beta 0`, or `--beta "1/2"`. Without this option, beta remains symbolic.
+For `--display-positive`, the positive expression is constructed with symbolic beta before specialization. With `--parabolic --beta 0`, specialization is deferred until after Kato projection so inverse powers of beta can cancel.
+
 ## Combinatorics
 
 The `schubmult.combinatorics` package provides the objects that index Schubert calculus, with conversions between them:
@@ -143,8 +214,8 @@ The `schubmult.combinatorics` package provides the objects that index Schubert c
 - **`Permutation`** -- one-line notation, Lehmer codes (`uncode`), reduced words, Bruhat order, descents, dominant/Grassmannian tests.
 - **`RCGraph`** -- reduced compatible sequences / pipe dreams, with enumeration (`RCGraph.all_rc_graphs(w, n)`), Kashiwara crystal operators (`raising_operator(i)`, `lowering_operator(i)`), Edelman-Greene insertion, and the crystal products used in the transition formulas.
 - **`BPD`** -- bumpless pipe dreams with droop moves, the Gao-Huang bijection to RC graphs (`BPD.from_rc_graph`, `.to_rc_graph()`), and marked/unreduced variants for Grothendieck polynomials.
-- **`WCGraph`**, **`PipeDream`**, **`HPD`** -- K-theoretic and hybrid pipe dream models.
-- **Tableaux** -- `Plactic` (semistandard, jeu de taquin), `NilPlactic` (Edelman-Greene), `RootTableau`, `IncreasingTableau`, `SetValuedTableau`, `HeckePlactic`.
+- **`WCGraph`**, **`PipeDream`** -- K-theoretic pipe dream models.
+- **Tableaux** -- `Plactic` (semistandard, jeu de taquin), `NilPlactic` (Edelman-Greene), `IncreasingTableau`, and `SetValuedTableau`.
 - **Forests** -- indexed forests and the Thompson monoid factorization behind the forest and grove bases.
 
 ```python
@@ -160,6 +231,33 @@ bpd = BPD.from_rc_graph(rc)              # Gao-Huang bijection
 assert bpd.to_rc_graph() == rc
 ```
 
+### Experimental combinatorics
+
+The `schubmult.combinatorics.experimental` namespace contains exploratory
+implementations that may be incomplete or incorrect:
+
+| Module | Main objects |
+| --- | --- |
+| `chute_move_element` | `ChuteMoveElement` |
+| `hecke_plactic` | `HeckePlactic` |
+| `hpd` | `HPD`, `HPDTile` |
+| `inversions_tableau` | `InversionsTableau` |
+| `quasi_crystal_graph` | `QuasiCrystalGraph`, `QuasiCrystalGraphTensor` |
+| `root_tableau` | `RootTableau` |
+
+These objects can be imported from the experimental namespace or their
+individual modules:
+
+```python
+from schubmult.combinatorics.experimental import HPD
+from schubmult.combinatorics.experimental.root_tableau import RootTableau
+```
+
+The former `schubmult.combinatorics.<module>` paths and top-level
+`schubmult` exports for these objects are no longer provided.
+Pickles referencing the former module paths will not load without migration.
+`ChuteMoveRing` remains available, but its basis uses `ChuteMoveElement`.
+
 ## Rings and algebras
 
 Beyond the Schubert rings, `schubmult.rings` includes:
@@ -229,6 +327,51 @@ pytest
 
 Tests live in `tests/`; the script tests compare CLI output against stored JSON cases in `tests/scripts/data`. `ruff check src/schubmult` should pass.
 
+## How to cite
+
+If you use `schubmult` in your research, please cite the software and, once available,
+the accompanying preprint. Include the version number (or Git commit hash for a
+development checkout) used for your computations.
+
+On GitHub, the **Cite this repository** button in the repository sidebar gives
+APA and BibTeX citations generated from [CITATION.cff](CITATION.cff).
+
+### Software
+
+Use this BibTeX template, replacing `<YEAR>` with the year of the cited release or
+commit and `<VERSION_OR_COMMIT>` with the version number or commit hash you used:
+
+```bibtex
+@misc{schubmult,
+  author = {Samuel, Matt},
+  title  = {{schubmult}},
+  year   = {<YEAR>},
+  url    = {https://github.com/matthematics/schubmult},
+  note   = {Version <VERSION_OR_COMMIT>}
+}
+```
+
+### Preprint (template)
+
+**arXiv link:** `<ARXIV_URL>`
+
+The preprint citation is not yet filled in. Replace the placeholders below with
+the paper's authors, title, year, arXiv identifier, and URL before citing it, or
+paste the BibTeX entry exported by arXiv. Also fill in and uncomment the
+`preferred-citation` block in [CITATION.cff](CITATION.cff). The software citation
+above can be used in the meantime.
+
+```bibtex
+@misc{schubmult_paper,
+  author        = {<AUTHORS>},
+  title         = {<PAPER_TITLE>},
+  year          = {<YEAR>},
+  eprint        = {<ARXIV_ID>},
+  archivePrefix = {arXiv},
+  url           = {<ARXIV_URL>}
+}
+```
+
 ## License
 
 GPL-3.0-or-later. See [LICENSE](LICENSE).

{schubmult-5.3.0 → schubmult-5.4.0}/README.md

@@ -10,6 +10,8 @@
 
 **Documentation:** <https://matthematics.github.io/schubmult/>
 
+**Citation:** [How to cite](#how-to-cite)
+
 ---
 
 ## Installation
@@ -31,7 +33,7 @@ Requires Python 3.10+. To build the documentation locally, install the `docs` ex
 ### Python
 
 ```python
-from schubmult import Sx, DSx, QSx, QDSx, Gx, DGx, Permutation
+from schubmult import Sx, DSx, QSx, QDSx, Gx, DGx, QDGx, Permutation
 from schubmult.abc import x, y, z
 
 # Ordinary Schubert polynomials: S_312 * S_132 = S_321 + S_4123
@@ -68,6 +70,13 @@ Gx([2, 1, 3]) * Gx([2, 1, 3])                # 𝔊_(3, 1, 2)(x)
 # -------------------------- + -----------------------------
 #         y_2*β + 1                      y_2*β + 1
 
+# Quantum double Grothendieck polynomials (conjectural equivariant quantum K-Pieri rule)
+g = QDGx([1, 3, 2], beta=-1)
+h = QDGx([2, 1, 3], beta=-1)
+product = (g * h).simplify()                 # multiplication uses the combinatorial kernel
+product.expand()                           # explicit Lenart--Maeno quantum polynomials
+g * QDGx([2, 1, 3], "z", beta=-1)           # mixed coefficient alphabets
+
 # Permutations use one-line notation; Lehmer codes are available too
 w = Permutation([3, 1, 4, 2])
 w.code, w.inv, w.descents()                  # ([2, 0, 1], 3, {0, 2})
@@ -75,6 +84,55 @@ w.code, w.inv, w.descents()                  # ([2, 0, 1], 3, {0, 2})
 
 Ring objects: `Sx` (single), `DSx` (double), `QSx`/`QDSx` (quantum, quantum double), `QPSx`/`QPDSx` (parabolic quantum), `Gx`/`DGx` (single/double Grothendieck). Elements are dictionaries `{Permutation: coefficient}` with `*`, `+`, `.expand()`, `.coproduct()`, and change of basis between them. The underlying multiplication kernels live in `schubmult.mult` (`single`, `double`, `quantum`, `quantum_double`, `groth`, `groth_double`).
 
+`QDGx` constructs stable quantum double Grothendieck elements, with symbolic beta by default.
+It supports linear combinations, kernel multiplication, coefficient simplification, and explicit
+polynomial expansion; `QDGx(w, "0")` uses the zero coefficient alphabet. The ring class is
+`QuantumDoubleGrothendieckRing(x_alphabet, y_alphabet, beta=None)`. Arbitrary x-polynomial
+conversion and coproducts are not implemented. Products retain permutations outside any chosen
+finite symmetric group; a finite-flag comparison must handle those separately.
+
+### Paper examples: equivariant quantum K-theory
+
+[examples/duan_khlaif_zou_qk.py](examples/duan_khlaif_zou_qk.py) computes all 156 distinct
+explicit equivariant Schubert-class products in [Duan--Khlaif--Zou, arXiv:2606.15261v2](https://arxiv.org/abs/2606.15261v2):
+Table 3.2 (Fl(3)), Appendix A.1 (Fl(4)), Appendix A.2 (Fl(1,3;4)), and Appendix A.3 (Fl(1,2;4)).
+The script records printed page references and notes the repeated product in A.2 and the
+omitted equivariant square in A.3. It generates new answers, rather than automatically comparing
+against the paper's printed right-hand sides.
+
+```bash
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --list
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --example fl4-04
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --section fl134
+PYTHONPATH=src python examples/duan_khlaif_zou_qk.py --tex --output products.tex
+```
+
+It uses `QuantumDoubleGrothendieckRing` at `beta=-1` with `ChangeOfVariables` implementing
+`z_i -> 1-1/y_i`, the paper's multiplicative equivariant-character convention. Finite-flag
+projection removes stable terms outside `S_n`; partial flags additionally use the existing
+Kato projection, with consecutive quantum-parameter indices. TeX output is a standalone
+document using `\widetilde{\mathfrak{G}}_w(x;y)`. Add `--non-equivariant` to specialize the
+selected products at `y_i=1`. The underlying equivariant quantum K-Pieri multiplication
+rule remains conjectural.
+
+### Generating sets
+
+`GeneratingSet("x")` supports any nonnegative index, including indices above 100.
+It starts with 10 cached symbols and grows geometrically on demand. Bounded slices
+such as `x[1:151]` also generate the requested variables. `len(x)`, iteration,
+negative indexing, and open-ended slices describe only the currently cached prefix;
+use explicit slice bounds when a computation needs a particular number of variables.
+`CustomGeneratingSet` remains a finite sequence.
+
+```python
+from schubmult import ChangeOfVariables, GeneratingSet
+
+x, t = GeneratingSet("x"), GeneratingSet("t")
+change = ChangeOfVariables(x, t, lambda i, target: 1 - 1 / target[i])
+change[150]                     # 1 - 1/t_150
+change.subs(x[150] + x[1]**2)   # simultaneous substitution of source variables
+```
+
 ### Command line
 
 Each ring has a CLI. Permutations are space-separated, factors are separated by `-`:
@@ -89,10 +147,22 @@ grothmult_py 2 1 3 - 2 1 3                         # Grothendieck
 grothmult_double 2 1 3 - 2 1 3                     # double Grothendieck (coefficients in y and β)
 grothmult_q 2 1 - 2 1                              # quantum Grothendieck (conjectural quantum K-Pieri rule; coefficients in q and β)
 grothmult_q_double 2 1 - 2 1 --mixed-var           # quantum double Grothendieck (coefficients in y, z, q and β)
+grothmult_q_double 2 1 - 2 1 --multiplicative-variables --simplify  # beta=-1, coordinates 1-1/y_i
 ```
 
+Both `grothmult_double` and `grothmult_q_double` support
+`--multiplicative-variables`: this uses `ChangeOfVariables` to calculate with
+`1-1/y_i` coefficient coordinates and fixes `beta=-1`. With `--mixed-var`, the
+second coefficient alphabet is also changed to `1-1/z_i`. Explicit
+`--beta=-1` is allowed; other beta values and `--display-positive` conflict
+with this mode and are rejected. Add `--simplify` to cancel the rational
+coefficients. Without the flag, the existing conventions are unchanged.
+
 `--display-positive` writes double and quantum double coefficients as manifestly positive expressions in the differences `y_i - z_j` (Graham positivity), using integer programming to find a positive representative. Run any script with `--help` for the full option list.
 
+All four `grothmult_*` scripts accept `--beta EXPR` to use a sympified expression as beta in the multiplication, for example `--beta=-1`, `--beta 0`, or `--beta "1/2"`. Without this option, beta remains symbolic.
+For `--display-positive`, the positive expression is constructed with symbolic beta before specialization. With `--parabolic --beta 0`, specialization is deferred until after Kato projection so inverse powers of beta can cancel.
+
 ## Combinatorics
 
 The `schubmult.combinatorics` package provides the objects that index Schubert calculus, with conversions between them:
@@ -100,8 +170,8 @@ The `schubmult.combinatorics` package provides the objects that index Schubert c
 - **`Permutation`** -- one-line notation, Lehmer codes (`uncode`), reduced words, Bruhat order, descents, dominant/Grassmannian tests.
 - **`RCGraph`** -- reduced compatible sequences / pipe dreams, with enumeration (`RCGraph.all_rc_graphs(w, n)`), Kashiwara crystal operators (`raising_operator(i)`, `lowering_operator(i)`), Edelman-Greene insertion, and the crystal products used in the transition formulas.
 - **`BPD`** -- bumpless pipe dreams with droop moves, the Gao-Huang bijection to RC graphs (`BPD.from_rc_graph`, `.to_rc_graph()`), and marked/unreduced variants for Grothendieck polynomials.
-- **`WCGraph`**, **`PipeDream`**, **`HPD`** -- K-theoretic and hybrid pipe dream models.
-- **Tableaux** -- `Plactic` (semistandard, jeu de taquin), `NilPlactic` (Edelman-Greene), `RootTableau`, `IncreasingTableau`, `SetValuedTableau`, `HeckePlactic`.
+- **`WCGraph`**, **`PipeDream`** -- K-theoretic pipe dream models.
+- **Tableaux** -- `Plactic` (semistandard, jeu de taquin), `NilPlactic` (Edelman-Greene), `IncreasingTableau`, and `SetValuedTableau`.
 - **Forests** -- indexed forests and the Thompson monoid factorization behind the forest and grove bases.
 
 ```python
@@ -117,6 +187,33 @@ bpd = BPD.from_rc_graph(rc)              # Gao-Huang bijection
 assert bpd.to_rc_graph() == rc
 ```
 
+### Experimental combinatorics
+
+The `schubmult.combinatorics.experimental` namespace contains exploratory
+implementations that may be incomplete or incorrect:
+
+| Module | Main objects |
+| --- | --- |
+| `chute_move_element` | `ChuteMoveElement` |
+| `hecke_plactic` | `HeckePlactic` |
+| `hpd` | `HPD`, `HPDTile` |
+| `inversions_tableau` | `InversionsTableau` |
+| `quasi_crystal_graph` | `QuasiCrystalGraph`, `QuasiCrystalGraphTensor` |
+| `root_tableau` | `RootTableau` |
+
+These objects can be imported from the experimental namespace or their
+individual modules:
+
+```python
+from schubmult.combinatorics.experimental import HPD
+from schubmult.combinatorics.experimental.root_tableau import RootTableau
+```
+
+The former `schubmult.combinatorics.<module>` paths and top-level
+`schubmult` exports for these objects are no longer provided.
+Pickles referencing the former module paths will not load without migration.
+`ChuteMoveRing` remains available, but its basis uses `ChuteMoveElement`.
+
 ## Rings and algebras
 
 Beyond the Schubert rings, `schubmult.rings` includes:
@@ -186,6 +283,51 @@ pytest
 
 Tests live in `tests/`; the script tests compare CLI output against stored JSON cases in `tests/scripts/data`. `ruff check src/schubmult` should pass.
 
+## How to cite
+
+If you use `schubmult` in your research, please cite the software and, once available,
+the accompanying preprint. Include the version number (or Git commit hash for a
+development checkout) used for your computations.
+
+On GitHub, the **Cite this repository** button in the repository sidebar gives
+APA and BibTeX citations generated from [CITATION.cff](CITATION.cff).
+
+### Software
+
+Use this BibTeX template, replacing `<YEAR>` with the year of the cited release or
+commit and `<VERSION_OR_COMMIT>` with the version number or commit hash you used:
+
+```bibtex
+@misc{schubmult,
+  author = {Samuel, Matt},
+  title  = {{schubmult}},
+  year   = {<YEAR>},
+  url    = {https://github.com/matthematics/schubmult},
+  note   = {Version <VERSION_OR_COMMIT>}
+}
+```
+
+### Preprint (template)
+
+**arXiv link:** `<ARXIV_URL>`
+
+The preprint citation is not yet filled in. Replace the placeholders below with
+the paper's authors, title, year, arXiv identifier, and URL before citing it, or
+paste the BibTeX entry exported by arXiv. Also fill in and uncomment the
+`preferred-citation` block in [CITATION.cff](CITATION.cff). The software citation
+above can be used in the meantime.
+
+```bibtex
+@misc{schubmult_paper,
+  author        = {<AUTHORS>},
+  title         = {<PAPER_TITLE>},
+  year          = {<YEAR>},
+  eprint        = {<ARXIV_ID>},
+  archivePrefix = {arXiv},
+  url           = {<ARXIV_URL>}
+}
+```
+
 ## License
 
 GPL-3.0-or-later. See [LICENSE](LICENSE).