QuTiP: The Quantum Toolbox in Python

5.2.3 · active · verified Thu Apr 16

QuTiP is an open-source Python library for simulating the dynamics of closed and open quantum systems. It provides user-friendly and efficient numerical simulations for a wide range of quantum mechanical problems, including those with arbitrary time-dependence, commonly found in quantum optics, trapped ions, superconducting circuits, and quantum nanomechanical resonators. The library, currently at version 5.2.3, is built upon NumPy, SciPy, and Cython for numerical backends and Matplotlib for graphical output, with regular minor and patch releases, and significant major updates.

Common errors

```
TypeError: 'complex' object is not subscriptable
```
cause In QuTiP v5.x, the multiplication of a bra `Qobj` with a ket `Qobj` now returns a scalar (a Python `complex` number) instead of a zero-dimensional `Qobj`. Attempting to index this scalar (e.g., `result[0][0]`) will raise this error.

fix If your code expects a `Qobj` and attempts to index it, remove the indexing. The result of `bra * ket` is directly the scalar complex number. If you need the complex value, use it directly (e.g., `value = bra * ket`).
```
AttributeError: 'QobjEvo' object has no attribute 'ops' / 'cte'
```
cause In QuTiP 5.x, direct access to individual Hamiltonian elements through `QobjEvo.ops` and `QobjEvo.cte` attributes has been removed as part of the core redesign.

fix Instead of direct attribute access, evaluate the `QobjEvo` object at a specific time step by calling it like a function, e.g., `quobjevo(t)`. Most metadata (dims, shape) can be obtained from its properties directly.
```
Object passed to assert_allclose is not an array.
```
cause QuTiP 5.x no longer implicitly converts `Qobj` instances to NumPy arrays using `numpy.array(qobj)`. This change prevents silent data type transformations.

fix When comparing `Qobj` instances or their NumPy array representations using functions like `numpy.testing.assert_allclose`, explicitly convert the `Qobj` to a NumPy array using the `.full()` method: `qobj.full()`.

Warnings

breaking QuTiP 5.x introduced significant breaking changes from 4.x, particularly in the core `Qobj`, `QobjEvo`, and solver implementations.
Fix: Consult the official migration guide for QuTiP 4 to 5. Key changes include how `QobjEvo` attributes are accessed, the return type of bra-ket multiplication, and explicit conversion to NumPy arrays using `Qobj.full()` instead of implicit conversion.
breaking The `qutip.qip` and `qutip.control` modules have been moved out of the core `qutip` library into separate packages (`qutip-qip`, `qutip-qtrl`, `qutip-qoc`).
Fix: Install the respective standalone packages (e.g., `pip install qutip-qip`) and update import statements. For example, `from qutip.qip import QubitCircuit` becomes `from qutip_qip import QubitCircuit` or `from qutip.qip import QubitCircuit` after installing `qutip-qip`.
gotcha Using an insufficient number of states (truncation) in simulations, especially for time-evolution of open quantum systems or harmonic oscillators, can lead to inaccurate or incorrect results at later times.
Fix: Always verify convergence by increasing the number of states and observing if the results change significantly. Plotting the error as a function of system size can help determine an appropriate truncation.
gotcha The `steadystate()` solver in older QuTiP versions sometimes produced pivot errors for systems with ill-defined steady states (e.g., dissipationless dark states or multiple steady states). While newer versions might avoid the explicit error, they could silently return a 'nonsense' result.
Fix: Carefully examine the physical validity of results from `steadystate()` if the system is known to have such pathologies. Consider checking the eigenvalues of the Liouvillian for multiple zero eigenvalues, though this can be computationally costly.

Install

pip install qutip Minimal installation
pip install qutip[full] With all optional dependencies

Imports

qutip
wrong:
```
from qutip import *
```
correct:
```
import qutip as qt
```
While `from qutip import *` is shown in some older tutorials, `import qutip as qt` is generally recommended for clarity and to avoid polluting the namespace.
Qobj
```
from qutip import Qobj
# or qt.Qobj if 'import qutip as qt' is used
```
Qobj is the core class for quantum objects (states and operators).

Quickstart

This quickstart demonstrates creating basic quantum objects (ket states and operators) and performing fundamental operations like applying an operator to a state and calculating an expectation value.

import qutip as qt

# Create a basis state |0> for a two-level system
ket0 = qt.basis(2, 0)
print(f"Ket |0>:\n{ket0}")

# Create a Pauli sigma-x operator
sigmax = qt.sigmax()
print(f"Sigma-x operator:\n{sigmax}")

# Apply the operator to the state
ket1 = sigmax * ket0
print(f"Sigma-x applied to |0> (gives |1>):\n{ket1}")

# Calculate expectation value
exp_val = qt.expect(sigmax, ket0)
print(f"Expectation value of sigma-x in |0>: {exp_val}")

view raw JSON →