quchip.chip.baths

Chip-level baths for shared or collective Lindblad dissipation.

A Bath is not a device. It owns no Hilbert-space factor and no Hamiltonian term, only collapse operators that couple a set of devices to a common environment. This layer is for physics around devices, e.g. a single chip temperature at which every device thermalizes. It also covers correlated or collective dissipation (collective decay, correlated dephasing), which per-device noise, independent by construction, cannot express.

Rates are in 1/ns (the Lindblad convention), with no 2π scaling, because that boundary applies only to the Hamiltonian. The thermal Bose factor uses k_B in GHz/mK, so n̄ = 1 / expm1(freq / (k_B * T)) with freq in GHz and T in mK.

Classes

Bath(recipe[, targets, temperature, rate, ...])

A shared environment that couples a set of devices to a common bath.

class quchip.chip.baths.Bath(recipe, targets=None, *, temperature=None, rate=None, correlated=False, label=None)

Bases: object

A shared environment that couples a set of devices to a common bath.

Attach the bath at construction (Chip(..., baths=[...])) or later with add_bath(). The next simulate or solve call collects the bath’s collapse operators automatically.

Parameters:

• recipe (str) – Built-in collapse-channel model: "thermal", "collective_decay", or "correlated_dephasing". The argument name stays the same for API and serialization compatibility.

• targets (list[BaseDevice | str] | None) – Devices the bath couples to (objects or labels). None (default) means every device in the chip, the natural choice for a global thermal bath.

• temperature (float | None) – Temperature in mK, required for "thermal". It can be a JAX tracer for sweeps or gradients.

• rate (float | None) – Bath–device coupling rate γ in 1/ns. For "thermal", it is the environmental coupling rate. It is explicit and never silently borrowed from a device T1, so it cannot double-count device-level noise. For the collective models, it is the overall jump rate. None defaults to 1.0 (the user controls the absolute scale elsewhere).

• correlated (bool) – "thermal" only. False (default) emits independent per-device channels that share one temperature. True is not supported and raises NotImplementedError. The collective models always emit a single correlated operator, independent of this flag.

• label (str | None) – Auto-generated "bath_{n}" when omitted.

Examples

>>> from quchip import DuffingTransmon, Chip, Bath
>>> q = DuffingTransmon(freq=5.0, anharmonicity=-0.25, levels=3, label="q")
>>> chip = Chip([q])
>>> _ = chip.add_bath(Bath("thermal", temperature=20.0))  # global 20 mK bath
>>> _ = chip.add_bath(Bath("collective_decay", targets=[q], rate=0.01))

resolve_targets(chip)

Return ordered target labels, defaulting to all devices.

Parameters:

chip (Chip) – Chip that supplies labels when targets were omitted.

property separable: bool

Whether this bath factorizes into independent per-target channels.

True for models that emit one collapse operator per target ("thermal" with independent channels). False for models that emit a single jump operator summed over targets ("collective_decay", "correlated_dephasing"). Partitioning treats a non-separable bath’s target set as one inseparable block.

to_dict()

Serialize the bath, with targets stored as label strings.

classmethod from_dict(d)

Reconstruct a bath from serialized state.

Parameters:

d (dict[str, Any]) – Payload produced by to_dict(). Targets are label strings.

physics_notes()

Return human-readable declarations of this bath’s model and scope.

Mirrors physics_notes(). Returns one entry naming the model and its targets, plus a model-specific assumption that users must know.

copy()

Independent copy of this bath (targets normalize to label strings).

Chip.clone and eliminate use this method, so a transformed chip never shares live Bath objects with its source. Parameter values (temperature, rate) are carried by reference, so traced values stay traced.

parameter_values()

Return active bath values by local field name.

set_parameter_value(name, value)

Apply one bath value on an isolated bath copy.

Parameters:

• name ({"temperature", "rate"}) – Local parameter name.

• value (Any) – Temperature in mK or rate in 1/ns.

dissipation(chip, bases=None)

Return authored full-chip collapse channels.

"thermal" emits independent per-target relaxation/absorption pairs that share one bath temperature. The two collective models each emit a single jump operator summed over the resolved targets:

• "collective_decay": L = sum_i a_i at rate gamma, an equal-phase, equal-weight rank-one collective channel. It is not general collective (super/subradiant) decay, which requires per-pair phase and weight factors set by the target geometry (Lehmberg, Phys. Rev. A 2, 883 (1970), for the general collective-radiative-decay construction).

• "correlated_dephasing": L = sum_i n_i at rate gamma, i.e. maximally correlated common-mode dephasing, where every target shares the identical dephasing fluctuation. It is not general correlated dephasing with a target-dependent correlation structure (Breuer & Petruccione, The Theory of Open Quantum Systems, Oxford, 2002, Ch. 3, for the general Lindblad construction).

Contributions stay backend-neutral.

Parameters:

• chip (Chip) – Chip whose targets and tensor-product order define the operators.

• bases (mapping or None, default=None) – Captured basis records keyed by device label. None resolves them.

collapse_channels(chip, bases=None)

Return normalized full-chip bath channels.

Parameters:

• chip (Chip) – Chip whose targets define the channels.

• bases (mapping or None, default=None) – Captured basis records, or None to resolve them.