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

Installation

Add to your deps.edn:

{:deps {org.scicloj/harmonica {:mvn/version "0.1.0"}}}

Documentation

The Harmonica book is organized for incremental learning, interleaving theory with applications — from the DFT and rosette patterns through necklace counting, music theory, and card shuffling.

API

See the API reference for the full list of functions with examples.

Most users need only two namespaces:

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

scicloj.harmonica is the public API — groups, character tables, Fourier transforms, representations, group actions, and visualization. cx provides ComplexTensor operations for working with complex-valued results.

Internal namespaces (analysis.characters, analysis.fourier, analysis.representations, linalg.ejml, protocols, action, etc.) are available but rarely needed directly.

Built on

• dtype-next — array/tensor numerics
• 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