ReplicaTN

A self-contained replica tensor network (RTN) library for averaged random-circuit observables, designed as the companion code for the SciPost Lecture Notes Replica Tensor Networks for Random Quantum Circuits.

The package provides a minimal single-header C++ MPS engine, a pybind11 frontend, the symbolic combinatorics of the symmetric, Brauer, and Clifford commutants, and a set of figure drivers that reproduce every worked example in the lecture notes.

At a glance

ReplicaTN/
├── cpp/             # single-header C++ engine + figure drivers
│   ├── ReplicaTN.h      # Tensor + MPS primitives, BLAS / LAPACK backed
│   ├── Makefile         # auto-detects Accelerate (macOS) / OpenBLAS (Linux)
│   └── src/             # one .cc per figure of the lecture notes
├── python/          # pybind11 frontend
│   ├── replicatn_py.cpp # bindings to the C++ engine
│   ├── Makefile         # auto-detects BLAS (Accelerate / OpenBLAS / vendor)
│   └── replicatn/       # Python package: _core + algebra + brickwork
├── tutorials/       # student-facing Jupyter notebooks (no solutions)
└── scripts/         # Python helpers for dumping the per-N input CSVs

Quick start

Build the C++ figure drivers

cd cpp
make -j

This produces binaries under cpp/build/, one per figure of the lecture notes:

• fig1_ipr_unitary — IPR of Haar-unitary brickworks (k = 2, 3)
• fig2_purity — half-chain Rényi-2 / Rényi-3 local purity
• fig3_coherence — relative entropy of coherence under depolarising noise
• fig4_coherent_info — Rényi-2 coherent information
• fig5_xeb — asymmetric linear cross-entropy benchmark
• fig6_ipr_orthogonal — orthogonal-Haar IPR (Brauer commutant)
• fig7_ipr_clifford — Clifford-random qutrit circuit IPR

Run any driver with --help to see its arguments. Inputs (gate, boundary, init CSV files) are dumped via the Python helper (numpy is the only runtime dependency):

python3 scripts/dump_inputs.py --basis sym --k 2 --d 2 --N 16 \
        --observable renyi --A_size 8 --outdir /tmp/fig2_N16/N16

Build the Python frontend

Requires pybind11 in the Python you build with:

python3 -m pip install pybind11    # one-time
cd python
make                                # or:  make PYTHON=/path/to/python3

The Makefile auto-detects the platform:

• macOS → links against the Apple Accelerate framework (always present on the system, no extra install).
• Linux → uses pkg-config to find OpenBLAS (or generic LAPACK + BLAS) at the standard paths. On Debian/Ubuntu install libopenblas-dev liblapack-dev; on Fedora openblas-devel lapack-devel; on Arch openblas lapack.

To force a vendor BLAS (MKL, AOCL, BLIS, …) override the link flags:

make BLAS_LDFLAGS="-lmkl_rt -lpthread -ldl -lm"     # Intel MKL
make BLAS_LDFLAGS="-lopenblas -llapack -lpthread"   # explicit OpenBLAS

The same BLAS_LDFLAGS hook works for cpp/Makefile.

Smoke-test:

import sys; sys.path.insert(0, '/path/to/ReplicaTN/python')
import replicatn as rtn
B = rtn.SymmetricBasis(2)
print(rtn.gram_matrix(B, 2))         # [[4, 2], [2, 4]]
print(rtn.weingarten_matrix(B, 2))

Run the tutorials

The tutorials/ directory contains Jupyter notebooks that walk the reader through the end-to-end RTN evaluation of the IPR, the half-chain Rényi-2 purity, the relative entropy of coherence, and the Setup-II coherent information. The cells contain the boundary conditions and bulk gates pre-computed, but the brickwork sweep and the boundary contraction are left as TODO for the student. Solutions are not included in this release; they are circulated separately during the school.

To run them:

cd tutorials
jupyter notebook .

Python API summary

The high-level surface mirrors the code listings of the lecture notes.

Object	Description
rtn.SymmetricBasis(k)	$S_k$ commutant basis ($k!$ permutations)
rtn.BrauerBasis(k)	Brauer commutant basis ($(2k-1)!!$ pair-diagrams)
rtn.CliffordBasis(k=3, d=3)	Clifford commutant for qutrits at $k=3$
rtn.gram_matrix(B, q)	Gram matrix of B at parameter q
rtn.weingarten_matrix(B, q)	Weingarten matrix Wg(q) = G(q)^{-1}
rtn.averaged_gate_tensor(B, d)	Dressed two-site averaged gate $\widetilde{\mathcal{T}}^{(k)}$
rtn.initial_amplitudes(B, d)	Per-site initial amplitudes for $
rtn.IPRBoundary(B, d)	Top boundary for $\mathbb{E}[\mathcal{I}^{(k)}]$
rtn.RenyiPurityBoundary(B, d, A)	Top boundary for $\mathbb{E}[\mathrm{Tr}(\rho_A^k)]$
rtn.OTOCBoundary(B, d, n=1)	Top boundary for the $n$-point OTOC
rtn.identity_choi(d)	Choi matrix of the identity channel
rtn.depolarizing_choi(d, p)	Choi matrix of the depolarising channel of strength p
rtn.coherent_rotation_choi(d, alpha)	Choi of a coherent $Z$-rotation by angle $\alpha$
rtn.noise_primal_transfer(B, d, channels)	Single-site noise transfer in the primal basis
rtn.brickwork_average(B, d, N, t, bnd, *, cutoff, maxdim)	High-level driver: depth-$t$ brickwork on $N$ sites, contracted with bnd
rtn.noisy_brickwork_average(B, d, N, t, bnd, channels, *, cutoff, maxdim)	Same with per-site noise inserted after every layer

The low-level C++ primitives are exposed under rtn._core (Tensor, MPS, product_mps, boundary_mps, apply_two_site, apply_one_site, brickwork_layer, inner, normalize, ...) for users who want to roll their own driver.

Citation

If you use ReplicaTN in your work, please cite:

@misc{turkeshi2026replicatn,
  author       = {Turkeshi, Xhek},
  title        = {ReplicaTN: replica tensor networks for random quantum circuits},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.XXXXXXX},
  url          = {https://doi.org/10.5281/zenodo.XXXXXXX}
}

and the companion lecture notes:

@misc{turkeshi2026leshouches,
  author       = {Turkeshi, Xhek},
  title        = {Replica Tensor Networks for Random Quantum Circuits},
  journal      = {arXiv},
  eprint       = {2605.xxxxx},
  year         = {2026},
}

License

MIT. See LICENSE.

See also

ReplicaTN ships a deliberately minimal MPS engine sized to the replica-tensor-network brickwork kernels of the lecture notes — no DMRG, no infinite MPS, no symmetry sectors, no GPU. For any tensor-network workload beyond these drivers I recommend one of the established production libraries:

ITensor — M. Fishman, S. R. White, E. M. Stoudenmire, SciPost Phys. Codebases 4 (2022), DOI 10.21468/SciPostPhysCodeb.4, github.com/ITensor/ITensor.

TeNPy — J. Hauschild, F. Pollmann, SciPost Phys. Lect. Notes 5 (2018), DOI 10.21468/SciPostPhysLectNotes.5, github.com/tenpy/tenpy.