Installation

This guide will help you install the qdesignoptimizer package and its dependencies on your system.

Prerequisites

  • Python 3.11 or 3.12 (required)

  • pip or poetry package manager. We recommend creating a virtual environment by following the steps below.

  • Git (for installation from repository)

  • Ansys HFSS. qdesignoptimizer has been tested with Ansys Electronics Desktop 2021 R2 and 2022 R2.

Installation with pip

The simplest way to install qdesignoptimizer is via the Python package manager pip:

pip install qdesignoptimizer
pip install --no-deps "quantum-metal>=0.8.1,<0.9"

Note that Quantum Metal (formerly Qiskit Metal) must be installed separately and without dependencies to make it work properly. The package uses PySide6 (version 6.10.x) for the GUI interface. Note that the full installation has been tested with quantum-metal 0.8.1 and PySide6 6.10.2.

Quantum Metal versions below 0.8.1 are not supported: they contain a Qt bug that crashes the GUI (and, in Jupyter, the whole kernel) on MetalGUI(design). PySide6 6.11 is excluded for the same reason.

Installation from GitHub Repository

For the latest version or if you want to contribute to development, you can directly clone and install from the GitHub repository.

Cloning the Repository

First, clone the repository and navigate to its directory:

git clone https://github.com/202Q-lab/QDesignOptimizer
cd QDesignOptimizer

Creating a Virtual Environment

It is strongly recommended to install the project in a separate virtual environment using our installation guide. You have several options:

Option 1: Using Poetry (Recommended)

This project is packaged with poetry, which handles the environment setup for you.

Option 2: Using Conda

Create the environment from the provided environment.yml file:

conda env create -f environment.yml
conda activate qdesignenv

Note that the C++ developer tools from the latest distribution of Visual Studio Installer are required for the successful installation of PySide6, which is part of the the environment.yml file. You can download the software from microsoft.

Option 3: Using venv

Create and activate a virtual environment using Python’s built-in venv module:

# Create new virtual environment
python3.12 -m venv qdesignenv

# Activate the environment
# On Linux/MacOS:
source qdesignenv/bin/activate
# On Windows:
qdesignenv\Scripts\activate

# Verify Python version
python --version

# Install poetry if not already available
pip install poetry

User Installation

For regular users, install the project with its dependencies and Quantum Metal:

poetry install
pip install --no-deps "quantum-metal>=0.8.1,<0.9"

Developer Installation

For developers who want to contribute to the project, install with additional development dependencies:

poetry install --with docs,analysis
pip install --no-deps "quantum-metal>=0.8.1,<0.9"
pre-commit install

This will install:

  • All project dependencies

  • Documentation tools

  • Analysis and testing tools

  • Pre-commit hooks for code quality

Building Documentation

To build the documentation yourself:

  1. Install pandoc (you may need to restart your computer to correctly set the path variables).

  2. Run the following command:

poetry run sphinx-build -b html docs/source docs/_build/html

Troubleshooting

Common Issues:

  • Python Version Mismatch: Ensure you’re using Python 3.11 or 3.12

  • Dependency Conflicts: If you encounter dependency conflicts, try installing in a fresh virtual environment

  • Ansys Connection Issues: Make sure Ansys HFSS is correctly installed and licensed

  • GUI crashes / “the kernel appears to have died” on MetalGUI(design): upgrade to quantum-metal>=0.8.1, which contains the upstream fix. If the machine is already in a poisoned state, the persisted Qt window layout has to be cleared once – either set QISKIT_METAL_RESET_UI_SETTINGS=1 before launching, or delete the registry key HKCU\Software\QiskitMetal\MainWindow. Useful further diagnostics: QISKIT_METAL_DEBUG_INIT=1 traces each GUI init step, and QISKIT_METAL_QT_HARDWARE_GL=1 opts out of the software-OpenGL default that Quantum Metal applies on Windows.

Migration from qiskit-metal to quantum-metal

If you have an existing QDesignOptimizer installation with qiskit-metal, follow these steps to migrate:

Delete your existing environment and recreate it to ensure all dependencies are correctly installed:

# Deactivate and remove the old environment
# If using conda:
conda deactivate
conda env remove -n qdesignenv

# If using venv:
deactivate
rm -rf qdesignenv  # On Windows: rmdir /s qdesignenv

Then follow the installation instructions above to create a fresh environment.

Note: quantum-metal v0.5+ uses PySide6 instead of PySide2. The import paths remain qiskit_metal for backward compatibility.

For more help, please open an issue on the GitHub repository.