Metadata-Version: 2.5
Name: joqed
Version: 0.2.0
Summary: JoQED - design flow for superconducting quantum chips and their control circuits
Project-URL: Homepage, https://github.com/joqed/joqed
Project-URL: Repository, https://github.com/joqed/joqed
Author: JoQED
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: EDA,circuit-QED,design-flow,quantum,qubit,superconducting
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: scipy>=1.10
Description-Content-Type: text/markdown

# JoQED

**Quantum control-circuit design flow.**

JoQED (*Josephson QED*, pronounced "Jo-Q-E-D") is a design-automation library
for superconducting quantum chips: state physical targets (qubit frequency,
anharmonicity, readout frequency, χ, κ), render the geometry, simulate it with
an open-source FEM stack, and iterate the geometry until the targets converge —
deterministically, with every run recorded.

```
joqed.design  →  joqed.simulate  →  joqed.analyze  →  joqed.optimize
  geometry         Palace solves      quantum params      ANMod loop
                       ↑ joqed.ledger: every run, with provenance ↑
```

Status: **0.2.0, pre-alpha.** One reference device runs end to end through
two independent routes to the Hamiltonian, the optimizer closes the loop on
real electrostatics, and the flow has been checked against a published,
measured device ([docs/validation.md](docs/validation.md)). See
[CHANGELOG.md](CHANGELOG.md) for what each release proved.

## Quickstart (clean Mac)

You need Python 3.11 (SQDMetal caps at <3.12), [uv](https://docs.astral.sh/uv/),
and Homebrew. Two layers: the `joqed` wheel itself depends only on SciPy; the
simulation stack (Qiskit Metal, scqubits, Gmsh, SQDMetal, Palace) is a dev-time
install that never ships in the wheel.

```bash
# 1. clone and create the environment
git clone https://github.com/joqed/joqed.git && cd joqed
uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python -e . --group dev --group sim

# 2. SQDMetal (Apache-2.0) is vendored as a checkout, installed editable.
#    NOTE: re-run this line after ANY `uv sync` -- sync drops editable installs
#    that are not in pyproject.
git clone https://github.com/sqdlab/SQDMetal tools/SQDMetal
uv pip install --python .venv/bin/python -e tools/SQDMetal

# 3. tests: unit tests always run; Palace integration tests auto-skip
#    until the solver is built
uv run pytest -q

# 4. the solver (30-60 min compile; needs `brew install cmake open-mpi
#    pkg-config ninja openblas gcc`)
tools/build_palace.sh          # -> tools/palace/bin/palace, found automatically
uv run pytest -q               # Palace tests now run too
```

Then, in order of cost:

```bash
# seconds: the optimizer loop on the analytic surrogate, five perturbed starts
uv run python -m joqed.examples.optimize_reference --evaluator analytic --starts 5

# minutes (Palace): the reference device's capacitance-route DeviceReport
uv run python -m joqed.examples.reference --mesh fine

# minutes per iteration (Palace): close the loop on f01 + anharmonicity,
# then re-solve the converged design on a finer mesh
uv run python -m joqed.examples.optimize_reference --evaluator capacitance --starts 5 --verify-mesh xfine

# the literature check (Palace): measured vs JoQED on a published device
uv run python -m joqed.examples.validate_wm1 --mesh fine xfine

# an hour (Palace, laptop): add the eigenmode route -- f_r, chi, kappa
uv run python -m joqed.examples.reference --full
```

The notebook [notebooks/reference_walkthrough.ipynb](notebooks/reference_walkthrough.ipynb)
walks the same path (build → GDS preview → solve → DeviceReport → optimize)
and executes **without Palace** by replaying the bundled ledger snapshot:

```bash
uv pip install --python .venv/bin/python ipykernel nbconvert matplotlib
cd notebooks && uv run jupyter nbconvert --to notebook --execute reference_walkthrough.ipynb
```

Install-from-wheel check on a machine with nothing else:
`tools/clean_install_check.sh` builds the wheel, installs it into a fresh venv
and verifies that `import joqed, joqed.optimize` works and loads none of
gmsh / SQDMetal / qiskit_metal.

## What it does

**Reference device** (`joqed.design.reference`): a floating transmon with a
quarter-wave CPW readout resonator hanger-coupled to a feedline through a
coupled-line tee. Five knobs map one-to-one onto five targets:

| knob | target | value |
|---|---|---|
| `pad_width_um` | anharmonicity α | −240 ± 30 MHz |
| `junction_inductance_nH` | f01 | 4.7 ± 0.1 GHz |
| `resonator_length_mm` | f_r | 7.0 ± 0.05 GHz |
| `coupling_gap_um` | χ/2π | −0.5 MHz ± 50 % |
| `feedline_gap_um` | κ/2π | 1 MHz ± 50 % |

**Two routes to the Hamiltonian**, kept deliberately redundant. The
capacitance route: Palace electrostatics → Maxwell matrix → C_Σ → exact
transmon spectrum via scqubits. The eigenmode route: Palace eigenmodes with
the junction as a lumped inductance and 50 Ω feedline ports → energy-
participation ratios → f_r, χ, κ. They must agree on f01; on the reference
device they do to 2.5–3.9 % (gate: ≤ 5 %).

**Optimizer** (`joqed.optimize`): the ANMod update — one knob per target,
each with a rough scaling law; the measured value is rescaled every step, so
the true target is a fixed point even when the law is only approximately
right (rule reimplemented from
[QDesignOptimizer](https://github.com/202Q-lab/QDesignOptimizer), Apache-2.0,
see NOTICE). Evaluations are ledger-cached — a design vector never solves
twice, a killed run resumes — and the best design is reported even when the
loop does not converge. On the reference device, five ±20 % starts converge
in two Palace iterations each (pad ≈ 658 µm, L_J ≈ 11.65 nH; xfine verify
f01 4.756 GHz, α −249.3 MHz).

**Ledger** (`joqed.ledger`): one JSON receipt per run — inputs, results, and
provenance (package versions, Palace commit, platform, literature reference
for validation runs). Reproducibility is the product; the ledger is its
memory.

**Mesh presets**: `coarse` (smoke tests only), `fine` (default, optimizer
iterations), `xfine` (reported numbers). C_Σ on the reference device is
69.8 / 61.0 / 59.3 fF at the three levels; the fine→xfine drift of 2.9 %
misses the plan's <2 % criterion and is documented as such in
[docs/mesh.md](docs/mesh.md).

**Literature validation**: qubit_1 of the SQuADDS "WM1" chip (Shanto et al.,
Quantum 8, 1465 (2024)) rebuilt from the authors' design notebook, nothing
tuned. Capacitance route: α −157.5 / −162.1 MHz at fine / xfine vs −153
measured (−2.9 % / −5.9 %, i.e. C_Σ 3–5 % low), f01 +1.3 % / +2.7 %,
g +9 % / +11 %; χ inherits g². f_r and κ await the eigenmode route. Full
table with residuals per mesh level, and where the missing capacitance
probably is, in [docs/validation.md](docs/validation.md).

## Documentation

- [docs/api.md](docs/api.md) — API overview per module
- [docs/validation.md](docs/validation.md) — the literature comparison
- [docs/mesh.md](docs/mesh.md) — mesh presets, convergence, rules learned
- [docs/design-flow](docs/design-flow) — the commercial (HFSS) and open-source
  flow charts this project implements
- [CHANGELOG.md](CHANGELOG.md)

## Agent-ready by construction

Every public return value is a dataclass with lossless JSON serialization,
error messages state what failed, the offending value and the likely fix, and
docstrings are written as tool descriptions — so the M4 MCP server
(`joqed-mcp`) can be generated over this library rather than written.

## Compute

A fine electrostatic solve is ~2 min on a MacBook Air; a coarse eigenmode
solve is ~50 min and the Air throttles after a few hours. Eigenmode work
(fine-mesh convergence, the f_r/χ/κ knobs) is meant for a dedicated box;
`run_palace()` is the one place a remote-execution path plugs in.

## Open-source stack

| Role | Tool | License |
|---|---|---|
| Chip layout | [Qiskit Metal](https://github.com/qiskit-community/qiskit-metal) (`quantum-metal` distribution) | Apache-2.0 |
| Meshing | [Gmsh](https://gmsh.info) | **GPL-2.0+** ([see note](#a-note-on-gmsh-and-licensing)) |
| FEM simulation (eigenmode, electrostatic) | [Palace](https://github.com/awslabs/palace) | Apache-2.0 |
| Metal → Palace bridge | [SQDMetal](https://github.com/sqdlab/SQDMetal) | Apache-2.0 |
| Quantum analysis | [scqubits](https://github.com/scqubits/scqubits), [pyEPR](https://github.com/zlatko-minev/pyEPR) | BSD |
| Optimizer rule | [QDesignOptimizer](https://github.com/202Q-lab/QDesignOptimizer) (reimplemented) | Apache-2.0 |

### A note on Gmsh and licensing

Every tool above is permissively licensed **except Gmsh, which is GPL-2.0+**
with only a narrow Netgen/METIS/OpenCASCADE/ParaView exception — not a
general linking exception. That matters for *distribution*, not use.
JoQED's position: the published `joqed` wheel depends on SciPy alone and
never imports gmsh, SQDMetal or qiskit_metal (`tests/test_import_boundary.py`
and `tools/clean_install_check.sh` enforce it); Palace runs as a separate
subprocess; SQDMetal's in-process gmsh use happens only in the dev-time
simulation stack you install yourself. Keep it that way unless a lawyer says
otherwise.

## Tooling

- [tools/build_palace.sh](tools/build_palace.sh) — builds Palace from source
  into `tools/palace/` with Homebrew CMake / Open MPI / gfortran / OpenBLAS.
- [tools/clean_install_check.sh](tools/clean_install_check.sh) — the
  clean-machine wheel install test.

## License

[Apache License 2.0](LICENSE)
