quchip 0.3.1

Website · Documentation · Paper

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

A predictive chip model needs more than a Hamiltonian. Device physics, control-line transformations, frames, approximations, dissipation, and measured observables all need explicit places in the model. Gain, delay, and crosstalk remain 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 implemented conventions and approximations are documented in the physics guide.

Install

quchip requires Python 3.11 or newer.

python -m pip install quchip

Install optional support for dynamiqs, graph visualization, or scqubits as needed:

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 .

Define and inspect a chip

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() preserves the local device and coupling expressions you declared. hamiltonian() applies the chip's basis, frame, and approximation. Both return inspectable symbolic expressions; call .matrix(t=...) when a resolved expression is time-dependent and you need its numerical array.

The remaining calls read dressed transition frequencies and the resonator frequency conditioned on the qubit state. Their half-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.

Add dynamics and readout

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.

Guides

• 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.

Focused studies

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

Project status and contributing

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

Paper and citation

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:

@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 is also available in CITATION.cff.

License

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