How to Configure Ansys Eigenmode Simulation Settings for Superconducting Qubit Designs in SQuADDS

The AnsysSimulator class in SQuADDS provides three flexible methods to configure Ansys eigenmode simulations: modifying the default_eigenmode_options dictionary, passing custom emode_setup parameters to sweep methods, or calling update_simulation_setup() for persistent configuration changes.

SQuADDS (Superconducting Qubit Automated Design and Documentation System) streamlines quantum hardware development through automated electromagnetic analysis. The AnsysSimulator class defined in squadds/simulations/ansys_simulator.py serves as the primary Python interface for driving Ansys HFSS eigenmode simulations, enabling precise extraction of resonant frequencies and electromagnetic field distributions for transmon and fluxonium designs.

Understanding the Default Eigenmode Configuration

The AnsysSimulator initializes with a comprehensive set of convergence and mesh parameters stored in self.default_eigenmode_options. These defaults control adaptive mesh refinement, basis function order, and Josephson junction variables.

According to the source code in squadds/simulations/ansys_simulator.py, the default eigenmode configuration dictionary structure is:

self.default_eigenmode_options = {
    "setup": {
        "basis_order": 1,
        "max_delta_f": 0.02,
        "max_passes": 30,
        "min_converged": 3,
        "min_converged_passes": 3,
        "min_freq_ghz": 1,
        "min_passes": 1,
        "n_modes": 1,
        "name": "default_eigenmode_setup",
        "pct_refinement": 30,
        "reuse_selected_design": True,
        "reuse_setup": True,
        "vars": {"Cj": "0fF", "Lj": "0nH"},
    }
}

Three Methods to Configure Ansys Eigenmode Simulations

SQuADDS offers three distinct approaches to customize eigenmode analysis parameters, each suited to different workflow requirements and persistence needs.

Modifying Default Options Directly

For permanent project-wide changes, edit the self.default_eigenmode_options dictionary inside the AnsysSimulator.__init__ method in squadds/simulations/ansys_simulator.py. This approach affects all subsequent simulator instances created from that modified class, making it suitable for institutional standards or repeated design templates.

Passing Custom emode_setup Dictionaries

For one-off simulations requiring unique configurations without altering the class defaults, pass a custom dictionary to the emode_setup argument of sweep() or sweep_qubit_cavity(). When emode_setup is provided, the simulator uses these values exclusively for that execution and falls back to default_eigenmode_options only when the parameter is None.

Using update_simulation_setup()

Call sim.update_simulation_setup() to modify the stored device dictionary in-place for the lifetime of the simulator instance. Specify target="generic" for single-system simulations or target="qubit" for coupled qubit-cavity systems to update the respective configuration blocks (setup_qubit, setup_cavity_claw, etc.).

Key Parameters for Superconducting Qubit Designs

When you configure Ansys eigenmode simulation settings for superconducting qubit designs in SQuADDS, these parameters require careful tuning to balance accuracy and computational efficiency:

• basis_order: Controls finite element basis function order. Increase to 2 or 3 for higher accuracy in regions with high electric field gradients, though this significantly increases memory usage and solve time.
• max_passes: Maximum adaptive mesh refinement iterations. Increase to 50 or 60 for complex geometries with tight coupling between qubit and resonator elements.
• min_freq_ghz: Lower frequency bound for mode searching. Set to 4 or 5 to exclude irrelevant low-frequency modes and accelerate convergence for typical transmon frequencies (4–8 GHz).
• n_modes: Number of eigenmodes to extract. Use 3 to 5 to capture the fundamental qubit mode and higher harmonics necessary for multi-mode Hamiltonian analysis.
• vars: Dictionary defining Josephson junction parameters. Override Cj (junction capacitance) and Lj (junction inductance) to match your specific qubit design values, such as {"Cj": "1fF", "Lj": "10nH"}.

Practical Configuration Examples

The following examples demonstrate how to implement each configuration method using the SQuADDS API with actual code patterns from the repository.

Example 1: Custom Eigenmode Setup for Parameter Sweeps

Override default settings for a specific sweep by passing a custom emode_setup dictionary to the sweep() method:

from squadds.simulations.ansys_simulator import AnsysSimulator

# Initialize simulator with existing analyzer and design options

sim = AnsysSimulator(analyzer, design_options)

# Define custom eigenmode configuration for high-accuracy single-mode analysis

custom_emode = {
    "setup": {
        "basis_order": 2,
        "max_passes": 45,
        "n_modes": 3,
        "min_freq_ghz": 4.0,
        "vars": {"Cj": "1fF", "Lj": "10nH"},
    }
}

# Execute parameter sweep with custom eigenmode settings

sim.sweep(
    sweep_dict={"gap": [0.2, 0.3, 0.4]},
    emode_setup=custom_emode
)

Example 2: Persistent Configuration with update_simulation_setup()

Update the simulator's stored configuration to affect all subsequent operations without modifying the class source code:

# Modify the generic setup for single-system simulations

sim.update_simulation_setup(
    target="generic",
    max_passes=60,
    n_modes=5,
    min_freq_ghz=3.5,
    vars={"Cj": "0.8fF", "Lj": "12nH"}
)

# Subsequent sweeps automatically use updated parameters

sim.sweep(sweep_dict={"pad_width": [10, 12, 14]})

Example 3: Configuring Coupled Qubit-Cavity Systems

For QubitCavity systems containing both qubit and resonator components, configure specific sub-setups using sweep_qubit_cavity():

# Device dictionary containing separate setups for qubit and cavity

device = {
    "setup_qubit": {...},
    "setup_cavity_claw": {...}
}

# High-accuracy eigenmode settings for coupled system analysis

my_eigenmode = {
    "setup": {
        "basis_order": 3,
        "max_passes": 70,
        "n_modes": 4,
        "min_freq_ghz": 5.0,
    }
}

# Execute coupled simulation with custom settings

sim.sweep_qubit_cavity(
    device_dict=device,
    emode_setup=my_eigenmode,
    lom_setup=None  # Use default lumped oscillator model settings

)

Summary

• The AnsysSimulator class in squadds/simulations/ansys_simulator.py manages all Ansys eigenmode configurations through the default_eigenmode_options dictionary.
• Custom emode_setup dictionaries passed to sweep() or sweep_qubit_cavity() provide temporary configuration overrides for individual simulations without affecting global defaults.
• The update_simulation_setup() method enables persistent configuration changes for the simulator instance lifetime, supporting both target="generic" for single systems and target="qubit" for coupled architectures.
• Critical parameters for superconducting qubit accuracy include basis_order (finite element order), max_passes (mesh refinement depth), and vars (Josephson junction capacitance and inductance).

Frequently Asked Questions

What is the default eigenmode setup in SQuADDS?

The default configuration resides in self.default_eigenmode_options within the AnsysSimulator.__init__ method, specifying conservative values including basis_order: 1, max_passes: 30, n_modes: 1, and zeroed Josephson junction variables (Cj: "0fF", Lj: "0nH"). These defaults prioritize fast execution over accuracy and should be customized for precise quantum device simulation.

How do I change the number of eigenmodes extracted in Ansys HFSS?

Modify the n_modes parameter in your eigenmode setup dictionary. Set "n_modes": 5 to extract the fundamental mode and four higher harmonics for multi-mode analysis. Pass this configuration via the emode_setup parameter to sweep(), or update it permanently using update_simulation_setup(target="generic", n_modes=5).

Can I configure different settings for qubit and cavity simulations?

Yes. When working with coupled systems, use update_simulation_setup() with target="qubit" or target="cavity_claw" to modify the respective sub-setup dictionaries (setup_qubit or setup_cavity_claw). This allows independent configuration of mesh density and convergence criteria for each component in a QubitCavity system.

Where are the Ansys simulator configurations stored in the codebase?

All eigenmode simulation logic, default parameters, and configuration methods are defined in squadds/simulations/ansys_simulator.py. The AnsysSimulator class contains the default_eigenmode_options dictionary and the primary interface methods including sweep(), sweep_qubit_cavity(), and update_simulation_setup().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}