Open-source solvers¶
The solvers that run without a commercial license. See Simulation pathways for what each computes and how to choose.
gmsh + scikit-fem¶
Finite-element solvers that run inside Python.
qiskit_metal.analyses.fem.solver meshes a chip in its package with
gmsh and solves it with scikit-fem: eigenmodes with lumped junctions, a port
reduced-order model, and electrostatics. Tutorials 4.41-4.45 use it. Needs
gmsh and scikit-fem, imported only when a mesh is built or a solver
runs.
- class Electrostatics(pmesh: PackageMesh, order=2)[source]¶
Maxwell capacitance matrix of all paddles, with one LU.
Each paddle is a perfect conductor, so its nodes share one potential: they collapse to a single unknown. Package walls are grounded; cut faces of a symmetry-reduced mesh are left free (images at equal potential, irrelevant for the local capacitance of a qubit). With K the stiffness matrix of div(eps grad phi) = 0, the capacitance matrix is the Schur complement of K onto the paddle unknowns.
- charges(a, b, energy=1.0)[source]¶
Nodal charges (C) on all paddles for the qubit mode of port (a, b).
Returns (locations (3, k) in mm, charges (k,)). Charges +q on a and -q on b with (1/2) C V^2 =
energy; every other paddle floats.
- dipole(a, b, energy=1.0)[source]¶
Dipole moment p (C m, 3-vector) of the qubit mode with the given energy.
Charges +q on a and -q on b, all other paddles floating; the nodal charges are the reactions K phi on the paddle nodes.
- class MaxwellFEM(pmesh: PackageMesh, cuts=('pmc', 'pmc'))[source]¶
Curl-curl eigenproblem for the package, on lowest-order Nedelec elements.
Weak form (lengths in mm, E in V/mm):
- int curl E . curl F dV + sum_ports (mu0 1e-3 / L_p) V_p(E) V_p(F)
= k0^2 int eps_r E . F dV,
where V_p(E) is the line integral of E across port p. Perfect-conductor walls and paddles pin the tangential E to zero (their edges are removed); a symmetry plane is either a perfect electric conductor (‘pec’, edges removed) or a perfect magnetic conductor (‘pmc’, nothing to do: the natural boundary condition).
- Parameters:
pmesh – the mesh from
mesh_package().cuts – boundary condition on the x = Lx/2 and y = Ly/2 cut faces of a quarter (or half) mesh, e.g. (‘pmc’, ‘pmc’) for LSM110.
- eigenmodes(f_target, n=1, inductors=None)[source]¶
The n modes closest to f_target (Hz), each normalized to 1 J.
inductorsmaps a port name to an inductance in henry: a lumped element across that junction (or probe). Ports not listed are open.
- energy(u)[source]¶
Energy (J) in the whole package of a field u defined on this region.
u is a peak amplitude, so
1/2 int eps abs(E)^2is the total mode energy.
- class Mode(f: float, u: ndarray, fem: MaxwellFEM)[source]¶
An eigenmode, normalized to 1 J of energy in the whole package.
- class Package(Lx: float, Ly: float, Lz: float, t: float, eps_r: float, metals: dict, junctions: dict)[source]¶
What the mesher needs: the box, the slab, the metal and the junctions (mm).
- class PackageMesh(p: ndarray, t: ndarray, material: ndarray, metal_tris: dict, junction_segs: dict, probe_segs: ndarray | None, probe_xy: tuple | None, bounds: tuple, region: str, package: Package, mesh_time: float = 0.0)[source]¶
A tetrahedral mesh of (part of) the package, with the entities we need.
- property n_sym¶
How many copies of this region make up the whole package.
- slice(axis, value)[source]¶
Cut the tetrahedra with the plane coordinate[axis] = value.
Returns (polygons, material): a list of (k, 2) arrays in the two remaining coordinates (triangles or quadrilaterals), and the material of the tetrahedron each came from. Plot them with a matplotlib PolyCollection to see the mesh through the package.
- class PortROM(fem: MaxwellFEM, ports, f_center, n_moments=6, extra=None, verbose=True)[source]¶
A reduced model of the package seen from its ports, built once.
Every junction or probe enters the finite-element problem only through a rank-one term (mu0 1e-3 / L) c c^T. So all four extraction methods need only the response of the open structure at its ports, near the band of interest. This class captures that response with a block Krylov space
span{ R, (A - sigma M)^-1 M R, … }, R = (A - sigma M)^-1 [c_1 … c_p],
one sparse LU and
n_momentsblock solves, then answers every question on small dense matrices: eigenmodes with any junction inductors, and the impedance matrix over any frequency grid. It is the same idea as the fast frequency sweep in commercial solvers (moment matching / Pade).- eigenmodes(inductors=None, fmin=0.0, fmax=inf)[source]¶
(frequencies in Hz, port voltages (n_modes, n_ports) for 1 J).
- emf_coupling(f, V, C, Em=1.0)[source]¶
Induced-EMF coupling, Eq. (11): g/2pi in Hz.
fis the package-mode frequency (Hz),Vthe voltage it induces across the open junction (V) at mode energyEm(J), andCthe capacitance seen across the junction (F).
- mesh_package(package: Package, region='full', h_metal=0.1, h_max=0.8, grow=3.0, h_junction=None, r_junction=0.2, probe=None, pads=True, substrate=True, verbose=False)[source]¶
Mesh the package with gmsh.
- Parameters:
package – the geometry, e.g. from
package_from_design().region –
'full','half'(y < Ly/2) or'quarter'(x < Lx/2, y < Ly/2). The cut faces become symmetry planes in the solver.h_metal – element size along the paddle edges (mm).
h_max – largest element size (mm), in the bulk of the package.
grow – distance (mm) over which the size grows from h_metal to h_max.
h_junction – optional finer element size around each junction (mm). By default the junctions get h_metal like the paddle edges. The field is strongest in the junction gap, so seeding it finely is the most economical way to converge the junction voltages.
r_junction – radius (mm) of the refined region around each junction.
probe – optional (x, y) of a vertical wire port from floor to lid.
pads – set False to leave the paddles (and junctions) out.
substrate – set False to leave the silicon out (empty box).
- mirror_signs(cuts)[source]¶
Sign of g under the x- and y-mirrors, for the given cut conditions.
The junction voltage is a line integral of E_x. Across a ‘pmc’ plane the tangential field is even, across a ‘pec’ plane it is odd; the x-cut is normal to E_x and the y-cut is parallel to it.
- package_from_design(design, eps_r)[source]¶
Read box, substrate, paddles and junction lines from a Metal design.
The chip outline sets the package walls; the silicon thickness comes from the layer stack and the lid height from the sample-holder variables. Subtracted shapes (ground-plane cuts) are ignored: this chip has no ground plane.
Analytic package-mode models¶
Package modes and qubit couplings, analytically.
A superconducting chip in a metal package sits in a box resonator loaded by the silicon slab. The lowest box modes are LSM modes, whose electric field at the slab surface drives every qubit on the chip at once, with a coupling that follows the mode’s standing-wave pattern across the array. This module holds the closed-form side of that picture, to check a full-wave simulation against:
the LSM_ab0 modes of a rectangular box partly filled with a dielectric slab (
lsm_mode, and the closed-form approximationslsm_mode_approx), and the electric-dipole estimate of a qubit’s coupling to one (dipole_coupling);the two-mode lumped circuit of a qubit and a package mode, its couplings, eigenfrequencies and impedance matrix (
circuit_couplings,circuit_impedance), and the fit of a simulated impedance matrix back to that circuit (fit_impedance);the amplitude of a coupling pattern over a uniform
n x narray (qubit_centers,fit_amplitude).
Equation numbers refer to R. Molavi et al., “Extracting electromagnetic
bare mode couplings in large superconducting quantum processors,”
arXiv:2609.22442 (2026). Used by tutorials 4.41-4.45; the finite-element side
is qiskit_metal.analyses.fem.
- class ImpedanceFit(poles: ndarray, residues: ndarray, C: ndarray, Lp: ndarray, dL: ndarray, rms_error: float)[source]¶
Result of the Appendix-D fit (SI units, index 0 = package, 1 = qubit).
- class LSMMode(a: int, b: int, f: float, kz_si: float, kz_air: float, gamma: float, E0z: float, E0x: float, U_ratio: float, Lx: float, Ly: float, Lz: float, t: float, eps_r: float)[source]¶
One LSM_ab0 mode of a rectangular box partially filled with a slab.
Lengths in metres.
E0xis the amplitude of the in-plane field at the slab surface for 1 J of mode energy, Eq. (E14).
- circuit_couplings(C, L)[source]¶
Bare frequencies and couplings of two coupled LC resonators, Eq. (A6)-(A11).
CandLare the 2x2 capacitance and inductance matrices (SI). Returns a dict with bare angular frequenciesw(2,), coupling efficiencieskC,kLand couplingsgC,gLin rad/s.
- circuit_eigenfrequencies(C, L)[source]¶
Exact normal-mode angular frequencies: eigenvalues of C^-1/2 L^-1 C^-1/2.
- circuit_impedance(w, Lp, C, dL)[source]¶
Impedance matrix of the lumped model, Eq. (12).
win rad/s.Lpholds the port shunts (diagonal),Cthe capacitance matrix anddLthe geometric inductances. Returns complex Z of shape (len(w), 2, 2) with the engineering convention Z = jX.
- dipole_coupling(px, mode: LSMMode, Em=1.0, En=1.0)[source]¶
Electric-dipole estimate of the on-resonance coupling amplitude.
k_C = p_x a E0x / (2 sqrt(Em En)) (Eq. 16 at the field maximum), and g_C = k_C sqrt(w_m w_n) / 2 with w_n = w_m. Returns (k_C, A) with A in Hz.
- fit_amplitude(g, a, b, Lx, Ly)[source]¶
Least-squares
Aing = A cos(a pi x/Lx) sin(b pi y/Ly)(Eqs. 14, 17).gis an (n, n) array [j, i] over a uniform grid of qubits on aLx x Ly(mm) chip. Returns(A, largest residual / abs(A)).
- fit_impedance(w, Z, n_poles=2)[source]¶
Fit a simulated 2x2 impedance matrix to Eq. (12), following Appendix D.
Fit Z = sum_mu 2 j w w_mu R_mu / (w_mu^2 - w^2) + j w dL~ (Eq. D1, D4): the pole frequencies by least squares, the residues and dL~ linearly.
Factor each residue as R_mu = sigma_mu sigma_mu^T (D5), stack Sigma.
L~^-1 = 1/2 Sigma^-T Omega Sigma^-1, C~ = 1/2 Sigma^-T Omega^-1 Sigma^-1 (D7).
Undo the tail correction with alpha = I + L~^-1 dL~ (D3).
win rad/s,Zcomplex (nw, 2, 2) in ohms.
- g_on_resonance(gC, gL, wm, wn)[source]¶
Eq. (10): convert (g_C, g_L) at a detuned qubit to the resonant g.
- lsm_mode(a, b, Lx, Ly, Lz, t, eps_r, Em=1.0)[source]¶
Solve the transcendental equation (E3) for the lowest LSM_ab0 mode.
The lowest mode is the root with
kz_si * t < pi/2, below the first pole ofks tan(ks t).Lx,Ly,Lz(the box) andt(the slab) are in mm; the returned mode is in SI units, normalized to mode energyEmjoules.
- lsm_mode_approx(a, b, Lx, Ly, Lz, t, eps_r, Em=1.0)[source]¶
The closed-form approximations at the end of Appendix E (SI units).
They assume a thin slab,
kz_si * t << 1. AUserWarningis issued when the approximatekz_si * texceeds 0.5, where the frequency is off by about 1 % or more (small boxes or thick slabs); uselsm_mode()there.
gmsh and ElmerFEM¶
Meshing is QGmshRenderer.
- class QElmerRenderer(design: MultiPlanar, layer_types: dict | None = None, initiate=True, options: Dict = None)[source]¶
Extends QRendererAnalysis class and imports meshes from Gmsh using the ElmerFEM python API.
- QElmerRenderer Default Options:
- simulation_type – Type of ElmerFEM simulation to run.
Default options found in elmer_configs.py under “simulations”.
simulation_dir – Directory to store simulation-related files.
mesh_file – Name of GMSH output mesh file ending in ‘.msh’.
simulation_input_file – Name of ElmerFEM simulation input file ending in ‘.sif’.
postprocessing_file – Name of ElmerFEM postprocessing output file ending in ‘.msh’.
output_file – Name of ElmerFEM results output file ending in ‘.result’.
- QElmerRenderer Default Setup:
capacitance – Default setup for capacitance simulation:
Calculate_Electric_Field – Defaults to True.
Calculate_Electric_Energy – Defaults to True.
Calculate_Capacitance_Matrix – Defaults to True.
Capacitance_Matrix_Filename – Defaults to “cap_matrix.txt”.
Linear_System_Solver – Defaults to “Iterative”.
Steady_State_Convergence_Tolerance – Defaults to 1.0e-5.
Nonlinear_System_Convergence_Tolerance – Defaults to 1.0e-7.
Nonlinear_System_Max_Iterations – Defaults to 20.
Linear_System_Convergence_Tolerance – Defaults to 1.0e-10.
Linear_System_Max_Iterations – Defaults to 500.
Linear_System_Iterative_Method – Defaults to “BiCGStab”.
BiCGstabl_polynomial_degree – Defaults to 2.
eigenmode – Default setup for Eigenmode simulation (to be added in future).
materials – Materials used in the simulation. Defaults to [“vacuum”, “silicon”].
constants – Default constants to be included in the simulation:
Permittivity_of_Vacuum – Defaults to 8.8542e-12 F/m.
Unit_Charge – Defaults to 1.602e-19 C.
- QGmshRenderer Default Options:
# Buffer between max/min x and edge of ground plane, in mm * x_buffer_width_mm – Buffer between max/min x and edge of ground plane, in mm * y_buffer_width_mm – Buffer between max/min y and edge of ground plane, in mm * mesh – to define meshing parameters
max_size – upper bound for the size of mesh node
min_size – lower bound for the size of mesh node
max_size_jj – maximum size of mesh nodes at jj
smoothing – mesh smoothing value
nodes_per_2pi_curve – number of nodes for every 2π radians of curvature
algorithm_3d – value to indicate meshing algorithm used by Gmsh
num_threads – number of threads for parallel meshing
mesh_size_fields – specify mesh size field parameters
min_distance_from_edges – min distance for mesh gradient generation
max_distance_from_edges – max distance for mesh gradient generation
distance_delta – delta change in distance with each consecutive step
gradient_delta – delta change in gradient with each consecutive step
colors – specify colors for the mesh elements, chips or layers
metal – color for metallized entities
jj – color for JJs
dielectric – color for dielectric entity
- Parameters:
design ('MultiPlanar') – The design.
layer_types (Union[dict, None]) – the type of layer in the format: dict(metal=[…], dielectric=[…]). Defaults to None.
initiate (bool) – True to initiate the renderer (Default: False).
settings (Dict, optional) – Used to override default settings. Defaults to None.
- add_solution_setup(sim_name: str = 'capacitance', solver_names: list[str] = ['capacitance', 'postprocessing_gmsh'], equation_name: str = 'poisson')[source]¶
- Initializes ElmerFEM analysis to run.
Currently only supports Electrostatic capacitance extraction
- Parameters:
- add_table_data_to_QDesign(class_name: str)¶
During init of renderer, this needs to happen. In particular, each renderer needs to update custom columns and values within QDesign.
- Parameters:
class_name (str) – Name from cls.name for each renderer.
- assign_nets(open_pins: list | None = None) dict[str | int, list[str]][source]¶
Assigns a netlist number to each galvanically connected metal region, and returns a dictionary with each net as a key, and the corresponding list of geometries associated with that net as values.
The nets come from
qiskit_metal.toolbox_metal.nets.galvanic_nets(), which every solver backend shares.
- define_bodies(setup: dict, equation: int, materials: list[int]) list[list][source]¶
Assigns bodies to simulation model.
- element_extensions = {}¶
Element extensions dictionary
- element_table_data = {}¶
Element table data.
- element_table_docs = {'capacitance': 'Junction capacitance used by {renderer} (0: none).', 'cell_name': "Cell of the junction GDS file (the GDS renderer's path_filename) that replaces this component's junction on export.", 'inductance': 'Junction inductance used when the junction is rendered to {renderer}.', 'mesh_kw_jj': 'Largest mesh element on the junction in {renderer}, in meters.', 'resistance': 'Junction resistance used by {renderer} (0: none).', 'wire_bonds': 'Add wire bonds over this path when rendered to {renderer}.'}¶
Descriptions of the
element_table_datacolumns, which components carry as<renderer name>_<column>options.{renderer}is replaced by the renderer’s name. A renderer that adds columns documents them here.
- get_gnd_qgeoms(open_pins: list | None = None) list[str][source]¶
Obtain a list of qgeometry names associated with pins shorted to ground.
- get_qgeometry_table() DataFrame[source]¶
- Combines the “path” and “poly” qgeometry tables into a single table, and adds
column containing the minimum z coordinate of the layer associated with each qgeometry.
- Raises:
ValueError – Raised when component in selection of qcomponents is not in QDesign.
- Returns:
Table with elements in both “path” and “poly” qgeometry tables.
- Return type:
pd.DataFrame
- classmethod get_template_options(design: QDesign, render_template: Dict = None, logger_: Logger = None, template_key: str = None) Dict¶
Creates template options for the Metal QRenderer class required for the class to function, based on the design template; i.e., be created, made, and rendered. Provides the blank option structure required.
The options can be extended by plugins, such as renderers.
- Parameters:
design (QDesign) – A design class.
render_template (Dict, optional) – Template options to overwrite the class ones. Defaults to None.
logger (logging.Logger, optional) – A logger for errors. Defaults to None.
template_key (str, optional) – The design.template_options key identifier. If None, then use _get_unique_class_name(). Defaults to None.
- Returns:
Dictionary of renderer’s default options based on design.template_options.
- Return type:
Dict
- get_unique_component_ids(highlight_qcomponents: list | None = None) tuple[list, int]¶
Confirm the list doesn’t have names of components repeated. Confirm that the name of component exists in QDesign. If QDesign doesn’t contain any component, or if all components in QDesign are found in highlight_qcomponents, return an empty list; otherwise return a list of unique components to be sent to the renderer. The second returned item, an integer, specifies which of these 3 cases applies.
- initialize_renderer()[source]¶
Initializes the Gmsh and Elmer renderer. NOTE TO USER: this should be used when using the QElmerRenderer through design.renderers.elmer instance.
Example: To change one of the options exposed by QGmshRenderer, one has to first initiate the QElmerRenderer using this method and then change the property like so,
` design.renderers.elmer.initialize_renderer() design.renderers.elmer.gmsh.options.mesh.num_threads = 1 ... `
- property initialized¶
Abstract method. Must be implemented by the subclass. Is renderer ready to be used? Implementation must return boolean True if successful. False otherwise.
- classmethod load()¶
Load the renderer and register all its extensions. Only performed once.
Once complete, the renderer is added to the class attribute ‘__loaded_renderers__’ of QRenderer
- Returns:
True if success, otherwise throws an error.
- Return type:
- name = 'elmer'¶
Name
- property options: Dict¶
Options for the QRenderer.
- parse_value(value: Any | list | Dict | Iterable) Any¶
Same as design.parse_value. See design for help.
- Returns:
Parsed value of input.
- Return type:
- classmethod populate_element_extensions()¶
Populate cls.element_extensions which will be used to create columns for tables in QGeometry tables.
The structure of cls.element_table_data should be same as cls.element_extensions.
- render_chip(chip_name: str)[source]¶
Abstract method. Must be implemented by the subclass. Render the given chip.
- Parameters:
name (str) – chip to render
- render_chips(chips: str | list[str] = [], draw_sample_holder: bool = True, box_plus_buffer: bool = True)[source]¶
Abstract method. Must be implemented by the subclass. Render all chips of the design. Calls render_chip for each chip.
- render_component(component)[source]¶
Abstract method. Must be implemented by the subclass. Render the specified component.
- Parameters:
component (QComponent) – Component to render.
- render_components(table_type: str)[source]¶
Abstract method. Must be implemented by the subclass. Render all components of the design. If selection is none, then render all components.
- Parameters:
selection (QComponent) – Component to render.
- render_design(selection: list | None = None, open_pins: list | None = None, box_plus_buffer: bool = True, draw_sample_holder: bool = True, skip_junctions: bool = False, mesh_geoms: bool = True, ignore_metal_volume: bool = False, omit_ground_for_layers: list[int] | None = None)[source]¶
Render the design in Gmsh and apply changes to modify the geometries according to the type of simulation. Simulation parameters provided by the user.
- Parameters:
selection (Union[list, None], optional) – List of selected components to render. Defaults to None.
open_pins (Union[list, None], optional) – List of open pins that are open. Defaults to None.
box_plus_buffer (bool, optional) – Set to True for adding buffer to chip dimensions. Defaults to True.
draw_sample_holder (bool, optional) – To draw the sample holder box. Defaults to True.
skip_junctions (bool, optional) – Set to True to sip rendering the junctions. Defaults to False.
mesh_geoms (bool, optional) – Set to True for meshing the geometries. Defaults to True.
ignore_metal_volume (bool, optional) – ignore the volume of metals and replace it with a list of surfaces instead. Defaults to False.
omit_ground_for_layers (Optional[list[int]]) – omit rendering the ground plane for specified layers. Defaults to None.
- render_element(qgeom: Series, table_type: str)[source]¶
Abstract method. Must be implemented by the subclass. Render the specified element
- Parameters:
element (Element) – Element to render.
- render_element_junction(junc: Series)[source]¶
Abstract method. Must be implemented by the subclass. Render an element junction.
- Parameters:
junc (str) – Junction to render.
- render_element_path(path: Series)[source]¶
Abstract method. Must be implemented by the subclass. Render an element path.
- Parameters:
path (str) – Path to render.
- render_element_poly(poly: Series)[source]¶
Abstract method. Must be implemented by the subclass. Render an element poly.
- Parameters:
poly (Poly) – Poly to render.
- render_layer(layer_number: str, datatype: int = 0)[source]¶
Abstract method. Must be implemented by the subclass. Render the given layer.
- Parameters:
name (str) – layer to render
- render_layers(draw_sample_holder: bool = True, layers: list[int] | None = None, box_plus_buffer: bool = True)[source]¶
Abstract method. Must be implemented by the subclass. Render all layers of the design. Calls render_layer for each layer.
- run(sim_type: str, display_cap_matrix: bool = False) None | DataFrame[source]¶
Runs ElmerFEM analysis.
- save_capacitance_matrix(path: str)[source]¶
Saves capacitance matrix to file.
- Parameters:
path (str) – path where capacitance matrix should be saved.
- save_screenshot(path: str | None = None, show: bool = True)[source]¶
Save the screenshot.
- Parameters:
- Returns:
path to png formatted screenshot.
- Return type:
- start(force: bool = False) bool¶
Call any initialization (single run) step required to setup the renderer for the first execution, such as connecting to some API or COM, or importing the correct material libraries, etc.
- update_options(render_options: Dict = None, render_template: Dict = None)¶
If template options has not been set for this renderer, then gather all the default options for children and add to design. The GUI would use this to store the template options.
Then give the template options to render to store in self.options. Then user can over-ride the render_options.
- Parameters:
render_options (Dict, optional) – If user wants to over-ride the template options. Defaults to None.
render_template (Dict, optional) – All the template options for each child. Defaults to None.