pyEPR package#

pyEPR

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

Abstract: Superconducting circuits incorporating non-linear devices, such as Josephson junctions and nanowires, are among the leading platforms for emerging quantum technologies. Promising applications require designing and optimizing circuits with ever-increasing complexity and controlling their dissipative and Hamiltonian parameters to several significant digits. Therefore, there is a growing need for a systematic, simple, and robust approach for precise circuit design, extensible to increased complexity. The energy-participation ratio (EPR) approach presents such an approach to unify the design of dissipation and Hamiltonians around a single concept — the energy participation, a number between zero and one — in a single-step electromagnetic simulation. This markedly reduces the required number of simulations and allows for robust extension to complex systems. The approach is general purpose, derived ab initio, and valid for arbitrary non-linear devices and circuit architectures. Experimental results on a variety of circuit quantum electrodynamics (cQED) devices and architectures, 3D and flip-chip (2.5D), have been demonstrated to exhibit ten percent to percent-level agreement for non-linear coupling and modal Hamiltonian parameters over five-orders of magnitude and across a dozen samples.

Here, in this package, all routines of the EPR approach are fully automated. An interface with ansys is provided. Automated analysis of lumped and distributed circuits is provided.

@author: Zlatko Minev, Zaki Leghas, … and the pyEPR team @site: zlatko-minev/pyEPR @license: “BSD-3-Clause” @version: 0.9.5 @maintainer: Zlatko K. Minev and Asaf Diringer @email: zlatko.minev@aya.yale.edu @url: zlatko-minev/pyEPR @status: “Dev-Production”

class pyEPR.DistributedAnalysis(*args, **kwargs)[source]#

Bases: object

DISTRIBUTED ANALYSIS of layout and microwave results.

Main computation class & interface with HFSS.

This class defines a DistributedAnalysis object which calculates and saves Hamiltonian parameters from an HFSS simulation.

Further, it allows one to calculate dissipation, etc.

calc_Q_external(variation, freq_GHz, U_E=None)[source]#

Calculate the coupling Q of mode m with each port p Expected that you have specified the mode before calling this

Parameters:

variation (str) – A string identifier of the variation,
'0' (such as)
'1'
...

calc_avg_current_J_surf_mag(variation: str, junc_rect: str, junc_line)[source]#

Peak current I_max for mode J in junction J.

The average is over the surface of the junction (spatial average).

Parameters:

variation (str) – A string identifier of the variation, such as ‘0’, ‘1’, …
junc_rect (str) – name of rectangle to integrate over
junc_line (str) – name of junction line to integrate over

Returns:

Value of peak current

calc_current(fields, line: str)[source]#

Function to calculate Current based on line. Not in use.

Parameters:: line (str) – integration line between plates - name

calc_current_using_line_voltage(variation: str, junc_line_name: str, junc_L_Henries: float, Cj_Farads: float = None)[source]#

Peak current I_max for prespecified mode calculating line voltage across junction.

Make sure that you have set the correct variation in HFSS before running this

Parameters:

variation – variation number
junc_line_name – name of the HFSS line spanning the junction
junc_L_Henries – junction inductance in henries
Cj_Farads – junction cap in Farads
TODO – Smooth?

calc_energy_electric(variation: str = None, obj: str = 'AllObjects', volume: str = 'Deprecated', smooth: bool = False, obj_dims: int = 3)[source]#

Calculates two times the peak electric energy, or 4 times the RMS, $4*\mathcal{E}_{\mathrm{elec}}$ (since we do not divide by 2 and use the peak phasors).

\[\mathcal{E}_{\mathrm{elec}}=\frac{1}{4}\mathrm{Re}\int_{V}\mathrm{d}v\vec{E}_{\text{max}}^{*}\overleftrightarrow{\epsilon}\vec{E}_{\text{max}}\]

Parameters:

variation (str) – A string identifier of the variation, such as ‘0’, ‘1’, …
obj (string | 'AllObjects') – Name of the object to integrate over
smooth (bool | False) – Smooth the electric field or not when performing calculation
obj_dims (int | 3) – 1 - line, 2 - surface, 3 - volume. Default volume

Example

Example use to calculate the energy participation ratio (EPR) of a substrate

ℰ_total  = epr_hfss.calc_energy_electric(obj='AllObjects')
ℰ_substr = epr_hfss.calc_energy_electric(obj='Box1')
print(f'Energy in substrate = {100*ℰ_substr/ℰ_total:.1f}%')

calc_energy_magnetic(variation: str = None, obj: str = 'AllObjects', volume: str = 'Deprecated', smooth: bool = False, obj_dims: int = 3)[source]#

See calc_energy_electric.

Parameters:

variation (str) – A string identifier of the variation, such as ‘0’, ‘1’, …
volume (string | 'AllObjects') – Name of the volume to integrate over
smooth (bool | False) – Smooth the electric field or not when performing calculation
obj_dims (int | 3) – 1 - line, 2 - surface, 3 - volume. Default volume

calc_line_current(variation, junc_line_name)[source]#

calc_p_electric_volume(name_dielectric3D, relative_to='AllObjects', variation=None, E_total=None)[source]#

Calculate the dielectric energy-participation ratio of a 3D object (one that has volume) relative to the dielectric energy of a list of objects.

This is as a function relative to another object or all objects.

When all objects are specified, this does not include any energy that might be stored in any lumped elements or lumped capacitors.

Returns:: ℰ_object/ℰ_total, (ℰ_object, _total)

calc_p_junction(variation, U_H, U_E, Ljs, Cjs)[source]#

For a single specific mode. Expected that you have specified the mode before calling this, set_mode().

Expected to precalc U_H and U_E for mode, will return pandas pd.Series object:

junc_rect = [‘junc_rect1’, ‘junc_rect2’] name of junc rectangles to integrate H over

junc_len = [0.0001] specify in SI units; i.e., meters

LJs = [8e-09, 8e-09] SI units

calc_sign = [‘junc_line1’, ‘junc_line2’]

WARNING: Cjs is experimental.

This function assumes there are no lumped capacitors in model.

Parameters:

variation (str) – A string identifier of the variation,
'0' (such as)
'1'
...

Note

U_E and U_H are the total peak energy (NOT twice as in U_ and U_H other places).

Warning

Potential errors: If you dont have a line or rect by the right name you will prob get an error of the type: com_error: (-2147352567, ‘Exception occurred.’, (0, None, None, None, 0, -2147024365), None)

calc_p_junction_single(mode, variation, U_E=None, U_H=None)[source]#

This function is used in the case of a single junction only. For multiple junctions, see calc_p_junction().

Assumes no lumped capacitive elements.

property design#: Ansys design class handle

do_EPR_analysis(variations: list = None, modes: list = None, append_analysis: bool = True)[source]#

Run the full EPR field extraction and save results to disk.

Iterates over all requested variations and eigenmodes, computes EPR participation ratios (p_mj), zero-point fluctuations (φ_zpf), junction currents and voltages, and saves the results to an HDF5/pickle file readable by QuantumAnalysis.

Parameters:

variations (list of str, optional) – Variation labels to analyse (e.g. ['0', '1']). Defaults to all solved variations.
modes (list of int, optional) – Eigenmode indices to include (e.g. [0, 2, 3] to skip mode 1). Defaults to all modes. Use consistent indices when later calling analyze_all_variations().
append_analysis (bool, optional) – If True (default), skip variations already present in the results file. Set to False to recompute and overwrite everything.

Returns:

Results are written to self.data_filename. Load them with:

epra = epr.QuantumAnalysis(eprd.data_filename)

Return type:

None

Note

Assumes low dissipation (high-Q). Lumped capacitor support (Cj_variable) is experimental — see the EPR paper for theoretical background.

Example

eprd = epr.DistributedAnalysis(pinfo)
eprd.do_EPR_analysis()
# or for a subset:
eprd.do_EPR_analysis(variations=['0', '2'], modes=[0, 1])

get_Qdielectric(dielectric, mode, variation, U_E=None)[source]#

get_Qseam(seam, mode, variation, U_H=None)[source]#: Calculate the contribution to Q of a seam, by integrating the current in the seam with finite conductance: set in the config file ref: http://arxiv.org/pdf/1509.01119.pdf

get_Qseam_sweep(seam, mode, variation, variable, values, unit, U_H=None, pltresult=True)[source]#

Q due to seam loss.

values = [‘5mm’,’6mm’,’7mm’] ref: http://arxiv.org/pdf/1509.01119.pdf

get_Qsurface(mode, variation, name, U_E=None, material_properties=None)[source]#: Calculate the contribution to Q of a dielectric layer of dirt on a given surface. Set the dirt thickness and loss tangent in the config file ref: http://arxiv.org/pdf/1509.01854.pdf

get_Qsurface_all(mode, variation, U_E=None)[source]#: Calculate the contribution to Q of a dielectric layer of dirt on all surfaces. Set the dirt thickness and loss tangent in the config file ref: http://arxiv.org/pdf/1509.01854.pdf

get_ansys_frequencies_all(vs='variation')[source]#

Return all ansys frequencies and quality factors vs a variation

Returns a multi-index pandas DataFrame

get_ansys_variables()[source]#

Get ansys variables for all variations

Returns:: Return a dataframe of variables as index and columns as the variations

get_ansys_variations()[source]#

Will update ansys information and result the list of variations.

Returns:

("Cj='2fF' Lj='12nH'",
"Cj='2fF' Lj='12.5nH'",
"Cj='2fF' Lj='13nH'",
"Cj='2fF' Lj='13.5nH'",
"Cj='2fF' Lj='14nH'")

Return type:

For example

get_convergence(variation='0')[source]#

Parameters:

variation (str) – A string identifier of the variation,
'0' (such as)
'1'
...

Returns:

A pandas DataFrame object

    Solved Elements     Max Delta Freq. % Pass Number
         128955              NaN
             167607          11.745000
             192746          3.208600
             199244          1.524000

get_convergence_vs_pass(variation='0')[source]#

Makes a plot in HFSS that return a pandas dataframe

Parameters:

variation (str) – A string identifier of the variation,
'0' (such as)
'1'
...

Returns:

Returns a convergence vs pass number of the eignemode freqs.

    re(Mode(1)) [g]     re(Mode(2)) [g] re(Mode(3)) [g]
Pass []
1       4.643101        4.944204        5.586289
2       5.114490        5.505828        6.242423
3       5.278594        5.604426        6.296777

get_freqs_bare(variation: str)[source]#

Warning

Outdated. Do not use. To be deprecated

Parameters:: variation (str) – A string identifier of the variation, such as ‘0’, ‘1’, …
Returns:: [type] – [description]

get_freqs_bare_pd(variation: str, frame=True)[source]#

Return the freq and Qs of the solved modes for a variation. I.e., the Ansys solved frequencies.

Parameters:

variation (str) – A string identifier of the variation, such as ‘0’, ‘1’, …
dataframe (frame {bool} -- if True returns)
series. (else tuple of)

Returns:

If frame = True, then a multi-index Dataframe that looks something like this

                Freq. (GHz)  Quality Factor
variation mode
0         0        5.436892             1020
        1        7.030932             50200
1         0        5.490328             2010
        1        7.032116             104500

If frame = False, then a tuple of two Series, such as (Fs, Qs) – Tuple of pandas.Series objects; the row index is the mode number

get_junc_len_dir(variation: str, junc_line)[source]#

Return the length and direction of a junction defined by a line

Parameters:

variation (str) – simulation variation
junc_line (str) – polyline object

Returns:

junction length uj (list of 3 floats): x,y,z components of the unit vector tangent to the junction line

Return type:

jl (float)

get_junctions_L_and_C(variation: str)[source]#

Returns a pandas Series with the index being the junction name as specified in the project_info.

The values in the series are numeric and in SI base units, i.e., not nH but Henries, and not fF but Farads.

Parameters:

variation (str) – label such as ‘0’ or ‘all’, in which case return
variations (pandas table for all)

get_mesh_statistics(variation='0')[source]#

Parameters:

variation (str) – A string identifier of the variation,
'0' (such as)
'1'
...

Returns: A pandas dataframe, such as

    Name        Num Tets    Min edge    length          Max edge length     RMS edge length Min tet vol     Max tet vol     Mean tet vol    Std Devn (vol)
0   Region      909451          0.000243    0.860488        0.037048            6.006260e-13        0.037352        0.000029        6.268190e-04
1   substrate       1490356     0.000270    0.893770        0.023639            1.160090e-12        0.031253        0.000007        2.309920e-04

get_nominal_variation_index()[source]#

Returns:: A string identifies, such as ‘0’ or ‘1’, that labels the nominal variation index number.

This may not be in the solved list!s

get_previously_analyzed()[source]#

Return previously analyzed data.

Does not yet handle data that was previously saved in a filename.

get_variable_vs_variations(variable: str, convert: bool = True)[source]#

Get ansys variables

Return HFSS variable from self.get_ansys_variables() as a pandas series vs variations.

Parameters:: convert (bool) – Convert to a numeric quantity if possible using the ureg

get_variables(variation=None)[source]#

Get ansys variables.

Parameters:: variation (str) – A string identifier of the variation, such as ‘0’, ‘1’, …

get_variation_string(variation=None)[source]#

Solved variation string identifier.

Parameters:

variation (str) – A string identifier of the variation, such as ‘0’, ‘1’, …

Returns:

Return the list variation string of parameters in ansys used to identify the variation.

"$test='0.25mm' Cj='2fF' Lj='12.5nH'"

get_variations()[source]#

An array of strings corresponding to solved variations corresponding to the selected Setup.

Returns:

Returns a list of strings that give the variation labels for HFSS.

OrderedDict([
    ('0', "Cj='2fF' Lj='12nH'"),
    ('1', "Cj='2fF' Lj='12.5nH'"),
    ('2', "Cj='2fF' Lj='13nH'"),
    ('3', "Cj='2fF' Lj='13.5nH'"),
    ('4', "Cj='2fF' Lj='14nH'")])

has_fields(variation: str = None)[source]#

Determine if fields exist for a particular solution. Just calls self.solutions.has_fields(variation_string)

Parameters:: variation (str) – String of variation label, such as ‘0’ or ‘1’. If None, gets the nominal variation

hfss_report_f_convergence(variation='0', save_csv=True)[source]#

Create a report inside HFSS to plot the converge of freq and style it.

Saves report to csv file.

Returns a convergence vs pass number of the eignemode freqs. Returns a pandas dataframe:

    re(Mode(1)) [g] re(Mode(2)) [g] re(Mode(3)) [g]
Pass []
1   4.643101        4.944204        5.586289
2   5.114490        5.505828        6.242423
3   5.278594        5.604426        6.296777

hfss_report_full_convergence(fig=None, _display=True)[source]#

Plot a full report of teh convergences of an eigenmode analysis for a a given variation. Makes a plot inside hfss too.

Keyword Arguments:

(default (_display {bool} -- Force display or not.) – {None})
(default – {True})

Returns:

[type] – [description]

load(filepath=None)[source]#

Utility function to load results file

Keyword Arguments:: (default (filepath {[type]} -- [description]) – {None})

property n_variations#: Number of solved variations, corresponding to the selected Setup.

property options#: Project info options

property project#: Ansys project class handle

quick_plot_frequencies(swp_variable='variations', ax=None)[source]#: Quick plot of frequencies from HFSS

static results_variations_on_inside(results: dict)[source]#: Switches the order on result of variations. Reverse dict.

save(project_info: dict = None)[source]#

Save results to self.data_filename

Keyword Arguments:: (default (project_info {dict} -- [description]) – {None})

set_mode(mode_num, phase=0)[source]#: Set source excitations should be used for fields post processing. Counting modes from 0 onward

set_variation(variation: str)[source]#

Set the ansys design to a solved variation. This will change all local variables!

Warning: not tested with global variables.

property setup#: Ansys setup class handle. Could be None.

setup_data()[source]#

Set up folder paths for saving data to.

Sets the save filename with the current time.

Saves to Path(config.root_dir) / self.project.name / self.design.name

update_ansys_info() → None[source]#

Refresh cached information from the live Ansys session.

Call this after changing the number of eigenmodes, adding or removing a parametric sweep variation, or modifying any design variable — any operation that changes the solved-variation list or eigenmode count without restarting Python.

Updates#

self.n_modes, self._list_variations, self.variations, self._nominal_variation, and self._hfss_variables.

variations#: List of variation indices, which are strings of ints, such as [‘0’, ‘1’]

class pyEPR.ProjectInfo(project_path: str = None, project_name: str = None, design_name: str = None, setup_name: str = None, dielectrics_bulk: list = None, dielectric_surfaces: list = None, resistive_surfaces: list = None, seams: list = None, junctions: dict = None, do_connect: bool = True)[source]#

Bases: object

Primary class to store interface information between pyEPR and Ansys.

Ansys: stores and provides easy access to the ansys interface classes pyEPR.ansys.HfssApp, pyEPR.ansys.HfssDesktop, pyEPR.ansys.HfssProject, pyEPR.ansys.HfssDesign, pyEPR.ansys.HfssSetup (which, if present could nbe a subclass, such as a driven modal setup pyEPR.ansys.HfssDMSetup, eigenmode pyEPR.ansys.HfssEMSetup, or Q3D pyEPR.ansys.AnsysQ3DSetup), the 3D modeler to design geometry pyEPR.ansys.HfssModeler.
Junctions: The class stores params about the design that the user puts will use, such as the names and properties of the junctions, such as which rectangle and line is associated with which junction.

Note

Junction parameters. The junction parameters are stored in the self.junctions ordered dictionary

A Josephson tunnel junction has to have its parameters specified here for the analysis. Each junction is given a name and is specified by a dictionary. It has the following properties:

Lj_variable (str):
Name of HFSS variable that specifies junction inductance Lj defined on the boundary condition in HFSS. WARNING: DO NOT USE Global names that start with $.
rect (str):
String of Ansys name of the rectangle on which the lumped boundary condition is defined.
line (str):
Name of HFSS polyline which spans the length of the rectangle. Used to define the voltage across the junction. Used to define the current orientation for each junction. Used to define sign of ZPF.
length (str):
Length in HFSS of the junction rectangle and line (specified in meters). To create, you can use epr.parse_units('100um').
Cj_variable (str, optional) [experimental]:
Name of HFSS variable that specifies junction inductance Cj defined on the boundary condition in HFSS. DO NOT USE Global names that start with $.

Warning

To define junctions, do NOT use global names! I.e., do not use names in ansys that start with $.

Note

Junction parameters example . To define junction parameters, see the following example

# Create project infor class
pinfo = ProjectInfo()

# Now, let us add a junction called `j1`, with the following properties
pinfo.junctions['j1'] = {
            'Lj_variable' : 'Lj_1', # name of Lj variable in Ansys
            'rect'        : 'jj_rect_1',
            'line'        : 'jj_line_1',
            #'Cj'          : 'Cj_1' # name of Cj variable in Ansys - optional
            }

To extend to define 5 junctions in bulk, we could use the following script

n_junctions = 5
for i in range(1, n_junctions + 1):
    pinfo.junctions[f'j{i}'] = {'Lj_variable' : f'Lj_{i}',
                                'rect'        : f'jj_rect_{i}',
                                'line'        : f'jj_line_{i}'}

check_connected() → bool[source]#

Return True if fully connected to Ansys (app, desktop, project, design, and setup).

Returns:: True when all five COM handles are non-None.
Return type:: bool

connect() → ProjectInfo[source]#

Establish a full connection to the Ansys Desktop API.

Calls connect_project(), connect_design(), and connect_setup() in sequence. Logs connection status at each step.

Returns:: Returns self to allow chaining (e.g. pinfo = ProjectInfo(...).connect()).
Return type:: ProjectInfo

connect_design(design_name: str = None) → None[source]#

Attach to an HFSS design within the open project.

Sets self.design and self.design_name.

Parameters:: design_name (str, optional) – Name of the design to open. If None, attaches to the currently active design. Raises if the named design does not exist.

connect_project() → None[source]#

Open the Ansys Desktop application and attach to the target project.

Sets self.app, self.desktop, self.project, self.project_name, and self.project_path.

If project_name is None, attaches to the currently active project in the running Ansys Desktop instance.

connect_setup() → None[source]#

Attach to a simulation setup within the active design.

If setup_name was specified in the constructor and the setup exists, that setup is used. If setup_name is None, the first available setup is selected automatically. If no setups exist, a default one is created for Eigenmode, DrivenModal, DrivenTerminal, and Q3D designs.

Raises:

ValueError – If setup_name was specified but does not exist in the design.
ValueError – If the design solution type is not supported.

disconnect() → None[source]#

Release all COM handles and disconnect from the Ansys Desktop API.

Raises:: AssertionError – If not currently connected. Call check_connected() first, or use the context manager form (with ProjectInfo(...) as pinfo:) which guards the call automatically.

get_all_object_names() → list[source]#

Return the names of all 3-D modeler objects in the active design.

Covers Non Model, Solids, Unclassified, Sheets, and Lines groups.

Returns:: All object names as reported by the HFSS 3-D Modeler.
Return type:: list of str

get_all_variables_names() → list[source]#

Return all project-level and design-level variable names.

Returns:: Concatenation of project variable names and local design variable names. Does not include global $-prefixed project variables from other designs.
Return type:: list of str

get_dm() → tuple[source]#

Return the active design and 3-D modeler as a tuple.

Returns:: (design, design.modeler) — the HfssDesign and HfssModeler handles.
Return type:: tuple

Example

oDesign, oModeler = pinfo.get_dm()

get_setup(name: str)[source]#

Connects to a specific setup for the design. Sets self.setup and self.setup_name.

Parameters:

name (str) – Name of the setup.
exist (If the setup does not)
error. (then throws a logger)
None (in which case returns)
None

get_variable_value(name: str) → str[source]#

Return the value of a local design variable as a string.

Parameters:: name (str) – Name of the design-level variable (e.g. 'Lj').
Returns:: Value string as stored in HFSS (e.g. '10nH').
Return type:: str

Note

Only reads local design variables. Global project variables (prefixed with $) are not accessible via this method.

save() → dict[source]#

Serialise project info to a dictionary of pandas objects.

Returns:: Keys: "pinfo" (Series of scalar attributes), "dissip" (Series), "options" (Series), "junctions" (DataFrame), "ports" (DataFrame).
Return type:: dict

validate_junction_info() → None[source]#

Validate that all junction parameters refer to objects that exist in HFSS.

Checks that each junction’s Lj_variable exists as a design or project variable, and that rect and line exist as 3-D modeler objects.

Raises:: AssertionError – Descriptive message identifying the junction name and the missing variable or object.

Note

Also verify the physical length of junction rectangles and polylines if you modify geometry after the initial setup.

class pyEPR.QuantumAnalysis(data_filename, variations: list = None, do_print_info=True, Res_hamil_filename=None)[source]#

Bases: object

Quantum Hamiltonian analysis from saved EPR data.

Loads the HDF5/pickle data file written by do_EPR_analysis(), computes dressed eigenmode frequencies, anharmonicities, and cross-Kerr couplings using first-order perturbation theory and/or numerical diagonalization (via QuTiP).

Typical workflow#

epra = epr.QuantumAnalysis(eprd.data_filename)
epra.analyze_all_variations(cos_trunc=8, fock_trunc=7)
epra.plot_hamiltonian_results()

param data_filename:: Path to the .hdf5 data file produced by DistributedAnalysis.
type data_filename:: str or Path
param variations:: Subset of variation labels to load (e.g. ['0', '2']). Defaults to all variations present in the file.
type variations:: list of str, optional
param do_print_info:: Print a summary of loaded data on construction. Defaults to True.
type do_print_info:: bool, optional
param Res_hamil_filename:: Path to a previously saved HamiltonianResultsContainer .npz file. Allows resuming a partially completed analysis.
type Res_hamil_filename:: str or Path, optional

analyze_all_variations(variations: List[str] = None, analyze_previous: bool = False, **kwargs)[source]#

Run analyze_variation() for every variation and save results.

Parameters:

variations (list of str, optional) – Variation labels to analyse (e.g. ['0', '1', '3']). Defaults to all variations loaded from the data file.
analyze_previous (bool, optional) – If False (default), skip variations whose results are already stored in self.results. Set to True to recompute everything.
**kwargs – Forwarded directly to analyze_variation() — e.g. cos_trunc, fock_trunc, modes, junctions, use_full_cos.

Returns:

Mapping of variation label → result dict (same structure as the return value of analyze_variation()).

Return type:

OrderedDict

Note

Results are automatically saved to disk after all variations are processed via HamiltonianResultsContainer.save().

analyze_variation(variation: str, cos_trunc: int = None, fock_trunc: int = None, print_result: bool = True, junctions: List = None, modes: List = None, use_full_cos: bool = False)[source]#

Compute the quantum Hamiltonian parameters for a single variation.

This is the core analysis method. It extracts EPR participation matrices from the stored data, applies perturbation theory, and optionally performs numerical diagonalization via QuTiP.

Parameters:

variation (str) – Variation label (e.g. '0', '3').
cos_trunc (int, optional) – Cosine Taylor expansion order for the Josephson nonlinearity. Typical values: 4–8. Must be set together with fock_trunc to enable numerical diagonalization; if either is None, only perturbation-theory results are computed. Ignored when use_full_cos=True.
fock_trunc (int, optional) – Fock space truncation (number of levels per mode). Typical values: 5–10. Memory scales as fock_trunc ** n_modes.
print_result (bool, optional) – Print a formatted summary table of results. Defaults to True.
junctions (list, optional) – Subset of junction indices or labels to include. Defaults to all junctions.
modes (list, optional) – Subset of mode indices to include (e.g. [0, 4] for modes 0 and 4 of a 5-mode simulation). Must match the indices used in do_EPR_analysis — the DataFrame index retains the original mode numbers, not a zero-based re-index. Defaults to all modes.
use_full_cos (bool, optional) – If True, use the exact matrix-exponential cosine cos(φ) = (e^{iφ} + e^{-iφ}) / 2 instead of the truncated Taylor series. Recommended for strongly anharmonic circuits such as fluxonium, where large zero-point phase fluctuations (φ_zpf ≳ 1) make the low-order expansion inaccurate. Default False.

Returns:

Contains at minimum:

f_0 — HFSS bare eigenmode frequencies [GHz].
f_1 — First-order PT dressed frequencies [MHz].
f_ND — Numerically diagonalized dressed frequencies [MHz]; None if cos_trunc/fock_trunc not provided.
chi_O1 — Analytic χ matrix [MHz] (diagonal = anharmonicity, off-diagonal = cross-Kerr).
chi_ND — Numerically diagonalized χ matrix [MHz]; None if numerical diagonalization was not requested.

Return type:

dict

full_report_variations(var_list: list = None)[source]#: see full_variation_report

full_variation_report(variation)[source]#

prints the results and parameters of a specific variation

Parameters:: variation (int or str) – the variation to be printed .
Return type:: None.

get_Ecs(variation)[source]#: ECs in GHz Returns as pandas series

get_Ejs(variation)[source]#: EJs in GHz See calcs.convert

get_ansys_energies(swp_var='variation')[source]#

Return a multi-index dataframe of ansys energies vs swep_variable

Parameters:: swp_var (str)

get_chis(swp_variable='variation', numeric=True, variations: list = None, m=None, n=None)[source]#

Return the chi (Kerr / cross-Kerr) matrix as a multi-index DataFrame.

The diagonal entries are anharmonicities (self-Kerr); the off-diagonal entries are cross-Kerr couplings between mode pairs.

Parameters:

swp_variable (str, optional) – Sweep variable for the outer index (default: "variation").
numeric (bool, optional) – If True (default) use numerically diagonalized chi (chi_ND); if False use first-order perturbation theory (chi_O1).
variations (list of str, optional) – Subset of variation keys. None returns all.
m (int or str, optional) – Row mode label. If both m and n are given, return only the chi element between modes m and n as a Series vs sweep variable.
n (int or str, optional) – Column mode label. See m.

Returns:

Multi-index DataFrame (swp_variable, mode_row) × mode_col when m and n are None; a 1-D Series vs sweep variable when both are specified.

Return type:

pandas.DataFrame or pandas.Series

Examples

>>> chi = epra.get_chis()                     # full matrix, all variations
>>> chi_01 = epra.get_chis(m=0, n=1)          # mode-0 / mode-1 cross-Kerr
>>> chi_Lj = epra.get_chis(swp_variable='Lj') # sweep over Lj

get_convergences_max_delta_freq_vs_pass(as_dataframe=True)[source]#: Index([u’Pass Number’, u’Solved Elements’, u’Max Delta Freq. %’ ])

get_convergences_max_tets()[source]#: Index([u’Pass Number’, u’Solved Elements’, u’Max Delta Freq. %’ ])

get_convergences_tets_vs_pass(as_dataframe=True)[source]#: Index([u’Pass Number’, u’Solved Elements’, u’Max Delta Freq. %’ ])

get_epr_base_matrices(variation, _renorm_pj=None, print_=False)[source]#

Return the key matrices used in the EPR method for analytic calculations.

All as matrices

PJ:: Participation matrix, p_mj
SJ:: Sign matrix, s_mj
Om:: Omega_mm matrix (in GHz) (hbar = 1) Not radians.
EJ:: E_jj matrix of Josephson energies (in same units as hbar omega matrix)
PHI_zpf:: ZPFs in units of phi_0 reduced flux quantum
PJ_cap:: capacitive participation matrix

Return all as np.array: PM, SIGN, Om, EJ, Phi_ZPF

get_frequencies(swp_variable='variation', numeric=True, variations: list = None)[source]#

Return mode frequencies as a DataFrame indexed by mode, columns by sweep variable.

Parameters:

swp_variable (str, optional) – Name of the sweep variable to use as column labels. "variation" (default) uses the integer variation index; any HFSS variable name (e.g. "Lj") converts the index to that variable’s magnitude.
numeric (bool, optional) – If True (default) return numerically diagonalized frequencies (f_ND); if False return first-order perturbation theory frequencies (f_1).
variations (list of str, optional) – Subset of variation keys to include. None returns all variations.

Returns:

Rows are eigenmode labels, columns are sweep-variable values.

Return type:

pandas.DataFrame

get_mesh_tot()[source]#

get_participations(swp_variable='variation', variations: list = None, inductive=True, _normed=True)[source]#

Return energy participation ratios (EPR) as a multi-index DataFrame.

Parameters:

swp_variable (str, optional) – Sweep variable for the outermost index level (default: "variation").
variations (list of str, optional) – Subset of variation keys. None returns all.
inductive (bool, optional) – If True (default) return inductive (junction) participation ratios; if False return capacitive participation ratios.
_normed (bool, optional) – Return normalised participation ratios (default True). Setting False returns raw un-normalised values. Only valid when inductive is True; inductive=False, _normed=False raises NotImplementedError.

Returns:

Multi-index DataFrame with levels [swp_variable, mode] as the index and junction index as columns.

Return type:

pandas.DataFrame

Examples

Plot junction-0 participation for mode 0 vs a sweep of Lj:

df = epra.get_participations(swp_variable='Lj')
df.loc[pd.IndexSlice[:, 0], 0].unstack(1).plot(marker='o')

get_quality_factors(swp_variable='variation', variations: list = None)[source]#

Return mode quality factors as a DataFrame indexed by mode, columns by sweep variable.

Parameters:

swp_variable (str, optional) – Sweep variable for column labels (default: "variation").
variations (list of str, optional) – Subset of variation keys to include. None returns all.

Returns:

Rows are eigenmode labels, columns are sweep-variable values. Infinite Q is stored as np.inf for lossless modes.

Return type:

pandas.DataFrame

get_variable_value(swpvar, lv=None)[source]#

get_variable_vs(swpvar, lv=None)[source]#

lv is list of variations (example [‘0’, ‘1’]), if None it takes all variations swpvar is the variable by which to organize

return: ordered dictionary of key which is the variation number and the magnitude of swaver as the item

get_variation_of_multiple_variables_value(Var_dic, lv=None)[source]#

Filter variations by multiple variable values.

See also get_variations_of_variable_value.

Parameters:

Var_dic (dict) – variable name → value to filter on.
lv (list, optional) – list of variations to search; defaults to all.

Returns:

(filtered_variations, description_string)

Return type:

tuple

get_variations_of_variable_value(swpvar, value, lv=None)[source]#

A function to return all the variations in which one of the variables has a specific value lv is list of variations (example [‘0’, ‘1’]), if None it takes all variations swpvar is a string and the name of the variable we wish to filter value is the value of swapvr in which we are interested

returns lv - a list of the variations for which swavr==value

get_vs_variable(swp_var, attr: str)[source]#

Convert the index of a dictionary that is stored here from variation number to variable value.

Parameters:

swp_var (str) – name of sweep variable in ansys
attr – name of local attribute, eg.., ‘ansys_energies’

plot_hamiltonian_results(swp_variable: str = 'variation', variations: list = None, fig=None, x_label: str = None)[source]#

Plot Hamiltonian parameters (frequencies, anharmonicities, χ) versus a sweep variable.

Produces a 2×2 grid of subplots: bare and dressed frequencies, χ matrix, and participation ratios.

Parameters:

swp_variable (str, optional) – Name of the HFSS variable swept (e.g. 'Lj_alice'). Use 'variation' (default) to plot against the variation index.
variations (list of str, optional) – Subset of variations to include. Defaults to all analyzed variations.
fig (matplotlib.figure.Figure, optional) – Existing figure to draw into. If None, a new figure is created.
x_label (str, optional) – X-axis label. Defaults to swp_variable.

Returns:

(fig, axs) — the matplotlib Figure and 2×2 array of Axes.

Return type:

tuple

plot_results(result, Y_label, variable, X_label, variations: list = None)[source]#

plotting_dic_x(Var_dic, var_name)[source]#

print_info()[source]#

print_result(result)[source]#: Utility reporting function

print_variation(variation)[source]#: Utility reporting function

property project_info#

quick_plot_chi_alpha(mode1, mode2, swp_variable='variation', ax=None, kw=None, numeric=False)[source]#

Quick plot chi between mode 1 and mode 2.

If you select mode1=mode2, then you will plot the alpha

kw : extra plot arguments

quick_plot_convergence(ax=None)[source]#: Plot a report of the Ansys convergence vs pass number ona twin axis for the number of tets and the max delta frequency of the eignemode.

quick_plot_frequencies(mode, swp_variable='variation', ax=None, kw=None, numeric=False)[source]#

Quick plot freq for one mode

kw : extra plot arguments

quick_plot_mode(mode, junction, mode1=None, swp_variable='variation', numeric=False, sharex=True)[source]#

Create a quick report to see mode parameters for only a single mode and a cross-kerr coupling to another mode. Plots the participation and cross participation Plots the frequencie plots the anharmonicity

The values are either for the numeric or the non-numeric results, set by numeric

quick_plot_participation(mode, junction, swp_variable='variation', ax=None, kw=None)[source]#

Quick plot participation for one mode

kw : extra plot arguments

report_results(swp_variable='variation', numeric=True)[source]#: Report in table form the results in a markdown friendly way in Jupyter notebook using the pandas interface.

pyEPR.parse_entry(entry, convert_to_unit='meter')[source]#: Should take a list of tuple of list… of int, float or str… For iterables, returns lists

pyEPR.parse_units(x)[source]#

Convert number, string, and lists/arrays/tuples to numbers scaled in HFSS units.

Converts to LENGTH_UNIT = meters [HFSS UNITS] Assumes input units LENGTH_UNIT_ASSUMED = mm [USER UNITS]

[USER UNITS] —-> [HFSS UNITS]

pyEPR.parse_units_user(x)[source]#: Convert from user assumed units to user assumed units [USER UNITS] —-> [USER UNITS]

pyEPR package#

Updates#

Typical workflow#

Subpackages#

Submodules#