Tutorial 16: Inverse Design by ML Screening#
In Tutorials 11-13 we started from a layout and asked for its capacitance matrix. In a real design job it is usually the other way round: we are given target numbers (a charging energy, a few coupling capacitances) and need a layout that hits them. In this tutorial we walk through the two examples of the “Practical workflows” section of our paper, using only public SQuADDS APIs:
example |
targets |
search |
|---|---|---|
an Xmon |
\(E_C\) and the claw coupling \(C_{NS}\), at three targets |
random screen, best pick per target |
a TransmonPocket with readout, bus and drive couplers |
four at once |
random screen, then a few rounds of refinement around the best candidates |
Why not hand the targets to an inverse-design optimizer? That needs a fast, accurate model of how the layout parameters map to the circuit, and a good idea of which parameters matter and over what range. For a new component neither is easy to come by. The capacitance model gives an accurate matrix in about a second to a few seconds per layout on one CPU core, so we can skip that problem: try thousands of random layouts within sensible bounds, keep the best, and spend one expensive Q3D run on the winner to confirm it.
Note: the ML models need the optional extras, pip install "squadds[ml,gds]". Xmon and TransmonPocket are families the released model was trained on, so this tutorial shows a design workflow, not the model’s accuracy on new kinds of layouts (the random candidates we generate are, of course, new layouts).
[1]:
%load_ext autoreload
%autoreload 2
%matplotlib inline
Setup#
We use quantum-metal without its GUI, and silence its (many) deprecation warnings.
[2]:
import os
import tempfile
import time
import warnings
from collections import Counter
from pathlib import Path
os.environ.setdefault("QISKIT_METAL_HEADLESS", "1")
warnings.filterwarnings("ignore")
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from matplotlib_inline.backend_inline import set_matplotlib_formats
from qiskit_metal import Dict, designs
from qiskit_metal.qlibrary.qubits.transmon_pocket import TransmonPocket
from squadds.components.xmon import Xmon
from squadds.layouts import export_dataset_gds
from squadds.ml.capacitance import CapacitancePredictor, inspect_layout, prepare_layout
from squadds.ml.capacitance.bridge import EC_MHz_from_matrix
set_matplotlib_formats("png")
pd.set_option("display.width", 160)
How big a search?#
The paper screened 5,000 layouts per example on a cluster, a few CPU-hours. By default this notebook runs a smaller version that finishes in about 12 minutes on a laptop (Apple M5 Pro, 8 processes). Set the knobs below to the paper’s values (in the comments) to run the full size. On the same laptop that takes about two hours.
knob |
this notebook |
paper |
|---|---|---|
|
1,000 |
5,000 |
|
300 |
5,000 |
|
10 x 8 |
20 x 50 in round 1, 20 x 40 after |
|
1, 1, 1, 0.2 |
1, 1, 1, 0.2 (four rounds) |
WORKERS processes run at once, each with THREADS CPU threads. WORKERS is 8, or the number of CPUs this process may use when that is fewer (under Slurm or in a container, the job’s allocation, not the node’s cores).
[3]:
N_XMON = 1000 # paper: 5000
N_POCKET = 300 # paper: 5000
TOP, PER = 10, 8 # paper: 20, 50 (round 1) then 40
JITTER = [1.0, 1.0, 1.0, 0.2] # one entry per refinement round
CPUS = len(os.sched_getaffinity(0)) if hasattr(os, "sched_getaffinity") else (os.cpu_count() or 1) # this job's CPUs (Slurm, containers)
WORKERS, THREADS = min(8, CPUS), 1
SEED = 16
WORKDIR = Path(tempfile.mkdtemp(prefix="tutorial16_")) # thousands of small GDS files; point it elsewhere to keep them
WORKDIR
[3]:
PosixPath('/var/folders/s5/b9svd25j78scrd1kw84_tcs00000gn/T/tutorial16_5_9u1xro')
We use the default model, QCap, for every score in this tutorial:
[4]:
predictor = CapacitancePredictor("QCap", threads=THREADS)
predictor
[4]:
CapacitancePredictor('QCap', threads=1)
predictor.predict takes a list of layouts and, with workers > 1, predicts them in that many processes at once. Here is a small wrapper that also records what each batch cost. Every result carries its own timing, thread count and machine, so we print those rather than guess them.
The per-layout time is the model’s own work (embedding, the two field solves of the physics prior, the networks). The wall time also counts starting the processes and loading the model in each.
[5]:
COST = []
def predict_all(layouts, stage):
t0 = time.perf_counter()
results = predictor.predict(layouts, workers=WORKERS)
wall = time.perf_counter() - t0
per = np.array([r.timing_s["total_s"] for r in results])
COST.append({"stage": stage, "layouts": len(results), "wall (min)": wall / 60, "processes": WORKERS,
"threads each": results[0].threads, "per layout, median (s)": np.median(per),
"per layout, p90 (s)": np.percentile(per, 90)})
print(f"{stage}: {len(results)} layouts in {wall / 60:.1f} min wall time ({WORKERS} processes x "
f"{results[0].threads} thread) | per layout: median {np.median(per):.2f} s, p90 {np.percentile(per, 90):.2f} s")
return results
One more helper: a quick design-rule check. A random layout can put two pieces of metal on top of each other or closer than we could fabricate, and such a layout would silently have fewer conductors. We keep a layout only if it has the conductors we expect and every gap (conductor-conductor and conductor-ground) is at least 2 µm, the rule the paper’s generator used.
[6]:
MIN_GAP_UM = 1.99
def check_layout(gds, n_conductors):
# The prepared layout (ground + conductor bodies) that the predictor will read, if it passes the checks.
lay = prepare_layout(str(gds))
bodies = list(lay.conductors)
if len(bodies) != n_conductors:
raise ValueError(f"{len(bodies)} conductors instead of {n_conductors}")
gaps = [a.distance(b) for i, a in enumerate(bodies) for b in bodies[i + 1:]] + [b.distance(lay.ground) for b in bodies]
if min(gaps) < MIN_GAP_UM:
raise ValueError("minimum gap below 2 um")
return lay
Example 1: Xmon screening#
An Xmon is a cross (the qubit island, whose junction goes to ground) in a ground pocket, with a claw that couples it to a readout resonator. From the predicted Maxwell matrix we need two numbers:
the charging energy \(E_C = e^2 / 2hC_{SS}\), where \(C_{SS}\) is the cross’s diagonal entry (so every claw counts), and
the claw coupling \(C_{NS}\), minus the Maxwell entry between the claw and the cross.
We want three Xmons:
target |
\(E_C\) (MHz) |
\(C_{NS}\) (fF) |
|---|---|---|
1 |
200 |
3 |
2 |
250 |
4 |
3 |
300 |
2 |
and score a candidate by its summed relative distance to a target, \(|E_C/E_C^{\rm t} - 1| + |C_{NS}/C_{NS}^{\rm t} - 1|\).
A random Xmon generator#
We draw every parameter uniformly within the bounds of the paper’s pool (µm):
parameter |
range |
|---|---|
|
120-320 |
|
16-40 |
|
30 to min( |
|
8-20 |
|
4-10 |
|
4-12 |
|
20-60 |
second claw (half of the layouts) |
same claw on the west or east arm, length 30 to min( |
The layout is SQuADDS’ Xmon component, exported with export_dataset_gds. That writes the GDS convention of the model’s training data: ground on layer 1/0, conductors on 1/10, and the chip margin of the Xmon family.
One difference from the paper’s Xmon pool
Xmon draws the claw’s feed line as in the training data (claw_cpw_width, 10 µm, wide). The paper’s pool came from a development build of quantum-metal whose feed is claw_width wide and a few µm shorter, so the same parameters give a slightly different layout. On one design, the same model put the two versions 0.29 % (0.58 MHz) apart on \(E_C\) and 0.47 % (0.014 fF) on \(C_{NS}\).
[7]:
def um(v):
return f"{v:.3f}um"
def sample_xmon(rng):
cl = rng.uniform(120, 320)
p = {"cross_length": cl, "cross_width": rng.uniform(16, 40), "cross_gap": rng.uniform(16, 40),
"claw_length": rng.uniform(30, min(cl, 220)), "claw_width": rng.uniform(8, 20), "claw_gap": rng.uniform(4, 10),
"ground_spacing": rng.uniform(4, 12), "claw_cpw_length": rng.uniform(20, 60),
"second_claw": bool(rng.random() < 0.5), "second_claw_location": str(rng.choice(["0", "180", "270"]))}
p["second_claw_length"] = rng.uniform(30, min(cl, 220))
return p
def build_xmon(p, path):
def claw(length, location):
return Dict(connector_location=location, connector_type="0", claw_length=um(length),
claw_width=um(p["claw_width"]), claw_gap=um(p["claw_gap"]), ground_spacing=um(p["ground_spacing"]),
claw_cpw_length=um(p["claw_cpw_length"]), claw_cpw_width="10um")
pads = Dict(readout=claw(p["claw_length"], "90"))
if p["second_claw"]:
pads["bus"] = claw(p["second_claw_length"], p["second_claw_location"])
design = designs.DesignPlanar({}, overwrite_enabled=True)
xmon = Xmon(design, "xmon", options=Dict(cross_length=um(p["cross_length"]), cross_width=um(p["cross_width"]),
cross_gap=um(p["cross_gap"]), connection_pads=pads))
# the chip margin is 8 ground gaps, from the unrounded parameters as the paper's generator did
return export_dataset_gds(xmon, path, ground_gap_um=max(p["cross_gap"], p["ground_spacing"]))
Let’s build one and look at it before we build a thousand. inspect_layout shows the layout the way the predictor reads it: the ground in grey and every conductor body with the name the prediction will use. The export writes the conductors in the dataset’s order, so C1 is the readout claw (N), C2 the cross (S) and C3, if there is one, the second claw.
[8]:
rng = np.random.default_rng(SEED)
example = sample_xmon(rng)
example_gds = build_xmon(example, WORKDIR / "xmon_example.gds")
view = inspect_layout(str(example_gds), figsize=(5, 5))
view["names"]
[8]:
['C1', 'C2', 'C3']
Generate the pool#
Now the whole pool. Layouts that fail the export (the ground breaks into pieces) or the design-rule check are redrawn, and we count why.
[9]:
rng = np.random.default_rng(SEED)
xmon_params, xmon_layouts, rejected = [], [], Counter()
(WORKDIR / "xmon").mkdir(exist_ok=True)
t0 = time.perf_counter()
while len(xmon_layouts) < N_XMON:
p = sample_xmon(rng)
try:
gds = build_xmon(p, WORKDIR / "xmon" / f"xmon_{len(xmon_layouts):04d}.gds")
lay = check_layout(gds, 3 if p["second_claw"] else 2)
except Exception as err:
rejected[str(err).split("(")[0].strip()] += 1
continue
xmon_params.append(p)
xmon_layouts.append(lay)
print(f"{len(xmon_layouts)} layouts in {time.perf_counter() - t0:.0f} s (one process); rejected: {dict(rejected)}")
1000 layouts in 42 s (one process); rejected: {'2 conductors instead of 3': 8, 'ground is not one connected body': 39}
Predict all of them#
One call, WORKERS processes:
[10]:
xmon_results = predict_all(xmon_layouts, "Xmon screen")
print(xmon_results[0].machine)
Xmon screen: 1000 layouts in 1.7 min wall time (8 processes x 1 thread) | per layout: median 0.71 s, p90 1.21 s
Apple M5 Pro, 18 CPUs, Darwin arm64
Every result is a full Maxwell matrix (fF, ground first). Let’s turn each into \(E_C\) and \(C_{NS}\). EC_MHz_from_matrix takes the cross’s diagonal entry for a grounded transmon:
[11]:
def xmon_quantities(res):
M, names = res.matrix_fF, res.names
return {"E_C (MHz)": EC_MHz_from_matrix(M, names, "C2"), "C_NS (fF)": -M[names.index("C1"), names.index("C2")]}
xmon = pd.DataFrame([xmon_quantities(r) for r in xmon_results]).join(pd.DataFrame(xmon_params))
print("every matrix passed its physics checks:", all(r.checks["passed"] for r in xmon_results))
xmon[["E_C (MHz)", "C_NS (fF)"]].describe().round(2)
every matrix passed its physics checks: True
[11]:
| E_C (MHz) | C_NS (fF) | |
|---|---|---|
| count | 1000.00 | 1000.00 |
| mean | 183.72 | 3.00 |
| std | 60.11 | 1.50 |
| min | 90.01 | 0.66 |
| 25% | 136.15 | 1.82 |
| 50% | 168.21 | 2.70 |
| 75% | 223.08 | 3.97 |
| max | 377.94 | 9.70 |
Pick the best candidate per target#
[12]:
XMON_TARGETS = [(200.0, 3.0), (250.0, 4.0), (300.0, 2.0)]
def xmon_loss(df, ec, cns):
return (df["E_C (MHz)"] / ec - 1).abs() + (df["C_NS (fF)"] / cns - 1).abs()
rows = []
for ec, cns in XMON_TARGETS:
loss = xmon_loss(xmon, ec, cns)
i = loss.idxmin()
r = xmon.loc[i]
rows.append({"target E_C (MHz)": ec, "target C_NS (fF)": cns, "layout": i,
"E_C (MHz)": r["E_C (MHz)"], "E_C - target (MHz)": r["E_C (MHz)"] - ec,
"E_C - target (%)": 100 * (r["E_C (MHz)"] / ec - 1),
"C_NS (fF)": r["C_NS (fF)"], "C_NS - target (fF)": r["C_NS (fF)"] - cns,
"C_NS - target (%)": 100 * (r["C_NS (fF)"] / cns - 1), "loss": loss[i],
"within 2 % of both": int((loss < 0.02).sum())})
xmon_picks = pd.DataFrame(rows)
xmon_picks.round(3)
[12]:
| target E_C (MHz) | target C_NS (fF) | layout | E_C (MHz) | E_C - target (MHz) | E_C - target (%) | C_NS (fF) | C_NS - target (fF) | C_NS - target (%) | loss | within 2 % of both | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 200.0 | 3.0 | 473 | 198.250 | -1.750 | -0.875 | 3.043 | 0.043 | 1.434 | 0.023 | 0 |
| 1 | 250.0 | 4.0 | 996 | 257.803 | 7.803 | 3.121 | 3.973 | -0.027 | -0.671 | 0.038 | 0 |
| 2 | 300.0 | 2.0 | 827 | 300.715 | 0.715 | 0.238 | 1.984 | -0.016 | -0.800 | 0.010 | 2 |
These are the model’s numbers for its picks, so the distance to the target here is a property of the pool. With random sampling, a target in a sparse corner of the \((C_{NS}, E_C)\) plane gets a worse pick. The last column counts how many layouts of the pool land within a summed 2 % of each target. Let’s see where the pool sits:
[13]:
fig, (ax, bx) = plt.subplots(1, 2, figsize=(12, 4.8))
ax.scatter(xmon["C_NS (fF)"], xmon["E_C (MHz)"], s=4, color="0.7", label=f"{len(xmon)} random layouts (model)")
colors = ["tab:blue", "tab:orange", "tab:green"]
for (ec, cns), (_, pk), c in zip(XMON_TARGETS, xmon_picks.iterrows(), colors):
ax.scatter(cns, ec, marker="*", s=260, color=c, edgecolor="k", zorder=3, label=f"target ({ec:.0f} MHz, {cns:.0f} fF)")
ax.scatter(pk["C_NS (fF)"], pk["E_C (MHz)"], s=60, facecolor="none", edgecolor=c, lw=2, zorder=3)
near = xmon.assign(loss=xmon_loss(xmon, ec, cns)).nsmallest(40, "loss")
bx.scatter(100 * (near["C_NS (fF)"] / cns - 1), 100 * (near["E_C (MHz)"] / ec - 1), s=14, color=c, alpha=0.5)
bx.scatter(pk["C_NS - target (%)"], pk["E_C - target (%)"], s=90, facecolor="none", edgecolor=c, lw=2)
ax.set(xscale="log", xlabel="$C_{NS}$ (fF)", ylabel="$E_C$ (MHz)", title="(a) the pool and the targets (circles: picks)")
ax.legend(fontsize=8, loc="upper right")
bx.axhline(0, color="k", lw=0.6)
bx.axvline(0, color="k", lw=0.6)
bx.set(xlim=(-12, 12), ylim=(-12, 12), xlabel="$C_{NS}$ - target (%)", ylabel="$E_C$ - target (%)",
title="(b) the 40 closest layouts per target (circles: picks)")
fig.tight_layout()
And the three picked layouts (C1 claw, C2 cross, C3 second claw):
[14]:
fig, axes = plt.subplots(1, 3, figsize=(14, 4.8))
for ax, (_, pk) in zip(axes, xmon_picks.iterrows()):
xmon_layouts[int(pk["layout"])].render(ax=ax, compact=True)
ax.set_title(f"target ({pk['target E_C (MHz)']:.0f} MHz, {pk['target C_NS (fF)']:.0f} fF): "
f"{pk['E_C (MHz)']:.1f} MHz, {pk['C_NS (fF)']:.3f} fF", fontsize=10)
fig.tight_layout()
The parameters of the picks, ready to go into a quantum-metal design:
[15]:
xmon.loc[xmon_picks["layout"], list(xmon_params[0])].round(2)
[15]:
| cross_length | cross_width | cross_gap | claw_length | claw_width | claw_gap | ground_spacing | claw_cpw_length | second_claw | second_claw_location | second_claw_length | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 473 | 171.31 | 26.90 | 20.18 | 82.99 | 16.18 | 5.20 | 5.44 | 26.00 | False | 180 | 83.76 |
| 996 | 131.78 | 24.24 | 17.69 | 118.59 | 17.30 | 8.23 | 11.01 | 23.33 | False | 180 | 100.68 |
| 827 | 139.15 | 27.90 | 39.29 | 88.48 | 15.65 | 7.78 | 11.07 | 30.45 | False | 270 | 83.80 |
What Q3D said in the paper#
We don’t run Q3D here. In the paper, the three picks of the full 5,000-layout pool were solved in Ansys Q3D (16 cores of a cluster node, 18-19 adaptive passes, 5.3-7.2 min each). The table below holds the paper’s numbers, not recomputed in this notebook.
Why the model column of the paper’s table differs slightly from the released model
The model column is the version of QCap that was deployed when the study ran (October 2026). The released model’s networks have been retrained since, so they give slightly different numbers for the same layout.
[16]:
paper_xmon = pd.DataFrame(
{"target E_C (MHz)": [200.0, 250.0, 300.0], "target C_NS (fF)": [3.0, 4.0, 2.0],
"model E_C (MHz)": [199.934, 246.239, 296.987], "model C_NS (fF)": [3.0396, 3.9819, 1.9524],
"Q3D E_C (MHz)": [200.345, 246.632, 296.747], "Q3D C_NS (fF)": [3.0432, 3.9710, 1.9491]},
index=pd.Index(["2659", "2073", "2147"], name="paper pick"))
def paper_table(df, quantities):
out = {}
for q, unit in quantities:
t, m, s = df[f"target {q} ({unit})"], df[f"model {q} ({unit})"], df[f"Q3D {q} ({unit})"]
out[f"{q}: Q3D - target ({unit})"] = s - t
out[f"{q}: Q3D - target (%)"] = 100 * (s / t - 1)
out[f"{q}: model - Q3D ({unit})"] = m - s
out[f"{q}: model - Q3D (%)"] = 100 * (m / s - 1)
return pd.DataFrame(out, index=df.index)
def summary(table, quantities):
for q, unit in quantities:
for what in ("Q3D - target", "model - Q3D"):
d, pct = table[f"{q}: {what} ({unit})"], table[f"{q}: {what} (%)"].abs()
print(f"{q:>9} {what:>13}: median {pct.median():.2f} % | MAE {d.abs().mean():.4g} {unit} | "
f"RMSE {np.sqrt((d ** 2).mean()):.4g} {unit} | max {pct.max():.2f} %")
XQ = [("E_C", "MHz"), ("C_NS", "fF")]
xmon_q3d = paper_table(paper_xmon, XQ)
display(xmon_q3d.round(4))
summary(xmon_q3d, XQ)
| E_C: Q3D - target (MHz) | E_C: Q3D - target (%) | E_C: model - Q3D (MHz) | E_C: model - Q3D (%) | C_NS: Q3D - target (fF) | C_NS: Q3D - target (%) | C_NS: model - Q3D (fF) | C_NS: model - Q3D (%) | |
|---|---|---|---|---|---|---|---|---|
| paper pick | ||||||||
| 2659 | 0.345 | 0.1725 | -0.411 | -0.2051 | 0.0432 | 1.440 | -0.0036 | -0.1183 |
| 2073 | -3.368 | -1.3472 | -0.393 | -0.1593 | -0.0290 | -0.725 | 0.0109 | 0.2745 |
| 2147 | -3.253 | -1.0843 | 0.240 | 0.0809 | -0.0509 | -2.545 | 0.0033 | 0.1693 |
E_C Q3D - target: median 1.08 % | MAE 2.322 MHz | RMSE 2.711 MHz | max 1.35 %
E_C model - Q3D: median 0.16 % | MAE 0.348 MHz | RMSE 0.3564 MHz | max 0.21 %
C_NS Q3D - target: median 1.44 % | MAE 0.04103 fF | RMSE 0.04202 fF | max 2.54 %
C_NS model - Q3D: median 0.17 % | MAE 0.005933 fF | RMSE 0.006896 fF | max 0.27 %
In Q3D, every pick landed close to its targets, and the model’s error against Q3D is several times smaller than the distance of the picks to their targets (compare the medians above). The larger misses of the second and third targets were already in the model’s prediction of its own pick, because the pool had no closer layout. A denser pool would close them, as panel (b) above suggests.
Example 2: a TransmonPocket with three couplers#
Now a harder problem. A TransmonPocket has two floating pads (the qubit is the voltage difference between them) and here three connection pads: a readout coupler and a bus coupler on top, a drive coupler at the bottom. With the ground, that is six conductors and a full 6 x 6 matrix. We want four things at once:
quantity |
target |
|---|---|
\(E_C\) of the qubit |
200 MHz |
\(C_{\rm eff}\) to the readout |
10 fF |
\(C_{\rm eff}\) to the bus |
1 fF |
\(C_{\rm eff}\) to the drive |
0.1 fF |
The three couplings span a factor of 100 and every one of them also changes \(E_C\), so it is hard to guess good parameter bounds up front.
The quantities of a floating transmon#
With the couplers held at ground, the qubit is the differential mode of the two pads \(s\) and \(b\). Eliminating their common mode (a Schur complement of the 2 x 2 pad block of the Maxwell matrix) leaves one capacitance for the qubit,
and coupler \(k\), which sees the two pads through \(c_{ks}\) and \(c_{kb}\), couples to that mode with
All entries are Maxwell entries (\(C_{sb}\) and the \(c\)’s are negative). A coupler that sees both pads equally does not couple to the qubit at all. What counts is the imbalance. The export writes the conductors in the order readout (C1), top pad (C2), bottom pad (C3), bus (C4), drive (C5).
[17]:
P3_TARGETS = {"E_C (MHz)": 200.0, "readout (fF)": 10.0, "bus (fF)": 1.0, "drive (fF)": 0.1}
COUPLERS = {"readout": "C1", "bus": "C4", "drive": "C5"}
def pocket_quantities(res):
M, names = res.matrix_fF, res.names
s, b = names.index("C2"), names.index("C3")
css, cbb, csb = M[s, s], M[b, b], M[s, b]
s_sum, b_sum = css + csb, cbb + csb
out = {"E_C (MHz)": EC_MHz_from_matrix(M, names, ["C2", "C3"])}
for coupler, name in COUPLERS.items():
k = names.index(name)
out[f"{coupler} (fF)"] = abs(M[k, s] * b_sum - M[k, b] * s_sum) / (s_sum + b_sum)
return out
def pocket_loss(df):
return sum(np.abs(np.log(df[q] / t)) for q, t in P3_TARGETS.items())
EC_MHz_from_matrix with two pads computes the same \(C_\Sigma\) (as \(1/C_\Sigma = (C^{-1})_{ss} + (C^{-1})_{bb} - 2(C^{-1})_{sb}\) of the pad block). The loss is the summed \(|\log(\text{predicted}/\text{target})|\) over the four quantities, so 0.01 means about 1 % off in total.
A random TransmonPocket generator#
This is the paper’s generator, built from the TransmonPocket of quantum-metal with three connection_pads (µm; “log” = log-uniform):
parameter |
range |
|---|---|
pad width, height, gap |
400-900, 100-320, 15-80 |
readout coupler width, height, gap |
40 to 0.9 x pad width / 2 (log), 15-80, 3-40 (log) |
bus coupler width, height, gap |
12-200 (log), 10-50, 5-90 (log) |
drive coupler width, height, gap |
3-30 (log), 6-30, 60-500 (log) |
pad width + 2 x (40-120) wide, tall enough for the couplers + 2 x (40-100) |
|
drive side |
left or right |
Exported with export_dataset_gds, the same parameters rebuild the paper’s layouts polygon for polygon.
[18]:
CPLRS = ("readout", "bus", "drive")
def sample_pocket(rng):
pw, ph, pg = rng.uniform(400, 900), rng.uniform(100, 320), rng.uniform(15, 80)
p = {"pad_width": pw, "pad_height": ph, "pad_gap": pg}
w = {"readout": (40, 0.9 * pw / 2), "bus": (12, 200), "drive": (3, 30)}
g = {"readout": (3, 40), "bus": (5, 90), "drive": (60, 500)}
h = {"readout": (15, 80), "bus": (10, 50), "drive": (6, 30)}
for c in CPLRS:
p[f"{c}_w"] = float(np.exp(rng.uniform(*np.log(w[c]))))
p[f"{c}_h"] = rng.uniform(*h[c])
p[f"{c}_gap"] = float(np.exp(rng.uniform(*np.log(g[c]))))
top = max(p["readout_h"] + p["readout_gap"], p["bus_h"] + p["bus_gap"])
p["pocket_width"] = pw + 2 * rng.uniform(40, 120)
p["pocket_height"] = pg + 2 * ph + 2 * (max(top, p["drive_h"] + p["drive_gap"]) + rng.uniform(40, 100))
p["drive_loc_W"] = int(rng.choice([-1, 1]))
return p
[18]:
def build_pocket(p, path):
side = {"readout": (1, 1), "bus": (-1, 1), "drive": (p["drive_loc_W"], -1)}
pads = Dict({c: Dict(loc_W=str(side[c][0]), loc_H=str(side[c][1]), pad_width=um(p[f"{c}_w"]),
pad_height=um(p[f"{c}_h"]), pad_gap=um(p[f"{c}_gap"]), cpw_width="10um", cpw_gap="6um",
cpw_extend="60um") for c in CPLRS})
design = designs.DesignPlanar({}, overwrite_enabled=True)
pocket = TransmonPocket(design, "pocket", options=Dict(
pad_width=um(p["pad_width"]), pad_height=um(p["pad_height"]), pad_gap=um(p["pad_gap"]),
pocket_width=um(p["pocket_width"]), pocket_height=um(p["pocket_height"]), connection_pads=pads))
# chip margin: 4 ground gaps, the pad-to-pocket gap (at least 20 um), as in the paper's generator
gap = min((p["pocket_width"] - p["pad_width"]) / 2, (p["pocket_height"] - p["pad_gap"]) / 2 - p["pad_height"])
return export_dataset_gds(pocket, path, ground_gap_um=max(gap, 20.0))
def build_pockets(params, folder):
# Build and check a list of parameter sets: (kept params, prepared layouts, rejection counts).
(WORKDIR / folder).mkdir(exist_ok=True)
kept, layouts, rejected = [], [], Counter()
for i, p in enumerate(params):
try:
layouts.append(check_layout(build_pocket(p, WORKDIR / folder / f"pocket_{i:04d}.gds"), 5))
kept.append(p)
except Exception as err:
rejected[str(err).split("(")[0].strip()] += 1
return kept, layouts, rejected
Let’s look at one (C1 readout, C2 / C3 the pads, C4 bus, C5 drive):
[19]:
example = sample_pocket(np.random.default_rng(SEED))
view = inspect_layout(str(build_pocket(example, WORKDIR / "pocket_example.gds")), figsize=(4.5, 6))
Step 1: screen random layouts#
[20]:
rng = np.random.default_rng(SEED)
t0 = time.perf_counter()
pocket_params, pocket_layouts, rejected = build_pockets([sample_pocket(rng) for _ in range(N_POCKET)], "pocket_screen")
print(f"{len(pocket_layouts)} layouts built in {time.perf_counter() - t0:.0f} s; rejected: {dict(rejected)}")
pocket_results = predict_all(pocket_layouts, "TransmonPocket screen")
300 layouts built in 24 s; rejected: {}
TransmonPocket screen: 300 layouts in 4.0 min wall time (8 processes x 1 thread) | per layout: median 5.90 s, p90 8.50 s
[21]:
QCOLS = list(P3_TARGETS)
screen = pd.DataFrame([pocket_quantities(r) for r in pocket_results])
screen["loss"] = pocket_loss(screen)
screen["params"] = pocket_params
within10 = (np.abs(np.log(screen[QCOLS] / pd.Series(P3_TARGETS))) < np.log(1.1)).all(axis=1).sum()
print(f"best loss {screen.loss.min():.3f}; layouts within 10 % of all four targets: {within10}")
screen.nsmallest(5, "loss")[QCOLS + ["loss"]].round(4)
best loss 0.870; layouts within 10 % of all four targets: 0
[21]:
| E_C (MHz) | readout (fF) | bus (fF) | drive (fF) | loss | |
|---|---|---|---|---|---|
| 38 | 266.7711 | 9.0458 | 1.1810 | 0.1370 | 0.8698 |
| 273 | 203.0406 | 10.5548 | 1.1307 | 0.2451 | 1.0884 |
| 176 | 177.8554 | 7.7540 | 1.2056 | 0.1889 | 1.1949 |
| 156 | 210.6467 | 10.0446 | 1.8950 | 0.1751 | 1.2557 |
| 174 | 154.1621 | 10.5360 | 1.5443 | 0.1724 | 1.2919 |
The random screen gets us close on one or two quantities at a time, but no layout fits all four. The paper’s 5,000-layout screen did not find one within 10 % of all four either. So we refine.
Step 2: refine around the best candidates#
Each round takes the TOP best layouts and makes PER - 1 variants of each, keeping the parent. A variant scales
the pad width by \((E_C/E_C^{\rm t})^{1/2}\) (a bigger pad means a bigger \(C_\Sigma\) and a smaller \(E_C\)),
each coupler’s width by \((C^{\rm t}_{\rm eff}/C_{\rm eff})^{0.7}\) (a wider coupler couples more),
times a random log-normal factor (5 % spread on the pad width, 15 % on the coupler widths, and 10 % on the coupler gaps), all scaled by that round’s JITTER. The pocket is then resized to fit. The steps use the model’s own prediction of the parent, so this is a crude Newton step plus noise. As in the paper, the last round uses five times smaller random changes.
[22]:
def propose(parent, q, rng, jitter):
# One variant of a parent layout (parameters p) with predicted quantities q.
p = dict(parent)
f_pad = (q["E_C (MHz)"] / P3_TARGETS["E_C (MHz)"]) ** 0.5 * np.exp(rng.normal(0, 0.05 * jitter))
p["pad_width"] = float(np.clip(parent["pad_width"] * f_pad, 300, 1100))
for c in CPLRS:
f = (P3_TARGETS[f"{c} (fF)"] / q[f"{c} (fF)"]) ** 0.7 * np.exp(rng.normal(0, 0.15 * jitter))
p[f"{c}_w"] = float(np.clip(parent[f"{c}_w"] * f, 3, 0.9 * p["pad_width"] / 2))
p[f"{c}_gap"] = float(np.clip(parent[f"{c}_gap"] * np.exp(rng.normal(0, 0.1 * jitter)), 3, 600))
top = max(p["readout_h"] + p["readout_gap"], p["bus_h"] + p["bus_gap"])
p["pocket_width"] = p["pad_width"] + (parent["pocket_width"] - parent["pad_width"])
p["pocket_height"] = p["pad_gap"] + 2 * p["pad_height"] + 2 * (max(top, p["drive_h"] + p["drive_gap"]) + 60)
return p
stages = [screen.assign(stage="screen")]
current = screen
for k, jitter in enumerate(JITTER, 1):
rng = np.random.default_rng(SEED + k)
parents = current.nsmallest(TOP, "loss")
variants = [propose(r["params"], r, rng, jitter) for _, r in parents.iterrows() for _ in range(PER - 1)]
kept, layouts, rejected = build_pockets(variants, f"pocket_round{k}")
results = predict_all(layouts, f"TransmonPocket round {k}")
new = pd.DataFrame([pocket_quantities(r) for r in results])
new["params"] = kept
new["loss"] = pocket_loss(new)
current = pd.concat([parents, new], ignore_index=True) # the parents stay in the running
stages.append(current.assign(stage=f"round {k}"))
print(f" round {k} (jitter {jitter}): {len(kept)} new, {sum(rejected.values())} rejected, best loss {current.loss.min():.4f}")
TransmonPocket round 1: 70 layouts in 1.3 min wall time (8 processes x 1 thread) | per layout: median 8.48 s, p90 10.17 s
round 1 (jitter 1.0): 70 new, 0 rejected, best loss 0.3654
TransmonPocket round 2: 70 layouts in 1.2 min wall time (8 processes x 1 thread) | per layout: median 7.67 s, p90 9.18 s
round 2 (jitter 1.0): 70 new, 0 rejected, best loss 0.1467
TransmonPocket round 3: 70 layouts in 1.3 min wall time (8 processes x 1 thread) | per layout: median 8.18 s, p90 9.56 s
round 3 (jitter 1.0): 70 new, 0 rejected, best loss 0.1467
TransmonPocket round 4: 70 layouts in 1.1 min wall time (8 processes x 1 thread) | per layout: median 7.03 s, p90 9.25 s
round 4 (jitter 0.2): 70 new, 0 rejected, best loss 0.0743
How the loss went down, round by round. Panel (b) follows the best layout of each stage on each of the four quantities:
[23]:
history = pd.concat(stages, ignore_index=True)
order = list(dict.fromkeys(history.stage))
best = history.loc[history.groupby("stage", sort=False).loss.idxmin()].set_index("stage").loc[order]
fig, (ax, bx) = plt.subplots(1, 2, figsize=(12, 4.5))
for i, st in enumerate(order):
l = history.loc[history.stage == st, "loss"]
ax.scatter(i + np.random.default_rng(i).uniform(-0.25, 0.25, len(l)), l, s=5, color="0.65")
ax.plot(range(len(order)), best.loss, "o-", color="tab:red", label="best layout")
ax.set(yscale="log", xticks=range(len(order)), xticklabels=order, ylabel="loss: sum of |log(pred / target)|",
title="(a) every scored layout per stage")
ax.legend()
for q, m in zip(QCOLS, "osD^"):
bx.plot(range(len(order)), 100 * (best[q] / P3_TARGETS[q] - 1), marker=m, label=q.split(" (")[0])
bx.axhline(0, color="k", lw=0.6)
bx.set(xticks=range(len(order)), xticklabels=order, ylabel="prediction - target (%)",
title="(b) the best layout of each stage")
bx.legend(fontsize=8)
fig.tight_layout()
The final pick#
The best four distinct layouts of the last round, by the model:
[24]:
final = current.assign(key=current.params.map(lambda p: tuple(sorted(p.items())))).drop_duplicates("key")
final = final.nsmallest(4, "loss").reset_index(drop=True)
pick_table = final[QCOLS + ["loss"]].copy()
for q, t in P3_TARGETS.items():
unit = q.split("(")[1].rstrip(")")
pick_table[f"{q.split(' (')[0]} - target ({unit})"] = final[q] - t
pick_table[f"{q.split(' (')[0]} - target (%)"] = 100 * (final[q] / t - 1)
pick_table.round(4)
[24]:
| E_C (MHz) | readout (fF) | bus (fF) | drive (fF) | loss | E_C - target (MHz) | E_C - target (%) | readout - target (fF) | readout - target (%) | bus - target (fF) | bus - target (%) | drive - target (fF) | drive - target (%) | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 204.6619 | 10.1186 | 1.0370 | 0.1003 | 0.0743 | 4.6619 | 2.3309 | 0.1186 | 1.1861 | 0.0370 | 3.6972 | 0.0003 | 0.3145 |
| 1 | 204.6733 | 9.8433 | 0.9686 | 0.1026 | 0.0970 | 4.6733 | 2.3366 | -0.1567 | -1.5673 | -0.0314 | -3.1428 | 0.0026 | 2.6482 |
| 2 | 203.6652 | 10.1301 | 0.9998 | 0.1074 | 0.1030 | 3.6652 | 1.8326 | 0.1301 | 1.3011 | -0.0002 | -0.0241 | 0.0074 | 7.4266 |
| 3 | 205.5600 | 9.6343 | 1.0423 | 0.0998 | 0.1082 | 5.5600 | 2.7800 | -0.3657 | -3.6573 | 0.0423 | 4.2296 | -0.0002 | -0.2116 |
Our laptop-size search stops further from the targets than the paper’s, whose four best layouts had a loss of 0.010-0.019 by the model. With 300 random layouts and 10 parents, every parent soon descends from the same few screen layouts. And when a coupler reaches the edge of the generator’s range (a 3 µm wide drive coupler, or a 600 µm gap), the rule cannot push it any further. A bigger screen and more parents (the paper’s 5,000 and 20) give the refinement more independent starting points. Here is how far the last round got, and whether any coupler sits at a limit:
[25]:
best_params = final.loc[0, "params"]
at_limit = {k: round(v, 2) for k, v in best_params.items() if k.endswith(("_w", "_gap")) and (v <= 3.0 or v >= 600.0)}
print(f"best loss {final.loss[0]:.4f}; coupler widths / gaps at a limit: {at_limit or 'none'}")
best loss 0.0743; coupler widths / gaps at a limit: none
Its parameters, and its layout:
[26]:
pocket_pick = final.loc[0, "params"]
display(pd.Series(pocket_pick).round(3).to_frame("final pick"))
pick_layout = check_layout(build_pocket(pocket_pick, WORKDIR / "pocket_final_pick.gds"), 5)
fig, (ax, bx) = plt.subplots(1, 2, figsize=(11, 6), gridspec_kw={"width_ratios": [1, 1.6]})
pick_layout.render(ax=ax, compact=True)
pick_layout.render(ax=bx, compact=True)
top = pocket_pick["pad_gap"] / 2 + pocket_pick["pad_height"]
reach = max(pocket_pick["readout_h"] + pocket_pick["readout_gap"], pocket_pick["bus_h"] + pocket_pick["bus_gap"])
bx.set(xlim=(-pocket_pick["pocket_width"] / 2, pocket_pick["pocket_width"] / 2), ylim=(top - 120, top + reach + 120))
ax.set_title("final pick")
bx.set_title("zoom: top pad (C2), readout (C1) and bus (C4) couplers")
fig.tight_layout()
| final pick | |
|---|---|
| pad_width | 442.916 |
| pad_height | 262.392 |
| pad_gap | 27.168 |
| readout_w | 134.102 |
| readout_h | 60.845 |
| readout_gap | 4.844 |
| bus_w | 30.636 |
| bus_h | 20.339 |
| bus_gap | 88.215 |
| drive_w | 6.591 |
| drive_h | 26.959 |
| drive_gap | 537.922 |
| pocket_width | 530.280 |
| pocket_height | 1801.713 |
| drive_loc_W | -1.000 |
What Q3D said in the paper#
In the paper, the screen was followed by four rounds with 20 parents each. The four best layouts of the last rounds were solved in Q3D (16 cores of a cluster node, 17 passes, 5.5-6.3 min each), and the first of them, fr4 0256, is the paper’s final candidate. These are the paper’s numbers, not recomputed here. The model column is again the QCap version deployed at the time of the study.
[27]:
paper_pocket = pd.DataFrame(
{"target E_C (MHz)": 200.0, "target readout (fF)": 10.0, "target bus (fF)": 1.0, "target drive (fF)": 0.1,
"model E_C (MHz)": [201.333, 199.820, 200.338, 199.285],
"model readout (fF)": [10.0114, 10.0530, 10.0454, 9.9601],
"model bus (fF)": [1.00056, 1.00051, 0.99541, 0.98920],
"model drive (fF)": [0.100152, 0.100803, 0.100798, 0.099929],
"Q3D E_C (MHz)": [200.973, 199.417, 199.981, 198.809],
"Q3D readout (fF)": [9.99379, 10.01283, 10.02106, 9.96481],
"Q3D bus (fF)": [0.998262, 0.998781, 0.994781, 0.989024],
"Q3D drive (fF)": [0.101855, 0.103303, 0.101726, 0.102443]},
index=pd.Index(["fr4 0256", "fr4 0084", "fr4 0052", "fr4 0496"], name="paper pick"))
PQ = [("E_C", "MHz"), ("readout", "fF"), ("bus", "fF"), ("drive", "fF")]
pocket_q3d = paper_table(paper_pocket, PQ)
display(pocket_q3d.round(4).T)
summary(pocket_q3d, PQ)
| paper pick | fr4 0256 | fr4 0084 | fr4 0052 | fr4 0496 |
|---|---|---|---|---|
| E_C: Q3D - target (MHz) | 0.9730 | -0.5830 | -0.0190 | -1.1910 |
| E_C: Q3D - target (%) | 0.4865 | -0.2915 | -0.0095 | -0.5955 |
| E_C: model - Q3D (MHz) | 0.3600 | 0.4030 | 0.3570 | 0.4760 |
| E_C: model - Q3D (%) | 0.1791 | 0.2021 | 0.1785 | 0.2394 |
| readout: Q3D - target (fF) | -0.0062 | 0.0128 | 0.0211 | -0.0352 |
| readout: Q3D - target (%) | -0.0621 | 0.1283 | 0.2106 | -0.3519 |
| readout: model - Q3D (fF) | 0.0176 | 0.0402 | 0.0243 | -0.0047 |
| readout: model - Q3D (%) | 0.1762 | 0.4012 | 0.2429 | -0.0473 |
| bus: Q3D - target (fF) | -0.0017 | -0.0012 | -0.0052 | -0.0110 |
| bus: Q3D - target (%) | -0.1738 | -0.1219 | -0.5219 | -1.0976 |
| bus: model - Q3D (fF) | 0.0023 | 0.0017 | 0.0006 | 0.0002 |
| bus: model - Q3D (%) | 0.2302 | 0.1731 | 0.0632 | 0.0178 |
| drive: Q3D - target (fF) | 0.0019 | 0.0033 | 0.0017 | 0.0024 |
| drive: Q3D - target (%) | 1.8550 | 3.3030 | 1.7260 | 2.4430 |
| drive: model - Q3D (fF) | -0.0017 | -0.0025 | -0.0009 | -0.0025 |
| drive: model - Q3D (%) | -1.6720 | -2.4201 | -0.9123 | -2.4540 |
E_C Q3D - target: median 0.39 % | MAE 0.6915 MHz | RMSE 0.8224 MHz | max 0.60 %
E_C model - Q3D: median 0.19 % | MAE 0.399 MHz | RMSE 0.4019 MHz | max 0.24 %
readout Q3D - target: median 0.17 % | MAE 0.01882 fF | RMSE 0.02171 fF | max 0.35 %
readout model - Q3D: median 0.21 % | MAE 0.02171 fF | RMSE 0.02519 fF | max 0.40 %
bus Q3D - target: median 0.35 % | MAE 0.004788 fF | RMSE 0.006169 fF | max 1.10 %
bus model - Q3D: median 0.12 % | MAE 0.001208 fF | RMSE 0.001475 fF | max 0.23 %
drive Q3D - target: median 2.15 % | MAE 0.002332 fF | RMSE 0.002413 fF | max 3.30 %
drive model - Q3D: median 2.05 % | MAE 0.001911 fF | RMSE 0.002021 fF | max 2.45 %
In Q3D, every quantity of all four picks is within the paper’s tolerance (2 % on \(E_C\), 5 % on each coupling), the final candidate fr4 0256 included. The drive coupling is the hardest to predict: 0.1 fF is a tiny entry, and its relative errors are the largest of the four.
Since the TransmonPocket generator rebuilds the paper’s layouts exactly, we can also ask the released model about the paper’s final candidate. Here are its parameters:
[28]:
fr4_0256 = {"pad_width": 688.6380909870743, "pad_height": 130.6369775175318, "pad_gap": 40.421818353482784,
"readout_w": 166.4378636685244, "readout_h": 50.55158510008755, "readout_gap": 6.586298346912528,
"bus_w": 13.100040788537827, "bus_h": 17.168234251229094, "bus_gap": 42.50251313812672,
"drive_w": 6.204543592956872, "drive_h": 23.15565208265336, "drive_gap": 533.9653419539899,
"pocket_width": 782.7944415333966, "pocket_height": 1535.9377614618327, "drive_loc_W": 1}
res = predictor.predict(str(build_pocket(fr4_0256, WORKDIR / "paper_fr4_0256.gds")))
released = pd.Series(pocket_quantities(res))
compare = pd.DataFrame({"target": pd.Series(P3_TARGETS).values, "released model (this notebook)": released.values,
"paper: model": paper_pocket.iloc[0, 4:8].values, "paper: Q3D": paper_pocket.iloc[0, 8:12].values},
index=QCOLS)
compare["released - Q3D"] = compare["released model (this notebook)"] - compare["paper: Q3D"]
compare["released - Q3D (%)"] = 100 * compare["released - Q3D"] / compare["paper: Q3D"]
print(f"{res.timing_s['total_s']:.1f} s on {res.threads} thread, {res.machine}")
compare.round(4)
4.0 s on 1 thread, Apple M5 Pro, 18 CPUs, Darwin arm64
[28]:
| target | released model (this notebook) | paper: model | paper: Q3D | released - Q3D | released - Q3D (%) | |
|---|---|---|---|---|---|---|
| E_C (MHz) | 200.0 | 201.4015 | 201.3330 | 200.9730 | 0.4285 | 0.2132 |
| readout (fF) | 10.0 | 10.0037 | 10.0114 | 9.9938 | 0.0099 | 0.0988 |
| bus (fF) | 1.0 | 0.9982 | 1.0006 | 0.9983 | -0.0000 | -0.0037 |
| drive (fF) | 0.1 | 0.1016 | 0.1002 | 0.1019 | -0.0003 | -0.2507 |
This layout was built and solved after the released model was trained, so it is not in its training data. Still, one layout is a sanity check, not an accuracy score. The paper’s accuracy tables are the score (see Tutorial 13 for the numbers).
What it cost#
Every batch of this notebook, on this machine:
[29]:
cost = pd.DataFrame(COST).set_index("stage")
cost.loc["total"] = [cost.layouts.sum(), cost["wall (min)"].sum(), WORKERS, THREADS, np.nan, np.nan]
cost = cost.astype({"layouts": int, "processes": int, "threads each": int})
print(xmon_results[0].machine)
cost.round(2)
Apple M5 Pro, 18 CPUs, Darwin arm64
[29]:
| layouts | wall (min) | processes | threads each | per layout, median (s) | per layout, p90 (s) | |
|---|---|---|---|---|---|---|
| stage | ||||||
| Xmon screen | 1000 | 1.69 | 8 | 1 | 0.71 | 1.21 |
| TransmonPocket screen | 300 | 4.03 | 8 | 1 | 5.90 | 8.50 |
| TransmonPocket round 1 | 70 | 1.32 | 8 | 1 | 8.48 | 10.17 |
| TransmonPocket round 2 | 70 | 1.23 | 8 | 1 | 7.67 | 9.18 |
| TransmonPocket round 3 | 70 | 1.26 | 8 | 1 | 8.18 | 9.56 |
| TransmonPocket round 4 | 70 | 1.11 | 8 | 1 | 7.03 | 9.25 |
| total | 1580 | 10.65 | 8 | 1 | NaN | NaN |
For comparison, here are the paper’s numbers. Generating the 5,000 Xmon layouts took about a minute on a laptop, and predicting them a few minutes of wall time over 64 processes of a cluster. The TransmonPocket screen of 5,000 took about 25 min on 64 CPUs of the cluster, the first two refinement rounds 12 min on 32 CPUs and the last two 21 min on a laptop with ten processes, about an hour in all. A Q3D solve of one such TransmonPocket took a median of 4.8 min on 16 cores, and the search needed only four of them at the end.
Congrats for making it to the end of this tutorial! You have now learned how to turn a capacitance model into a design tool: write a parametrised generator, screen a random pool in parallel, compute \(E_C\) and effective couplings from the predicted matrix (including the differential mode of a floating transmon), refine around the best candidates, and render the winner. The model’s pick is still a prediction: the layout you send to the fab deserves one real simulation, and that is the only one you need to run.
Next Steps…#
To screen a component family the model was not trained on, check it on a few of your own simulations first, and train on them if it falls short. Tutorial 14 shows how.
License#
This code is a part of SQuADDS
Developed by Sadman Ahmed Shanto
This tutorial is written by Sadman Ahmed Shanto and Claude Opus 5.5
© Copyright Sadman Ahmed Shanto & Eli Levenson-Falk 2026.
This code is licensed under the MIT License. You may obtain a copy of this license in the LICENSE.txt file in the root directory of this source tree.
Any modifications or derivative works of this code must retain thiscopyright notice, and modified files need to carry a notice indicatingthat they have been altered from the originals.