Website · Documentation · Paper

quchip is an open-source Python toolkit for modeling superconducting quantum chips.

A predictive chip model needs more than a Hamiltonian: device physics, control-line transformations, frames and approximations, dissipation, and measured observables all belong to it. quchip represents each part explicitly. Line properties such as gain, delay, and crosstalk belong to the control chain, not to Hamiltonian terms written by hand.

Declare the chip once. The same declaration drives dressed-state analysis, model reduction, control sequencing, open-system simulation, parameter sweeps, and exact JAX gradients. The engine resolves each device's frame, applies the requested approximations, and records the bands it drops.

Chip + QuantumSequence → ResolvedFrame → HamiltonianDescription → SolveProblem → QuTiP or dynamiqs → SimulationResult

QuTiP is the default backend. The dynamiqs backend is JAX-native and keeps declared device and control parameters differentiable through the solve.

quchip uses GHz for ordinary frequencies, ns for time, and mK for temperature. The implemented conventions and approximations are documented in the physics guide.

quchip requires Python 3.11 or newer.

python -m pip install quchip

Optional extras are available for the dynamiqs backend, graph visualization, and scqubits interoperability:

python -m pip install 'quchip[dynamiqs]'
python -m pip install 'quchip[viz]'
python -m pip install 'quchip[scqubits]'

Extras can be combined. To install the current source instead:

git clone https://github.com/quchip/quchip.git
cd quchip
python -m pip install .

from quchip import Capacitive, ChargeDrive, Chip, DuffingTransmon, Resonator

qubit = DuffingTransmon(freq=5.0, anharmonicity=-0.30, levels=6, label="qubit")
readout = Resonator(freq=6.8, levels=10, quality_factor=6800, label="readout")
coupling = Capacitive(qubit, readout, g=0.060, rwa=True, label="qubit-readout")
chip = Chip([qubit, readout], couplings=[coupling], frame="rotating", rwa=True)
qubit_line = ChargeDrive(qubit, label="qubit-charge")
readout_line = ChargeDrive(readout, label="readout-charge")
chip.wire(qubit_line, readout_line)

f01 = chip.freq(qubit)
f12 = chip.freq(qubit, when={qubit: 1})
fr0 = chip.freq(readout, when={qubit: 0})
fr1 = chip.freq(readout, when={qubit: 1})

The complete example derives short and selective nominal-pi Gaussian drives from $|f_{12}-f_{01}|$, then derives a Gaussian-edge readout duration from the conditional pull and resonator linewidth. Both parts run the real multilevel, lossy chip with compact reproducibility receipts.

The complete walkthrough is available as authored Markdown and an executed notebook.

Install the dependencies used by all shipped test lanes:

python -m pip install -e '.[test,dynamiqs]'

Run the full suite:

python -m pytest

Run one lane:

python -m pytest -m core
python -m pytest -m physics_sentinel
python -m pytest -m extended

• Hello, drive and readout: compare qubit-drive leakage, then resolve pulse-level dispersive readout on the same chip.
• Cookbook: practical conventions and task recipes.

The accompanying paper is quchip: A Differentiable Toolkit for Modeling Quantum Devices (arXiv:2607.17081).

The interactive walkthrough follows one five-device model through declaration, crosstalk identification and correction, adiabatic reduction from 576 to 16 dimensions, and gradient-based recovery of four directed crosstalk parameters.

If you use quchip in your work, please cite it:

@misc{alyousef2026quchip,
      title={quchip: A Differentiable Toolkit for Modeling Quantum Devices},
      author={Ibraheem AlYousef},
      year={2026},
      eprint={2607.17081},
      archivePrefix={arXiv},
      primaryClass={quant-ph},
      doi={10.48550/arXiv.2607.17081},
      url={https://arxiv.org/abs/2607.17081},
}

Citation metadata for the software itself is in CITATION.cff.

quchip is distributed under the Apache License 2.0. See LICENSE.