Installation

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

Prerequisites

  • Python 3.10 (required)

  • pip or poetry package manager

  • Git (for installation from repository)

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

Installation with pip

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

pip install qdesignoptimizer
pip install --no-deps qiskit-metal==0.1.5

Note that at the moment Qiskit Metal must be installed separately and without dependencies to make it work properly.

Installation from GitHub Repository

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

Clone the Repository

First, clone the repository and navigate to its directory:

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

Create a Virtual Environment

It is strongly recommended to install the project in a separate virtual environment using Python 3.10. 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

Option 3: Using venv

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

# Create new virtual environment
python3.10 -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 Qiskit Metal:

poetry install
pip install --no-deps qiskit-metal==0.1.5

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 qiskit-metal==0.1.5
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 set path variables correctly)

  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.10

  • 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

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