Website · Documentation · Paper

quchip is an open-source Python toolkit to model quantum devices. Its built-in models cover circuit QED, and custom Hamiltonians, operators, and loss channels describe other systems.

A predictive chip model needs more than a Hamiltonian. Device physics, control-line transformations, frames, approximations, dissipation, and measured observables each need an explicit place in it. Gain, delay, and crosstalk stay properties of the control chain instead of being folded into Hamiltonian coefficients by hand.

Declare the chip once, then use the same model for dressed-state analysis, model reduction, control sequences, open-system simulation, parameter sweeps, and JAX gradients.

QuTiP is the default simulation backend. The optional dynamiqs backend is JAX-native and keeps declared device and control parameters differentiable through a solve. The backend guide compares their numerical and workflow tradeoffs. The scqubits integration imports and exports selected device and composite models.

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

quchip requires Python 3.11 or newer.

python -m pip install quchip

Optionally, install support for dynamiqs, graph visualization, or scqubits:

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 RWA, Capacitive, Chip, DuffingTransmon, Resonator

qubit = DuffingTransmon(
    freq=5.0,
    anharmonicity=-0.30,
    levels=6,
    label="q",
)
readout = Resonator(
    freq=6.8,
    levels=10,
    internal_quality_factor=6800,
    label="r",
)
coupling = Capacitive(qubit, readout, g=0.060, label="qr")

chip = Chip(
    [qubit, readout],
    couplings=[coupling],
    frame="rotating",
    approximation=RWA(),
)

authored_hamiltonian = chip.unresolved_hamiltonian()
resolved_hamiltonian = chip.hamiltonian()

f01 = chip.freq(qubit)
f12 = chip.transition_frequency(qubit, 1, 2)
fr0 = chip.freq(readout, when={qubit: 0})
fr1 = chip.freq(readout, when={qubit: 1})
chi = (fr1 - fr0) / 2

unresolved_hamiltonian() keeps the local device and coupling expressions you declared. hamiltonian() applies the chip's basis, frame, and approximation. Both return inspectable symbolic expressions. If a resolved expression is time-dependent and you need its numerical array, call .matrix(t=...).

The remaining calls read dressed transition frequencies and the resonator frequency conditioned on the qubit state. Half their difference gives the dispersive shift $\chi$.

The defining and inspecting a chip guide continues from this example with LaTeX output, term inspection, frame transformations, projections, and graph views.

The dynamics guide adds control lines and pulse sequences to the chip above. It compares short and selective Gaussian qubit drives in the full multilevel model, then simulates conditional resonator readout.

• Your first chip: build a coupled model, inspect its Hamiltonian, and fit dressed targets.
• Spectra and parameter sweeps: follow an avoided crossing and compare a fluxonium model with measured spectroscopy.
• Pulses, leakage, and readout: compare pulse selectivity, conditional resonator response, and cavity depletion.
• Readout and fridge wiring: calculate VNA traces and qubit readout with receiver noise.
• Model reduction: compare a reduced model with the full pulse simulation.
• Gradients and parameter fitting: differentiate spectra and pulse responses, and fit measured circuit parameters.
• Extending quchip: define custom models, controls, dissipation and interoperability mappings.
• Cookbook: practical API choices, tips and common pitfalls.
• SQA 2026 examples: five short calculations from the talk.

• Purcell filtering and T1: how much can a Purcell filter suppress qubit decay while keeping the readout bandwidth?

Report bugs and model requests through GitHub Issues. Use Discussions for questions and open-ended proposals. Before making code or physics changes, read the contributing guide.

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

The interactive walkthrough takes 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, cite:

@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},
}

Software citation metadata is also in CITATION.cff.

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