Standard transmon: EJ/h = 20 GHz, EC/h = 300 MHz

June 27, 2026 · View on GitHub

Automated Python module for the design and quantization of Josephson quantum circuits

HFSS field simulation: cavity E-field mode and qubit current-density mode

pyEPR bridges classical EM simulation and quantum circuit theory via the energy-participation ratio (EPR) method. Given a 3-D HFSS eigenmode simulation — or your own frequencies and inductances — it extracts the full quantum Hamiltonian in minutes:

Simulate the linearized circuit in Ansys HFSS to get eigenmode frequencies and field distributions.
Extract energy participation ratios $p_{mj}$ and zero-point phase fluctuations $\varphi_\mathrm{zpf}^{(mj)}$ for each junction and mode.
Diagonalize $H = \sum_m \omega_m a_m^\dagger a_m - \sum_j E_J[\cos\hat\varphi_j - 1 + \hat\varphi_j^2/2]$ numerically to get dressed frequencies, anharmonicities, and the dispersive-shift matrix $\chi$ .

Works for any number of modes and junctions. Handles strongly anharmonic circuits (fluxonium, $\varphi_\mathrm{zpf}\gtrsim 1$ ). No manual circuit diagram — only the 3-D geometry.

No HFSS licence? The Hamiltonian diagonalization (steps 2–3) works with any frequencies and inductances. Start with Tutorial 6 on Binder — runs in your browser, no install.

Install

pip install pyEPR-quantum

Requires Python 3.9–3.12. All dependencies (numpy, qutip, matplotlib, …) are installed automatically.

conda:

conda install -c conda-forge pyepr-quantum

development install:

git clone https://github.com/zlatko-minev/pyEPR.git && cd pyEPR
pip install -e ".[test]" && pytest

New in v0.9.6 — cross-platform gRPC backend (Linux · macOS · Windows)

pyEPR now ships a second HFSS transport that runs entirely over gRPC through Ansys's official PyAEDT library — no COM, no pywin32, and no Windows requirement.

	Classic COM backend	PyAEDT / gRPC backend
Install	`pip install pyEPR-quantum`	`pip install "pyEPR-quantum[pyaedt]"`
Class	`DistributedAnalysis`	`PyaedtDistributedAnalysis`
Platform	Windows only	Linux · macOS · Windows
Transport	COM / pywin32	gRPC (Ansys official API)
Session attach	new COM session	attaches to running AEDT via `.aedt.lock`

from pyEPR.ansys_pyaedt import PyaedtDistributedAnalysis

eprd = PyaedtDistributedAnalysis(pinfo, aedt_version="2026.1")
eprd.do_EPR_analysis()   # pure gRPC — no COM, works on Linux/macOS
f_ND, chi_ND = eprd.analyze()

The physics is identical — participations, eigenfrequencies, and the full diagonalization feed pyEPR's own QuantumAnalysis unchanged, validated digit-for-digit against the COM path. The gRPC backend also resolves the stale-session and project-locked errors that have long been the main pain point with COM.

Many thanks to Joey Yaker for designing and contributing this backend. See the PyAEDT backend docs for full details and Tutorial 7.

Quickstart — no Ansys required

Compute the transmon anharmonicity from first principles, no HFSS needed:

import numpy as np
from pyEPR.calcs.back_box_numeric import epr_numerical_diagonalization

# Standard transmon: E_J/h = 20 GHz, E_C/h = 300 MHz
# Plasma frequency f_p = sqrt(8 E_J E_C)/h ≈ 6.93 GHz
freqs   = np.array([6.928])     # GHz  (linearised plasma frequency)
Ljs     = np.array([8.2e-9])    # H    (Josephson inductance L_J = (Phi_0/2pi)^2 / E_J)
phi_zpf = np.array([[0.416]])   # dimensionless  (n_modes x n_junctions)

# Diagonalize — returns dressed frequencies in Hz and chi matrix in MHz
f_dressed, chi_matrix = epr_numerical_diagonalization(
    freqs, Ljs, phi_zpf, cos_trunc=8, fock_trunc=15
)
print(f"Qubit frequency : {f_dressed[0].real / 1e9:.3f} GHz")
print(f"Anharmonicity   : {chi_matrix[0,0].real:.0f} MHz")
# -> Qubit frequency : 6.615 GHz
# -> Anharmonicity   : 335 MHz

For multi-mode systems, fluxonium, or custom potentials: Tutorial 6.

Full HFSS workflow

import pyEPR as epr

# 1. Connect to Ansys HFSS
pinfo = epr.ProjectInfo(project_path=r'C:\sim_folder',
                        project_name=r'cavity_with_two_qubits',
                        design_name=r'Alice_Bob')

# 2. Specify Josephson junctions
pinfo.junctions['jAlice'] = {'Lj_variable':'Lj_alice', 'rect':'rect_alice',
                              'line': 'line_alice', 'Cj_variable':'Cj_alice'}
pinfo.junctions['jBob']   = {'Lj_variable':'Lj_bob',   'rect':'rect_bob',
                              'line': 'line_bob',   'Cj_variable':'Cj_bob'}
pinfo.validate_junction_info()

# 3. Extract EPR participation ratios
eprd = epr.DistributedAnalysis(pinfo)
eprd.do_EPR_analysis()

# 4. Quantum Hamiltonian — dressed frequencies and chi matrix
epra = epr.QuantumAnalysis(eprd.data_filename)
epra.analyze_all_variations(cos_trunc=8, fock_trunc=15)
epra.plot_hamiltonian_results(swp_variable='Lj_alice')

Documentation

Full docs, API reference, and guides: pyepr-docs.readthedocs.io

Tutorial Notebooks

The tutorials are Jupyter notebooks in _tutorial_notebooks/.

#	Title	HFSS?	Topics
1	Startup example	Yes	End-to-end workflow: HFSS → EPR → χ matrix
2	Dielectric loss EPR	Yes	Dielectric energy participation, loss rates, HFSS fields calculator
3	Circuit QED parameters	No	E_J, E_C, L_J, I_c conversions; transmon model
4	Parametric sweeps	Yes	HFSS Optimetrics: linear, log, file-based sweeps
5	Generic junction potential & fluxonium	No	Exact cosine for fluxonium; custom V(phi); asymmetric SQUIDs
6	EPR without HFSS	No	Numerical workflow: supply freqs, Ljs, phi_zpf directly

Tutorials 3, 5, and 6 require only pip install pyEPR-quantum — no Ansys licence.

Video Tutorials

Tutorial 1 - Overview	Tutorial 2 - Setup of Conda & Git	Tutorial 3 - Setup of Packages & Config

Who uses pyEPR?

pyEPR is used by superconducting qubit research groups worldwide, including:

Yale University — Michel Devoret QLab and Rob Schoelkopf RSL
IBM Quantum and Qiskit Metal
QUANTIC — INRIA/ENS/MINES Paris/UPMC/CNRS (Zaki Leghtas group), France
Quantum Circuit Group — Benjamin Huard, ENS Lyon, France
Emanuel Flurin, CEA Saclay, France
Ioan Pop group, KIT Physikalisches Institut, Germany
UC Berkeley, Quantum Nanoelectronics Laboratory, Irfan Siddiqi
Quantum Circuits, Inc. · Seeqc · Alice&Bob, France · Bleximo
Serge Rosenblum Lab, Weizmann Institute, Israel
University of Oxford — Leek Lab
Britton Plourde Lab, Syracuse University
Javad Shabani Lab, NYU
UChicago Dave Schuster Lab · Lawrence Berkeley National Lab · Colorado School of Mines
IPQC, SJTU, Shanghai · Bhabha Atomic Research Centre, India
Quantum Device Lab ETHZ — Andreas Wallraff · Centre for Quantum Technologies / Qcrew
SQC lab — Shay Hacohen-Gourgy, Israel · Quantum Computing UK
... and many more — e-mail zlatko.minev@aya.yale.edu to be added.

Platform support

Feature	Windows	macOS	Linux
EPR / quantum analysis	Yes	Yes	Yes
Ansys HFSS COM interface	Yes	limited	limited

The HFSS COM interface uses pythoncom/win32com (Windows). On macOS/Linux you can connect to a remote Windows HFSS instance via network COM.

PyAEDT is Ansys's official cross-platform AEDT scripting library. pyEPR and PyAEDT are complementary — use PyAEDT for geometry/mesh/solve automation, pyEPR for EPR quantization.

HFSS Project Setup

Eigenmode Design — Junction setup

The EPR method requires each Josephson junction to be modelled as a lumped RLC boundary on a rectangle in HFSS, together with a polyline defining the current direction. Steps:

Create a rectangle for each junction (e.g., rect_alice). Assign a Lumped RLC boundary with inductance variable Lj_alice.
Draw a polyline spanning the junction rectangle to define current flow (e.g., line_alice).
The linearised Josephson inductance used in HFSS is $L_J = (\Phi_0/2\pi)^2/E_J$ . The full cosine potential is restored in the quantum Hamiltonian step.
Enable Save Fields for each variation if running parametric sweeps (Tutorial 4).
Use Mixed Order solutions for best accuracy.

Junction setup example

For a full walkthrough, see Tutorial 1 and the HFSS setup guide in the docs.

Troubleshooting

See the troubleshooting guide in the docs.

Common issues:

pint error system='mks' unknown — upgrade pint: pip install pint --upgrade
QuTiP not found — it is installed automatically with pyEPR-quantum; for manual install: pip install qutip
COM Error on opening HFSS — check file path (no apostrophes/special chars); check HFSS hasn't popped an error dialog
Parametric sweep missing field solutions — enable "Save Fields and Mesh" in ParametricSetup → Properties → Options (see Tutorial 4)
ValueError: cannot set WRITEABLE flag — upgrade numpy

Citation

If you use pyEPR in your research, please cite:

EPR method (primary reference):

Z. K. Minev, Z. Leghtas, S. O. Mundhada, L. Christakis, I. M. Pop, M. H. Devoret, Energy-participation quantization of Josephson circuits, npj Quantum Information 7, 131 (2021) · arXiv:2010.00620

Software (Zenodo DOI for the specific version):

BibTeX for both: pyEPR.bib

Z. K. Minev, Ph.D. Dissertation, Yale (2018), Ch. 4 — arXiv:1902.10355
A. Petrescu, C. T. Hann, Z. K. Minev et al., EPR for very anharmonic circuits — arXiv:2411.15039

Authors and Contributors

Authors: Zlatko Minev & Zaki Leghtas, 2015–present.
Contributors: Phil Reinhold, Lysander Christakis, Devin Cody, Zachary Parrott, Asaf Diringer, and many others.
Original pyHFSS.py and pyNumericalDiagonalization.py by Phil Reinhold — original repo.
To contribute: open a GitHub issue or PR, or contact Z. Minev.

Community contributions

Joey Yaker — PyAEDT gRPC backend (pyEPR.ansys_pyaedt, v0.9.6). Designed and implemented PyaedtDistributedAnalysis: a complete alternative HFSS transport layer that drives the EPR field extraction entirely over gRPC via Ansys's official PyAEDT API, with no COM / pywin32. Includes the key insight that CalculatorWrite (write to a .fld file) must replace the stateful ClcEval/GetTopEntryValue round-trip for results to survive gRPC — validated digit-for-digit against the COM path. Makes pyEPR fully cross-platform for users with PyAEDT installed.