harmonica

1 Preface

Computational group theory and representation theory in Clojure

Harmonica is a library for working with finite groups, their representations, and Fourier analysis. It covers cyclic, dihedral, symmetric, and product groups, with applications to combinatorics, signal processing, and card shuffling.

General info

Website	https://scicloj.github.io/harmonica/
Source
Deps
License	MIT
Status	🛠alpha🛠

Features

Groups

• Cyclic groups Z/nZ, dihedral groups D_n, symmetric groups S_n, product groups G₁ × G₂
• Uniform protocol — op, inv, id, elements, order, conjugacy-classes

Permutations and partitions

• Cycle decomposition, cycle type, sign, composition, inverse
• Partition enumeration, conjugate partitions
• Standard Young tableaux, hook-length formula

Character tables

• Cyclic (DFT matrix), dihedral, symmetric (Murnaghan-Nakayama rule), product (Kronecker product)
• Character inner product, orthogonality relations

Fourier analysis

• Forward and inverse Fourier transform on any finite abelian group
• Convolution via pointwise multiplication in the Fourier domain
• Total variation distance between distributions

Representations

• Irreducible representations of S_n via Young’s orthogonal form
• Matrix Fourier transform (matrix-valued coefficients)
• Tensor product, direct sum, restriction, induction, branching rule

Group actions

• Orbits, stabilizers, fixed points
• Burnside’s lemma, cycle index, Pólya enumeration
• Subset actions, coloring actions

Visualization

• SVG: Young diagrams, hook diagrams, standard Young tableaux, cycle diagrams
• SVG: Cayley tables, Cayley graphs

Documentation

The Harmonica book is organized for incremental learning, interleaving theory with applications:

• Getting Started — Quickstart
• Groups and the DFT — Groups and Structure, DFT as Group Fourier, Product Group DFT, Random Walks
• Groups in Action — Symmetry Sketchpad, Counting Necklaces, Chord Geometry, Hearing Symmetry
• Symmetric Groups — Symmetric Groups, Character Theory, Random Transpositions
• Representation Matrices — Representation Matrices, Riffle Shuffle
• Reference — API Reference, Group Actions

API

Most users need only one namespace:

(require '[scicloj.harmonica :as hm])

scicloj.harmonica is the public API — groups, character tables, Fourier transforms, representations, group actions, and visualization.

For complex-valued results (character tables, Fourier coefficients), harmonica uses lalinea tensors. See scicloj.lalinea.elementwise and scicloj.lalinea.tensor for element-wise and tensor operations.

Built on

• lalinea — complex tensors and linear algebra
• fastmath — matrix operations

The book notebooks also use tablecloth, tableplot, and kindly (kindly is also a top-level dependency; tablecloth and tableplot are in the :dev and :test aliases).

Development

clojure -M:dev -m nrepl.cmdline   # start REPL
./run_tests.sh                     # run tests
clojure -T:build ci                # test + build JAR

References

• Diaconis, P. (1988). Group Representations in Probability and Statistics. IMS Lecture Notes.
• Diaconis, P. & Shahshahani, M. (1981). Generating a random permutation with random transpositions. Z. Wahrscheinlichkeitstheorie, 57, 159–179.
• Bayer, D. & Diaconis, P. (1992). Trailing the dovetail shuffle to its lair. Annals of Applied Probability, 2(2), 294–313.
• Sagan, B. (2001). The Symmetric Group: Representations, Combinatorial Algorithms, and Symmetric Functions. Springer.
• James, G. & Kerber, A. (1981). The Representation Theory of the Symmetric Group. Addison-Wesley.

License

MIT License — see LICENSE file.

---

Part of the scicloj ecosystem for scientific computing in Clojure.

source: notebooks/index.clj