18 API Reference

Complete reference for scicloj.harmonica — the public API for computational group theory and representation theory.

Group Constructors

`cyclic-group`

Create the cyclic group Z/nZ of order n. Elements are integers 0, 1, …, n-1. The group operation is addition mod n.

(hm/cyclic-group 5)

{:n 5}

`symmetric-group`

Create the symmetric group S_n — all permutations of {0, …, n-1}. Elements are 0-indexed one-line notation vectors. The group operation is composition (right-to-left).

(hm/symmetric-group 3)

{:n 3}

`dihedral-group`

Create the dihedral group D_n — symmetries of a regular n-gon. Order 2n. Elements are [:r k] (rotations) and [:s k] (reflections).

(hm/dihedral-group 4)

{:n 4}

`product-group`

Create the direct product G₁ × G₂ of two finite groups. Elements are pairs [g h].

(hm/product-group (hm/cyclic-group 2) (hm/cyclic-group 3))

{:G1 {:n 2}, :G2 {:n 3}}

Group Operations

`op`

Group operation: combine two elements.

(hm/op (hm/cyclic-group 7) 3 5)

(hm/op (hm/symmetric-group 3) [1 2 0] [0 2 1])

[1 0 2]

`inv`

Group inverse of an element.

(hm/inv (hm/cyclic-group 7) 3)

(hm/inv (hm/symmetric-group 3) [1 2 0])

[2 0 1]

`id`

The identity element of a group.

(hm/id (hm/cyclic-group 5))

(hm/id (hm/symmetric-group 3))

[0 1 2]

(hm/id (hm/dihedral-group 4))

[:r 0]

`elements`

Sequence of all elements of a finite group.

(vec (hm/elements (hm/cyclic-group 4)))

[0 1 2 3]

`order`

Number of elements in a finite group.

(hm/order (hm/symmetric-group 4))

`conjugacy-classes`

Conjugacy classes of a finite group.

(let [classes (hm/conjugacy-classes (hm/symmetric-group 3))]
  (mapv :size classes))

[2 3 1]

Permutation Utilities

`cycles`

Cycle decomposition of a permutation. Returns a vector of cycles (each a vector), omitting fixed points.

(hm/cycles [1 2 3 0])

[[0 1 2 3]]

(hm/cycles [1 0 3 2])

[[0 1] [2 3]]

`cycle-type`

The cycle type of a permutation as a partition (descending sorted). Includes 1-cycles (fixed points).

(hm/cycle-type [1 0 3 2])

[2 2]

`sign`

The sign of a permutation: +1 for even, -1 for odd.

(hm/sign [1 0 2 3])

-1

(hm/sign [0 1 2 3])

`identity-perm`

The identity permutation of size n: [0 1 2 … n-1].

(hm/identity-perm 4)

[0 1 2 3]

`transposition`

Create a transposition permutation that swaps positions i and j. (transposition n i j) returns a permutation of size n.

(hm/transposition 5 1 3)

[0 3 2 1 4]

`adjacent-transposition-decomposition`

Decompose a permutation into adjacent transpositions s_i = (i, i+1). Returns a vector of indices [i_1, i_2, …] such that sigma = s_{i_1} ∘ s_{i_2} ∘ … ∘ s_{i_k}.

(hm/adjacent-transposition-decomposition [2 0 1])

[1 0]

Partitions

`partitions`

All partitions of n, as descending vectors.

(hm/partitions 4)

[[4] [3 1] [2 2] [2 1 1] [1 1 1 1]]

`partition-conjugate`

Conjugate (transpose) of a partition — swap rows and columns in the Young diagram.

(hm/partition-conjugate [4 2 1])

[3 2 1 1]

Young Tableaux

`standard-young-tableaux`

All standard Young tableaux of shape lambda (a partition). Each SYT is a vector of row vectors.

(hm/standard-young-tableaux [2 1])

[[[1 2] [3]] [[1 3] [2]]]

`hook-length-dimension`

Dimension of the irrep of S_n for partition lambda, via the hook-length formula.

(hm/hook-length-dimension [3 2])

(hm/hook-length-dimension [2 2 1])

Characters

`character-table`

Compute the character table of a finite group.

(let [ct (hm/character-table (hm/cyclic-group 3))]
  (count (:table ct)))

(let [ct (hm/character-table (hm/symmetric-group 3))
      re-table (mapv (fn [row] (mapv #(Math/round (el/re %)) row))
                     (:table ct))]
  re-table)

[[1 1 1] [2 0 -1] [1 -1 1]]

`character-inner-product`

Inner product of two class functions.

(let [ct (hm/character-table (hm/symmetric-group 3))
      {:keys [table class-sizes]} ct
      order (hm/order (:group ct))]
  (el/re (hm/character-inner-product (nth table 0) (nth table 1) class-sizes order)))

0.0

`format-cx`

Format a complex character value for display. Integers stay as integers, pure imaginary values display as i/-i/ni, and general complex values display as re+imi.

(hm/format-cx (t/complex 0 1))

"i"

`show-character-table`

Display a character table as a kind/table with labeled rows and columns. Rows are irreducible representations, columns are conjugacy classes. Complex values are formatted for readability.

(hm/show-character-table (hm/character-table (hm/symmetric-group 3)))

	[1 1 1]	[2 1]	[3]
[3]	1	1	1
[2 1]	2	0	-1
[1 1 1]	1	-1	1

Representations

`irrep`

Construct an irreducible representation of S_n from a partition. Returns an opaque value to pass to rep-matrix, etc.

(let [ir (hm/irrep [2 1])]
  (hm/rep-dimension ir))

`rep-matrix`

Compute the representation matrix ρ(σ) for a group element.

(let [ir (hm/irrep [2 1])]
  (fm/nrow (hm/rep-matrix ir [1 0 2])))

`rep-dimension`

Dimension of a representation.

(hm/rep-dimension (hm/irrep [3 1]))

`rep-character`

Character value χ(σ) = tr(ρ(σ)).

(let [ir (hm/irrep [2 1])]
  (hm/rep-character ir [0 1 2]))

2.0

`rep-generators`

Generator matrices for adjacent transpositions s_1, …, s_{n-1}.

(let [ir (hm/irrep [2 1])]
  (count (hm/rep-generators ir)))

`tensor-product`

Tensor product ρ₁ ⊗ ρ₂ of two representations. (ρ₁⊗ρ₂)(g) = ρ₁(g) ⊗ ρ₂(g) (Kronecker product).

(let [ir1 (hm/irrep [2 1])
      ir2 (hm/irrep [2 1])
      tp (hm/tensor-product ir1 ir2)]
  (hm/rep-dimension tp))

`direct-sum`

Direct sum ρ₁ ⊕ ρ₂ of two representations. (ρ₁⊕ρ₂)(g) is block-diagonal with ρ₁(g) and ρ₂(g).

(let [ir1 (hm/irrep [2 1])
      ir2 (hm/irrep [1 1 1])
      ds (hm/direct-sum ir1 ir2)]
  (hm/rep-dimension ds))

`frobenius-norm-sq`

Squared Frobenius norm: ||M||²_F = tr(M Mᵀ).

(let [M (fm/rows->mat [[1.0 0.0] [0.0 1.0]])]
  (hm/frobenius-norm-sq M))

2.0

`frobenius-norm`

Frobenius norm: ||M||_F = sqrt(tr(M Mᵀ)).

(let [M (fm/rows->mat [[3.0 0.0] [0.0 4.0]])]
  (hm/frobenius-norm M))

5.0

`matrix-fourier-transform`

Matrix-valued Fourier transform: f̂(ρ) = Σ f(σ)·ρ(σ).

(let [G (hm/symmetric-group 3)
      ir (hm/irrep [2 1])
      f (zipmap (hm/elements G) (repeat 1.0))
      fhat (hm/matrix-fourier-transform ir G f)]
  (fm/nrow fhat))

Riffle Shuffles

`rising-sequences`

Number of rising sequences of a permutation.

(hm/rising-sequences [0 1 2 3])

(hm/rising-sequences [3 2 1 0])

`gsr-probability`

Probability of permutation σ after k riffle shuffles (GSR model). Q_a(σ) = C(a+n-r(σ), n) / a^n where a=2^k, r = rising sequences.

(let [p (hm/gsr-probability [0 1 2 3] 1)]
  (> p 0.0))

true

Group Actions

`orbit`

The orbit of point x under the action of group G. act is a function (act g x) → x’.

(let [G (hm/cyclic-group 4)
      act (fn [g x] (mod (+ g x) 4))]
  (hm/orbit G act 0))

#{0 1 3 2}

`orbits`

Partition domain into orbits under the action of group G. Returns a vector of sets.

(let [G (hm/cyclic-group 3)
      act (fn [g x] (mod (+ g x) 3))]
  (count (hm/orbits G act (range 3))))

`fixed-points`

The set of points in domain fixed by group element g. (fixed-points act g domain)

(let [act (fn [g x] (mod (+ g x) 5))]
  (hm/fixed-points act 0 (range 5)))

#{0 1 4 3 2}

`stabilizer`

The stabilizer of point x: group elements that fix x.

(let [G (hm/cyclic-group 4)
      act (fn [g x] (mod (+ g x) 4))]
  (hm/stabilizer G act 0))

#{0}

`burnside-count`

Number of orbits via Burnside’s lemma: |orbits| = (1/|G|) Σ_{g∈G} |Fix(g)|

(let [G (hm/cyclic-group 4)
      act (fn [g coloring] (mapv #(coloring (mod (+ % g) 4)) (range 4)))
      domain [[0 0 0 0] [0 0 0 1] [0 0 1 0] [0 0 1 1]
              [0 1 0 0] [0 1 0 1] [0 1 1 0] [0 1 1 1]
              [1 0 0 0] [1 0 0 1] [1 0 1 0] [1 0 1 1]
              [1 1 0 0] [1 1 0 1] [1 1 1 0] [1 1 1 1]]]
  (hm/burnside-count G act domain))

`cycle-index`

The cycle index of a group action. Returns a map from cycle-type partition to coefficient.

(let [G (hm/cyclic-group 3)
      act (fn [g x] (mod (+ g x) 3))
      ci (hm/cycle-index G act (range 3))]
  (= 1 (reduce + (vals ci))))

true

`polya-count`

Number of distinct colorings with k colors via Pólya enumeration.

(let [G (hm/cyclic-group 4)
      act (fn [g x] (mod (+ g x) 4))
      ci (hm/cycle-index G act (range 4))]
  (hm/polya-count ci 2))

6N

`subset-action`

Induced action on k-element subsets of a domain. Returns {:act act-fn :domain all-subsets}.

(let [perm-act (fn [sigma x] (sigma x))
      {:keys [domain]} (hm/subset-action perm-act (range 4) 2)]
  (count domain))

Fourier Analysis

`fourier-transform`

Fourier transform of a function on a finite group.

(let [ct (hm/character-table (hm/cyclic-group 4))
      f (t/complex-tensor-real [1 0 0 0])
      fhat (hm/fourier-transform ct f)]
  (count fhat))

`inverse-fourier-transform`

Recover a function from its Fourier coefficients.

(let [ct (hm/character-table (hm/cyclic-group 4))
      f (t/complex-tensor-real [1 2 3 4])
      fhat (hm/fourier-transform ct f)
      f-back (hm/inverse-fourier-transform ct fhat)
      max-err (apply max (vec (el/abs (el/- f-back f))))]
  (< max-err 1e-10)
  (< max-err 1e-10))

true

`convolve`

Convolve two functions on a finite group via the Fourier domain.

(let [ct (hm/character-table (hm/cyclic-group 4))
      f (t/complex-tensor-real [1 0 0 0])
      g (t/complex-tensor-real [0 1 0 0])
      conv (hm/convolve ct f g)]
  (Math/round (el/re (conv 1))))

`total-variation-distance`

Total variation distance between two distributions.

(hm/total-variation-distance [0.5 0.5 0.0 0.0] [0.25 0.25 0.25 0.25])

0.5

SVG Visualizations

`young-diagram-svg`

Render a partition as an SVG Young diagram (hiccup). Options: :cell-size, :fill, :stroke.

(kind/hiccup (hm/young-diagram-svg [4 2 1]))

`young-hooks-svg`

Render a Young diagram with hook lengths in each cell (hiccup). Options: :cell-size.

(kind/hiccup (hm/young-hooks-svg [4 2 1]))

`syt-svg`

Render a standard Young tableau as SVG (hiccup). Options: :cell-size.

(kind/hiccup (hm/syt-svg [[1 2 3 4] [5 6] [7]]))

`cycle-diagram-svg`

Render a permutation as a cycle diagram SVG (hiccup). Options: :radius.

(kind/hiccup (hm/cycle-diagram-svg [1 2 3 0]))

`cayley-table-svg`

Render a group Cayley table as an SVG grid with colored cells (hiccup). Options: :cell-size.

(kind/hiccup (hm/cayley-table-svg (hm/cyclic-group 4)))

`cayley-graph-svg`

Render a Cayley graph as SVG (hiccup). Vertices = group elements in a circle, directed edges colored by generator. Options: :radius, :node-r, :labels, :colors.

(kind/hiccup (hm/cayley-graph-svg (hm/symmetric-group 3) [[1 0 2] [0 2 1]] :radius 100))

Complex Tensors

The scicloj.lalinea.tensor / scicloj.lalinea.elementwise namespace provides tensor-backed complex numbers. A ComplexTensor wraps a lalinea tensor whose last dimension is 2 (interleaved real/imaginary pairs).

Constructors

`complex-tensor`

[tensor-or-re]

[re-data im-data]

Create a ComplexTensor.

Arities: (complex-tensor tensor) — wrap an existing tensor with last dim = 2 (complex-tensor re-data im-data) — from separate real and imaginary parts

re-data and im-data can be: double arrays, seqs, dtype readers, or tensors. They must have the same shape.

(t/complex-tensor [1.0 2.0 3.0] [4.0 5.0 6.0])

#la/C [:float64 [3] [1.000 + 4.000 i  2.000 + 5.000 i  3.000 + 6.000 i]]

(t/complex-tensor [[1.0 2.0] [3.0 4.0]])

#la/C [:float64 [2] [1.000 + 2.000 i  3.000 + 4.000 i]]

`complex-tensor-real`

[re-data]

Create a ComplexTensor from real data only (imaginary parts = 0).

(t/complex-tensor-real [5.0 6.0 7.0])

#la/C [:float64 [3] [5.000 + 0.000 i  6.000 + 0.000 i  7.000 + 0.000 i]]

Real and imaginary parts

`re`

[a]

Real part(s). For complex: returns a RealTensor view (or double for scalars). For real: returns the input unchanged.

(vec (el/re (t/complex-tensor [1.0 2.0] [3.0 4.0])))

[1.0 2.0]

`im`

[a]

Imaginary part(s). For complex: returns a RealTensor view (or double for scalars). For real: returns zeros matching the input shape.

(vec (el/im (t/complex-tensor [1.0 2.0] [3.0 4.0])))

[3.0 4.0]

Accessors

`complex-shape`

The complex shape (underlying shape without trailing 2).

(t/complex-shape (t/complex-tensor [[1.0 2.0] [3.0 4.0]]
                                   [[5.0 6.0] [7.0 8.0]]))

[2 2]

`scalar?`

True if this ComplexTensor represents a scalar complex number.

(t/scalar? (t/complex-tensor [3.0 4.0]))

true

(t/scalar? (t/complex-tensor [1.0 2.0] [3.0 4.0]))

false

`->tensor`

[x]

Extract the underlying dtype-next tensor from a RealTensor or ComplexTensor. Returns x unchanged if it is neither.

(t/shape (t/->tensor (t/complex-tensor [1.0 2.0] [3.0 4.0])))

[2 2]

`->double-array`

[a]

Get the backing double[] of a tensor. Zero-copy when the tensor is backed by a contiguous array; copies for subviews or lazy tensors. Works for both RealTensors and ComplexTensors.

(let [ct (t/complex-tensor [1.0 2.0] [3.0 4.0])]
  (vec (t/->double-array ct)))

[1.0 3.0 2.0 4.0]

Arithmetic

`*`

[a b]

Element-wise multiply (Hadamard product for real, pointwise complex multiply for complex).

\((1+3i)(5+7i) = -16+22i\)

(let [a (t/complex-tensor [1.0] [3.0])
      b (t/complex-tensor [5.0] [7.0])
      c (el/* a b)]
  [(el/re (c 0)) (el/im (c 0))])

[-16.0 22.0]

`conj`

[a]

Complex conjugate. For complex: negates imaginary parts. For real: returns the input unchanged.

(let [ct (el/conj (t/complex-tensor [1.0 2.0] [3.0 -4.0]))]
  (vec (el/im ct)))

[-3.0 4.0]

`scale`

[a alpha]

Scalar multiply. Returns α · a.

(let [ct (el/scale (t/complex-tensor [1.0 2.0] [3.0 4.0]) 2.0)]
  [(vec (el/re ct)) (vec (el/im ct))])

[[2.0 4.0] [6.0 8.0]]

`abs`

[a]

Element-wise absolute value (magnitude for complex). Returns a RealTensor.

\(|3+4i| = 5\)

(let [m (el/abs (t/complex-tensor [3.0] [4.0]))]
  (< (Math/abs (- (double (m 0)) 5.0)) 1e-10))

true

Inner products

`dot`

[u v]

Inner product. For real vectors: \(\sum u_i v_i\) (returns double). For complex vectors: Hermitian \(\langle u,v \rangle = \sum u_i \overline{v_i}\) (returns scalar ComplexTensor).

Hermitian inner product: \(\langle a, a \rangle = \|a\|^2\).

(let [a (t/complex-tensor [3.0 1.0] [4.0 2.0])
      d (la/dot a a) re (el/re d) im (el/im d)]
  (and (< (Math/abs (- re 30.0)) 1e-10)
       (< (Math/abs im) 1e-10)))

true

`dot-conj`

[u v]

Hermitian inner product: \(\sum u_i \overline{v_i}\). For real vectors: same as dot (\(\sum u_i v_i\)). For complex vectors: \(\sum u_i \overline{v_i}\) (returns scalar ComplexTensor).

\(\langle a, a \rangle = \|a\|^2\) for the Hermitian inner product.

(let [a (t/complex-tensor [3.0 1.0] [4.0 2.0])
      d (la/dot-conj a a) re (el/re d) im (el/im d)]
  (and (< (Math/abs (- re 30.0)) 1e-10)
       (< (Math/abs im) 1e-10)))

true

Element access

(let [ct (t/complex-tensor [1.0 2.0 3.0] [4.0 5.0 6.0])]
  [(count ct) (t/scalar? (ct 0)) (el/re (ct 1))])

[3 true 2.0]

source: notebooks/harmonica_book/api_reference.clj