Metadata-Version: 2.4
Name: zena-sdk
Version: 0.1.7
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Requires-Dist: numpy>=1.24.0
Requires-Dist: fastapi>=0.109.0 ; extra == 'backend'
Requires-Dist: uvicorn[standard]>=0.27.0 ; extra == 'backend'
Requires-Dist: pydantic>=2.6.0 ; extra == 'backend'
Requires-Dist: requests>=2.31.0 ; extra == 'backend'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: hypothesis ; extra == 'dev'
Requires-Dist: black ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Provides-Extra: backend
Provides-Extra: dev
License-File: LICENSE
Summary: A high-performance Quantum SDK with a Rust + C++ hybrid kernel for ultra-efficient statevector simulation.
Keywords: quantum,sdk,simulator,statevector,quantum-computing,rust,qasm
Home-Page: https://github.com/epazztech/quantum.hw.sdk
Author: Zena Team
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/epazztech/quantum.hw.sdk/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/epazztech/quantum.hw.sdk/tree/main/docs
Project-URL: Homepage, https://github.com/epazztech/quantum.hw.sdk
Project-URL: Repository, https://github.com/epazztech/quantum.hw.sdk

# Zena SDK ⚛️

**Zena SDK** is a high-performance Quantum SDK that combines a **Rust + C++ hybrid kernel** for ultra-efficient statevector simulation with a **professional IBM Carbon-based** web interface (FastAPI + React). It also supports executing circuits on **IBM Quantum Hardware**.

---

## 🚀 Overview

This repository provides a unified environment for building, simulating, and visualizing quantum circuits. It leverages a unique hybrid math core—combining Rust's safety and high-level abstractions with performance-critical kernels implemented in optimized C++—while providing a premium, interactive web interface that mirrors the IBM Quantum Composer aesthetic.

### Key Features
- **Hybrid Math Core**: Optimized statevector simulation using a **Rust (PyO3) + C++ (cxx)** bridge. Fundamental gates like Hadamard, Pauli-X, and CX are offloaded to C++ for maximum throughput.
- **RESTful API**: High-performance FastAPI backend for simulation and code execution.
- **IBM Carbon UI**: Authentic "IBM Quantum Composer" experience using the **IBM Carbon Design System** (React + Sass).
- **Interactive Visualizations**: High-fidelity Q-Sphere, Phase/Magnitude analysis, and measurement probability plots.
- **Noise Modeling**: Sophisticated gate-level and qubit-level noise simulation with custom fidelity tracking.
- **Extensible Architecture**: Modular structure with `crates` for low-level logic and `frontend`/`backend` separation.

---

## 🛠️ Performance Architecture

Zena SDK uses a tiered performance model:
1.  **Python Layer**: User-friendly API and SDK logic.
2.  **Rust Layer (`crates/simulator_statevector`)**: High-level state management, noise handling, and Python bindings via PyO3.
3.  **C++ Math Core**: Performance-critical gate kernels (H, X, CX) implemented in C++ and linked via the `cxx` bridge for zero-overhead execution.

---

## 🛠️ Installation & Setup

Follow these steps to set up your development environment:

### 1. Prerequisites
- Python 3.10 or higher
- [Rust & Cargo](https://rustup.rs/) (for building Rust shells)
- [C++ Compiler](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (MSVC, GCC, or Clang for math core)
- **Node.js 20.19+ or 22.12+** (required by Vite)
  - **Recommended**: Install Node.js 22 using [nvm](https://github.com/nvm-sh/nvm):
    ```bash
    # Install nvm (if not already installed)
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
    # Or on Windows WSL, follow: https://github.com/nvm-sh/nvm#installing-and-updating
    
    # Install Node.js 22
    nvm install 22
    
    # Use Node.js 22
    nvm use 22
    
    # Verify installation
    node --version  # Should show v22.x.x
    ```

### 2. Backend Setup
Create and activate a virtual environment, then install dependencies:

```bash
# Create and activate venv
python3 -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

# Link the Hybrid Rust/C++ simulator kernel
maturin develop --manifest-path crates/simulator_statevector/Cargo.toml
```

### 3. Frontend Setup
Install the necessary Node.js packages (including Carbon Design System and Sass):

```bash
cd frontend
npm install
cd ..
```

---

## 🖥️ Running the Application

To run the full application, you need to start both the backend and the frontend.

### 1. Start Backend (FastAPI)
```bash
python3 backend/main.py
# OR directly with uvicorn:
# uvicorn backend.main:app --reload
```
*Backend API will be available at: http://localhost:8000*
*Interactive API Docs (Swagger UI): http://localhost:8000/docs*

### 2. Start Frontend (React + Vite)
```bash
cd frontend
npm run dev
```
*Frontend will be available at: http://localhost:5173* (or as reported by Vite)

---

## 📂 Project Structure

- `backend/`: FastAPI application containing API endpoints and simulation logic.
- `frontend/`: React source code, IBM Carbon components, and SCSS styling.
- `crates/`: Rust workspace containing the hybrid Rust/C++ simulation kernels.
  - `simulator_statevector/src/math_core.cpp`: Optimized C++ gate implementations.
  - `simulator_statevector/src/lib.rs`: Rust logic and PyO3 bindings.
- `zena/`: Core Python SDK package (circuit, providers, transpiler).
- `docs/`: Project documentation and user manual.


---

## 📄 License
Detailed in the [LICENSE](LICENSE) file.

