Metadata-Version: 2.4
Name: quvis
Version: 0.35.0
Summary: Quvis - Quantum Circuit Visualization System
Author: Alejandro Gonzalvo Hidalgo
Author-email: alejandro@gonzalvo.org
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: fastapi (>=0.115.0,<0.116.0)
Requires-Dist: ipykernel (>=6.29.5,<7.0.0)
Requires-Dist: numpy (>=1.24.0,<2.0.0)
Requires-Dist: pillow (>=11.3.0,<12.0.0)
Requires-Dist: pydantic (>=2.10.0,<3.0.0)
Requires-Dist: qiskit (>=2.1.0,<3.0.0)
Requires-Dist: uvicorn[standard] (>=0.32.0,<0.33.0)
Description-Content-Type: text/markdown

[![PyPI version](https://img.shields.io/pypi/v/quvis.svg)](https://pypi.org/project/quvis/)
[![Python Version](https://img.shields.io/pypi/pyversions/quvis)](https://pypi.org/project/quvis/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy-lang.org/)

# Quvis - Quantum Circuit Visualization Platform

Quvis is a 3D quantum circuit visualization platform for logical and compiled circuits.

## 🚀 Quick Start

### Interactive Playground (Web App)

Run the interactive web playground locally:

```bash
git clone https://github.com/alejandrogonzalvo/quvis.git
cd quvis
pip install poetry
poetry install
npm install

./scripts/start-dev.sh
```

Open http://localhost:5173 in your browser.

## Installation

### Option 1: Install from PyPI (Recommended)

```bash
pip install quvis
```

### Option 2: Install from Source (Development)

```bash
git clone https://github.com/your-repo/quvis.git
cd quvis
poetry install
```

### Prerequisites

- Python 3.12+
- Node.js 16+ (for web interface)
- npm or yarn (for frontend dependencies)

### Running Examples

After installation, you can run the examples directly:

```bash
python examples/library_usage.py
```

## **Usage**

### Basic Usage

```python
from quvis import Visualizer
from qiskit import QuantumCircuit

# Create visualizer
quvis = Visualizer()

# Add any quantum circuit
circuit = QuantumCircuit(4)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)

# Add and visualize - opens your browser with interactive 3D view!
quvis.add_circuit(circuit, algorithm_name="Bell State Chain")
quvis.visualize()
```

### Multi-Circuit Comparison

```python
from quvis import Visualizer
from qiskit.circuit.library import QFT
from qiskit import transpile

quvis = Visualizer()

# Add logical circuit
logical_qft = QFT(4)
quvis.add_circuit(logical_qft, algorithm_name="QFT (Logical)")

# Add compiled circuit with hardware constraints
coupling_map = [[0, 1], [1, 2], [2, 3]]
compiled_qft = transpile(logical_qft, coupling_map=coupling_map, optimization_level=2)
quvis.add_circuit(
    compiled_qft,
    coupling_map={"coupling_map": coupling_map, "num_qubits": 4, "topology_type": "line"},
    algorithm_name="QFT (Compiled)"
)

# Visualize both circuits with tabs - logical (green) vs compiled (orange)
quvis.visualize()
```

## 🏗️ **Architecture & Layout Generation**

Quvis employs a sophisticated Force-Directed layout engine powered by `d3-force-3d`. Key highlights include:
- **Planar Anchoring**: Automatic 2D vs 3D detection to prevent non-physical geometric buckling (Z-folding) of intrinsically flat architectures like heavy-hex grids.
- **Peripheral Cushioning**: Implements isolated `.distanceMax()` repulsion bounds to alleviate edge compression frequently seen in large monolithic node graphs.
- **Multilevel Rigidity**: To cleanly render large distributed quantum processing units (multi-core architecture), the visualizer calculates individual processor cores dynamically, converts them to mathematical rigid bodies, and dynamically calculates the optimal SE(3) rotation matrices (`THREE.Quaternion`) to align communication links without causing internal topological warping.

For deep technical details on the visualization layout, refer to the [LayoutManager README](quvis/web/src/scene/core/README.md).

## 🤝 **Contributing**

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 📄 **License**

This project is licensed under the MIT License.

