beta_ensembles

beta_ensembles is a Python package for numerical work with random matrix ensembles, with a particular focus on the Gaussian, Laguerre, Jacobi, and Circular beta ensembles. A central feature of the package is the ability to generate spectra for general positive values of the Dyson index $\beta$, rather than restricting calculations to the classical values $\beta=1$, 2, and 4.

For the Gaussian and Laguerre beta ensembles, the package implements the tridiagonal and bidiagonal matrix constructions introduced by Dumitriu and Edelman. Likewise, for Jacobi ensembles it uses the tridiagonal construction of Killip and Nenciu. These constructions reduce spectrum generation to the diagonalization of symmetric tridiagonal matrices, making it possible to efficiently generate spectra of large matrices at arbitrary $\beta$ without constructing dense random matrices.

For the Circular beta ensemble, the package uses the Killip–Nenciu construction, which similarly provides an explicit matrix model for arbitrary positive $\beta$. In the present implementation, however, the resulting structured matrices are diagonalized using standard dense-matrix routines, so spectrum generation is substantially less efficient than for the other ensembles at large $N$.

The beta-ensemble generators are designed to generate eigenvalue spectra rather than generic random matrices, and therefore return the spectra directly without constructing a full dense random matrix.

In addition to spectrum generation, the package provides tools for unfolding eigenvalues, computing spectral statistics, fitting random-matrix predictions to numerical data, and studying spectral form factors. The package is intended primarily as a research and educational tool, with an emphasis on transparent implementations of standard constructions and on making numerical experiments with random matrix theory straightforward to reproduce.

The package requires Python and standard scientific Python dependencies, including NumPy, SciPy, and Matplotlib.

The package documentation is supplemented by a technical note, available on the arXiv at nlin.CD/2608.27224. The note provides the necessary mathematical background, establishes the conventions and notation used throughout the package, and describes the numerical experiments implemented in the example notebooks.

Installation

The package is available on PyPI and can be installed with:

pip install beta-ensembles

Alternatively, the latest version can be installed directly from the GitHub repository:

pip install git+https://github.com/dorinw/beta_ensembles.git

Features

The package currently implements:

• Spectrum generation for Gaussian beta ensembles (GBE) at general $\beta$
• Spectrum generation for Laguerre beta ensembles (LBE) at general $\beta$
• Spectrum generation for Jacobi beta ensembles (JBE) at general $\beta$
• Spectrum generation for Circular beta ensembles (CBE) at general $\beta$
• Implementation of all twelve classical ensembles corresponding to the four families of beta-ensembles at $\beta=1$, 2, and 4.
• Spectral unfolding utilities for generated spectra
• Nearest-neighbor spacings and spacing ratios
• $k$-spacings and $k$-spacing ratios
• Fits to spacing and ratio distributions
• Spectral form factor calculations
• Analytical predictions for the spectral form factor in the interpolating regime $1 \leq \beta \leq 4$
• Plotting utilities for common random-matrix statistics

Basic usage

The basic workflow is to generate many spectra from an ensemble, unfold the resulting eigenvalues, and then compute the desired spectral statistics. For example, the following code defines the Gaussian beta ensemble with $\beta=1.5$ and matrix size $N=100$:

import beta_ensembles as be

beta = 1.5
N = 100

ens = be.gaussian.Ensemble(beta, N)

The package is designed such that the analysis workflow is largely independent of the choice of ensemble. The following generates an array containing 2000 spectra from the chosen ensemble:

n_spectra = 2000
spectra = ens.spectra(n_spectra)

The spectra can be unfolded and used to compute the nearest-neighbor spacings and spacing ratios:

unfolded = ens.unfold(spectra)

spacings = be.spacings(unfolded)
ratios = be.ratios(unfolded)

The package also contains fitting routines for comparing numerical data with analytical distributions and surmises. For example, the Dyson index can be estimated from the spacing ratios and the resulting fit compared with the corresponding analytical PDF:

beta_fit = be.fit_ratios(ratios)

be.plot.hist_r(ratios)
be.plot.pdf_r(beta_fit)

Examples

The repository contains the following notebooks:

• Basic usage tutorial: introduction to the package and its basic usage
• ex0_spacing_analysis_tutorial: demonstration of spectral statistics for the Gaussian, Laguerre, and Circular ensembles
• ex1a_fitting_beta: fitting numerical data to random-matrix predictions and estimating $\beta$
• ex1b_goodness_of_fit: assessing the quality of fits using goodness-of-fit tests and estimating uncertainties in the fitted value of $\beta$
• ex2_k_spacing_ratios: analysis of $k$-spacing ratios
• ex3_spectral_form_factor: numerical analysis of the spectral form factor
• Jacobi: demonstration of spectral statistics of the Jacobi beta ensemble

These notebooks are intended as practical examples of numerical studies that can be performed with the package. They can also serve as starting points for experimenting with other ensemble parameters, matrix sizes, and spectral observables.

Citation

If you find this package useful in your research, please consider citing the accompanying technical note on the arXiv and the software release on Zenodo:

• Exploring continuous beta-ensembles: A Python implementation for random matrix spectral statistics [arXiv:nlin.CD/2608.27224]
• beta_ensembles: A Python package for continuous beta-ensembles [DOI:10.5281/zenodo.22127517]