psiqdk-visualize 0.97.2

Jupyter widget for rendering Circuit and QRE files

🧩 Jupyter Widgets for Viewing Circuit and QRE Files

This module creates Jupyter widgets that provide an interactive interface for visualizing quantum circuit and QRE files within notebooks.

---

✨ Features

• 📊 Interactive visualization of circuit and QRE files
• 🧪 Seamless integration with Jupyter notebooks
• 🌐 Modern frontend built with anywidget

---

📦 Installation

Install the widget using the provided .whl package:

pip install build_artifacts/construct_tools-0.1.1-py3-none-any.whl

---

🚀 Usage

To use the widget in a Jupyter notebook:

# Load construct_tools package
# See `yarn jup:install` below for installing the package.
from construct_tools import CallGraph, FlameGraph, Circuit

# Load and display a QRE file as a CallGraph from a local file.
CallGraph(src="myfile.qre-analysis")

# Display a specific FlameGraph from a local file.
FlameGraph(src="myfile.qre-analysis", graph="toffs")

# Load and display a Circuit design file from a public URL.
Circuit(src="https://path/to/myfile.circuit")

Replace "myfile....circuit" or "myfile....qre-analysis" with the path to your circuit or QRE data file.

Development

Widget Overview

• We encapsulate part of the construct-app UI into a [PsiConstruct Web Component] (https://developer.mozilla.org/en-US/docs/Web/API/Web_components).
  • This lets us e.g. visualize a Circuit or QRE by creating a single HTML element, e.g.
    <psi-construct runtime="jupyter" data="...json-data...">
• The Jupyter widget works by:
  • Installing the psi-construct.js script within the Jupyter environment.
  • Using the anywidget framework to wrap the web component as CallGraph, FlameGraph and Circuit widget classes.
• Within the Jupyter notebook:
  • The user imports construct-tools
  • They create instances of e.g. CallGraph() widgets, passing a src parameter as a local file path or https url.

📁 Project Structure

jupyter-widget/
├── construct_tools/              # Python package (installed by pip)
│   ├── __init__.py               - Public API: Circuit, CallGraph, FlameGraph
│   ├── psi_construct_widget.py   - Widget class definitions
│   └── psi-construct.js          - Web component (copied from construct-app at build time)
├── demo/
│   └── demo.ipynb                - Interactive demo notebook
├── build_artifacts/              # Wheel output from local builds (gitignored)
├── scripts/                      # Build helpers (e.g. namespace pyproject generator)
├── requirements.txt              # Dev / build dependencies
├── pyproject.toml                # Package metadata and dependencies
└── README.md                     # (this file)

Virtual Environments

All of the commands below assume that you are within a python virtual environment.

• Create the virtual env: mkvirtualenv jupyter-widget
• Enter an existing env: workon jupyter-widget
• Exit the current virtual env: deactivate

Building the Widget Locally

• Clone the repo locally:
  git clone [e-mail]:applications/construct/construct-tools.git
• Set up a virtual environment for development.
• Use the following yarn commands for building and testing the jupyter widget.

Command	Description
yarn jup:update	Build widget and install within current virtualenv.
yarn jup:build-widget	Build widget (without installing).
yarn jup:install	Install widget within current virtualenv (without building). This lets you use it within a local Jupyter notebook or VSCode.
yarn webc:update	Build <psi-construct> web component and install in this project. - Only necessary if construct-app code has changed. - Run webc:update BEFORE jup:update if the construct-app code has changed.
yarn jup:notebook	Run the demo notebook in jupyter, within the current virtualenv. - Make sure you are in the proper virtualenv before running this. - Choose the "Python 3 (ipykernel)" kernel if necessary.

Look at the scripts in package.json to figure out the details or see sub-commands which can be used for more precise development.

Testing the widget

• You must build the widget locally before you can test.
• NOTE: Make sure you are running within a virtual environment before doing the following.

Environment	Description
Jupyter Notebook	Run yarn jup:notebook to open the demo in a Jupyter Notebook on your machine. • Choose the Python 3 (ipykernel) kernel when prompted. • NOTE: You must reload the web page (e.g. cmd-R) to see changes if the javascript web component file changes.
VSCode	Open the file demo/demo.ipynb in VSCode to view it. • Choose the Python 3 (ipykernel) kernel with the appropriate virtualenv when prompted. • NOTE: You must reload the VSCode Window to see changes if the javascript web component changes. (e.g. View => Command Palette then Developer: Reload Window)

---

🧪 Notes

• For development:
  • Make sure you are working within a python virtual environment.
  • Ensure python tools setuptools, wheel, and build are installed.
  • Ensure node and yarn are installed.
• If things are not working, try a different Jupyter environment.
  It is remotely possible that your Jupyter environment does not support anywidget.

---

📄 License

© 2026 PsiQuantum Corp. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, transfer, or reproduction of the contents of this project, via any medium, is strictly prohibited.