qutip

Files (13)

• SKILL.md
• advanced.md · references/
• analysis.md · references/
• core_concepts.md · references/
• time_evolution.md · references/
• visualization.md · references/
• _common.py · scripts/
• convergence_sweep.py · scripts/
• qobj_model_validator.py · scripts/
• result_audit.py · scripts/
• solver_config_planner.py · scripts/
• steady_state_spectrum_planner.py · scripts/
• two_level_simulation.py · scripts/

SKILL.md (first lines)

# 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:

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

For plots:

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

Optional QuTiP family packages are independently versioned:

```bash
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:

```python
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.

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills