qdesignoptimizer.sim_capacitance_matrix module

Study classes for capacitance matrix based simulations.

class qdesignoptimizer.sim_capacitance_matrix.CapacitanceMatrixStudy(qiskit_component_names: list, open_pins: list | None = None, x_buffer_width_mm: float = 2, y_buffer_width_mm: float = 2, render_qiskit_metal: Callable | None = None, render_qiskit_metal_kwargs: dict | None = None, percent_error: float | None = 0.5, nbr_passes: int | None = 10)[source]

Bases: object

Base class for capacitance matrix simulations of quantum circuit components in DesignAnalysis.

When multiple components are rendered in the capacitance matrix analysis, the union of all connected components will be represented by a unique name, which becomes a column in the resulting capacitance matrix. These capacitance names typically change if you modify which components are included in the analysis.

This class can be used directly for basic capacitance simulations or extended by specialized subclasses to calculate specific decay parameters like T1 or kappa.

Parameters:

qiskit_component_names (list) – Names of Qiskit Metal components to include in the capacitance simulation.
open_pins (list, optional) – Pin connections to leave open (not grounded or connected), specified as tuples of (component_name, pin_name). Defaults to an empty list.
x_buffer_width_mm (float, optional) – Width of simulation buffer space in x-direction in millimeters. Defaults to 2mm.
y_buffer_width_mm (float, optional) – Width of simulation buffer space in y-direction in millimeters. Defaults to 2mm.
render_qiskit_metal (Callable, optional) – Function for rendering the design before simulation. If None, the function from DesignAnalysisState will be used when this study is part of a DesignAnalysis optimization. Takes the form render_qiskit_metal(design, **kwargs).
render_qiskit_metal_kwargs (dict, optional) – Keyword arguments for the render_qiskit_metal function. Defaults to an empty dict.
percent_error (float, optional) – Target percentage error for simulation convergence. Defaults to 0.5%.
nbr_passes (int, optional) – Maximum number of mesh refinement passes to perform. Defaults to 10.

capacitance_matrix_fF

Capacitance matrix results from simulation in femtofarads (fF). Populated by calling simulate_capacitance_matrix().

Type:: pandas.DataFrame

mode_capacitances_matrix_fF

Extracted mode capacitances from the capacitance matrix. Populated by calling simulate_capacitance_matrix().

Type:: dict

set_render_qiskit_metal(render_qiskit_metal: Callable)[source]

Set the rendering function to use before capacitance simulation.

This method allows updating the rendering function after initialization, particularly useful when a CapacitanceMatrixStudy is being used within a DesignAnalysis context.

Parameters:: render_qiskit_metal (Callable) – Function that renders the design components, with signature render_qiskit_metal(design, **kwargs).

simulate_capacitance_matrix(design: QDesign)[source]

Run the capacitance matrix simulation for the specified design.

Parameters:: design (QDesign) – The Qiskit Metal design to simulate.
Returns:: The simulated capacitance matrix in femtofarads (fF). Rows and columns correspond to component/island names.
Return type:: pandas.DataFrame

Note

The simulation results are also stored in the capacitance_matrix_fF attribute for later use by derived classes.

class qdesignoptimizer.sim_capacitance_matrix.ModeDecayStudy(mode: str, mode_freq_GHz: float, qiskit_component_names: list, open_pins: list | None = None, x_buffer_width_mm: float = 2, y_buffer_width_mm: float = 2, render_qiskit_metal: Callable | None = None, render_qiskit_metal_kwargs: dict | None = None, percent_error: float = 0.5, nbr_passes: int = 10)[source]

Bases: ABC, CapacitanceMatrixStudy

Abstract base class for studies that analyze mode decay using capacitance simulations.

This class extends CapacitanceMatrixStudy to provide a common interface for different types of decay studies. Specific decay mechanisms (such as decay into charge lines or waveguides) are implemented by subclasses.

Since capacitance values should be evaluated at the frequency of the specific mode, each decay analysis should be performed in a separate ModeDecayStudy instance.

Parameters:

mode (str) – Name of the mode being analyzed (e.g., “qubit_1”).
mode_freq_GHz (float) – Frequency of the mode in GHz.
qiskit_component_names (list) – Components to include in simulation.
open_pins (list, optional) – Pins to leave open. Defaults to [].
x_buffer_width_mm (float, optional) – X buffer width in mm. Defaults to 2.
y_buffer_width_mm (float, optional) – Y buffer width in mm. Defaults to 2.
render_qiskit_metal (Callable, optional) – Function for rendering the design before simulation. If None, the function from DesignAnalysisState will be used when this study is part of a DesignAnalysis optimization. Takes the form render_qiskit_metal(design, **kwargs).
render_qiskit_metal_kwargs (dict, optional) – Keyword arguments for the render_qiskit_metal function. Defaults to an empty dict.
percent_error (float, optional) – Target simulation error. Defaults to 0.5.
nbr_passes (int, optional) – Maximum simulation passes. Defaults to 10.

abstract get_decay_parameter_value()[source]

Calculate and return the decay parameter value for this mode.

This abstract method must be implemented by subclasses to compute specific decay parameters (T1, kappa, etc.) from the capacitance matrix.

Returns:: The calculated decay parameter value in appropriate units.
Return type:: float

get_decay_parameter_type()[source]

Get the type of decay parameter this study calculates.

Returns:: Parameter type identifier (e.g., “charge_line_limited_t1”, “kappa”).
Return type:: str

class qdesignoptimizer.sim_capacitance_matrix.ModeDecayIntoChargeLineStudy(mode: str, mode_freq_GHz: float, mode_capacitance_name: str | List[str], charge_line_capacitance_name: str, charge_line_impedance_Ohm: float, qiskit_component_names: list, open_pins: list | None = None, ground_plane_capacitance_name: str | None = None, x_buffer_width_mm: float = 2, y_buffer_width_mm: float = 2, render_qiskit_metal: Callable | None = None, render_qiskit_metal_kwargs: dict | None = None, percent_error: float = 0.5, nbr_passes: int = 10)[source]

Bases: ModeDecayStudy

Study for calculating T1 relaxation time due to decay into a charge line.

This class calculates the T1 relaxation time limit for a mode (typically a qubit) due to its coupling to a charge line. The calculation accounts for the capacitance between the mode’s islands and the charge line, using either a grounded or floating island model depending on the physical configuration.

Parameters:

mode (str) – Name of the mode being analyzed (e.g., “qubit_1”).
mode_freq_GHz (float) – Frequency of the mode in GHz.
mode_capacitance_name (str or List[str]) –
Capacitance name(s) of the mode’s islands:
- For a grounded design: provide a single string with the island name
- For a floating design: provide a list of two strings with the island names
charge_line_capacitance_name (str) – Capacitance name of the charge line.
charge_line_impedance_Ohm (float) – Impedance of the charge line in Ohms.
qiskit_component_names (list) – Components to include in simulation.
open_pins (list, optional) – Pins to leave open. Defaults to [].
ground_plane_capacitance_name (str, optional) – Capacitance name of the ground plane. Required for floating island calculations.
x_buffer_width_mm (float, optional) – X buffer width in mm. Defaults to 2.
y_buffer_width_mm (float, optional) – Y buffer width in mm. Defaults to 2.
render_qiskit_metal (Callable, optional) – Function for rendering the design before simulation. If None, the function from DesignAnalysisState will be used when this study is part of a DesignAnalysis optimization. Takes the form render_qiskit_metal(design, **kwargs).
render_qiskit_metal_kwargs (dict, optional) – Keyword arguments for the render_qiskit_metal function. Defaults to an empty dict.
percent_error (float, optional) – Target simulation error. Defaults to 0.5.
nbr_passes (int, optional) – Maximum simulation passes. Defaults to 10.

Note

The calculation method differs between grounded and floating designs:

Grounded design: Single island capacitively coupled to charge line
Floating design: Two islands (e.g., split transmon) coupled to charge line

get_t1_limit_due_to_decay_into_charge_line() → float[source]

Calculate the T1 relaxation time limit due to charge line coupling..

Returns:

The T1 limit in seconds.

Return type:

float

Raises:

AssertionError – If capacitance_matrix_fF has not been set (run simulate_capacitance_matrix first).
NotImplementedError – If mode_capacitance_name has an invalid format.

Note

For grounded designs (single island), the function calculates T1 using:

The total island self-capacitance
The coupling capacitance to the charge line

For floating designs (two islands), the function uses:

The coupling capacitance between islands
The capacitances between each island and ground
The capacitances between each island and the charge line

get_decay_parameter_value() → float[source]

Get the T1 limit due to charge line coupling.

Returns:: The T1 limit in seconds.
Return type:: float

class qdesignoptimizer.sim_capacitance_matrix.ResonatorDecayIntoWaveguideStudy(mode: str, mode_freq_GHz: float, resonator_name: str, waveguide_name: str, impedance_ohm: float, qiskit_component_names: list, resonator_type: Literal['lambda_4', 'lambda_2'], open_pins: list | None = None, x_buffer_width_mm: float = 2, y_buffer_width_mm: float = 2, render_qiskit_metal: Callable | None = None, render_qiskit_metal_kwargs: dict | None = None, percent_error: float = 0.5, nbr_passes: int = 10)[source]

Bases: ModeDecayStudy

Study for calculating resonator decay rate (kappa) into a waveguide.

This class calculates the decay rate (kappa) of a resonator mode into a coupled waveguide based on the capacitance between them. The calculation uses a simplified model assuming the resonator and waveguide have the same impedance.

Parameters:

mode (str) – Name of the resonator mode being analyzed.
mode_freq_GHz (float) – Frequency of the resonator mode in GHz.
resonator_name (str) – Capacitance name of the resonator in the simulation.
waveguide_name (str) – Capacitance name of the waveguide in the simulation.
impedance_ohm (float) – Impedance of both the waveguide and resonator in Ohms.
qiskit_component_names (list) – Components to include in simulation.
resonator_type (Literal["lambda_4", "lambda_2"]) –
Type of resonator:
- ”lambda_4”: Quarter-wavelength resonator
- ”lambda_2”: Half-wavelength resonator
open_pins (list, optional) – Pins to leave open. Defaults to [].
x_buffer_width_mm (float, optional) – X buffer width in mm. Defaults to 2.
y_buffer_width_mm (float, optional) – Y buffer width in mm. Defaults to 2.
render_qiskit_metal (Callable, optional) – Function for rendering the design before simulation. If None, the function from DesignAnalysisState will be used when this study is part of a DesignAnalysis optimization. Takes the form render_qiskit_metal(design, **kwargs).
render_qiskit_metal_kwargs (dict, optional) – Keyword arguments for the render_qiskit_metal function. Defaults to an empty dict.
percent_error (float, optional) – Target simulation error. Defaults to 0.5.
nbr_passes (int, optional) – Maximum simulation passes. Defaults to 10.

Note

The calculation differs between quarter-wavelength and half-wavelength resonators:

Quarter-wavelength (lambda/4): kappa value is doubled compared to half-wavelength
Half-wavelength (lambda/2): standard calculation

get_kappa_estimate() → float[source]

Calculate the resonator decay rate (kappa) into the waveguide.

This method extracts the coupling capacitance between the resonator and waveguide from the simulation results and calculates the decay rate using a simplified model. The calculation assumes the resonator and waveguide have the same impedance.

Returns:: The estimated kappa (decay rate) in Hz.
Return type:: float
Raises:: AssertionError – If capacitance_matrix_fF has not been set (run simulate_capacitance_matrix first).

Note

The formula used is: κ = Z₀²·ω³·C²/π/(2π) Where:

Z₀ is the impedance (ohms)
ω is the angular frequency (2π·f)
C is the coupling capacitance (fF)

For quarter-wavelength resonators, the result is doubled.

get_decay_parameter_value() → float[source]

Get the resonator decay rate (kappa) into the waveguide.

Returns:: The estimated kappa (decay rate) in Hz.
Return type:: float