1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
//! A kernel for computing with symmetric functions: the six classical bases,
//! every transition between them, and the Hall–Littlewood, Macdonald, LLT and
//! Jack families above them, together with Schubert polynomials.
//!
//! Each basis is a distinct Rust type over a coefficient ring the caller
//! chooses, so a basis mix-up is a compile error and `ℚ[q,t]` is as ordinary a
//! coefficient ring as `ℤ`. Every value that leaves the library is exact, or
//! the call fails loudly.
//!
//! ## What it computes
//!
//! **The classical core.** The six bases — [`Schur`], [`Homogeneous`],
//! [`Elementary`], [`Monomial`], [`PowerSum`], [`Forgotten`] — as distinct
//! types unified by the [`SymFn`] trait, with [`convert()`] between every
//! ordered pair. Three products: ordinary — Littlewood–Richardson behind the
//! [`LrBackend`] trait, native in Rust with no external C library —
//! plethystic ([`plethysm()`]) and internal ([`kronecker`]). The full Hopf
//! structure: [`coproduct`], [`counit`], [`antipode`], and skewing by an
//! *arbitrary* symmetric function ([`SkewBy`]). Evaluation at a finite
//! alphabet, the principal specializations and their q-analog ([`eval`]),
//! symmetric-group characters ([`character()`]) and Kostka numbers
//! ([`kostka()`]) — as single values and as whole tables.
//!
//! **The parametrized families.** Hall–Littlewood `Q'_λ(x;t)` and `P_λ(x;t)`
//! ([`hl`]) and the Kostka–Foulkes polynomials ([`kf`]); Macdonald `P_λ`,
//! `Q_λ` and `J_λ` ([`macdonald`]); the `(q,t)`-Kostka polynomials and the
//! modified Macdonald basis [`Ht`] ([`qtkostka`]); Jack `P/Q/J_λ(x;α)` and
//! the zonal specialization ([`jack`]); LLT polynomials in both the ribbon
//! and tuple models, the tuple entries straight or skew ([`llt`],
//! [`SkewTuple`]); the delta-operator tower `∇`, `Δ'_f`, `Θ` ([`deltaop`]);
//! Schubert polynomials and their structure constants ([`schubert`]). Each
//! family's deformed Hall pairing sits beside the classical one —
//! [`hl::scalar_t`], [`macdonald::scalar_qt`], [`jack_scalar`] — and each
//! family is orthogonal under its own.
//!
//! Everything is generic over [`Ring`], and the paths that divide ask only
//! for [`QAlgebra`], a ring containing `ℚ`, because every division in the
//! library is by `z_μ` — an *integer*. That is weaker than a field on
//! purpose: `ℚ[t]` and `ℚ[q,t]` are not fields, and they are exactly the
//! rings Hall–Littlewood and Macdonald need. Plethysm asks one thing more,
//! [`Plethystic`], since `p_n` acts on the coefficients too.
//!
//! ## What this opens
//!
//! - **A single structure constant for a product that cannot be
//! materialized.** `schubert::schubert_coeff` answers `c^w_{uv}` by Bruhat
//! pruning for pairs whose product no machine holds, and
//! `ops::kronecker_coeff` (under `bignum`) answers one `g^ν_{λμ}` where the
//! whole internal product does not fit. The query itself is the capability,
//! not a faster route to the full product.
//! - **Reduced (stable) Kronecker coefficients as an outer product** in the
//! Orellana–Zabrocki bases ([`character_basis`]). The calculation never
//! leaves the power-sum basis, so no Littlewood–Richardson coefficient
//! enters it at all.
//! - **Matchings–Jack and b-conjecture coefficients** ([`gj`]), which no other
//! package computes, and the two [`llt`] outputs with no Sage entry point at
//! any speed: the `∇e_n` by-path Schur-positive refinement, and parabolic
//! affine Kazhdan–Lusztig columns.
//!
//! `docs/record/oracles-and-comparisons.md` is the measured survey of the
//! incumbents behind those claims, including what does exist elsewhere;
//! `docs/record/` carries the degrees and shapes each engine reaches.
//!
//! ## Conventions
//!
//! Every `K_{λμ}` variant, LLT `G`, and `H̃` in circulation differs from its
//! rivals by a normalization twist that yields plausible wrong answers, not
//! errors. Each family's module doc therefore opens with the conventions in
//! circulation, names the one that ships with references by equation number,
//! and pins it with a doctest whose value distinguishes it from its rivals —
//! "The conventions in circulation" in [`llt`] is the fullest example.
//!
//! ## Exactness
//!
//! **Every value that leaves this library is exact, or the call fails
//! loudly — in every build profile.** A computation has three legal outcomes
//! and no fourth: the exact answer; escalation to a wider ring and then the
//! exact answer; or a refusal the caller cannot mistake for an answer —
//! `None`, `Err`, a typed Python exception, or a panic the item documents. No
//! path returns a wrapped, truncated or rounded value.
//!
//! The default coefficient rings `i64`, `i128` and [`Rational`] are the fast
//! path: exact until a value leaves the width, and then a panic rather than a
//! wrap. `BigInt` and `BigRational` (the `bignum` feature) have no wall. In
//! between, [`Guarded`] and [`GuardedRat`] inside a [`guarded`] scope
//! *report* an overflow instead of panicking, so a caller can re-run the same
//! generic code over a bignum ring — which is what the Python boundary does
//! on every call. Where a fixed-width family has a wall a caller can reach,
//! its own module doc states the wall in reproducible terms, next to the
//! degrees and shapes the engine is measured to reach.
//! `docs/policies/failure.md` is the rulebook this compresses.
//!
//! ## Verification
//!
//! The test suite checks computed values against reference output from
//! independent software, committed to the tree: `tests/sage_oracle.rs` and
//! `tests/lrcalc_oracle.rs` compare against fixtures Sage and `lrcalc`
//! produced, with `scripts/gen_sage_oracle.sage` alongside so an auditor can
//! regenerate the fixtures rather than trust them; `tests/algebra_laws.rs`
//! checks the laws a fixed value cannot — conversions are ring homomorphisms,
//! `ω` is an involutive algebra map, `Δ` is an algebra map; and
//! `scripts/check_backend.py` runs this crate underneath Sage, so the inputs
//! are chosen by Sage rather than by these tests. Where no independent
//! software computes a family at all, the cross-check is internal: the
//! `(q,t)`-Kostka table is computed by three algorithms sharing nothing above
//! [`Partition`], and the three [`LrBackend`] implementations agree
//! exhaustively on every product with `|μ| + |ν| ≤ 7`.
//! `docs/policies/validation.md` is the standard each family is held to.
//!
//! ## Feature flags
//!
//! - **`bignum`** — `BigInt` / `BigRational` coefficient rings and the
//! [`guarded`] escalation they complete. An entry point whose fixed-width
//! path fails across most of its intended range — `ops::kronecker_coeff`
//! is one — exists only under this feature.
//! - **`python`** — the PyO3 bindings the wheel is built from; enables
//! `bignum`. The Python surface has its own reference at
//! <https://symfn.readthedocs.io>.
//!
//! ## Examples
//!
//! Littlewood–Richardson over `ℤ`:
//!
//! ```
//! use symfn::{Schur, SymFn, Partition};
//!
//! // s_2 · s_1 = s_3 + s_{21}
//! let s2: Schur<i64> = Schur::monomial(Partition::new([2]), 1);
//! let s1: Schur<i64> = Schur::monomial(Partition::new([1]), 1);
//! let prod = s2.mul(&s1);
//! assert_eq!(prod.coeff(&Partition::new([3])), 1);
//! assert_eq!(prod.coeff(&Partition::new([2, 1])), 1);
//! ```
//!
//! Hall–Littlewood over `ℤ[q,t]` — the same [`Schur`] type, with [`QtPoly`]
//! coefficients:
//!
//! ```
//! use symfn::{hall_littlewood, Partition, QtPoly, SymFn};
//!
//! // Q'_{21}(x; t) = s_{21} + t·s_3
//! let qp = hall_littlewood::<i64>(&Partition::new([2, 1]));
//! assert_eq!(qp.coeff(&Partition::new([3])), QtPoly::t());
//! assert_eq!(qp.coeff(&Partition::new([2, 1])).coeff(0, 0), 1);
//! assert!(qp.coeff(&Partition::new([1, 1, 1])).is_empty());
//! ```
// Affordable only because the module sort below shrank the surface it applies
// to: the lint skips `#[doc(hidden)]` items, so the nine hidden modules and the
// two private ones account for 17 of the 53 undocumented items this found, and
// the 36 that remained were accessors and trait-method signatures rather than
// mathematics (`docs/public-api.md`).
// Two modules hold every `unsafe` block in the crate and allow the lint at
// their own top, each with the reason beside the block: `skew_lr`, one
// `repr(transparent)` slice cast, and `measure`, the counting allocator that
// forwards to `System`. A third would have to say why here
// (`docs/policies/failure.md`; `docs/record/failure-and-overflow.md`, "The
// unsafe review").
// The public module list is a decided list, not an accumulated one
// (`docs/public-api.md`). Three tiers, and the test that sorts
// them is whether a caller who only wants symmetric functions would ever name
// the module:
//
// * **API** — the families, the types, the coefficient rings. Documented,
// semver-stable, and what the policy in `docs/public-api.md` promises.
// * **`#[doc(hidden)]`** — reachable and compiled, absent from the reference,
// promised nothing. Two kinds live here: the cross-check engines that exist
// to disagree with a primary route (`bh`, `gjmod`, `macop`), and the
// strategy modules whose *results* are API but whose paths are not (`rect`,
// `two_row`, `three_row`, `strip_lr` — their re-exports below stay
// documented). `measure` is a heap-accounting harness and `python` is a
// PyO3 bridge; neither is symmetric functions.
// * **`pub(crate)`** — `memo`, `modular` and `candidates`, named from nowhere
// outside `src/`. `clear_caches` is re-exported below because the
// measurement discipline needs it (`CLAUDE.md`), and `cache_stats` beside
// it because a session that can clear the caches should be able to see
// them first.
//
// The `pub use` list at the bottom is sorted by the same test applied to
// items (`docs/public-api.md`, "The crate root"). The root holds what a
// consumer names: the types and rings, each family's entry points, the
// tables, the conversions, the operators and pairings, the LR backends, the
// cache controls, and every type that appears in a root signature. A second
// route to a value the root already computes, a cross-check engine, element
// arithmetic over plain maps, or an enumeration primitive stays behind its
// module path, public and documented there. Promoting a name later is
// additive and removing one is a break, so a doubtful name stays behind its
// module path.
pub
pub
pub
// The README's `rust` fence runs under `cargo test`, so the front page cannot
// drift from the API; its other fences carry non-Rust tags and are skipped.
pub use AFrac;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Frac;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use plethysm;
pub use QtPoly;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use three_row_product;
pub use ;