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

> Learn how to configure Ansys eigenmode simulation settings for superconducting qubit designs in SQuADDS using default options custom parameters or persistent setup updates

- Repository: [Levenson-Falk Lab/squadds](https://github.com/lfl-lab/squadds)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/squadds/simulations/ansys_simulator.py), the default eigenmode configuration dictionary structure is:

```python
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`](https://github.com/lfl-lab/squadds/blob/main/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:

```python
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:

```python

# 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()`:

```python

# 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`](https://github.com/lfl-lab/squadds/blob/main/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`](https://github.com/lfl-lab/squadds/blob/main/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()`.