Quantum Metal Documentation

Quantum Metal is an open-source chip-design layer for superconducting quantum hardware. It is a Python library designed to build chips from QComponents, attach analyses, and export results to various solvers, fabrication tools, or orchestrators.

Key Characteristics:

• Solver-agnostic: The core library does not depend on a specific solver; instead, it uses renderers as integration layers for tools like GDS, HFSS, Q3D, gmsh, Elmer, and AWS Palace.
• Lite-by-default: The base installation is minimal and dependency-light. It does not assume the presence of heavy dependencies like Qt, AEDT, gmsh, or Palace. These are treated as opt-in extras.
• Orchestration-friendly: Designed for use in AI-driven design loops (e.g., LLMs or optimization agents). The API is intended to be predictable, scriptable, and minimal, avoiding GUI prompts or hidden states.

Quantum Metal is researching an open Finite Element Method (FEM) stack to provide an alternative to the Ansys HFSS/Q3D bridge, which requires an AEDT license. The goal is to enable HFSS-free CI validation and provide academic users with a free path to full-field analysis.

The stack components include:

• gmsh: A mesher (renderer_gmsh/) used for mesh generation and boundary tagging.
• Elmer: An eigenmode solver (renderer_elmer/) for electromagnetic analysis.
• AWS Palace: An open-source Maxwell solver supporting eigenmode, driven, and electrostatic analysis. A renderer_palace/ module is planned to follow the QRendererAnalysis protocol.
• OpenEMS: A lightweight FEM option that is easier to build than Palace but has more limited capabilities.

To create a custom component for the QLibrary, you must extend the base qlibrary component and override specific attributes and the make method.

Required Attributes:

• default_options: Default drawing options.
• component_metadata: Metadata associated with the component.
• options: A dictionary containing the component-designer-defined options.

Required Method:

• make(): This method implements the logic to generate geometry (such as polygons or paths) from the self.options dictionary. It must add these geometries to the design using self.add_qgeometry(...), ensuring necessary metadata like layer or subtract are included.

Quantum Metal supports a 'lite-by-default' mode that allows it to run in environments without a GUI (like Google Colab, Binder, or CI/CD pipelines).

When running in these environments, the qm.gui(design) factory automatically detects the environment and uses MetalGUIHeadless to render designs as inline matplotlib figures instead of attempting to open a Qt/PySide6 window.

You can explicitly force headless mode by setting the environment variable: QISKIT_METAL_HEADLESS=1

export QISKIT_METAL_HEADLESS=1

The project is rebranding from Qiskit Metal to Quantum Metal.

Key changes:

• Package Name: The PyPI package is now quantum-metal. The old qiskit-metal package remains archived at its pre-v0.5 state.
• Import Path: The Python import path is planned to change from qiskit_metal to quantum_metal. Currently, import qiskit_metal works but emits a FutureWarning.
• Installation: v0.7.0+ defaults to a 'Lite' installation strategy.

The qm.gui(design) function returns a MetalGui object, which is a subclass of ipywidgets.VBox.

API Design Note:

• The widget is the API. Because it inherits from VBox, you can use display(gui) directly in Jupyter to render the interface.
• The object provides high-level methods for interaction, such as .select(), .refresh(), and .close().
• Users should interact with these methods rather than attempting to manipulate the underlying widget tree directly.

When extending the base QRenderer to support a new external tool, you must implement the following interface:

Required Attributes:

• name: The name of the renderer.
• element_extensions: A dictionary for element extensions.
• element_table_data: Data used for the element table.

Required Methods:

• render_chips(): Renders all chips in the design by calling render_chip for each.
• render_chip(chip): Renders a specific chip.
• render_components(selection=None): Renders all components, or a specific selection if provided.
• render_component(component): Renders a specific component.
• render_element(element): Renders a specific element.
• render_element_path(path): Renders an element path.
• render_element_poly(poly): Renders an element polygon.

Quantum Metal provides three distinct ways to view designs, depending on your environment and installation:

Choose qm.gui if you are working in a web-based notebook environment where you cannot run a Qt-based desktop application.