K-Dense-AI/scientific-agent-skills / skills/qutip
qutip
VerifiedSimulate 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.4 KB |
| references/advanced.md | markdown | 15.4 KB |
| references/analysis.md | markdown | 10.5 KB |
| references/core_concepts.md | markdown | 8.3 KB |
| references/time_evolution.md | markdown | 13.5 KB |
| references/visualization.md | markdown | 8.8 KB |
| scripts/_common.py | script | 11.8 KB |
| scripts/convergence_sweep.py | script | 12.1 KB |
| scripts/qobj_model_validator.py | script | 10.7 KB |
| scripts/result_audit.py | script | 12.2 KB |
| scripts/solver_config_planner.py | script | 10.9 KB |
| scripts/steady_state_spectrum_planner.py | script | 7.8 KB |
| scripts/two_level_simulation.py | script | 12.9 KB |
references/core_concepts.md
View on GitHub# QuTiP 5.3 Core Concepts
Research and API verification date: **2026-10-01**. Examples target
`qutip==5.3.1`.
## Units and the equation being solved
QuTiP does not attach physical units. The standard solver equations use
\(\hbar=1\), so a Hamiltonian has angular-frequency units and time has reciprocal
units:
\[
\dot{\rho}=-i[H,\rho]+\sum_k\left(C_k\rho C_k^\dagger
-\tfrac12\{C_k^\dagger C_k,\rho\}\right).
\]
Choose one unit system and state it in reports:
- if time is ns, Hamiltonian coefficients and rates are in ns\(^{-1}\);
- a frequency quoted in cycles/time becomes angular frequency \(2\pi f\);
- temperature in HEOM or thermal spectra must be converted consistently with
\(k_B=1\) only if that convention was explicitly selected.
Dimensional consistency is a model property, not something QuTiP can infer.
## Qobj structure
`Qobj` stores numerical data plus quantum dimension metadata:
```python
from qutip import Qobj, basis, sigmaz
ket = basis(2, 0)
rho = ket.proj()
H = 0.5 * sigmaz()
assert ket.isket and ket.dims == [[2], [1]]
assert rho.isoper and rho.dims == [[2], [2]]
assert H.isherm
```
Important properties and methods:
| API | Meaning |
|---|---|
| `.dims` | Structured input/output Hilbert spaces |
| `.shape` | Flattened matrix shape |
| `.type` | `ket`, `bra`, `oper`, `super`, `operator-ket`, or `operator-bra` |
| `.isket`, `.isoper`, `.issuper` | Semantic type checks |
| `.isherm`, `.isunitary` | Cached/computed structural properties |
| `.dag()` | Adjoint |
| `.tr()` | Trace |
| `.norm()` | L2 norm for kets by default; trace norm for operators by default |
| `.proj()` | Ket/bra projector |
| `.ptrace(sel)` | Keep selected subsystems and trace out the rest |
| `.full()` | Dense matrix with flattened shape |
| `.full_tensor()` | QuTiP 5.3 dense array reshaped by tensor dimensions |
Construct raw `Qobj` values only when built-in constructors are unsuitable:
```python
from qutip import Qobj
rho = Qobj(
[[0.75, 0.1], [0.1, 0.25]],
dims=[[2], [2]],
)
```
Supplying correct matrix shape with incorrect `dims` can invalidate later
tensor, partial-trace, and superoperator operations.
## States and physicality
### Kets
```python
from qutip import basis, coherent
qubit = (basis(2, 0) + basis(2, 1)).unit()
oscillator = coherent(30, 1.5)
assert abs(qubit.norm() - 1.0) < 1e-12
```
### Density matrices
A physical finite-dimensional density matrix is Hermitian, trace one, and
positive semidefinite:
```python
import numpy as np
from qutip import thermal_dm
rho = thermal_dm(20, 0.7)
tol = 1e-10
eigenvalues = np.asarray(rho.eigenenergies(), dtype=float)
assert rho.isherm
assert abs(complex(rho.tr()) - 1.0) < tol
assert eigenvalues.min() >= -tol
```
Use a tolerance tied to solver error and matrix scale. Report the minimum
eigenvalue instead of silently clipping it. If a method such as non-secular
Bloch-Redfield produces material negativity, revisit its physical assumptions.
Common constructors:
```python
from qutip import (
basis,
coherent,
coherent_dm,
fock,
fock_dm,
maximally_mixed_dm,
thermal_dm,
)
psi_n = fock(16, 3)
rho_n = fock_dm(16, 3)
psi_alpha = coherent(24, 1.2)
rho_alpha = coherent_dm(24, 1.2)
rho_th = thermal_dm(24, 0.5)
rho_mix = maximally_mixed_dm([2, 2])
```
Oscillator constructors use a finite truncation. Sweep the cutoff and monitor
edge population, observables, and state trace. A normalized truncated state is
not by itself evidence that the cutoff is adequate.
## Tensor products and subsystem order
Arguments to `tensor` define subsystem order from left to right:
```python
from qutip import basis, destroy, qeye, sigmaz, tensor
N = 12
psi = tensor(basis(N, 2), basis(2, 0)) # cavity index 0, qubit index 1
a = tensor(destroy(N), qeye(2))
sz = tensor(qeye(N), sigmaz())
assert psi.dims == [[N, 2], [1]]
assert a.dims == [[N, 2], [N, 2]]
assert sz.dims == a.dims
```
`Qobj.ptrace(sel)` keeps `sel`:
```python
rho = psi.proj()
rho_cavity = rho.ptrace(0)
rho_qubit = rho.ptrace(1)
```
The selected subsystems remain in their original order even if `sel` is passed
in another order. Use `permute` when an explicit subsystem reordering is
intended.
For a composite operator with `dims == [[2, 3], [2, 3]]`,
`full_tensor().shape` is `(2, 3, 2, 3)`. Treat this as a useful dimensional
audit, not a replacement for documenting subsystem labels.
## Operators and observables
```python
from qutip import create, destroy, jmat, num, sigmam, sigmap, sigmax, sigmay, sigmaz
N = 20
a = destroy(N)
adag = create(N)
n = num(N)
sx, sy, sz = sigmax(), sigmay(), sigmaz()
sm, sp = sigmam(), sigmap()
Jx = jmat(1, "x")
```
Hamiltonians and ideal observables should be Hermitian within tolerance.
Collapse operators generally need not be Hermitian.
Expectation and variance:
```python
from qutip import expect, variance
mean_n = expect(n, rho)
var_n = variance(n, rho)
```
Do not interpret a visibly non-real expectation of a Hermitian observable as a
physical value; first audit Hermiticity, state validity, dimensions, and solver
accuracy.
## Collapse operators and rate conventions
If a dissipator is written as \(\gamma\,\mathcal{D}[A]\rho\), pass
\(C=\sqrt{\gamma}A\):
```python
import numpy as np
from qutip import sigmam, sigmaz
gamma_down = 0.2
gamma_phi = 0.05 # desired off-diagonal coherence decay
c_ops = [
np.sqrt(gamma_down) * sigmam(),
np.sqrt(gamma_phi / 2.0) * sigmaz(),
]
```
The factor for dephasing depends on how a publication defines its dephasing
rate. Derive the matrix-element decay for the chosen dissipator and test it on
a two-level state instead of copying a symbol by name.
For a thermal oscillator with occupation \(n_\mathrm{th}\):
```python
c_ops = [
np.sqrt(kappa * (n_th + 1.0)) * a,
np.sqrt(kappa * n_th) * a.dag(),
]
```
Rates must be finite and nonnegative in standard Lindblad form. Time-dependent
rates require extra care: a coefficient multiplies the collapse **amplitude**,
so a target rate \(\gamma(t)\) needs an amplitude proportional to
\(\sqrt{\gamma(t)}\).
## Liouvillians and vectorization
```python
from qutip import liouvillian, operator_to_vector, vector_to_operator
L = liouvillian(H, c_ops)
rho_vec = operator_to_vector(rho)
derivative = L * rho_vec
rho_roundtrip = vector_to_operator(rho_vec)
assert L.issuper
assert (rho_roundtrip - rho).norm() < 1e-12
```
QuTiP uses column-stacked operator vectorization. Use
`operator_to_vector`/`vector_to_operator`; do not reproduce reshape order by
guesswork.
Useful superoperator constructors and conversions include:
```python
from qutip import (
kraus_to_super,
spost,
spre,
sprepost,
to_choi,
to_kraus,
to_super,
)
```
For a quantum channel, check the intended representation and the map properties
such as complete positivity and trace preservation. QuTiP exposes properties
including `iscp`, `istp`, and `iscptp` on suitable map objects.
## Truncation and basis audits
For every truncated bosonic or spin model:
1. increase each cutoff independently;
2. compare the actual reported observables, not only energies;
3. inspect occupation near the cutoff;
4. recheck all tensor dimensions after changing a cutoff;
5. state whether the model is in a bare, dressed, rotating, Floquet, Dicke, or
other basis;
6. document every rotating-wave or excitation-number restriction.
An excitation-number-restricted space does not have the same factorization as
the corresponding full tensor space. Do not apply subsystem operations unless
their meaning in the restricted representation is established.
## Local model validation
`../scripts/qobj_model_validator.py` accepts a bounded strict-JSON model made
only of numeric arrays. It rejects URLs, symlinks, duplicate keys, non-finite
numbers, unknown roles, executable coefficients, dimensions whose product
exceeds 64, and incompatible subsystem structures. It checks Hamiltonian and
observable Hermiticity, initial-state norm/trace/positivity, and nonnegative
collapse rates.
It is a preflight audit, not a proof that the physical model is appropriate.
## Sources (verified 2026-10-01)
- [QuTiP 5.3 quantum-object API](https://qutip.readthedocs.io/en/stable/apidoc/quantumobject.html)
- [Tensor-product guide](https://qutip.readthedocs.io/en/stable/guide/guide-tensor.html)
- [QuTiP 5.3.1 release notes](https://github.com/qutip/qutip/releases/tag/v5.3.1)
- [QuTiP 5.3 changelog](https://qutip.readthedocs.io/en/stable/changelog.html)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |