qcanvas-sdk 1.0.2__tar.gz

qcanvas_sdk-1.0.2/LICENSE

@@ -0,0 +1,53 @@
+Open Quantum Workbench Proprietary License
+==========================================
+
+Copyright (c) 2025 Open Quantum Workbench.
+All rights reserved.
+
+1. Grant of Limited Rights
+--------------------------
+Open Quantum Workbench (“Licensor”) grants you a non-transferable,
+non-exclusive, revocable license to install and use this repository
+(“Software”) solely for personal evaluation, academic review, or internal
+research. Any other use is strictly prohibited.
+
+2. Prohibited Activities
+------------------------
+You may NOT, under any circumstance, do any of the following:
+
+- Copy, reproduce, or redistribute the Software or any derivative work.
+- Modify, fork, translate, adapt, or otherwise create derivative works.
+- Sell, sublicense, rent, lease, lend, or otherwise commercialize the Software.
+- Use the Software to build competing products or services.
+- Remove, obscure, or alter any proprietary notices.
+
+3. Ownership
+------------
+The Software is licensed, not sold. All rights, title, and interest—including
+all intellectual property rights—remain exclusively with Open Quantum Workbench
+and its contributors.
+
+4. Termination
+--------------
+Licensor reserves the right to terminate this license at any time. Upon
+termination you must cease all use, destroy all copies, and certify
+destruction to Licensor.
+
+5. Disclaimer of Warranty
+-------------------------
+THE SOFTWARE IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, WHETHER EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+6. Limitation of Liability
+--------------------------
+IN NO EVENT SHALL OPEN QUANTUM WORKBENCH OR ITS CONTRIBUTORS BE LIABLE FOR ANY
+CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.
+
+7. Acceptance
+-------------
+By accessing or using the Software, you acknowledge that you have read,
+understood, and agree to be bound by the terms of this license. If you do not
+agree, do not use the Software.

qcanvas_sdk-1.0.2/PKG-INFO

@@ -0,0 +1,468 @@
+Metadata-Version: 2.4
+Name: qcanvas-sdk
+Version: 1.0.2
+Summary: A package for compiling quantum circuit code from Cirq, Qiskit, and PennyLane to OpenQASM 3.0.
+Author: QCanvas Team
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: antlr4-python3-runtime>=4.13.2
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: cirq
+Requires-Dist: cirq>=1.5.0; extra == "cirq"
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=2.1.2; extra == "qiskit"
+Requires-Dist: qiskit-aer>=0.17.2; extra == "qiskit"
+Provides-Extra: pennylane
+Requires-Dist: pennylane>=0.42.3; extra == "pennylane"
+Requires-Dist: pennylane-lightning>=0.42.0; extra == "pennylane"
+Provides-Extra: qsim
+Requires-Dist: qsim; extra == "qsim"
+Provides-Extra: all
+Requires-Dist: cirq>=1.5.0; extra == "all"
+Requires-Dist: qiskit>=2.1.2; extra == "all"
+Requires-Dist: qiskit-aer>=0.17.2; extra == "all"
+Requires-Dist: pennylane>=0.42.3; extra == "all"
+Requires-Dist: pennylane-lightning>=0.42.0; extra == "all"
+Requires-Dist: openqasm3>=1.0.1; extra == "all"
+Requires-Dist: pyqasm>=0.5.0; extra == "all"
+Dynamic: license-file
+
+# Quantum Unified Simulator (QCanvas)
+
+A comprehensive quantum computing platform that provides unified simulation, circuit conversion, and visualization capabilities across multiple quantum frameworks using a hybrid Next.js and FastAPI architecture.
+
+## 🚀 Overview
+
+QCanvas is a modern, web-based quantum computing platform that bridges the gap between different quantum computing frameworks. It provides a unified interface for simulating quantum circuits, converting between different quantum programming languages, and visualizing quantum states and operations.
+
+### Key Features
+
+- **Multi-Framework Support**: Convert circuits between Cirq, Qiskit, and PennyLane
+- **Hybrid CPU–QPU Model**: QCanvas orchestrates; QSim executes (simulator-first, pluggable QPU later)
+- **Real-Time Simulation**: Execute quantum circuits with statevector, density matrix, or stabilizer backends
+- **OpenQASM 3.0 (Rosetta Stone)**: Universal intermediate representation across frameworks
+- **Smart Conversion Engine**: AST-based parsing, intelligent gate mapping, built-in validation, instant analytics
+- **Interactive Visualization**: Circuit rendering, histograms, and results analysis
+- **Shared TypeScript Types**: Type safety across frontend and backend services
+- **Extensible Architecture**: Plugin-based system for adding new frameworks
+
+## 🏗️ Architecture
+
+```
+QCanvas/
+├── frontend/             # Next.js-based web interface
+│   ├── app/              # App Router pages and layouts
+│   ├── components/       # Reusable UI components
+│   ├── lib/              # Utility functions and state management
+│   └── public/           # Static assets (images, icons)
+│
+├── backend/              # FastAPI REST API and WebSocket server
+│   ├── app/              # Main application logic
+│   │   ├── api/          # API routes and endpoints
+│   │   ├── models/       # Database models and Pydantic schemas
+│   │   └── services/     # Business logic services
+│   └── alembic/          # Database migration scripts
+│
+├── quantum_converters/   # Framework conversion modules
+│   ├── qiskit/           # Qiskit to OpenQASM converters
+│   ├── cirq/             # Cirq to OpenQASM converters
+│   └── pennylane/        # PennyLane to OpenQASM converters
+│
+├── quantum_simulator/    # Quantum simulation engine
+│   ├── backends/         # Simulation backends (statevector, density matrix)
+│   └── core/             # Core simulation logic
+│
+├── examples/             # Sample circuits and tutorials
+│
+├── docs/                 # Project documentation
+│
+├── tests/                # Comprehensive test suite
+│
+└── scripts/              # Helper scripts for setup and maintenance
+```
+
+### Core Components
+
+1. **QCanvas (Compilation/Orchestration)**: AST parsing, QASM generation, validation, hybrid scheduling
+2. **QSim (Execution)**: High-performance simulation backends and result aggregation
+3. **Next.js Frontend**: UI components, routing, and simple operations
+4. **FastAPI Backend**: API, WebSockets, and heavy computations
+5. **Shared TypeScript Types**: Type safety across frontend and backend
+
+## 🛠️ Installation
+
+### Prerequisites
+
+- Python 3.9+
+- Node.js 18+ (for Next.js)
+- Docker Engine with **Compose V2** (`docker compose` CLI)
+- Git
+
+## Docker and Docker Compose
+
+The repo includes [`docker-compose.yml`](docker-compose.yml) for **PostgreSQL**, **Redis**, **QCanvas FastAPI backend**, **Cirq-RAG-Code-Assistant** (Cirq AI / Bedrock), and optionally **SonarQube** (metrics profile).
+
+The **Next.js frontend is not in Compose**; run it locally with `npm run dev` in `frontend/` (see below).
+
+### Service overview
+
+| Service | Container name | Host port | Notes |
+|--------|----------------|-----------|--------|
+| PostgreSQL | `qcanvas_postgres` | **5433** → 5432 | Database for QCanvas |
+| Redis | `qcanvas_redis` | **6379** | Caching |
+| Cirq AI | `qcanvas_cirq_agent` | **8001** → 8000 | Bedrock/RAG; internal URL `http://cirq_agent:8000` |
+| QCanvas API | `qcanvas_backend` | **8000** | Sets `CIRQ_AGENT_URL=http://cirq_agent:8000` |
+| SonarQube | `qcanvas_sonarqube` | **9000** | Only with `--profile metrics` |
+
+Each container can use port **8000 internally** without conflict; they are isolated. Only **host** ports must be unique (**8000** vs **8001**).
+
+### Environment file (project root)
+
+Create a **`.env`** in the repository root (Compose loads it automatically). Minimum for the database:
+
+```env
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=qcanvas_db
+```
+
+For **Cirq AI** inside Docker, add the same variables you use for Bedrock (see [`Cirq-RAG-Code-Assistant/.env.example`](Cirq-RAG-Code-Assistant/.env.example)):
+
+```env
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+AWS_DEFAULT_REGION=us-east-1
+BEDROCK_INFERENCE_PROFILE_ARN_DESIGNER=...
+BEDROCK_INFERENCE_PROFILE_ARN_OPTIMIZER=...
+BEDROCK_INFERENCE_PROFILE_ARN_VALIDATOR=...
+BEDROCK_INFERENCE_PROFILE_ARN_EDUCATIONAL=...
+```
+
+Put AWS keys in **`Cirq-RAG-Code-Assistant/.env`** when using Docker: that file is bind-mounted into the `cirq_agent` container as `/app/.env`. The Compose file does **not** set `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` to empty defaults anymore—empty values used to block `python-dotenv` from applying the mounted file.
+
+### Commands (run from the repo root)
+
+**Build images and start the default stack** (postgres, redis, cirq_agent, backend):
+
+```bash
+docker compose up -d --build
+```
+
+**Start or restart without rebuilding images:**
+
+```bash
+docker compose up -d
+```
+
+**Include SonarQube** (metrics profile):
+
+```bash
+docker compose --profile metrics up -d --build
+```
+
+**Rebuild only specific services** (e.g. after changing a `Dockerfile`):
+
+```bash
+docker compose build cirq_agent backend
+docker compose up -d
+```
+
+**Force a clean rebuild** (slower; use when dependencies change):
+
+```bash
+docker compose build --no-cache cirq_agent backend
+docker compose up -d
+```
+
+**View running services:**
+
+```bash
+docker compose ps
+```
+
+**Follow logs** (all services or one):
+
+```bash
+docker compose logs -f
+docker compose logs -f backend
+docker compose logs -f cirq_agent
+```
+
+**Stop containers** (keeps named volumes such as database data):
+
+```bash
+docker compose stop
+```
+
+**Stop and remove containers** (keeps volumes unless you add `-v`):
+
+```bash
+docker compose down
+```
+
+**Stop and remove containers and volumes** (⚠️ deletes Postgres/Redis/SonarQube data):
+
+```bash
+docker compose down -v
+```
+
+**Run a one-off command in the backend container** (example: open a shell):
+
+```bash
+docker compose exec backend bash
+```
+
+### After Docker is up
+
+- **API:** http://localhost:8000 — docs: http://localhost:8000/docs  
+- **Health:** http://localhost:8000/api/health  
+- **Cirq AI (direct):** http://localhost:8001/docs  
+
+Run **database migrations** against the Dockerized Postgres (from host, with venv and `PYTHONPATH` set, or `exec` into `backend`):
+
+```bash
+# Example from host (Windows PowerShell); adjust path and venv
+$env:PYTHONPATH = "D:\path\to\QCanvas\backend"
+$env:DATABASE_URL = "postgresql://postgres:postgres@127.0.0.1:5433/qcanvas_db"
+python -m alembic -c backend/alembic.ini upgrade head
+```
+
+Then start the **frontend**:
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Open http://localhost:3000
+
+### Windows Setup (Recommended for Development)
+
+#### 1. Clone Repository
+```bash
+git clone https://github.com/Umer-Farooq-CS/QCanvas.git
+cd QCanvas
+```
+
+#### 2. Create Virtual Environment
+```bash
+python -m venv qcanvas_env
+.\qcanvas_env\Scripts\activate
+```
+
+#### 3. Install Dependencies
+```bash
+pip install -r requirements.txt
+```
+
+#### 4. Start Docker Services
+
+Use **Docker Compose** as described in [Docker and Docker Compose](#docker-and-docker-compose) (e.g. `docker compose up -d --build`). For SonarQube, add `--profile metrics`.
+
+#### 5. Set Up Database Schema
+```powershell
+# From repo root; set path to your clone
+$env:PYTHONPATH = "D:\path\to\QCanvas\backend"
+# If Postgres is the Docker Compose service (mapped to host 5433):
+$env:DATABASE_URL = "postgresql://postgres:postgres@127.0.0.1:5433/qcanvas_db"
+
+python -m alembic -c backend/alembic.ini upgrade head
+```
+
+#### 6. Create Admin User (Optional)
+```bash
+python backend/create_user.py
+```
+
+Follow prompts to create an admin account.
+
+#### 7. Create Demo Account (Optional)
+```bash
+python backend/create_demo_account.py
+```
+
+This creates a demo account (`demo@qcanvas.dev` / `demo123`) for testing. Demo data is cleared on logout.
+
+#### 8. Verify Database
+```bash
+python backend/verify_database.py
+```
+
+📚 **For detailed information about database architecture, security (CIA principles), and troubleshooting, see [docs/db_setup.md](docs/db_setup.md)**
+
+#### 9. Start Backend Server
+
+If you already use **Docker Compose** for the API, **skip this step** (backend is on http://localhost:8000).
+
+```powershell
+$env:PYTHONPATH="d:\path\to\QCanvas\backend"
+python backend/start.py
+```
+
+Backend will run on `http://localhost:8000`
+- API Docs: `http://localhost:8000/docs`
+- Health Check: `http://localhost:8000/api/health`
+
+**Cirq AI assistant (optional):** The IDE can proxy to [Cirq-RAG-Code-Assistant](Cirq-RAG-Code-Assistant/QCANVAS_INTEGRATION_GUIDE.md). Run the Cirq service on **port 8001** (QCanvas already uses **8000**). Set `CIRQ_AGENT_URL` in the QCanvas backend environment (defaults to `http://127.0.0.1:8001`). The frontend calls `{QCanvas API}/api/cirq-agent/api/v1/...`. For local UI-only testing without the QCanvas API proxy, set `NEXT_PUBLIC_CIRQ_USE_NEXT_REWRITE=true` and optionally `CIRQ_REWRITE_TARGET` (Next.js rewrites `/cirq-api/*` to the Cirq server).
+
+#### 10. Start Frontend (New Terminal)
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Frontend will run on `http://localhost:3000`
+
+### Linux Quick Setup (Recommended)
+
+For a fresh Linux machine, you can install all requirements and start QCanvas using the provided scripts:
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/Umer-Farooq-CS/QCanvas.git
+   cd QCanvas
+   ```
+
+2. **Run first‑time setup**
+   ```bash
+   # Installs system packages, creates venv, installs backend + frontend deps
+   bash setup.sh
+   ```
+
+3. **Configure environment**
+   ```bash
+   cp environment.env.example environment.env
+   # Edit environment.env with your configuration
+   ```
+
+4. **Start/stop QCanvas in the background**
+   ```bash
+   # Start Next.js frontend and FastAPI backend in background
+   ./run.sh start
+
+   # Stop all QCanvas services (kills node/next/uvicorn and clears PID files)
+   ./run.sh stop
+   ```
+
+   - Background logs are written to `logs/frontend.log` and `logs/backend.log`.
+   - PID files `frontend.pid` and `backend.pid` are used to avoid double‑starting services.
+
+## 📡 API Usage
+
+### Conversion API
+
+**Endpoint:** `POST /api/converter/convert`
+
+Convert quantum circuit code from a specific framework to OpenQASM 3.0.
+
+```json
+{
+  "source_code": "from qiskit import QuantumCircuit\nqc = QuantumCircuit(2)\nqc.h(0)\nqc.cx(0, 1)",
+  "source_framework": "qiskit",
+  "conversion_type": "classic"
+}
+```
+
+**Response:**
+```json
+{
+    "success": true,
+    "qasm_code": "OPENQASM 3.0;...",
+    "framework": "qiskit",
+    "conversion_stats": { ... }
+}
+```
+
+### Simulation API (QSim)
+
+**Endpoint:** `POST /api/simulator/execute`
+
+Execute OpenQASM 3.0 code using the QSim engine with various backends.
+
+```json
+{
+  "qasm_code": "OPENQASM 3.0; include \"stdgates.inc\"; qubit[2] q; bit[2] c; h q[0]; cx q[0], q[1]; c = measure q;",
+  "backend": "cirq",  // Options: "cirq", "qiskit", "pennylane"
+  "shots": 1024
+}
+```
+
+**Response:**
+```json
+{
+    "success": true,
+    "counts": { "00": 512, "11": 512 },
+    "metadata": { ... }
+}
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+- `DATABASE_URL`: PostgreSQL connection string
+- `REDIS_URL`: Redis connection string for caching
+- `SECRET_KEY`: Application secret key
+- `DEBUG`: Enable debug mode (True/False)
+- `ALLOWED_HOSTS`: Comma-separated list of allowed hosts
+- `NEXT_PUBLIC_API_URL` / `NEXT_PUBLIC_API_BASE`: Frontend API endpoint for Next.js
+- `CIRQ_AGENT_URL`: QCanvas backend proxy target for Cirq AI (Compose sets `http://cirq_agent:8000` inside Docker; locally often `http://127.0.0.1:8001`)
+
+## 🧪 Testing
+
+### Run Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test categories
+pytest tests/unit/
+pytest tests/integration/
+pytest tests/e2e/
+
+# Run frontend tests
+cd frontend
+npm test
+
+# Run with coverage
+pytest --cov=quantum_converters --cov=quantum_simulator --cov=backend
+```
+
+## 📚 Documentation
+
+- [API Documentation](docs/api/)
+- [User Guide](docs/user-guide/)
+- [Developer Guide](docs/developer/)
+- [Deployment Guide](docs/deployment/)
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](docs/developer/contributing.md) for details.
+
+## 📄 License
+
+This project is licensed under the **Open Quantum Workbench Proprietary License**. See the [LICENSE](LICENSE) file for details.
+
+## 👥 Teams
+
+### QCanvas Team
+- Umer Farooq
+- Hussan Waseem Syed
+- Muhammad Irtaza Khan
+
+### QSim Team
+- Aneeq Ahmed Malik
+- Abeer Noor
+- Abdullah Mehmood
+
+### Supervisors
+- Dr. Imran Ashraf (Project Supervisor)
+- Dr. Muhammad Nouman Noor (Co-Supervisor)
+
+**Built under Open Quantum Workbench: A FAST University Initiative**