Welcome to SpinGlassPEPS.jl documentation!

Welcome to SpinGlassPEPS.jl, an open-source Julia package for heuristic optimization on Ising-type problems defined on quasi-2D lattices.

Overview

In this section we will provide a condensed overview of the package.

SpinGlassPEPS.jl is one Julia package containing the complete solver stack. It supports Julia 1.11 and can be installed from the package prompt with

using Pkg; 
Pkg.add("SpinGlassPEPS")

SpinGlassPEPS.jl is distributed as one package. Internally, its source is organized into four modules: model and lattice construction, tensor operations, the PEPS solver, and exhaustive-search routines. All public functionality is available after a single using SpinGlassPEPS; the components do not need to be installed or loaded separately.

Our goals

SpinGlassPEPS.jl uses tensor-network contractions to estimate the conditional probabilities required by a branch-and-bound search. It reconstructs low-energy spectra of Ising spin-glass and more general Potts Hamiltonians. In addition to configurations and probabilities, it reports contraction diagnostics such as accumulated and maximum discarded weight. It can also reconstruct low-energy spectra from localized excitations called spin-glass droplets.

Citing SpinGlassPEPS.jl

If you use SpinGlassPEPS.jl for academic research and wish to cite it, please use the following papers:

• Article describing the package and its implementation.

@article{SpinGlassPEPS.jl,
    author = {Tomasz \'{S}mierzchalski and Anna Maria Dziubyna and Konrad Ja\l{}owiecki and Zakaria
    Mzaouali and {\L}ukasz Pawela and Bart\l{}omiej Gardas and Marek M. Rams},
    title = {{SpinGlassPEPS.jl}: Tensor-network package for {Ising}-like optimization on quasi-two-dimensional graphs},
    journal = {SoftwareX},
    volume = {31},
    pages = {102257},
    year = {2025},
    doi = {10.1016/j.softx.2025.102257},
}

• Article describing the algorithms and their benchmark evaluation.

@article{SpinGlassPEPS, 
    author = {Anna Maria Dziubyna and Tomasz \'{S}mierzchalski and Bart\l{}omiej Gardas and Marek M. Rams and Masoud Mohseni},
    title = {Limitations of tensor-network approaches for optimization and sampling: A comparison to quantum and classical {Ising} machines},
    journal = {Physical Review Applied},
    volume = {23},
    pages = {054049},
    year = {2025},
    doi = {10.1103/PhysRevApplied.23.054049},
}

Contributing

Contributions are always welcome:

• Please report any issues and bugs that you encounter in Issues
• Questions about SpinGlassPEPS.jl can be asked by directly opening up an Issue on its GitHub page
• If you plan to contribute new features, extensions, bug fixes, etc, please first open an issue and discuss the feature with us.