IntegrateUnitary.jl Documentation

Welcome to the documentation for IntegrateUnitary.jl, a generic symbolic integration engine for random matrices and quantum states.

Getting Started

IntegrateUnitary.jl is designed to make "back-of-the-envelope" calculations in Random Matrix Theory and Quantum Information exact and automated.

Installation

using Pkg
Pkg.add(url="https://github.com/iitis/IntegrateUnitary.jl")

Reproducible Setup From a Checkout

For paper-grade reproducibility, use a tagged checkout (for this manuscript: v1.0.0) and instantiate the pinned project environments used by the examples and benchmarks:

using Pkg
Pkg.activate("examples"); Pkg.instantiate()
Pkg.activate("benchmarks"); Pkg.instantiate()

This uses the versioned Manifest.toml files in examples/ and benchmarks/.

The @integrate Macro

For more intuitive symbolic integration, IntegrateUnitary.jl provides the @integrate macro. It automatically identifies random matrices based on the measure and manages variable declarations.

@integrate expr measure

[!TIP] Symbol Scope and Redefinition: The macro manages a persistent symbolic state. If a symbol is used in one context (e.g., as a random matrix for dU) and then in another (e.g., as a constant for dO), the macro automatically re-binds it to the correct type. This "Safety Rebind" prevents silent mathematical errors during sequential execution.

Common Interface

The primary way to interact with IntegrateUnitary.jl is through the integrate function. It provides a unified interface for all supported groups and ensembles.

integrate(expr, measure)

expr: A symbolic expression (e.g., product of SymbolicMatrix elements) or an array of such expressions.
measure: A measure object defining the group/ensemble and its dimension (e.g., dU(d), dO(d), dGUE(d)).

Choosing a Measure

If you want to average over…	Measure	Page
Generic random unitary matrices	`dU(d)`	Unitary Integration
Special unitary (balanced polynomials)	`dSU(d)`	Unitary Integration
Real orthogonal matrices	`dO(d)`	Orthogonal & Symplectic
Symplectic matrices ($d$ even)	`dSp(d)`	Orthogonal & Symplectic
Haar-random unitary matrices (CUE)	`dCUE(d)`	Circular Ensembles
Symmetric unitary matrices (COE)	`dCOE(d)`	Circular Ensembles
Self-dual unitary matrices (CSE)	`dCSE(d)`	Circular Ensembles
Hermitian random matrices	`dGUE(d)` / `dGOE(d)` / `dGSE(d)`	Gaussian Ensembles
Non-Hermitian random matrices	`dGinUE(d)` / `dGinOE(d)` / `dGinSE(d)`	Gaussian Ensembles
Random permutation matrices	`dPerm(d)`	Permutation Groups
Centered permutation matrices	`dCPerm(d)`	Permutation Groups
Random pure states	`dPsi(d)`	Pure States
Orthonormal $k$-frames (Stiefel)	`dStiefel(d, k)`	Stiefel Manifolds
Independent diagonal phases	`dDiagUnitary(d)`	Diagonal Unitaries
Moments up to order $t$ only	`dDesign(d, t)`	Unitary Integration

Manual

Unitary Integration: Core functionality for $U(d)$ and $SU(d)$ (balanced polynomials).
Diagonal Unitaries: Integration over the Torus group.
Orthogonal & Symplectic: Integration over real groups.
Gaussian Ensembles: GUE, GOE, and GSE.
Circular Ensembles: COE, CUE, and CSE.
Permutation Groups: Symmetric and centered permutations.
Pure States: Integration over random vectors.
Stiefel Manifolds: Integration over Stiefel manifolds $V_k(\mathbb{C}^d)$.
Symbolic Trace Logic: Index-free matrix integration.
Asymptotic Expansions: Large-$d$ limit analysis.
Integral Library: Pre-computed standard results.
QI Helpers: Partial trace and quantum information helpers.
ITensors Integration: Symmetric integration of tensor networks.

API Reference

See the API Reference for detailed function signatures.