zena-sdk 0.1.7

A high-performance Quantum SDK with a Rust + C++ hybrid kernel for ultra-efficient statevector simulation.

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 (for building Rust shells)
• C++ Compiler (MSVC, GCC, or Clang for math core)
• Node.js 20.19+ or 22.12+ (required by Vite)
  • Recommended: Install Node.js 22 using nvm:

    # 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:

# 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):

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)

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)

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 file.