quchip.interop.scqubits.composite

Composite import — scqubits HilbertSpace -> quchip Chip.

An scqubits HilbertSpace bundles a list of subsystems and a list of InteractionTerm couplings between them. import_hilbertspace() imports each subsystem individually through the shipped device mappings (quchip.interop.scqubits.devices), preserving order and each subsystem’s id_str as the device label, then transcribes every InteractionTerm into a callable-form Coupling whose operator matrices are the term’s subsystem operators expressed in the gauge of the imported device they act on.

Gauge consistency (Principle 3). Each imported circuit device (CircuitDevice, e.g. ChargeBasisTransmon) re-diagonalizes its own native Hamiltonian, fixing an eigenvector gauge — an arbitrary per-eigenvector phase/sign — that need not agree with scqubits’ own diagonalization of the same Hamiltonian. The undriven spectrum is gauge-invariant, but a drive on such a device that also participates in a coupling mixes the two gauges, corrupting the driven dynamics. So a coupling factor is projected through the device’s eigenvectors (project_operator()) whenever the device re-diagonalizes the same native basis scqubits stores the operator in.

Limitation (declared, Principle 12). When the imported device’s native basis differs in dimension from scqubits’ native basis for that subsystem — e.g. a Fluxonium (quchip phase grid vs scqubits’ harmonic-oscillator basis) — the factor cannot be re-projected into the device gauge and is frozen in the source’s eigenbasis gauge instead; a UserWarning names the device, and driven dynamics through it may carry gauge-inconsistent matrix elements. Declarative devices without a native basis of their own (Resonator, KerrCavity, whose Fock eigenbasis matches scqubits Oscillator’s by construction) and EigenbasisDevice (whose native basis is scqubits’ eigenbasis) are already in the device gauge and take the source eigenbasis path without warning.

Scope of v1 (declared, Principle 12): only pairwise InteractionTerm products of two operators are translated. Each term’s operator matrices are a frozen snapshot at the source parameter point, so the coupling is not differentiable with respect to the source circuit parameters (the same frozen-snapshot contract EigenbasisDevice carries). InteractionTermStr string expressions and non-pairwise products raise NotImplementedError rather than importing a partial model.

Functions

export_chip(chip, **opts)

Export a quchip Chip to an scqubits HilbertSpace.

import_hilbertspace(hs, **opts)

Import an scqubits HilbertSpace into a quchip Chip.
quchip.interop.scqubits.composite.import_hilbertspace(hs, **opts)[source]

Import an scqubits HilbertSpace into a quchip Chip.

Each subsystem imports through the shipped device mappings (order and id_str label preserved); each InteractionTerm becomes a callable-form Coupling.

Parameters:

  • hs (scqubits.HilbertSpace) – The composite system to import.

  • **opts – frame and rwa are forwarded to the Chip constructor. Device-level options are not forwarded in v1: every subsystem imports at its own truncated_dim and native noise defaults.

Raises:

  • NotImplementedError – A string-expression (InteractionTermStr) or non-pairwise interaction term is present.

  • LookupError – A subsystem has no registered device mapping.

Return type:

Chip

quchip.interop.scqubits.composite.export_chip(chip, **opts)[source]

Export a quchip Chip to an scqubits HilbertSpace.

Each device exports through the shipped device mappings (quchip.interop.scqubits.devices) in chip order, and every Coupling factorizes into a scalar strength and two device operators (see _coupling_product_factors()) added as one InteractionTerm per edge. scqubits carries the bare diagonal energies of each subsystem (gauge-invariant) plus these interaction matrices, so the whole composite lives in one consistent gauge — quchip’s — and its dressed spectrum reproduces the chip’s.

Couplings are exported in their full (non-RWA) operator form: scqubits interaction terms are bare operator products and apply no rotating-wave truncation of their own. Exporting a chip whose resolved RWA actually masks a Capacitive, TunableCapacitive, or product-form Coupling therefore fails closed with ValueError: silently exporting the full form anyway would reproduce different physics than the chip’s own RWA-resolved dynamics. CrossKerr is exempt — its RWA and full forms coincide, since n̂_a n̂_b conserves excitation number and is never touched by the RWA mask. Export an explicitly non-RWA chip (Chip(..., rwa=False), or rwa=False on the coupling) to proceed.

Chip-level control equipment and baths have no scqubits counterpart (it models neither drives nor dissipation) and are dropped with a single UserWarning naming what was dropped.

Parameters:

  • chip (Chip) – The composite system to export. Coupling strengths must be concrete — a strength carrying a JAX tracer raises ValueError.

  • opts (Any)

Raises:
Return type:

Any