Metadata-Version: 2.4
Name: psiqdk-visualize
Version: 0.97.2
Summary: Jupyter widget for rendering Circuit and QRE files
Author-email: PsiQuantum <construct@psiquantum.com>
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
Requires-Dist: anywidget>=0.9.0
Requires-Dist: requests>=2.32.3
Requires-Dist: pyyaml>=6.0

# 🧩 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`](https://anywidget.dev/)

---

## 📦 Installation

Install the widget using the provided `.whl` package:

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

---

## 🚀 Usage

To use the widget in a Jupyter notebook:

```python
# 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.

<br>

# 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. <br>`<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](#-usage):
  - 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](https://virtualenv.pypa.io/en/latest/).

- 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: <br> `git clone git@gitlab.psiquantum.com:applications/construct/construct-tools.git`
- Set up a [virtual environment](#virtual-environments) for development.
- Use the following `yarn` commands for building and testing the jupyter widget.

| Command                               | Description                                                                                                                                                                                                                                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <nobr>`yarn jup:update`</nobr>        | Build widget and install within current virtualenv.                                                                                                                                                                                                  |
| <nobr>`yarn jup:build-widget`</nobr>  | Build widget (without installing).                                                                                                                                                                                                                   |
| <nobr>`yarn jup:install`</nobr>       | Install widget within current virtualenv (without building). <br> This lets you use it within a local Jupyter notebook or VSCode.                                                                                                                    |
| <nobr>`yarn webc:update`</nobr>       | <details><summary>Build `<psi-construct>` web component and install in this project. </summary>- Only necessary if `construct-app` code has changed. <br>- Run `webc:update` BEFORE `jup:update` if the `construct-app` code has changed. </details> |
| <nobr>`yarn jup:notebook`</nobr>      | <details><summary>Run the demo notebook in jupyter, within the current virtualenv.</summary>- Make sure you are in the proper virtualenv before running this.<br>- 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](#building-the-widget-locally) before you can test.
- **NOTE**: Make sure you are running within a [virtual environment](#virtual-environments) before doing the following.

| Environment                   | Description                                                                                                                                                                                                                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <nobr>Jupyter Notebook</nobr> | Run `yarn jup:notebook` to open the demo in a Jupyter Notebook on your machine. <br> • Choose the `Python 3 (ipykernel)` kernel when prompted.<br>• **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. <br> • Choose the `Python 3 (ipykernel)` kernel with the appropriate virtualenv when prompted.<br>• **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](#virtual-environments).
  - 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. <br>It is remotely possible that your [Jupyter environment does not support `anywidget`](https://www.google.com/search?q=are+there+jupyter+environments+that+do+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.
