/qutip

name: qutip
description: Simulate and audit closed and open quantum-system models with QuTiP 5, including deterministic, trajectory, steady-state, spectral, and phase-space workflows. Use for local quantum-dynamics work where physical assumptions, dimensions, and numerical convergence must be explicit.
license: MIT
compatibility: Requires Python 3.11+, uv, and qutip==5.3.1 for executable simulations. Bundled planners and all script help run with the Python standard library; plotting requires the graphics extra. No network service or credentials are used.
metadata:
  version: "1.4"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-10-01"

QuTiP 5

Scope

Use QuTiP for finite-dimensional quantum mechanics, quantum optics, Lindblad dynamics, trajectories, weak-coupling Bloch-Redfield models, and specialized Floquet, HEOM, and permutational-invariance methods. It is not a hardware execution SDK. Circuit and control functionality moved to separate QuTiP family packages.

This skill targets **QuTiP 5.3.1**, released 2026-08-04. QuTiP 5.3 requires Python 3.11 or newer. Its required distributions are NumPy (`>=1.23.2`), SciPy (`>=1.9.2`, excluding `1.16.0` and `1.17.0`), and `packaging`.

Reproducible uv snapshot

Create a dedicated environment and pin every direct distribution:

uv venv --python 3.11
uv pip install "qutip==5.3.1"

For plots:

uv pip install "qutip[graphics]==5.3.1"

Optional QuTiP family packages are independently versioned:

uv pip install "qutip-qip==0.4.2"
uv pip install "qutip-qtrl==0.2.0"
uv pip install "qutip-jax==0.1.1"

• `qutip-qip` 0.4.2 (2026-06-23) is the production/stable circuit, gate, and

noisy-device simulation package. Import from `qutip_qip`, not `qutip.qip`.

• `qutip-qtrl` 0.2.0 (2026-06-23) provides GRAPE and CRAB **quantum optimal

control**. It is not a trajectory viewer. Import from `qutip_qtrl`, not `qutip.control`; PyPI still classifies it pre-alpha.

• `qutip-jax` 0.1.1 (2025-05-29) is the official JAX data backend for GPU and

automatic-differentiation experiments. It is explicitly pre-alpha.

• `qutip-cupy` is an official QuTiP-organization repository, but it has no PyPI

release and its own README says it is not officially released. Do not put an unreleased Git install into a reproducible workflow.

Use a project lockfile or a hash-generating `uv pip compile` workflow when transitive dependency identity must also be frozen.

Core tests cover small native CPU systems with known solutions. Optional JAX checks cover CPU conversion/evolution and differentiation only; GPU/MPI, large HEOM hierarchies, and experimentally realistic physics are unvalidated. Snippets with placeholders such as `H`, `rho0`, or `c_ops` are illustrative fragments to adapt after defining a consistent model.

Non-negotiable model contract

Before solving, record:

1. **Units and convention.** QuTiP equations normally set \(\hbar=1\). Hamiltonian entries are angular frequencies and rates have reciprocal-time units. A decay rate specified as `1/T1` needs no `2*pi` factor. Convert cyclic frequency with \(2\pi f\); never mix Hz and rad/s. 2. **Subsystem order.** `tensor(A, B, C)` fixes subsystem indices `0, 1, 2`. Preserve that order in every state, operator, collapse channel, and partial trace. `obj.ptrace([0, 2])` keeps those subsystems; it does not trace them. 3. **State validity.** Check ket norm or density-matrix Hermiticity, unit trace, and eigenvalues above a stated negative tolerance. Tiny negative values may be numerical; material negativity invalidates a claimed state. 4. **Generator meaning.** A Lindblad channel with rate `gamma` is represented by `sqrt(gamma) * A`, not `gamma * A`. Define what each rate measures. For example, `sqrt(gamma_phi / 2) * sigmaz()` gives coherence decay `exp(-gamma_phi * t)`. 5. **Approximations.** State rotating-wave, Born-Markov, secular, weak-coupling, bath-equilibrium, truncation, symmetry, and initial-factorization assumptions wherever used. 6. **Numerics.** Justify Hilbert truncation, output grid, integration method, tolerances, trajectory count, and random seeds. Report `result.stats`. 7. **Convergence.** Sweep every artificial cutoff: Fock dimension, time/frequency window and spacing, ODE tolerances, trajectories, Floquet harmonics, HEOM depth and bath exponents, or PIQS representation as applicable.

Qobj, dimensions, and tensor order

Prefer explicit imports and inspect both shape and structured dimensions:

from qutip import basis, qeye, sigmaz, tensor

psi = tensor(basis(2, 0), basis(3, 1))
z_on_first = tensor(sigmaz(), qeye(3))

assert psi.shape == (6, 1)
assert psi.dims == [[2, 3], [1]]
assert z_on_first.dims == [[2, 3], [2, 3]]
rho_first = psi.proj().ptrace(0)  # keep subsystem 0

Matrix shape alone is insufficient: two objects can both be 6-by-6 but encode different tensor factorizations. Read `references/core_concepts.md` before building composite, superoperator, or channel models.

Choose the solver by physics

| Model | Current API | Required justification | |---|---|---| | Closed, pure, unitary | `sesolve` | Hermitian Hamiltonian; no dissipation | | Lindblad/open or mixed | `mesolve` | Markovian completely positive model and channel rates | | Quantum jumps | `mcsolve` | Unravelling, trajectory convergence, seeds | | Microscopic weak bath | `brmesolve` | Born-Markov/weak coupling, spectra, secular choice | | Diffusive measurement | `ssesolve`, `smesolve` | monitored versus unmonitored channels | | Periodic drive | `FloquetBasis`, `fsesolve`, `fmmesolve` | verified period and Floquet convergence | | Structured non-Markovian bath | `qutip.solver.heom` | bath expansion and hierarchy convergence | | Symmetric spin ensemble | `qutip.piqs` | permutation symmetry and basis choice |

Do not select a more specialized solver merely because it exists.

Deterministic open-system example

QuTiP 5.3 uses ordinary