Tensor-Network Solver Gets a Major Overhaul for Hard Optimization Problems

A quietly influential piece of scientific software has just received its most significant upgrade yet. SpinGlassPEPS.jl, a Julia-based package that uses tensor networks to tackle Ising-like optimization problems on quasi-two-dimensional graphs, has reached version 2.0.1, and the changes go far beyond routine maintenance. The release consolidates what was once a sprawling collection of separately registered packages into a single installable unit, fixes result-affecting defects, and introduces diagnostic tools that researchers have long needed when no exact reference solution exists. For a community racing to find better ways of solving hard combinatorial problems, the update represents a meaningful step toward trustworthy, reproducible computation.

The package addresses a class of problems that sits at the heart of both physics and computer science: finding the lowest-energy configuration of spins on a lattice, the classic task of computing a ground state. These problems are computationally brutal in general, and they matter well beyond condensed matter theory. Many scheduling, routing and circuit-design challenges can be mapped onto Ising models, which is why quantum annealers and specialized Ising machines have attracted so much attention. Tensor networks offer a classical alternative, compressing the exponentially large space of spin configurations into structured objects that can be manipulated with controlled approximations. SpinGlassPEPS.jl implements this approach using projected entangled-pair-style constructions adapted to quasi-two-dimensional connectivity, including the Chimera graphs used by D-Wave quantum hardware.

The consolidation alone changes the user experience substantially. The original release consisted of four packages, SpinGlassTensors, SpinGlassNetworks, SpinGlassExhaustive and SpinGlassEngine, whose version numbers were kept in sync but whose interfaces gradually drifted apart. Renamed symbols lacked deprecation paths, leaving users with breakages and no guidance. Version 2.0.1 folds all four into internal modules of one package, so a single command, adding SpinGlassPEPS, installs the complete solver. The public surface shrinks from roughly 240 re-exported symbols to about 80 documented ones, while lower-level kernels remain accessible through the submodules for those who need them. It is a classic engineering trade: less clutter at the top, the same power underneath.

Two correctness fixes deserve particular attention because they affected results. The corner_matrix function, a core building block of the contraction scheme, failed on every SiteTensor input and permuted the trailing dimensions of VirtualTensor outputs. Meanwhile, the exhaustive GPU search launched too few execution blocks and returned incomplete spectra for problems with ten or more spins. Both defects are now covered by regression tests against independent dense references on CPU and GPU, including a deterministic ten-spin test that compares all 1024 GPU state codes and energies, produced by two 512-thread blocks, against complete CPU enumeration. The release also bundles the benchmark instances behind the original publication’s figures, which had previously been referenced but not distributed, closing a reproducibility gap that plagues much of computational science.

The most scientifically interesting addition is a discarded-weight diagnostic. Every truncating factorization in the contraction now records the relative weight it discards, accumulated in a task-local accumulator so that concurrent solves cannot mix statistics. A solve reports the sum and maximum of these discarded weights, along with how many truncations were forced by the bond-dimension cap rather than the singular-value tolerance, and how many of the offered singular values were retained. On a 128-spin instance, bond dimension 4 yields a total discarded weight of 3.1 times ten to the minus four, with all 18 truncations limited by the bond bound; at bond dimension 32 the figure drops to 5.6 times ten to the minus fourteen, with none of its four truncations bond-limited. In effect, users gain an internal warning light that was previously available only to those with an exact solution to compare against.

The diagnostics come with honest caveats, which is refreshing in a field where optimism often outruns rigor. Discarded weight measures truncation loss in cold contractions, not warm-start error: a warm start optimizes within a fixed bond dimension without a truncating factorization, so it can report essentially zero discarded weight despite a nonzero variational gap. The package warns when the two are combined. Nor does discarded weight reliably rank solution quality. In benchmarks on ten 2500-spin square-lattice instances, the median accumulated discarded weight peaked at inverse temperature 4, where the median energy error was smaller, while at inverse temperature 2 the discarded weight was near its minimum but the energy error was largest. The documentation now positions the diagnostic as a contraction indicator and optional preference filter, not a selection criterion.

Performance work runs throughout the release. A new beta_ladder feature evaluates an increasing schedule of the inverse temperature, which controls how strongly the solver’s branch probabilities favor low-energy states. When a retained boundary matrix product state has the dimensions required by the next rung, it warm-starts variational compression instead of building the target state exactly and truncating it. On a 2048-spin instance where boundary construction dominates, the two warmed rungs saw wall times fall by about 24 and 25 percent, with identical energies, translating to roughly 16 percent over the full ladder. Meanwhile, a sweep over eight lattice transformations now runs concurrently, with a calibration solve estimating peak memory and admitting tasks within a byte budget. On an Intel Xeon Platinum 8462Y+ processor, CPU speed-ups reached 3.1 times for a 36-spin case at eight concurrent solves, and identical energies were returned in every serial and concurrent configuration tested.

Perhaps the most surprising finding concerns hardware. The original publication recommended GPU execution for larger examples, but on the tested Xeon and NVIDIA H100 system, the GPU won in only one matched configuration: a 2048-spin sparse instance at bond dimension 32, where the CPU-to-GPU wall-clock ratio was 1.45. At 36 spins, CPU wall time was roughly 2 percent of GPU time. Profiling explains why: on a 128-spin solve, host-side CUDA API calls occupied 27 percent of the profiled interval while GPU activities occupied just 6.6 percent, meaning at least two-thirds of the time lay outside both categories. Even eliminating the entire measured CUDA API overhead would cap speed-up at about 1.4 times by Amdahl’s law. Faster tensor kernels alone cannot fix a problem that lives on the host side.

So the developers attacked host allocation instead. In the previous implementation, a function called branch_states accounted for 52.7 percent of the bytes allocated by a 128-spin solve, spawning tens of thousands of small vectors per call; a single matrix now stores branched configurations instead. Contraction temporaries were moved off the garbage-collected heap, cutting allocated bytes on a corresponding CPU solve from 90.9 to 32 gibibytes, a reduction of about two thirds. The post-change totals were 32.3 gibibytes on CPU and 24.1 gibibytes on GPU for a 2048-spin, bond-32 solve. These are the unglamorous numbers that determine whether a scientific tool feels responsive or sluggish, and they illustrate how modern performance engineering often means fighting the runtime environment rather than the mathematics.

Version 2.0.1, archived on Zenodo and released under the Apache License 2.0, arrives as debate intensifies over whether classical algorithms can match specialized quantum and analog Ising machines. A companion study comparing tensor-network approaches to quantum and classical Ising machines suggests the answer is nuanced, and honest tooling like this strengthens the comparison. With one public API, deprecation shims for renamed entry points, distributed benchmark instances and raw per-run data with runnable drivers, the release models what reproducible computational research should look like. The work was supported by the National Science Centre, Poland, and the package’s developers, Łukasz Pawela and Bartłomiej Gardas, have made clear-eyed limitations part of the documentation itself. For anyone using tensor networks to hunt ground states, the message is simple: the toolkit got faster, safer and considerably more transparent, and it now tells you when it might be wrong.

Subject of Research: A tensor-network software package for solving Ising-like optimization problems on quasi-two-dimensional graphs

Article Title: Version 2.0.1 – SpinGlassPEPS.jl: Tensor-network package for Ising-like optimization on quasi-two-dimensional graphs

Article References: Pawela, Ł., & Gardas, B. (2026). Version 2.0.1 – SpinGlassPEPS.jl: Tensor-network package for Ising-like optimization on quasi-two-dimensional graphs. SoftwareX, 36, Article 103027. https://doi.org/10.1016/j.softx.2026.103027

Image Credits: AI Generated

DOI: 10.1016/j.softx.2026.103027

Keywords: tensor networks, Ising optimization, SpinGlassPEPS.jl, Julia language, ground state computation, GPU computing, high-performance computing, combinatorial optimization, reproducibility, software engineering, spin glasses, quantum annealing