Major refactor (#21)

* new consistent interface

* update symbolic matrix and its docs

* update interface

* another iteration

* make tests pass

* make test and examples pass

* almost working

* consistency

* fix performance, make tests, exampels and benchmarks pass

* update manuscript

* cleanup comments

* update docs

* cleanup obsolete macros

* fix includes

* fix tests

* update memory allocations

* fix tags

* ux improvments and centered permutation optimization

* minot optimizations

* remove try catch blocks

* remove all try catch blocks

* clenaup manuscript

* update readme

* reformat

* fix symbols in manuscript

* refactor interface

* refactor gaussian measures

* refactor integration core

* refator type hierarchy

* minor refactors

* fix macro inconsistency

* fix symbols in @integrate

* fix docs

* fix docs

* make more consistent

* make docs more consistent

* fix itensors

* update authors

* update kronecker products

* fix krons and symplectic itnegration

* fix evaluate

* fix docstring

Author: lpawela

Project.toml

@@ -1,18 +1,19 @@
 name = "IntU"
 uuid = "70c8b9a1-b4c5-4d7a-a56e-8e7e6495d68b"
-version = "0.8.0"
+version = "0.9.0"
 authors = ["Łukasz Pawela", "Zbigniew Puchała"]
 
 [deps]
 Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 Memoization = "6fafb56a-5788-4b4e-91ca-c0cea6611c73"
 SymbolicUtils = "d1185830-fcd6-423d-90d6-eec64667417b"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 
 [weakdeps]
-ITensors = "9136182c-28ba-11e9-034c-db136f33ea42"
+ITensors = "9136182c-28ba-11e9-034c-db9fb085ebd5"
 
 [extensions]
 IntUITensorsExt = "ITensors"
@@ -21,11 +22,12 @@ IntUITensorsExt = "ITensors"
 Aqua = "0.8.14"
 Combinatorics = "1"
 DataStructures = "0.19.3"
+ITensors = "0.3, 0.6"
 LinearAlgebra = "1.11, 1.12"
+MacroTools = "0.5.16"
 Memoization = "0.2.2"
 SymbolicUtils = "4"
 Symbolics = "7"
-ITensors = "0.3, 0.6"
 Test = "1.11, 1.12"
 julia = "1.11, 1.12"
 

README.md

@@ -17,50 +17,45 @@ To introduce the main functionality of IntU, consider the problem of averaging
 $|U_{i,j}|^2$ over the unitary group, i.e., computing $\int dU |U_{i,j}|^2 =
 \int dU U_{i,j} U_{k,l}^* dU$.
 
-While numerical approaches (like sampling random matrices) can estimate this,
-they are slow and approximate. IntU provides the **exact** analytic result
-instantly, even for symbolic dimensions.
+IntU provides an exact analytic result instantly, even for symbolic dimensions, using a simple unified interface: `integrate(expr, measure)`. It supports matrix-valued expressions and provides the `@integrate` macro for intuitive symbolic integration.
+
+The `@integrate` macro implicitly identifies random matrices based on the measure:
+- `dU`, `dSU` $\rightarrow$ `U` (Unitary)
+- `dO` $\rightarrow$ `O` (Orthogonal)
+- `dSp` $\rightarrow$ `Sp` (Symplectic)
+- `dPerm` $\rightarrow$ `P` (Permutation)
+- `dCPerm` $\rightarrow$ `Y` (Centered Permutation)
+- `dCOE`, `dCSE` $\rightarrow$ `S` (Circular Orthogonal/Symplectic)
+- `dPsi` $\rightarrow$ `psi` (Pure State)
+- `dDiagUnitary` $\rightarrow$ `D` (Diagonal Unitary)
+- `dStiefel` $\rightarrow$ `V` (Stiefel Manifold)
+- Ginibre Ensembles $\rightarrow$ `G`
+
+Unknown symbols (like `A`, `B`, `d`) are automatically treated as constants or dimensions.
+
+> [!NOTE]
+> **Symbol Scope and Redefinition**: The `@integrate` macro manages a persistent symbolic state in your session. If you use a symbol (e.g., `U`) as a random matrix in one call and then use it in a different context (e.g., as a constant in an orthogonal integral), the macro automatically re-declares and re-binds the symbol to the correct type and measure context. This "Safety Rebind" mechanism prevents silent math errors when running examples in sequence.
 
-**New Feature**: You can now integrate matrix-valued expressions directly!
 ```julia
 using IntU, Symbolics, LinearAlgebra
 
-d = 3
-@variables U[1:d, 1:d]::Complex
-measure = dU(U, d)
-
 # Integrate the matrix expression U * U'
-# This performs element-wise integration automatically
-res = integrate(collect(U * U'), measure)
-# Output: Identity Matrix (I)
+# The @integrate macro knows 'U' is the random matrix for measure dU(2)
+res = @integrate U * U' dU(2)
+# Output: [1.0 0.0; 0.0 1.0] (2x2 Identity Matrix)
 ```
 
 ```julia
-using IntU, Symbolics
-
-# Define symbolic dimension 'd' and a unitary matrix 'U'
-@variables d
-@variables U[1:d, 1:d]::Complex
-
-# Define the Haar measure
-measure = dU(U, d)
-
-# Compute the integral of |U_{i,j}|^2
-# Note: IntU handles symbolic indices automatically if defined, 
-# but here we use concrete 1,1 for simplicity which yields the same result by symmetry.
-integrate(abs(U[1,1])^2, measure)
-# Output: 1 / d
-
-# New: Convenient measure constructors
-measure = dU(d) # No matrix variable required
-integrate(abs(U[1,1])^2, measure)
+using IntU
+# Compute the integral of |U_{1,1}|^2
+@integrate abs(U[1, 1])^2 dU(d)
 # Output: 1 / d
 ```
 
 For more complex moments, such as $\int dU |U_{1,1}|^2 |U_{1,2}|^2$, IntU handles the combinatorics (Weingarten functions) automatically:
 
 ```julia
-integrate(abs(U[1,1])^2 * abs(U[1,2])^2, measure)
+@integrate abs(U[1, 1])^2 * abs(U[1, 2])^2 dU(d)
 # Output: 1 / (d * (1 + d))
 ```
 
@@ -75,15 +70,15 @@ can calculate averages over the unitary Haar measure using `dU` and `integrate`.
 
 ```julia
 # 4-th moment of a diagonal entry
-integrate(abs(U[1,1])^4, dU(U, d))
+@integrate abs(U[1, 1])^4 dU(d)
 # Output: 2 / (d * (1 + d))
 ```
 
 ### Special Unitary Group
 The Special Unitary group $SU(d)$ consists of unitary matrices with determinant 1. Use `dSU`.
 
 ```julia
-integrate(abs(U[1,1])^2, dSU(U, d))
+@integrate abs(U[1, 1])^2 dSU(d)
 # Output: 1/d
 ```
 
@@ -92,18 +87,16 @@ Orthogonal matrices $O$ are real matrices satisfying $O O^T = I_d$. Averages are
 computed using the `dO` measure.
 
 ```julia
-@variables O_mat[1:d, 1:d]::Real
-integrate(O_mat[1,1]^4, dO(O_mat, d))
+@integrate O[1, 1]^4 dO(d)
 # Output: 3 / (d * (2 + d))
 ```
 
 ### Symplectic group
-Symplectic matrices $S$ are unitary matrices of even dimension $2n$ that
-preserve the symplectic form, $S \Omega S^T = \Omega$. Use `dSp`.
+Symplectic matrices $Sp$ are unitary matrices of even dimension $2n$ that
+preserve the symplectic form, $Sp \Omega Sp^T = \Omega$. Use `dSp`.
 
 ```julia
-@variables S_mat[1:d, 1:d]::Complex
-integrate(abs(S_mat[1,1])^2, dSp(S_mat, d))
+@integrate abs(Sp[1, 1])^2 dSp(d)
 # Output: 1 / d
 ```
 
@@ -114,12 +107,8 @@ Ginibre ensembles consist of non-Hermitian matrices with i.i.d. Gaussian entries
 - **GinSE (Symplectic Ginibre Ensemble)**: i.i.d. quaternionic Gaussian entries. Use `dGinSE`.
 
 ```julia
-@variables d
-# Use T=Complex{Num} for GinUE to ensure conj(G) != G
-G = [Symbolics.variable(:G, i, j, T=Complex{Num}) for i = 1:2, j = 1:2]
-# E[Tr(G G')] = d^2 = 4 (for 2x2 matrix)
-integrate(tr(G * G'), dGinUE(G, d))
-# Output: 4
+# E[Tr(G G')] = d^2
+@integrate tr(G * G') dGinUE(d)
 ```
 
 ### Circular Ensembles
@@ -129,9 +118,8 @@ IntU also supports Circular Ensembles (CUE, COE, CSE) which are commonly used in
 - **CSE (Circular Symplectic Ensemble)**: Ensemble of self-dual unitary matrices of even dimension $2n$. Use `dCSE`.
 
 ```julia
-@variables S_coe[1:d, 1:d]::Complex
 # COE moment E[|S_{1,1}|^2]
-integrate(abs(S_coe[1,1])^2, dCOE(S_coe, d))
+@integrate abs(S[1, 1])^2 dCOE(d)
 # Output: 2 / (d + 1)
 ```
 
@@ -140,29 +128,27 @@ IntU can integrate polynomial functions of the components of a Haar-random pure
 state vector $|\psi\rangle$ of dimension $d$.
 
 ```julia
-@variables dim
-@variables psi[1:dim]::Complex
-measure_psi = dPsi(psi, dim)
-
 # Average of |ψ_1|^2
-integrate(abs(psi[1])^2, measure_psi)
-# Output: 1 / dim
+@integrate abs(psi[1, 1])^2 dPsi(d)
+# Output: 1 / d
 ```
 
-### Permutation Groups
-IntU supports integration over the Symmetric Group $S_d$ (permutation matrices) and centered permutation matrices $Y = P - J/d$.
+### Permutation Group
+IntU supports integration over the Symmetric group $S_d$ (permutation matrices).
+- **dPerm**: Integration over the set of $d \times d$ permutation matrices.
+
+```julia
+# E[P_11]
+@integrate P[1, 1] dPerm(d)
+# Output: 1 / d
+```
+
+IntU also supports centered permutation matrices $Y = P - J/d$.
+- **dCPerm**: Integration over centered permutation matrices.
 
 ```julia
-@variables P[1:d, 1:d]
-measure = dPerm(P, d)
-# E[P_11 * P_22]
-integrate(P[1,1] * P[2,2], measure)
-# Output: 1 / (d * (d - 1))
-
-@variables Y[1:d, 1:d]
-m_centered = dCPerm(Y, d)
 # E[Y_11^2]
-integrate(Y[1,1]^2, m_centered)
+@integrate Y[1, 1]^2 dCPerm(d)
 # Output: (d - 1) / d^2
 ```
 
@@ -171,11 +157,8 @@ IntU supports integration over the group of diagonal unitary matrices, which
 corresponds to independent phase averaging for each diagonal entry.
 
 ```julia
-@variables V[1:d, 1:d]::Complex
-measure = dDiagUnitary(V, d)
-
-# E[|V_11|^2]
-integrate(abs(V[1,1])^2, measure)
+# E[|D_11|^2]
+@integrate abs(D[1, 1])^2 dDiagUnitary(d)
 # Output: 1
 ```
 
@@ -184,13 +167,8 @@ IntU supports index-free notation for integrating traces of products of random
 matrices, which is often more convenient for quantum information tasks.
 
 ```julia
-using IntU: tr
-# Define symbolic matrices A, B (constant) and U (random)
-A = SymbolicMatrix(:A)
-B = SymbolicMatrix(:B)
 # Compute ∫ tr(U A U† B) dU
-expr = tr(SymbolicMatrix(:U, false, :U) * A * SymbolicMatrix(:U, true, :U) * B)
-integrate(expr, dU(d))
+@integrate tr(U * A * U' * B) dU(d)
 # Output: (tr(A)*tr(B)) / d
 ```
 
@@ -210,13 +188,8 @@ hciz(A, B)
 IntU supports integration over the Stiefel manifold $V_k(\mathbb{C}^d)$, which represents the set of $d \times k$ matrices with orthonormal columns. This generalizes Haar-random pure states ($k=1$).
 
 ```julia
-@variables d
-k = 2
-V = [Symbolics.variable(Symbol("V_$(i)_$(j)"), T=Complex{Num}) for i=1:3, j=1:k] 
-measure = dStiefel(V, d, k)
-
 # E[|V_{1,1}|^2]
-integrate(abs(V[1,1])^2, measure)
+@integrate abs(V[1, 1])^2 dStiefel(d, 2)
 # Output: 1 / d
 ```