quimb

1.13.0 · active · verified Thu Apr 16

quimb is a versatile Python library for quantum information and many-body physics, offering tools for exact diagonalization, tensor networks (Matrix Product States, PEPS, etc.), quantum circuits, and general quantum mechanics simulations. It is currently at version 1.13.0 and maintains an active release cadence, with major and minor updates often arriving monthly or bi-monthly, frequently including breaking changes.

Common errors

```
ImportError: cannot import name 'OperatorBuilder' from 'quimb.operatorbuilder'
```
cause The `OperatorBuilder` class was moved in quimb v1.12.0 from `quimb.operatorbuilder` to `quimb.operator`.

fix Change your import statement to `from quimb.operator import OperatorBuilder`.
```
RuntimeError: 'quimb' requires python>=3.11.
```
cause You are attempting to run quimb version 1.12.1 or newer on a Python environment older than 3.11.

fix Upgrade your Python installation to version 3.11 or higher. For example, using `conda create -n quimb_env python=3.11` or `pyenv install 3.11`.
```
TypeError: not all indices were contracted (contracting ... to ...)
```
cause When performing a tensor network contraction, some indices that were expected to be summed over remain uncontracted, often due to an incorrect `output_inds` specification or a mismatch in tensor indices.

fix Carefully review the indices of your tensors and the `output_inds` argument passed to `tn.contract()`. Ensure all internal indices are matched for summation and only desired external indices are left.
```
NumbaDeprecationWarning: The 'nopython' keyword argument was not supplied to the 'jit' decorator.
```
cause This warning typically indicates a minor compatibility issue between the installed `numba` and `numpy` versions, or a general Numba best-practice recommendation. While usually harmless, it can sometimes precede other issues.

fix Upgrade both `numba` and `numpy` to their latest compatible versions. Use `pip install --upgrade numba numpy`.

Warnings

breaking quimb now requires Python 3.11 or newer.
Fix: Ensure your Python environment is 3.11 or greater. Consider using pyenv or conda for managing Python versions.
breaking Sign conventions for hopping strength `t` in `ham_hubbard_hardcore` and magnetic field terms in `heisenberg_from_edges` have been fixed/changed.
Fix: If using these Hamiltonian generation functions, review your energy calculations and potentially adjust signs in your code to match the new convention (refer to official docs for details).
breaking The `OperatorBuilder` class has moved from `quimb.operatorbuilder` to `quimb.operator`.
Fix: Update your import statements from `from quimb.operatorbuilder import OperatorBuilder` to `from quimb.operator import OperatorBuilder`.
breaking The `belief_propagation` module has moved from `quimb.tensor` to its own submodule `quimb.tensor.belief_propagation`.
Fix: Adjust import paths from `from quimb.tensor import belief_propagation` (or specific functions) to `from quimb.tensor.belief_propagation import ...`.
breaking The method `MatrixProductState.partial_trace` was renamed to `MatrixProductState.partial_trace_to_mpo` to clarify its output type (an MPO).
Fix: Update calls from `mps.partial_trace(...)` to `mps.partial_trace_to_mpo(...)`.
gotcha Tensor network contraction can be computationally and memory intensive. Default optimization (`optimize='auto'`) might not always be ideal for very large or complex networks.
Fix: For performance, consider installing `opt_einsum` and `cotengra` (`pip install quimb[tensor,cut]`). For specific problems, manually specify `optimize` strategies (e.g., `'optimal'`, `'greedy'`, or use a `ContractionTree` object) for `tn.contract()`.

Install

pip install quimb Basic installation
pip install quimb[tensor,cut] Recommended for full tensor network features

Imports

quimb
```
import quimb as qb
```
quimb.tensor
```
import quimb.tensor as qb.tn
```
OperatorBuilder
wrong:
```
from quimb.operatorbuilder import OperatorBuilder
```
correct:
```
from quimb.operator import OperatorBuilder
```
Moved in v1.12.0 from its own submodule to the main `quimb.operator` module.
belief_propagation
wrong:
```
from quimb.tensor import belief_propagation
```
correct:
```
from quimb.tensor.belief_propagation import ...
```
Moved in v1.11.0 from `quimb.tensor` to its dedicated `quimb.tensor.belief_propagation` submodule.

Quickstart

This quickstart demonstrates creating a random state vector and a simple Matrix Product State (MPS) using quimb's core and tensor network modules, along with basic operations like calculating norm and contraction.

import quimb as qb
import quimb.tensor as qb.tn

# Create a random state vector
psi = qb.rand_ket(8)  # 8-dimensional random state
print(f"State vector shape: {psi.shape}")

# Create a simple Matrix Product State (MPS)
L = 10  # Number of sites
D = 8   # Max bond dimension
d = 2   # Local dimension
psi_mps = qb.tn.rand_mps(L, D, d)
print(f"MPS with {L} sites, max bond dim {psi_mps.max_bond_dim()}, local dim {d}")

# Calculate the MPS norm
print(f"MPS norm: {psi_mps.norm()}")

# Contract the MPS to a single tensor (the full state vector)
# Note: This can be memory intensive for large L and D
full_state_from_mps = psi_mps.contract()
print(f"Full state from MPS shape: {full_state_from_mps.shape}")

view raw JSON →