lrcalc-rs

lrcalc-rs is a standalone Rust implementation targeting compatibility with Anders Buch's lrcalc library and command-line tool.

The project/repository name is lrcalc-rs; the installed compatibility surface keeps the classic names: liblrcalc.so, liblrcalc.a, lrcalc, schubmult, and include/lrcalc/....

The crate includes Littlewood-Richardson, Schur, fusion, coproduct, Schubert, Kostka, and stretched-coefficient paths, with benchmark harnesses against upstream C.

Upstream, Credits, and Ecosystem

lrcalc-rs is a compatibility-oriented Rust implementation of the classic Littlewood-Richardson Calculator by Anders S. Buch. The upstream source repository is asbuch/lrcalc on Bitbucket.

The upstream project and ecosystem deserve explicit credit. The original lrcalc package is by Anders S. Buch; its upstream page also credits Nicolas M. Thiery and Jean-Pierre Flori for the GNU automake system, and Pierre-Emmanuel Chaput for suggestions that led to a large speedup in single LR coefficient computation. Sage's lrcalc interface credits Mike Hansen for the core interface, and Anne Schilling, Nicolas M. Thiery, and Anders Buch for fusion products, LR-tableau iteration, finalization, and documentation.

Classic lrcalc is used by several downstream systems and package ecosystems:

• SageMath package lrcalc
• SageMath sage.libs.lrcalc interface
• Python bindings on PyPI
• Repology package overview

Mathematical Background

For background on the main objects computed by this project, see SymCat:

• Schur polynomials
• Littlewood--Richardson coefficients
• Kostka coefficients and Kostka--Foulkes polynomials
• Schubert polynomials

Support

To support SymCat and related symmetric-functions resources, see Ko-fi: symmetricfunctions.

Implemented

• liblrcalc library target configured as cdylib, staticlib, and rlib.
• Linux release builds use upstream-compatible SONAME liblrcalc.so.2.
• Compatibility headers for the upstream Python/Sage Cython surface under include/lrcalc/.
• C ABI smoke coverage for staged headers, shared and static library links, ivlc_iter layout, low-level containers, Schur/LR-tableau helpers, Schubert helpers, staged CLI binaries, and the native LR coefficient kernel.
• C-facing ivector, ivlincomb, ilist, ivlist, partition iterator, partition, permutation/string, LR-tableau iterator, Schur, fusion, and Schubert ABI surfaces. A release nm check currently has no missing upstream exported symbols; the only extra export is lrcalc_new_abi_version.
• lrcalc coef / lrcalc lrcoef, lrcalc mult, lrcalc skew, lrcalc coprod, and lrcalc tab CLI commands. mult supports ordinary, fusion -f, and quantum-printing -q products.
• schubmult CLI and Schubert ABI exports trans, monk, mult_poly_schubert, mult_schubert, and mult_schubert_str.
• Native Buch-style single LR coefficient counter with upstream-style compactification and branch pruning.
• Beta-prefix LR counts for skew shape outer/inner, content content, and a virtual Yamanouchi prefix beta, including paired full/interior counts.
• Variable-content beta-prefix expansion, used by native Rust skew/content experiments and by skew Kostka weight expansion with dominant finite beta.
• Upstream-style skew-shape optimization for skew Schur expansion. The C ABI schur_skew path uses optimized shape reduction plus direct lrit_expand accumulation for the beta-empty case.
• Schur product and coproduct expansion via skew Schur backends, using disconnected skew shapes and upstream-style coproduct filtering.
• Fusion product expansion by row-bounded Schur multiplication followed by upstream-style affine fusion reduction.
• GT-chain LR counter, including relative-interior and dimension variants.
• Hybrid LR full-count stats that dispatch exact Kostka translations to the packed Kostka DP, use certified partial-collapse masks near Kostka shapes, and otherwise fall back to Buch's tableau search.
• Hybrid LR full/interior count stats that use packed Kostka on exact translations and Buch full/interior counts otherwise.
• Signed Kostka expansion for LR coefficients.
• Fast ordinary and skew Kostka dynamic programs.
• Ehrhart h-vector interpolation for pure stretched LR coefficients and the beta-prefix generalization.
• Benchmark binaries and shell scripts comparing Rust paths with upstream C.

Known Gaps Before A Drop-In Release

• Broader C layout/link smoke tests against the full upstream header inventory.
• Sage rebuild tests against the Rust library; the current Sage check is an LD_PRELOAD wrapper smoke test.
• Complete installed-header audit against the full upstream header inventory.

License

lrcalc-rs is distributed under the GNU General Public License, version 3 or any later version (GPL-3.0-or-later). This matches the upstream Littlewood-Richardson Calculator license and is compatible with SageMath's GPL distribution model.

See LICENSE for the project notice and attribution notes, and COPYING for the full GPLv3 text.

Repository Status

For contribution workflow notes, see CONTRIBUTING.md.

Build And Test

cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release
scripts/c_abi_smoke.sh
scripts/python_bindings_smoke.sh
scripts/sage_bindings_smoke.sh
scripts/sage_lrcalc_bench.sh

The Rust library target is named lrcalc, so release builds should produce liblrcalc.so and liblrcalc.a on Linux. The staging helper scripts/stage_liblrcalc_prefix.sh creates a local prefix under target/lrcalc-rs-prefix with include/lrcalc/, liblrcalc.a, liblrcalc.so, liblrcalc.so.2, liblrcalc.so.2.0.0, bin/lrcalc, and bin/schubmult.

The Sage scripts use sage -python when sage is on PATH. Alternatively, set SAGE_PYTHON=/path/to/sage/python.

Useful Commands

cargo run --bin lrcalc -- coef 3 2 1 - 2 1 - 2 1
cargo run --bin lrcalc -- mult 2 1 - 2 1
cargo run --bin lrcalc -- mult -f 3,2 2 1 - 2 1
cargo run --bin lrcalc -- mult -q 3,2 2 1 - 2 1
cargo run --bin lrcalc -- skew 3 2 1 / 2 1
cargo run --bin lrcalc -- tab 2 1 / 1
cargo run --bin schubmult -- 2 1 - 2 1
cargo run --bin lrcalc -- lr-gt 3 2 1 - 2 1 - 2 1
cargo run --bin lrcalc -- lr-gt-hybrid-stats 7 4 2 1 - 4 2 - 5 2 1
cargo run --bin lrcalc -- lr-tableau-hybrid-stats 7 4 2 1 - 4 2 - 5 2 1
cargo run --bin lrcalc -- lr-tableau-hybrid-counts-stats 7 4 2 1 - 4 2 - 5 2 1
cargo run --bin lrcalc -- lr-buch-counts 3 2 1 - 2 1 - 2 1
cargo run --bin lrcalc -- beta-lr-buch-counts 5 3 1 - 3 2 1 - 2 1 - 2 0
cargo run --bin lrcalc -- kostka-fast 3 2 1 - 2 2 2
cargo run --bin lrcalc -- skew-kostka-fast 5 3 1 - 3 2 1 - 2 1
cargo run --bin lrcalc -- lr-stretch-hvector 3 2 1 - 2 1 - 2 1
cargo run --bin lrcalc -- beta-lr-stretch-dimension 3 3 2 1 1 - 1 1 - 2 2 1 1 1 1 - 4 3 2 1
cargo run --bin lrcalc -- beta-lr-stretch-hvector 5 3 1 - 3 2 1 - 2 1 - 2 0
cargo run --release --bin lr_hybrid_bench -- 5 3
cargo run --release --bin stretched_dp_bench -- 5 3
cargo run --release --bin partial_collapse_probe
scripts/lrcoef_ffi_bench.sh 5000 mixed
scripts/lrcoef_benchmark_report.sh
scripts/skew_kostka_ffi_bench.sh 1000
scripts/schur_schubert_ffi_bench.sh 500

Benchmark Snapshot

The detailed benchmark report is notes/LRCOEF_BENCHMARK_REPORT.md. Ratios below 1.000x mean the Rust path was faster than the lrcalc baseline in that run.

Computation	Rust path	lrcalc baseline	Ratio
24 listed LR coefficients, including c^(7,6,5,4,3,2,1)_(4,4,3,2,1),(5,4,3,2) = 56	16.504ms	16.673ms	0.990x
c^(5000,3000)_(3500),(3000,1500) = 1	251.416us	341.265us	0.737x
c^(300,200,100)_(200,100),(200,100) = 101	501.186ms	479.124ms	1.046x
c^(70,60,50,40,30,20,10)_(40,40,30,20,10),(50,40,30,20) = 247237177	84.940ms h* build plus 2.403ms for 1000 cached evaluations	timeout >5s	n/a
c^(140,120,100,80,60,40,20)_(80,80,60,40,20),(100,80,60,40) = 140522126162	84.940ms h* build plus 4.016ms for 1000 cached evaluations	timeout >5s	n/a
K_(7,4,3,1),(1,1,1,1,1,1,1,1,1,1,1,1,1,1,1) = 135135	557.181us direct Kostka DP	1.400s LR-translation path	<0.001x
15 stretched Kostka-as-LR full/interior counts listed in the report	4.075ms hybrid LR	3.678s GT-chain LR	0.001x
Sage wrapper, 11 listed operations	geometric mean 0.965x Rust/Sage-C	Sage's packaged liblrcalc	0.965x

Benchmark scripts live under scripts/. CLI-oracle scripts usually take UPSTREAM_BIN; FFI benchmark scripts usually take UPSTREAM_LIB or UPSTREAM_LIB_DIR. Sage benchmark output defaults to target/; set OUT=... only when intentionally saving a local report. See scripts/README.md for the script index.

Reference

Upstream source: https://bitbucket.org/asbuch/lrcalc/src/master/

Current notes use upstream commit 8705a16e1575351684ed692f88552f97da3724f4 from 2025-04-16.