quimb splits quantum many-body work into a tensor path and a matrix path

One package, two different representations of a quantum state

quimb is described as an easy but fast Python library for quantum information many-body calculations, focusing primarily on tensor networks. The design choice that matters to a user is that the package is split in two, and the split follows how the state is represented rather than how the physics is organised.

The `quimb.tensor` module holds tensors and tensor networks, with a stated focus on automatically handling arbitrary geometry, beyond one and two dimensional lattices. The listed capabilities there include constructing and manipulating arbitrary hypergraphs of tensor networks, automatically contracting, optimizing and drawing them, running specific MPS, PEPS, MERA and quantum circuit algorithms such as DMRG and TEBD, and using backend array libraries through autoray.

The core `quimb` module takes the other route. There the states and operators are represented as either `numpy.ndarray` or `scipy.sparse` matrices, and the listed capabilities are constructing operators in complicated tensor spaces, finding groundstates and excited states, doing time evolutions including with slepc, computing quantities such as entanglement measures, taking advantage of numba accelerations, and stochastically estimating Tr f(X) quantities.

So the package serves two audiences in one import. Someone studying entanglement in a two dimensional lattice can stay in the tensor module and never build a dense matrix. Someone checking a small system exactly against a tensor result can switch to the matrix module without leaving the library. The cost of that design is a split API surface: the two modules do not share one uniform set of call signatures, and learning quimb means learning which representation each function expects.

autoray decides how your arrays are actually computed

The tensor module does not hardcode numpy. It reaches backend array libraries such as jax and torch through autoray, a separate project by the same author, and the README pairs that with symmray for symmetries and fermions. In practice that means a tensor in quimb can be a jax array or a torch tensor, and the contraction and derivative machinery follows whatever backend the data is in.

That choice has consequences on both sides. On the useful side, a user with an existing jax or torch pipeline can keep their arrays on their chosen device and let quimb operate on them, rather than converting to numpy at every boundary. On the cost side, quimb is only as capable as the union of its backends, and some features work in one backend but not another. The README does not document a per-feature support matrix, so the honest answer for any specific function is that behaviour depends on the backend and on the optional packages installed alongside it.

The optional dependency groups show how wide that surface is. The recommended group pulls in autograd, cmaes, cotengrust, kahypar, matplotlib, networkx, plotly and pygraphviz, which together cover automatic differentiation, optimisation, faster contraction routines, hypergraph partitioning and drawing. The advanced_solvers group adds mpi4py, petsc4py and slepc4py, the distributed and sparse eigenvalue solver stack. Installing only the base package therefore gives you the core, and each extra capability has a cost in install time and in the number of versions you now have to track.

Installing quimb on Python 3.11 and later

quimb is published on PyPI and on conda-forge, and the project also carries a pixi badge, with a pixi.lock file at the top of the repository, so the environment can be pinned by lock file if that is your preference. The packaging metadata in pyproject.toml states the supported interpreter range and the base dependency set:

requires-python = ">=3.11"
dependencies = [
    "autoray>=0.10.0",
    "cotengra>=0.7.1",
    "cytoolz>=0.8.0",
    "numba>=0.39",
    "numpy>=1.17",
    "psutil>=4.3.1",
    "scipy>=1.16.0",
    "tqdm>=4",
]

That block tells you two things before you install anything. The floor is Python 3.11, and the classifiers list support for 3.11, 3.12, 3.13 and 3.14, with the operating system marked as independent. Second, numba is a base dependency rather than an optional one, which means compilation of numba kernels happens on your machine the first time those code paths run. It also means the base install is not lightweight, since numba, scipy and cotengra all come along.

If you plan to use the sparse eigenvalue solvers, the extra group is separate:

advanced_solvers = [
    "mpi4py",
    "petsc4py",
    "slepc4py"
]

The documented home for full instructions is the documentation site at quimb.readthedocs.io, which the README links as the place where the complete documentation lives. The repository also contains a docs directory, a tests directory and a paper directory, and the contributing guide sits under .github.

cotengra handles the contraction path you would otherwise write yourself

The tensor module's automatic contraction and optimisation is not built in isolation. The README links the contraction step to cotengra, a separate project, and cotengra is a required dependency at version 0.7.1 or later, with cotengrust and kahypar in the recommended group.

This matters because contracting a tensor network is the hard part of the work. A network has to be turned into an order of index contractions, and the order changes the cost by orders of magnitude. quimb hands that decision to cotengra, which is where the hypergraph partitioning and the optional Rust based acceleration come from, kahypar and cotengrust being the two optional accelerators. The quimb.tensor list of abilities reads in one line: automatically contract, optimize and draw networks.

Drawing is worth a note as well, since it is listed as part of the same automatic pipeline rather than as an afterthought. NetworkX and pygraphviz sit in the recommended group for that purpose, with plotly available as another option. For a library whose networks can have tens or hundreds of tensors, having the layout produced automatically is a practical requirement, and it is one of the reasons the dependency list is as long as it is.

The division of labour across these companion projects is the main architectural fact to understand about quimb. The core package holds the tensor algebra and the physics, and the surrounding projects hold the array abstraction, the contraction scheduling and the partitioning.

Where the matrix module is the better tool

The core module covers the regime where the whole Hilbert space fits in memory. States and operators are `numpy.ndarray` or `scipy.sparse` matrices, and the module handles operators in complicated tensor spaces, groundstates and excited states, time evolution, entanglement measures, numba acceleration and stochastic estimates of Tr f(X).

That last item is a real differentiator. A stochastic estimator for a trace of a function lets you approximate an expensive quantity without forming the full operator, which is the standard trick for large moment calculations. The README lists it among the capabilities of the matrix path, and it is not something the tensor module offers in the same form.

The choice between the two modules comes down to scale and to the question being asked. A tensor network with a small bond dimension and a large number of sites can describe a state that would need an astronomically large dense matrix, so there is no contest. A small system, on the other hand, can be computed exactly, and the exact result is the one you check a truncated approximation against. Researchers typically use both, which is precisely why they are in one package rather than in two.

The limits are just as concrete. The exact path runs into memory as the Hilbert space grows, and the tensor path runs into bond dimension and contraction cost. Neither module in the README is described as handling a genuinely enormous system, and the documentation is the place to check what happens at the sizes you care about.

A moving target, and a licence that needs reading

quimb is not archived and it moves quickly. The last push was on 2026-10-14, and the published releases include v1.15.0 on 2026-08-10, v1.14.0 on 2026-05-11 and v1.13.0 on 2026-03-20, so a new minor version every couple of months has been the pattern. The project status classifier in the packaging metadata says Development Status :: 4 - Beta. That combination, frequent releases plus a beta marker, tells you to pin your version and to read the changelog before upgrading, because an API you rely on in a research script can change underneath you between minor versions.

The licence is where a careful adopter should slow down. GitHub does not classify the licence itself and points instead to the LICENSE file, while the packaging metadata declares `license = "Apache-2.0"` with `license-files = ["LICENSE"]`. The repository listing shows a file named LICENSE.txt. Those three statements do not obviously agree, and a licence classification tool that cannot decide is a signal worth resolving before a group depends on the code. This is not legal advice, only the observation that the declaration and the file present need to be read side by side.

Feedback channels are conventional and open: issues and pull requests on GitHub, a discussions page for other questions, a contributing guide, and a JOSS DOI badge for citation. The tests directory, the codecov configuration and the pixi lock file together suggest a project that expects pinned, reproducible environments.

Editorial conclusion

quimb fits a researcher who wants DMRG, TEBD, MERA or PEPS work and exact matrix calculations to sit behind one import, and who is ready to choose an array backend such as jax or torch through autoray. It is the wrong tool if you need a stable release trail, since the published version moves every few months and the last push was on 2026-10-14, or if your licensing review cannot accept an ambiguity between the Apache-2.0 string in pyproject.toml and the LICENSE file GitHub could not classify. Before adopting it, confirm your Python version is 3.11 or later, decide whether the extra solvers group with mpi4py, petsc4py and slepc4py is needed, and read the LICENSE file rather than relying on the classifier.

Frequently asked questions

Official sources

1. Issues
2. jcmgray/quimb on GitHub
3. Project website
4. README
5. Releases