API Reference

integrate(expr::SymbolicMatrix, measure)

Integrate a SymbolicMatrix as a whole. Returns a matrix of results if the dimension in measure is a concrete integer.

integrate(expr::SymbolicMatrixProduct, measure)

Integrate a product of SymbolicMatrices. Returns a matrix of results if the dimension in measure is a concrete integer. It skips expansion and returns the product itself if it does not contain the integration variable.

integrate(expr::AbstractArray, measure)

Performs element-wise integration of a matrix or array of expressions. Returns an array of the same shape containing integrated values.

integrate(expr, measure)

Top-level integration function. It first checks the Pre-computed Integral Library for instant results. If not found, it calls fallback_integrate for the specific measure.

@integrate expr measure

Symbolically integrate an expression over a measure, automatically declaring variables. Heuristics are used to identify which symbols represent random matrices and dimensions.

evaluate(expr, dict)
evaluate(expr, pair)

Shorthand for Symbolics.substitute. Useful for substituting symbolic dimensions with numeric values in integration results. Also handles substituting symbolic traces.

This function automatically handles removable singularities in fractions (e.g., $0/0$ forms). If a denominator evaluates to zero after substitution, the expression is first simplified to attempt resolving the singularity before completing the evaluation.

asymptotic(ex, d, order=1)

Generic asymptotic expansion of a rational function ex in powers of 1/d.

asymptotic(expr, measure::HaarMeasure, order=1)

Returns the series expansion of the integral in powers of 1/d.

asymptotic(expr, measure::PureStateMeasure, order=1)

Returns the series expansion of the integral in powers of 1/d.

asymptotic(expr, measure::Union{OrthogonalMeasure, SymplecticMeasure}, order=1)

asymptotic(expr, measure::StiefelMeasure, order=1)

Returns the series expansion of the integral in powers of 1/d.

hciz(A, B)
hciz(a::AbstractVector, b::AbstractVector)

Computes the Harish-Chandra-Itzykson-Zuber (HCIZ) integral:

\[\int_{U(d)} dU e^{\text{Tr}(A U B U^\dagger)} = \left( \prod_{p=1}^{d-1} p! \right) \frac{\det(e^{a_i b_j})_{i,j=1}^d}{\Delta(a) \Delta(b)}\]

where a and b are eigenvalues of A and B, and \Delta is the Vandermonde determinant.

If A and B are matrices, their eigenvalues are extracted. Supporting:

• Numeric matrices (via eigen)
• Matrix{Num} (symbolic diagonal or 2x2)
• SymbolicMatrix (by generating symbolic eigenvalues a_1, ..., a_d)

Note: This formula is sensitive to degenerate eigenvalues where the denominators become zero. In such cases, the limit should be taken. This implementation currently uses a small perturbation for numerical stability if exact degeneracies are detected in numeric input.

vandermonde_det(v)

Computes the Vandermonde determinant of a vector v:

\[\Delta(v) = \prod_{1 \le i < j \le d} (v_i - v_j)\]

AbstractMeasure

Abstract base type for all integration measures (Haar, Gaussian, Circular, etc.). Provides generic dispatch for element-wise integration of arrays and ambiguity resolution for SymbolicMatrix and SymbolicMatrixProduct.

measure_info(measure)

Returns (subs_dict, matcher, dim, measure_type) for a given measure. Subtypes should implement this to participate in the unified integration flow.

measure_info(measure)

Returns a tuple (matcher, dim, type) for the given measure. Internal function used for dispatching integration logic.

dU(dim)

Defines the Haar measure for the Unitary group $U(d)$.

Integration engine identifies variables via metadata tag :U.

dO(dim)

Defines the Haar measure for the real Orthogonal group $O(d)$ with dimension dim. Integration engine identifies variables via metadata tag :O.

dSp(dim)

Defines the Haar measure for the Symplectic group $Sp(d)$. The dimension dim must be even. Integration engine identifies variables via metadata tag :Sp.

dGUE(dim)

Gaussian Unitary Ensemble (GUE) measure.

dGOE(dim)

Gaussian Orthogonal Ensemble (GOE) measure.

dGSE(dim)

Gaussian Symplectic Ensemble (GSE) measure. dim must be even.

dGinUE(dim)

Complex Ginibre Ensemble (GinUE) measure.

dGinOE(dim)

Real Ginibre Ensemble (GinOE) measure.

dGinSE(dim)

Quaternionic/Symplectic Ginibre Ensemble (GinSE) measure. dim must be even.

dPsi(dim)

Defines the Fubini-Study measure for a random pure state |psi> distributed according to the Haar measure.

Integration engine identifies variables via metadata tag :psi.

dPerm(dim)

Defines the Haar measure for the Symmetric group $S_d$ (permutation matrices) of dimension dim.

Integration engine identifies variables via metadata tag :Perm.

dCPerm(dim)

Defines the measure for Centered Permutation matrices $Y = P - J/d$ where $P \in S_d$.

dDiagUnitary(dim)

Defines the measure for the group of diagonal unitary matrices (the torus $T^d$) of dimension dim. Integration engine identifies variables via metadata tag :DiagUnitary.

DiagonalUnitaryMeasure{D}

Represents integration over the group of diagonal unitary matrices (the torus $T^d$). For a diagonal unitary matrix $V$, the only non-zero entries are $V_{ii} = e^{i\theta_i}$. Integration over $T^d$ is equivalent to independent phase integrations for each diagonal entry.

SymbolicMatrix(name::Symbol)
SymbolicMatrix(name::Symbol, special_type::Symbol)
SymbolicMatrix(name::Symbol, special_type::Symbol, dim)
SymbolicMatrix(name::Symbol, is_adj::Bool, special_type::Symbol, dim)

A wrapper associated with a symbolic name to represent a matrix in a coordinate-free way. Used in the symbolic trace logic (via tr_lazy) and for metadata-driven element-wise integration.

tr(A::SymbolicMatrix)
tr(A::SymbolicMatrixProduct)

Symbolic trace of a coordinate-free matrix expression. Returns a LazyTrace object that can be integrated.

purity(rho)

Calculate the purity of a density matrix rho, defined as Tr(rho^2).

average_purity(rho, measure)

Calculate the Haar-average purity of a density matrix rho under the given measure.

fidelity(rho, sigma)

Calculate the fidelity between two density matrices rho and sigma. For pure states, this is |<phi|psi>|^2. In this package, we use the Hilbert-Schmidt inner product Tr(rho * sigma) as a convenience.

average_fidelity(rho, sigma, measure)

Calculate the Haar-average fidelity between rho and sigma under the given measure.

partial_trace(M, dims, subsystem)

Compute the partial trace of matrix M over the specified subsystem. dims is a tuple/vector of dimensions for each subsystem. subsystem is the index of the subsystem to be TRACED OUT.

Example: For a bipartite system with dims=(2, 2), partial_trace(M, (2, 2), 2) returns the reduced density matrix of the first subsystem.

integrate_indices(U_idxs, U_bar_idxs, dim)

Low-level integration function using Weingarten calculus (Unitary).

integrate_indices_orthogonal(indices, dim)

Low-level integration function using Orthogonal Weingarten calculus. Indices are a list of (i, j) for O{ij}. Formula: sum{pi, sigma in PairPartitions} deltapi(i) * deltasigma(j) * Wg(pi, sigma)

integrate_indices_symplectic(indices, dim)

Low-level integration function using Symplectic Weingarten calculus. Formula: sum{pi, sigma} Jpi(i) * J_sigma(j) * Wg^Sp(pi, sigma)

integrate_indices_permutation(indices, dim)

Integration over the symmetric group S_d.

integrate_indices_diagonal(U_idxs, U_bar_idxs, dim)

Low-level integration function for the Diagonal Unitary group (Torus). The integral is non-zero (equal to 1) only if the multisets of indices of U and Ubar are identical. Indices are already checked to be diagonal (i == j) in processterm.

integrate_indices_coe(all_indices, dim)

Integration of COE terms by reducing to Haar integration.

Index Mapping

$S = U U^T$, so each $S_{ij}$ expands as:

\[S_{ij} = \sum_k U_{ik} U_{jk}, \qquad \bar{S}_{ij} = \sum_k \bar{U}_{ik} \bar{U}_{jk}\]

Each $S_{i_k j_k}$ produces two U-type indices $(i_k, a_k)$ and $(j_k, a_k)$ with shared dummy column $a_k$. Similarly each $\bar{S}_{p_k q_k}$ produces two $\bar{U}$-type indices with shared dummy column $b_k$.

Weingarten Integration

With $m$ S-terms and $m$ $\bar{S}$-terms, we have $2m$ U and $2m$ $\bar{U}$ indices. The Haar integral gives:

\[\sum_{\sigma, \tau \in S_{2m}} \delta_{\text{rows}}(\sigma) \cdot d^{\#\text{loops}(\tau)} \cdot \text{Wg}(\sigma\tau^{-1}, d)\]

The dummy column summation $\sum_{a,b} \delta_{\text{cols}}(\tau)$ yields $d^{\#\text{loops}(\tau)}$, where the number of loops is the number of connected components in a bipartite graph:

• Vertices: $a_1 \ldots a_m$ and $b_1 \ldots b_m$
• Structural edges: $a_k$ pairs columns $(2k{-}1, 2k)$; same for $b_k$
• $\tau$-edges: $a_{\lceil r/2 \rceil} \leftrightarrow b_{\lceil \tau(r)/2 \rceil}$

The loop count is computed via union-find on these $2m$ variable nodes.

integrate_indices_gue(indices, dim)

Low-level integration function using Wick's theorem for GUE. Formula: sum{pi in PairPartitions} prod{(u, v) in pi} delta(iu, jv) * delta(ju, iv)

integrate_indices_goe(indices, dim)

Low-level integration function using Wick's theorem for GOE. Formula: sum{pi in PairPartitions} prod{(u, v) in pi} (delta(iu, kv)delta(ju, lv) + delta(iu, lv)delta(ju, kv)) where pair is H{iu ju} and H{kv lv} (indices re-labeled for clarity).

integrate_indices_ginue(u_indices, ub_indices, dim)

Low-level integration for Complex Ginibre Ensemble. Formula: sum{sigma in Sn} prodm delta(im, ibsigma(m)) * delta(jm, jb_sigma(m))

integrate_indices_ginoe(indices, dim)

Low-level integration for Real Ginibre Ensemble. Formula: sum{pi in PairPartitions} prod{(u, v) in pi} delta(iu, iv) * delta(ju, jv)

integrate_indices_ginse(indices, dim)

Low-level integration for Symplectic Ginibre Ensemble. Uses duality with GinOE.

tr_lazy(product)

Creates a LazyTrace representing the symbolic trace of a matrix product. The product can be a SymbolicMatrix, SymbolicMatrixProduct, or a vector of matrices.

LazyTrace(cycles::Vector{Vector{AbstractMatrix}}, prefactor::Union{Num, Number})

A lazy representation of a trace (or product of traces) of matrix products. Used to represent expressions like tr(A*B) * tr(C) symbolically before integration.

LazySum(terms::Vector{LazyTrace})

A lazy representation of a sum of LazyTrace objects. Enables symbolic integration of expressions like tr(A*B) + tr(C*D).

check_library(expr, measure)

Check if the integral of expr over measure is available in the pre-computed library. Returns the symbolic result if found, otherwise nothing.

tr_val(factors::AbstractVector)

Evaluates the trace of a product of matrices. If all factors are concrete, returns the numeric trace. If any factor is symbolic, returns a symbolic representation normalized by circular shifts and adjoints to ensure unique naming.

_expand_asymptotic(ex, d, order)

Helper to expand a rational function of d in powers of 1/d. Uses Taylor expansion in ε = 1/d around ε = 0.

_poly_degree(p, d)

Helper to get the degree of a polynomial p in variable d.

_ensure_symbolic_dim(d)

Ensure dimension d is a proper Symbolics variable. If d unwraps to a plain Symbol, wrap it via Symbolics.variable; otherwise return as-is.

_try_numeric(v)

Attempt to convert a value to a clean numeric form. Returns the converted value, or nothing if conversion is not possible.

• AbstractFloat → rationalized
• Real → returned as-is

_try_extract_int(p_val)

Attempt to extract an integer from a symbolic or numeric value. Handles Julia Integer, AbstractFloat with integer value, and SymbolicUtils.BasicSymbolic types that print as integers. Returns the Int value or nothing.

robust_substitute(ex, dict)

Substitute symbolic variables in ex using dict. Falls back to manual Postwalk traversal with unwrapped keys if Symbolics.substitute doesn't produce a different expression.

get_full_cycle_type(pi, sigma)

Returns the cycle type of the union of two pair partitions as a sorted partition of k. The union forms cycles of lengths 2l1, 2l2, ... where sum li = k. Returns [l1, l_2, ...] sorted descending.

get_weingarten_orthogonal_data(k, d)

Internal function to generate the Orthogonal Weingarten matrix. The matrix $G$ is a Gram matrix of size $(2k-1)!! \times (2k-1)!!$ where $G_{\pi, \sigma} = d^{\ell(\pi, \sigma)}$. The Weingarten matrix is the inverse of $G$.

AbstractIndexMatcher

Base type for index matching strategies. Subtypes must implement match_index.

MetadataMatcher(type_tag::Symbol)

A matcher that identifies random matrix entries based on metadata attached to the symbols. The type_tag should match the special_type of a SymbolicMatrix (e.g., :U, :O, :Sp).

_integrate_core(expr, dim, subs_dict, matcher, measure_type=:U)

The internal integration engine. It performs several steps:

1. Normalization/Rewriting: Expands abs2(z), real(z), imag(z) into explicit polynomials.
2. Substitution: Replaces symbolic variables with internal atomic representatives via subs_dict.
3. Expansion: Distributes products over sums to get a sum of monomials.
4. Monomial Integration: For each monomial, invokes process_term to identify indices and apply the appropriate integration rule (Weingarten or Wick).

process_term(term, matcher, dim, measure_type)

Integrates a single monomial term.

1. Index Collection: Traverses the term to find all random matrix elements using the matcher.
2. Dispatch: Calls specific index integration functions based on measure_type:
   • :U: integrate_indices (Weingarten)
   • :O: integrate_indices_orthogonal
   • :Sp: integrate_indices_symplectic
   • :GUE, :GOE, :GSE: Wick contraction rules.

weingarten(partition_type::Vector{Int}, d)

Computes the Unitary Weingarten function \text{Wg}(\sigma, d) where \sigma is a permutation with cycle type given by partition_type.

The Weingarten function is defined as the sum over irreducible representations of S_n:

\[\text{Wg}(\sigma, d) = \frac{1}{(n!)^2} \sum_{\lambda \vdash n, \ell(\lambda) \le d} \frac{(f^\lambda)^2 \chi^\lambda(\sigma)}{s_\lambda(1^d)}\]

where f^\lambda is the dimension of the Sn irrep, \chi^\lambda(\sigma) is the character, and s\lambda(1^d) is the dimension of the U(d) irrep.

Reference:

• Collins, B., & Śniady, P. (2006). Integration with respect to the Haar measure on unitay, orthogonal and symplectic groups. Communications in Mathematical Physics.

ParityUnionFind

Union-find data structure with parity tracking for CSE integration. Tracks whether the path from a node to its root has odd or even parity.

weingarten_orthogonal_val(pi, sigma, d)

Returns the Orthogonal Weingarten function value \text{Wg}^O(\pi, \sigma, d).

Reference:

• Collins, B., & Śniady, P. (2006). Integration with respect to the Haar measure on unitary, orthogonal and symplectic groups.

weingarten_symplectic_val(pi, sigma, d)

Returns the Symplectic Weingarten function value \text{Wg}^{Sp}(\pi, \sigma, d). Uses the duality relation:

\[\\text{Wg}^{Sp}(\\pi, \\sigma, d) = (-1)^k \\text{Wg}^{O}(\\pi, \\sigma, -d)\]

where k is the number of pairs.

Reference:

• Collins, B., & Śniady, P. (2006). Integration with respect to the Haar measure on unitary, orthogonal and symplectic groups.

get_pair_partitions(n)

Generate all partitions of the set {1, ..., n} into n/2 disjoint pairs. n must be even. The number of such partitions is given by the double factorial (n-1)!!.

These partitions are also known as perfect matchings of the complete graph K_n.

get_matching_pair_partitions_filtered(indices)

Returns all pair partitions of 1..2k such that for every pair (a,b), indices[a] == indices[b].

canonicalize_pair_partition(p)

Returns a sorted list of pairs (min, max), sorted by min, to uniquely identify a matching.

conjugate_partition(part::Vector{Int})

Returns the conjugate partition \lambda' of a partition \lambda. The conjugate partition is obtained by transposing the Young diagram of \lambda. Mathematically, \lambda'i = \text{card}{j : \lambdaj \ge i}.

murnaghan_nakayama(lambda, mu)

Computes the character \chi^\lambda(\mu) of the symmetric group S_n for the irrep \lambda at the conjugacy class with cycle type \mu using the Murnaghan-Nakayama rule.

The rule states:

\[\chi^\lambda(\mu) = \sum_{T \in RIM(\lambda, \mu)} (-1)^{\text{ht}(T)}\]

where the sum is over "rim hook" tableaux of shape \lambda and content \mu.

Reference:

• Murnaghan, F. D. (1937). The characters of the symmetric group.
• Nakayama, T. (1940). On some finite group of substitutions.

character_at_id(part::Vector{Int})

Calculates the character of the symmetric group S_n at the identity element for the irreducible representation (irrep) corresponding to the partition part (\lambda). This is equivalent to the dimension f^\lambda of the irrep.

The dimension is given by the Hook Length Formula:

\[f^\\lambda = \\frac{n!}{\\prod_{(i,j) \\in \\lambda} h_{\\lambda}(i,j)}\]

where h_\lambda(i,j) is the hook length of the cell (i,j) in the Young diagram of \lambda.

Reference:

• Frame, J. S., Robinson, G. de B., & Thrall, R. M. (1954). The hook graphs of the symmetric group.

irrep_dimension(part::Vector{Int}, d)

Computes the dimension s_\lambda(1^d) of the irreducible representation of the unitary group U(d) (or the Schur polynomial at ones) corresponding to the partition \lambda.

The dimension is given by the Hook-Content Formula:

\[\text{dim}_d(\lambda) = \prod_{(i,j) \in \lambda} \frac{d + j - i}{h_\lambda(i,j)}\]

where h_\lambda(i,j) is the hook length and j-i is the content of the cell (i,j).

This implementation supports symbolic dimension d, returning a rational function in d.

Reference:

• Stanley, R. P. (1999). Enumerative Combinatorics, Vol. 2.

compute_symplectic_contraction(partition, indices, dim)

Computes prod_{(u, v) in partition} J(indices[u], indices[v]). J = [0 I; -I 0].

weingarten_orthogonal_val_canonical(c_pi, c_sigma, d)

Internal version of weingarten_orthogonal_val that assumes arguments are already canonical.

INTEGRATION_RULES

A dictionary mapping measure types (symbols) to their respective integration rule functions. Each rule function should have the signature (u_indices, u_bar_indices, dim, measure_type).