How to Configure the Palace Electromagnetic Simulator for Resonator Eigenmode Analysis in SQuADDS

To configure Palace for resonator eigenmode analysis in SQuADDS, create a Python dictionary with "simulator": "palace" and "solution_type": "eigenmode", then pass it to the run_eigenmode dispatcher in squadds/simulations/objects.py, which automatically handles JSON translation and launches the external Palace process.

SQuADDS (Superconducting Quantum Device Design System) provides a unified simulation framework that treats electromagnetic solvers as interchangeable plugins. When you need to compute resonator eigenfrequencies, you can configure the Palace electromagnetic simulator as your backend by constructing a structured options dictionary that the framework translates into Palace-compatible input files.

Understanding the Palace Plugin Architecture

SQuADDS abstracts electromagnetic solvers through a common interface defined in squadds/simulations/simulator.py. The base Simulator class establishes the contract that each backend must satisfy, keeping the core UI code agnostic of specific solver implementations. When you select Palace, the system delegates to the PalaceSimulator class in squadds/simulations/ansys_simulator.py, which handles the conversion of Python dictionaries into the JSON input files that Palace requires. The default Palace eigenmode template is defined around line 52 of this file, providing baseline settings for resonator analysis.

Creating Palace Eigenmode Configuration Options

The configuration for a resonator eigenmode analysis centers on a Python dictionary containing Palace-specific keywords. This dictionary informs the generic dispatcher which backend to invoke and how to parameterize the finite element analysis.

Required Parameters

• simulator: Must be set to "palace" to trigger the Palace backend.
• solution_type: Set to "eigenmode" for resonator frequency analysis.
• frequency_range: A list defining the target sweep range in GHz (e.g., [4.0, 6.0]).
• max_modes: Integer specifying the number of eigenfrequencies to compute (e.g., 5).

Optional Geometry and Mesh Settings

• mesh_order: Polynomial order for finite elements (typically 1 or 2 for higher accuracy).
• boundary_conditions: Wall specifications such as "pec" (perfect electric conductor).
• output_dir: Directory path where Palace writes raw simulation files.

palace_eigenmode_options = {
    "simulator": "palace",
    "solution_type": "eigenmode",
    "frequency_range": [4.0, 6.0],
    "max_modes": 5,
    "mesh_order": 2,
    "boundary_conditions": "pec",
    "output_dir": "palace_output",
}

Running the Eigenmode Simulation

Once your options dictionary is defined, you invoke the simulation through the generic dispatcher. The run_eigenmode function in squadds/simulations/objects.py (defined at line 283) automatically routes the call to the Palace backend when it detects "simulator": "palace" in your configuration.

from squadds.simulations.objects import run_eigenmode

# design: SQuADDS Design object

# geometry_dict: Resonator geometry specification

eigenmode_df, eigenmode_obj = run_eigenmode(
    design,
    geometry_dict,
    palace_eigenmode_options,
    generate_plots=True,  # Optional: auto-generate mode shape visualizations

)

The function returns a tuple containing a Pandas DataFrame with eigenfrequencies and mode data, plus a simulation object for further programmatic analysis. Palace executes as an external process, with the SQuADDS wrapper monitoring execution status and parsing results upon completion.

Installation Prerequisites

Before executing simulations, you must install the Palace binary on your Linux, macOS, or Windows system and ensure it is available in your system PATH. The SQuADDS repository provides detailed installation guidance in docs/source/resources/palace.rst. Without the external palace binary, the run_eigenmode dispatcher will fail to spawn the subprocess.

End-to-End Tutorial Resources

For a complete working example that progresses from design creation through eigenmode visualization, consult the Jupyter notebook Tutorial-7_Simulate_designs_with_palace.ipynb in the repository's documentation folder. This tutorial demonstrates practical usage of the configuration dictionary, execution monitoring, and post-processing of eigenmode results. You can also reference the actual source at squadds/simulations/ansys_simulator.py to inspect the default eigenmode option template used when instantiating Palace simulations.

Summary

• SQuADDS uses a plugin architecture where Palace operates through the PalaceSimulator class, isolating solver-specific logic from the core framework.
• Configuration requires a Python dictionary with specific keys including "simulator": "palace", "solution_type": "eigenmode", and target frequency ranges.
• The run_eigenmode function in squadds/simulations/objects.py handles automatic dispatching and returns structured results as a Pandas DataFrame.
• Palace requires external binary installation and runs as a subprocess, with SQuADDS managing the JSON input generation and output parsing automatically.

Frequently Asked Questions

What is the minimum required configuration to run a Palace eigenmode simulation?

You must provide a dictionary containing "simulator": "palace", "solution_type": "eigenmode", a frequency_range list defining the GHz region of interest, and an integer max_modes specifying how many eigenfrequencies to compute. While the system provides defaults for mesh order and boundary conditions, these four parameters are essential for the dispatcher to route your job to Palace and configure the analysis scope.

How do I switch between Palace and Ansys HFSS for the same resonator design?

The run_eigenmode dispatcher in squadds/simulations/objects.py is backend-agnostic. You only need to change the "simulator" value from "palace" to "ansys" and adjust the option keys to match HFSS-specific requirements. Your SQuADDS Design object and geometry dictionary remain identical, allowing seamless comparison between electromagnetic solvers without modifying your design logic.

Where does SQuADDS store the raw Palace simulation files?

Palace writes output files to the directory specified in the output_dir configuration key of your options dictionary. While the run_eigenmode function automatically captures and parses these results into a returned DataFrame, the original Palace JSON inputs and field solution files remain available in the specified directory for external post-processing or manual inspection.

How does SQuADDS convert Python dictionaries into Palace input files?

The PalaceSimulator class in squadds/simulations/ansys_simulator.py implements a translation layer that maps dictionary keys—such as mesh_order, frequency_range, and boundary_conditions—into the JSON schema that Palace expects. This abstraction allows you to work with native Python data structures while the backend handles solver-specific file formatting and validation.

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