Source code for qiskit_metal.analyses.em.package_modes

# This code is part of Qiskit.
#
# (C) Copyright IBM 2017, 2021.
#
# This code is licensed under the Apache License, Version 2.0. You may
# obtain a copy of this license in the LICENSE.txt file in the root directory
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
#
# Any modifications or derivative works of this code must retain this
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.
"""Package modes and qubit couplings, analytically.

A superconducting chip in a metal package sits in a box resonator loaded by
the silicon slab. The lowest box modes are LSM modes, whose electric field at
the slab surface drives every qubit on the chip at once, with a coupling that
follows the mode's standing-wave pattern across the array. This module holds
the closed-form side of that picture, to check a full-wave simulation
against:

- the LSM_ab0 modes of a rectangular box partly filled with a dielectric slab
  (``lsm_mode``, and the closed-form approximations ``lsm_mode_approx``), and
  the electric-dipole estimate of a qubit's coupling to one (``dipole_coupling``);
- the two-mode lumped circuit of a qubit and a package mode, its couplings,
  eigenfrequencies and impedance matrix (``circuit_couplings``,
  ``circuit_impedance``), and the fit of a simulated impedance matrix back to
  that circuit (``fit_impedance``);
- the amplitude of a coupling pattern over a uniform ``n x n`` array
  (``qubit_centers``, ``fit_amplitude``).

Equation numbers refer to R. Molavi *et al.*, "Extracting electromagnetic
bare mode couplings in large superconducting quantum processors,"
arXiv:2609.22442 (2026). Used by tutorials 4.41-4.45; the finite-element side
is :mod:`qiskit_metal.analyses.fem`.
"""

from __future__ import annotations

import warnings
from dataclasses import dataclass

import numpy as np
import scipy.linalg as la
import scipy.optimize as opt

EPS0 = 8.8541878128e-12  # F/m
MU0 = 1.25663706212e-6  # H/m
C0 = 299792458.0  # m/s
C0_MM = C0 * 1e3  # mm/s


[docs] def qubit_centers(n, pitch): """{(i, j): (x, y)} qubit centers in mm, column i along x, row j along y.""" return { (i, j): ((i + 0.5) * pitch, (j + 0.5) * pitch) for i in range(n) for j in range(n) }
# --------------------------------------------------------------------------- # 2. Analytic package modes: LSM modes of a dielectric-loaded box (App. E) # ---------------------------------------------------------------------------
[docs] @dataclass class LSMMode: """One LSM_ab0 mode of a rectangular box partially filled with a slab. Lengths in metres. ``E0x`` is the amplitude of the in-plane field at the slab surface for 1 J of mode energy, Eq. (E14). """ a: int b: int f: float kz_si: float kz_air: float gamma: float E0z: float E0x: float U_ratio: float Lx: float Ly: float Lz: float t: float eps_r: float
[docs] def Ez(self, z): """Vertical field E_z(z) at the in-plane maximum, Eqs. (E1)-(E2).""" z = np.asarray(z, dtype=float) si = self.E0z * np.cos(self.kz_si * z) air = ( self.eps_r * self.E0z * np.cos(self.kz_si * self.t) / np.cosh(self.kz_air * (self.Lz - self.t)) * np.cosh(self.kz_air * (self.Lz - z)) ) return np.where(z <= self.t, si, air)
[docs] def Ex_surface(self, x, y): """In-plane field E_x at the slab surface z = t, Eqs. (15), (E8)-(E9). ``E0x`` holds the magnitude the paper quotes. Eq. (E9) carries a minus sign, because E_z decreases with height in the silicon: ``E_x = -a abs(E0x) cos(a pi x/Lx) sin(b pi y/Ly)`` for E_z > 0. """ return ( -self.a * self.E0x * np.cos(self.a * np.pi * x / self.Lx) * np.sin(self.b * np.pi * y / self.Ly) )
[docs] def lsm_mode(a, b, Lx, Ly, Lz, t, eps_r, Em=1.0): """Solve the transcendental equation (E3) for the lowest LSM_ab0 mode. The lowest mode is the root with ``kz_si * t < pi/2``, below the first pole of ``ks tan(ks t)``. ``Lx``, ``Ly``, ``Lz`` (the box) and ``t`` (the slab) are in mm; the returned mode is in SI units, normalized to mode energy ``Em`` joules. """ Lx, Ly, Lz, t = [1e-3 * v for v in (Lx, Ly, Lz, t)] gamma = np.hypot(a * np.pi / Lx, b * np.pi / Ly) def kz(w): k0 = w / C0 return np.sqrt(eps_r * k0**2 - gamma**2), np.sqrt(gamma**2 - k0**2) def residual(w): ks, ka = kz(w) return ks * np.tan(ks * t) - eps_r * ka * np.tanh(ka * (Lz - t)) # The lowest root has ks t < pi/2; ks tan(ks t) has a pole at ks t = pi/2, # which lies inside (c gamma / sqrt(eps_r), c gamma) for small boxes or # thick slabs. Stop the bracket just below it. lo = C0 * gamma / np.sqrt(eps_r) * (1 + 1e-12) w_pole = C0 * np.sqrt(gamma**2 + (np.pi / (2 * t)) ** 2) / np.sqrt(eps_r) hi = min(C0 * gamma * (1 - 1e-12), w_pole * (1 - 1e-9)) w = opt.brentq(residual, lo, hi, xtol=1e-6) ks, ka = kz(w) # Mode energy, Eq. (E13), in units of U0 = eps0 E0z^2 V / 16 r_si = (ks / gamma) ** 2 r_air = (ka / gamma) ** 2 U_ratio = eps_r * ( (1 + r_si) * t / Lz + (1 - r_si) * np.sin(2 * ks * t) / (2 * ks * Lz) ) + (eps_r**2 * np.cos(ks * t) ** 2 / np.cosh(ka * (Lz - t)) ** 2) * ( (1 - r_air) * (1 - t / Lz) + (1 + r_air) * np.sinh(2 * ka * (Lz - t)) / (2 * ka * Lz) ) V = Lx * Ly * Lz E0z = np.sqrt(Em / (EPS0 * V / 16 * U_ratio)) E0x = (np.pi / Lx) * ks * np.sin(ks * t) / gamma**2 * E0z # Eq. (E14) return LSMMode( a, b, w / (2 * np.pi), ks, ka, gamma, E0z, E0x, U_ratio, Lx, Ly, Lz, t, eps_r )
[docs] def lsm_mode_approx(a, b, Lx, Ly, Lz, t, eps_r, Em=1.0): """The closed-form approximations at the end of Appendix E (SI units). They assume a thin slab, ``kz_si * t << 1``. A ``UserWarning`` is issued when the approximate ``kz_si * t`` exceeds 0.5, where the frequency is off by about 1 % or more (small boxes or thick slabs); use :func:`lsm_mode` there. """ Lx, Ly, Lz, t = [1e-3 * v for v in (Lx, Ly, Lz, t)] gamma = np.hypot(a * np.pi / Lx, b * np.pi / Ly) eps_eff = 1 / (t / Lz / eps_r + (1 - t / Lz)) V = Lx * Ly * Lz kz_si = gamma * np.sqrt((eps_r - 1) * (1 - t / Lz)) if kz_si * t > 0.5: warnings.warn( f"lsm_mode_approx: kz_si * t = {kz_si * t:.2f} > 0.5, outside the " "thin-slab validity of the closed-form approximation (frequency " "error ~1 % or more); use lsm_mode.", stacklevel=2, ) return dict( f=C0 * gamma / np.sqrt(eps_eff) / (2 * np.pi), kz_si=kz_si, kz_air=gamma * np.sqrt(1 - 1 / eps_eff), E0x=(eps_r - 1) * np.pi * t / Lx * (1 - t / Lz) * np.sqrt(8 * Em / (eps_r * EPS0 * V) * eps_eff / eps_r), eps_eff=eps_eff, )
[docs] def dipole_coupling(px, mode: LSMMode, Em=1.0, En=1.0): """Electric-dipole estimate of the on-resonance coupling amplitude. k_C = p_x a E0x / (2 sqrt(Em En)) (Eq. 16 at the field maximum), and g_C = k_C sqrt(w_m w_n) / 2 with w_n = w_m. Returns (k_C, A) with A in Hz. """ kC = px * mode.a * mode.E0x / (2 * np.sqrt(Em * En)) return kC, kC * mode.f / 2
# --------------------------------------------------------------------------- # 3. The two-mode circuit (Fig. 3) and the impedance-matrix fit (App. D) # ---------------------------------------------------------------------------
[docs] def circuit_couplings(C, L): """Bare frequencies and couplings of two coupled LC resonators, Eq. (A6)-(A11). ``C`` and ``L`` are the 2x2 capacitance and inductance matrices (SI). Returns a dict with bare angular frequencies ``w`` (2,), coupling efficiencies ``kC``, ``kL`` and couplings ``gC``, ``gL`` in rad/s. """ Ci = la.inv(C) Li = la.inv(L) w = np.sqrt(np.diag(Li) * np.diag(Ci)) kC = Ci[0, 1] / np.sqrt(Ci[0, 0] * Ci[1, 1]) kL = -Li[0, 1] / np.sqrt(Li[0, 0] * Li[1, 1]) s = np.sqrt(w[0] * w[1]) return dict(w=w, kC=kC, kL=kL, gC=kC * s / 2, gL=kL * s / 2)
[docs] def g_on_resonance(gC, gL, wm, wn): """Eq. (10): convert (g_C, g_L) at a detuned qubit to the resonant g.""" return (gC - gL * wm / wn) * np.sqrt(wm / wn)
[docs] def circuit_eigenfrequencies(C, L): """Exact normal-mode angular frequencies: eigenvalues of C^-1/2 L^-1 C^-1/2.""" Cih = la.inv(la.sqrtm(C)).real return np.sqrt(np.sort(la.eigvalsh(Cih @ la.inv(L) @ Cih)))
[docs] def circuit_impedance(w, Lp, C, dL): """Impedance matrix of the lumped model, Eq. (12). ``w`` in rad/s. ``Lp`` holds the port shunts (diagonal), ``C`` the capacitance matrix and ``dL`` the geometric inductances. Returns complex Z of shape (len(w), 2, 2) with the engineering convention Z = jX. """ w = np.atleast_1d(w) Z = np.empty((len(w), 2, 2), dtype=complex) for k, wk in enumerate(w): inner = la.inv(la.inv(1j * wk * C) + 1j * wk * dL) Z[k] = la.inv(la.inv(1j * wk * Lp) + inner) return Z
[docs] @dataclass class ImpedanceFit: """Result of the Appendix-D fit (SI units, index 0 = package, 1 = qubit).""" poles: np.ndarray # angular frequencies of the two poles residues: np.ndarray # (2, 2, 2) residue matrices R_mu C: np.ndarray Lp: np.ndarray dL: np.ndarray rms_error: float @property def L(self): return self.Lp + self.dL
[docs] def couplings(self): """(g_C, g_L, g) in Hz: g_C, g_L at the fitted detuning, g via Eq. (10).""" c = circuit_couplings(self.C, self.L) g = g_on_resonance(c["gC"], c["gL"], c["w"][0], c["w"][1]) return c["gC"] / (2 * np.pi), c["gL"] / (2 * np.pi), g / (2 * np.pi)
[docs] def fit_impedance(w, Z, n_poles=2): """Fit a simulated 2x2 impedance matrix to Eq. (12), following Appendix D. 1. Fit Z = sum_mu 2 j w w_mu R_mu / (w_mu^2 - w^2) + j w dL~ (Eq. D1, D4): the pole frequencies by least squares, the residues and dL~ linearly. 2. Factor each residue as R_mu = sigma_mu sigma_mu^T (D5), stack Sigma. 3. L~^-1 = 1/2 Sigma^-T Omega Sigma^-1, C~ = 1/2 Sigma^-T Omega^-1 Sigma^-1 (D7). 4. Undo the tail correction with alpha = I + L~^-1 dL~ (D3). ``w`` in rad/s, ``Z`` complex (nw, 2, 2) in ohms. """ w = np.asarray(w, dtype=float) X = np.asarray(Z).imag.reshape(len(w), -1) finite = np.all(np.isfinite(X), axis=1) # a sample exactly on a pole is infinite w, X = w[finite], X[finite] # relative weights, softened so zero crossings of X do not dominate weight = 1 / (np.abs(X) + np.median(np.abs(X), axis=0)) def rows(poles): """Drop samples that sit on top of a pole.""" return np.all( np.abs(w[:, None] - poles[None, :]) > 1e-9 * poles[None, :], axis=1 ) def design(poles, keep): cols = [2 * w[keep] * p / (p**2 - w[keep] ** 2) for p in poles] + [w[keep]] return np.stack(cols, axis=1) # (nw, n_poles + 1) def solve_linear(poles): keep = rows(poles) A = design(poles, keep) s = np.abs(A).max(axis=0) # column scaling for conditioning coef = np.empty((A.shape[1], X.shape[1])) for k in range( X.shape[1] ): # weighted least squares, one matrix element at a time wk = weight[keep, k][:, None] coef[:, k] = la.lstsq(wk * A / s, weight[keep, k] * X[keep, k])[0] / s return coef, A, keep def resid(poles): coef, A, keep = solve_linear(poles) r = np.zeros_like( X ) # fixed length: samples on top of a trial pole count as zero misfit r[keep] = (A @ coef - X[keep]) * weight[keep] return r.ravel() # Poles: det X jumps through infinity at a pole (and passes through zero # at a zero of Z). Take the sign changes with the largest |det X| and # refine each as the root of 1/det X, which is smooth across the pole. det = X[:, 0] * X[:, 3] - X[:, 1] * X[:, 2] flips = np.nonzero(np.sign(det[:-1]) != np.sign(det[1:]))[0] size = np.sqrt(np.abs(det[flips] * det[flips + 1])) flips = np.sort(flips[np.argsort(-size)[:n_poles]]) if len(flips) < n_poles: raise ValueError( f"found {len(flips)} of {n_poles} poles: refine the frequency grid so that " "each pole and the zero next to it fall in different intervals" ) guess, lower, upper = [], [], [] for k in flips: lo, hi = max(k - 1, 0), min(k + 3, len(w)) dw = w[k + 1] - w[k] coeffs = np.polyfit((w[lo:hi] - w[k]) / dw, 1 / det[lo:hi], min(hi - lo - 1, 3)) roots = ( np.roots(coeffs).real * dw + w[k] if np.all(np.isfinite(coeffs)) else np.array([]) ) roots = roots[(roots >= w[k]) & (roots <= w[k + 1])] guess.append(roots[0] if len(roots) else 0.5 * (w[k] + w[k + 1])) lower.append(w[k]) # the pole lies between the two samples where det X flips upper.append(w[k + 1]) guess, lower, upper = np.array(guess), np.array(lower), np.array(upper) sol = opt.least_squares( resid, guess, x_scale=(upper - lower) / 10, bounds=(lower, upper), xtol=1e-15, ftol=1e-15, gtol=1e-15, ) poles = np.sort(sol.x) coef, A, keep = solve_linear(poles) residues = coef[:n_poles].reshape(n_poles, 2, 2) dLt = coef[n_poles].reshape(2, 2) dLt = (dLt + dLt.T) / 2 sig = [] for R in residues: R = (R + R.T) / 2 ev, vec = la.eigh(R) k = np.argmax(np.abs(ev)) sig.append(vec[:, k] * np.sqrt(abs(ev[k]))) Sig = np.stack(sig, axis=1) Om = np.diag(poles) SiT = la.inv(Sig).T Lt_inv = 0.5 * SiT @ Om @ la.inv(Sig) Ct = 0.5 * SiT @ la.inv(Om) @ la.inv(Sig) alpha = np.eye(2) + Lt_inv @ dLt ai = la.inv(alpha) C = ai @ Ct @ ai.T Lp_inv = ai @ Lt_inv dL = alpha.T @ dLt Lp = la.inv((Lp_inv + Lp_inv.T) / 2) rms = np.sqrt(np.mean(resid(poles) ** 2)) return ImpedanceFit(poles, residues, (C + C.T) / 2, Lp, (dL + dL.T) / 2, rms)
[docs] def fit_amplitude(g, a, b, Lx, Ly): """Least-squares ``A`` in ``g = A cos(a pi x/Lx) sin(b pi y/Ly)`` (Eqs. 14, 17). ``g`` is an (n, n) array [j, i] over a uniform grid of qubits on a ``Lx x Ly`` (mm) chip. Returns ``(A, largest residual / abs(A))``. """ n = g.shape[0] c = qubit_centers(n, Lx / n) shape = np.zeros_like(g) for (i, j), (x, y) in c.items(): shape[j, i] = np.cos(a * np.pi * x / Lx) * np.sin(b * np.pi * y / Ly) ok = np.isfinite(g) A = np.sum(g[ok] * shape[ok]) / np.sum(shape[ok] ** 2) return A, np.max(np.abs(g[ok] - A * shape[ok])) / abs(A)