TopQAD™ SDK by 1QBit®

The TopQAD™ SDK by 1QBit® is a Python software development kit for the TopQAD automated quantum design platform, used to design fault-tolerant quantum computers and quantum processors. With it you can estimate the resources a quantum algorithm needs, compile quantum circuits, and benchmark fault-tolerant quantum computing protocols under realistic hardware noise.

The TopQAD SDK is developed and owned by 1QBit (1QB Information Technologies Inc.).

The code in this repository is intended to make access to the TopQAD platform as easy as writing Python!
This guide provides everything you need to set up your local development environment, run the demo script, and understand the core features of the SDK.

1. Development Setup

Follow these steps to set up a local environment for developing and testing the SDK.

a. Create and Activate a Virtual Environment

This creates an isolated Python environment for the project.

Open your terminal and navigate to the root directory of this project.

Create the virtual environment:
python3 -m venv .venv

Activate the environment:
macOS / Linux:
source .venv/bin/activate
Windows:
.\.venv\Scripts\activate

Your terminal prompt should now begin with (.venv).

Update pip:
python -m pip install -U pip

b. Install the Package in Editable Mode

This project uses pyproject.toml to manage dependencies. The following command will install the SDK in editable mode (-e) along with all development dependencies. This means any changes you make to the source code are immediately reflected in your environment.

pip install -e .

c. Get Your Refresh Token (Required for Authentication)

To use the SDK, you need a TOPQAD_REFRESH_TOKEN from the TopQAD portal.

1. Visit: https://portal.topqad.1qbit-dev.com/
2. Go through the registration process and log in.
3. Click your profile picture in the top right.
4. Select "Get refresh token".
5. Copy the token shown.

⚠️ Security Note: Your refresh token is as sensitive as a password. Keep it safe and never commit it to source control.

Set the environment variable in your shell or put it in .env file in root:
macOS / Linux:
export TOPQAD_REFRESH_TOKEN="<PASTE_YOUR_TOKEN_HERE>"
Windows:
set TOPQAD_REFRESH_TOKEN="<PASTE_YOUR_TOKEN_HERE>"

d. Verify the Installation

Run the following to check that the topqad-sdk package is installed, see its version, and confirm the installation path:

pip show topqad-sdk

2. Running the Interactive Demo

To see the SDK in action, we have prepared an interactive Jupyter Notebook that demonstrates the core functionality of the Noise Profiler.

To run the demo, open and run the notebook located at:

Noise_Profiler_Demo.ipynb

This notebook will guide you through setting your authentication token and running a simulation.

3. Logging Setup

The SDK supports two ways to configure logging:

1. Using the TOPQAD_LOG_LEVEL Environment Variable: Set the desired logging level (e.g., INFO, DEBUG, WARNING) in your environment:

   export TOPQAD_LOG_LEVEL=DEBUG
   

2. Programmatically in Your Code: You can configure the logging level directly in your Python script:

   import logging
   logging.getLogger("topqad_sdk").setLevel(logging.DEBUG)
   

By default, logging is disabled unless explicitly configured using one of the above methods.

SDK Documentation

The SDK documentation contains API references, guides, and examples for interacting with the SDK.

From the project root, run:

cd docs
make html

Once the build completes, open the generated homepage in your browser:

open _build/html/index.html

License and Trademarks

© 2025–2026 1QB Information Technologies Inc.

This project is licensed under the Apache 2.0 License. See NOTICE for attribution notices.

1QBit is a registered trademark of 1QB Information Technologies Inc. in Canada and the United States. The 1QBit logo, Q design and TopQAD are trademarks of 1QB Information Technologies Inc. The Apache 2.0 License does not grant permission to use these trademarks (see Section 6 of the License).