zena-sdk 0.1.0__tar.gz

zena_sdk-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# General / IDEs
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.egg-info
+.venv/
+venv/
+env/
+.env
+.mypy_cache/
+.tox/
+
+# Testing and Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+.hypothesis/
+junit.xml
+cov.xml
+
+# Rust
+target/
+**/*.rs.bk
+
+# Node.js / Frontend
+node_modules/
+frontend/.vite/
+frontend/dist/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.npm/
+.next/
+
+# Generated Artifacts / Logs
+*.log
+*.bak
+test_*.png
+*_results.png
+*.ir
+output.txt
+app.py.local_backup
+
+# Documentation
+docs/_build/
+
+# Project Specific
+web_app_copy/
+features/
+tests/

zena_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: zena-sdk
+Version: 0.1.0
+Summary: A high-level Python SDK for the Zena Quantum Simulator, inspired by Qiskit.
+Author-email: Zena Team <info@zena.quantum>
+License: Apache-2.0
+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: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.20
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Zena SDK
+
+**Zena SDK** is a high-level Python library for creating and simulating quantum circuits, designed with a familiar API for users of Qiskit. It serves as the user-facing layer for the powerful Zena Quantum Simulator engine.
+
+## Installation
+
+```bash
+pip install zena-sdk
+```
+
+*(Note: Requires valid `qsys` and `simulator_statevector` backend installations)*
+
+## Basic Usage
+
+Zena SDK allows you to build circuits using `QuantumRegister`, `ClassicalRegister`, and `QuantumCircuit` in a way that feels completely natural.
+
+```python
+from zena import QuantumCircuit, execute, Aer
+
+# 1. Create a Quantum Circuit
+qc = QuantumCircuit(2, 2)
+qc.h(0)
+qc.cx(0, 1)
+qc.measure([0, 1], [0, 1])
+
+# 2. visualizae
+print(qc.draw())
+
+# 3. Choose a Backend
+backend = Aer.get_backend('statevector_simulator')
+
+# 4. Execute
+job = execute(qc, backend, shots=1024)
+result = job.result()
+
+# 5. Get Results
+print("Counts:", result.get_counts())
+```
+
+## Features
+
+- **Familiar API**: Drop-in conceptual replacement for basic Qiskit circuits.
+- **High Performance**: Powered by a Rust-based statevector simulator.
+- **Visualizations**: Built-in methods for circuit drawing and result plotting.
+- **Extensible**: Modular architecture allowing for future backend plugins.
+
+## Architecture
+
+Zena SDK (`zena`) sits on top of the Core Engine (`qsys`).
+
+- **Base Layer**: `qsys` (Intermediate Representation & Composer)
+- **Simulation Layer**: `simulator_statevector` (Rust-based capabilities)
+- **User Layer**: `zena` (High-level Circuit & Provider API)

zena_sdk-0.1.0/README.md

@@ -0,0 +1,53 @@
+# Zena SDK
+
+**Zena SDK** is a high-level Python library for creating and simulating quantum circuits, designed with a familiar API for users of Qiskit. It serves as the user-facing layer for the powerful Zena Quantum Simulator engine.
+
+## Installation
+
+```bash
+pip install zena-sdk
+```
+
+*(Note: Requires valid `qsys` and `simulator_statevector` backend installations)*
+
+## Basic Usage
+
+Zena SDK allows you to build circuits using `QuantumRegister`, `ClassicalRegister`, and `QuantumCircuit` in a way that feels completely natural.
+
+```python
+from zena import QuantumCircuit, execute, Aer
+
+# 1. Create a Quantum Circuit
+qc = QuantumCircuit(2, 2)
+qc.h(0)
+qc.cx(0, 1)
+qc.measure([0, 1], [0, 1])
+
+# 2. visualizae
+print(qc.draw())
+
+# 3. Choose a Backend
+backend = Aer.get_backend('statevector_simulator')
+
+# 4. Execute
+job = execute(qc, backend, shots=1024)
+result = job.result()
+
+# 5. Get Results
+print("Counts:", result.get_counts())
+```
+
+## Features
+
+- **Familiar API**: Drop-in conceptual replacement for basic Qiskit circuits.
+- **High Performance**: Powered by a Rust-based statevector simulator.
+- **Visualizations**: Built-in methods for circuit drawing and result plotting.
+- **Extensible**: Modular architecture allowing for future backend plugins.
+
+## Architecture
+
+Zena SDK (`zena`) sits on top of the Core Engine (`qsys`).
+
+- **Base Layer**: `qsys` (Intermediate Representation & Composer)
+- **Simulation Layer**: `simulator_statevector` (Rust-based capabilities)
+- **User Layer**: `zena` (High-level Circuit & Provider API)

zena_sdk-0.1.0/__init__.py

@@ -0,0 +1,7 @@
+from .circuit import QuantumCircuit, QuantumRegister, ClassicalRegister
+from .providers.aer import Aer
+from .execute import execute
+from .visualization import plot_histogram
+from .compiler import transpile
+
+__version__ = "0.1.0"

zena_sdk-0.1.0/circuit/__init__.py

@@ -0,0 +1,2 @@
+from .quantum_circuit import QuantumCircuit
+from .register import QuantumRegister, ClassicalRegister

zena_sdk-0.1.0/circuit/quantum_circuit.py

@@ -0,0 +1,218 @@
+"""
+QuantumCircuit class mimicking Qiskit's API, delegating to qsys.
+"""
+from typing import Union, List, Optional
+from .register import QuantumRegister, ClassicalRegister
+
+# Import the core composer from existing codebase
+# We treat qsys as the internal engine
+try:
+    from qsys.circuit.quantum_circuit import QuantumCircuit as QSysCircuit
+except ImportError as e:
+    # Fallback/Mock for development if qsys is not in path
+    print(f"DEBUG: Failed to import qsys: {e}")
+    QSysCircuit = None
+
+class QuantumCircuit:
+    """
+    QuantumCircuit adaptable to Zena SDK.
+    """
+    def __init__(self, *regs, name: Optional[str] = None):
+        self.name = name
+        self.qregs = []
+        self.cregs = []
+        self._qubits = []
+        self._clbits = []
+        
+        # Parse arguments similar to Qiskit (int or Register)
+        if len(regs) == 0:
+            # Empty circuit
+            pass
+        elif all(isinstance(r, int) for r in regs):
+            # Case: QuantumCircuit(n_qubits, n_clbits)
+            n_qubits = regs[0]
+            n_clbits = regs[1] if len(regs) > 1 else 0
+            self.add_register(QuantumRegister(n_qubits, 'q'))
+            if n_clbits > 0:
+                self.add_register(ClassicalRegister(n_clbits, 'c'))
+        else:
+            # Case: QuantumCircuit(qreg, creg)
+            for r in regs:
+                if isinstance(r, (QuantumRegister, ClassicalRegister)):
+                    self.add_register(r)
+                else:
+                    raise TypeError("Arguments must be integers or Registers")
+
+        # Initialize the underlying qsys Core Circuit
+        if QSysCircuit:
+            self._core_circuit = QSysCircuit(len(self._qubits), len(self._clbits))
+        else:
+            self._core_circuit = None
+            print("Warning: qsys.circuit not found. Core delegation disabled.")
+
+    def add_register(self, register: Union[QuantumRegister, ClassicalRegister]):
+        if isinstance(register, QuantumRegister):
+            self.qregs.append(register)
+            # Flatten qubits mapping (simplistic for now)
+            start_index = len(self._qubits)
+            self._qubits.extend([i for i in range(start_index, start_index + register.size)])
+        elif isinstance(register, ClassicalRegister):
+            self.cregs.append(register)
+            start_index = len(self._clbits)
+            self._clbits.extend([i for i in range(start_index, start_index + register.size)])
+            
+    def h(self, qubit):
+        """Apply Hadamard gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            self._core_circuit.h(q_idx)
+        return self
+
+    def x(self, qubit):
+        """Apply Pauli-X gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            self._core_circuit.x(q_idx)
+        return self
+
+    def y(self, qubit):
+        """Apply Pauli-Y gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            # Note: qsys uses string name 'y' for Instruction, which execute.py handles
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(Instruction(name="y", qubits=(q_idx,)))
+        return self
+
+    def z(self, qubit):
+        """Apply Pauli-Z gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(Instruction(name="z", qubits=(q_idx,)))
+        return self
+
+    def s(self, qubit):
+        """Apply S gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(Instruction(name="s", qubits=(q_idx,)))
+        return self
+
+    def sdg(self, qubit):
+        """Apply S-dagger gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(Instruction(name="sdg", qubits=(q_idx,)))
+        return self
+
+    def t(self, qubit):
+        """Apply T gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(Instruction(name="t", qubits=(q_idx,)))
+        return self
+
+    def tdg(self, qubit):
+        """Apply T-dagger gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(Instruction(name="tdg", qubits=(q_idx,)))
+        return self
+
+    def sx(self, qubit):
+        """Apply sqrt-X gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            self._core_circuit.sx(q_idx)
+        return self
+
+    def rx(self, theta, qubit):
+        """Apply RX gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(
+                Instruction(name="rx", qubits=(q_idx,), params=(float(theta),))
+            )
+        return self
+
+    def ry(self, theta, qubit):
+        """Apply RY gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(
+                Instruction(name="ry", qubits=(q_idx,), params=(float(theta),))
+            )
+        return self
+
+    def rz(self, theta, qubit):
+        """Apply RZ gate."""
+        q_idx = self._resolve_index(qubit)
+        if self._core_circuit:
+            self._core_circuit.rz(q_idx, theta)
+        return self
+
+    def cx(self, control_qubit, target_qubit):
+        """Apply CNOT gate."""
+        c_idx = self._resolve_index(control_qubit)
+        t_idx = self._resolve_index(target_qubit)
+        if self._core_circuit:
+            self._core_circuit.cx(c_idx, t_idx)
+        return self
+
+    def swap(self, qubit1, qubit2):
+        """Apply SWAP gate."""
+        q1_idx = self._resolve_index(qubit1)
+        q2_idx = self._resolve_index(qubit2)
+        if self._core_circuit:
+            from qsys.ir.types import Instruction
+            self._core_circuit._instructions.append(Instruction(name="swap", qubits=(q1_idx, q2_idx)))
+        return self
+
+    def measure(self, qubits, clbits):
+        """Measure quantum bits into classical bits."""
+        if isinstance(qubits, int):
+            qubits = [qubits]
+        if isinstance(clbits, int):
+            clbits = [clbits]
+
+        if len(qubits) != len(clbits):
+            raise ValueError("Number of qubits and classical bits must match.")
+
+        for q, c in zip(qubits, clbits):
+            q_idx = self._resolve_index(q)
+            c_idx = self._resolve_cbit_index(c)
+            if self._core_circuit:
+                self._core_circuit.measure(q_idx, c_idx)
+        return self
+
+    def draw(self, output='text'):
+        """Draw the circuit."""
+        if self._core_circuit:
+            return self._core_circuit.draw(mode=output)
+        return "Core circuit not initialized."
+
+    def _resolve_index(self, qubit) -> int:
+        """
+        Resolve user input (int or bit object) to flat integer index for qsys.
+        For now, we assume user passes integers as indices.
+        """
+        # TODO: Support Qubit object (e.g. qreg[0])
+        if isinstance(qubit, int):
+            if qubit < 0 or qubit >= len(self._qubits):
+                raise IndexError(f"Qubit index {qubit} out of range.")
+            return qubit
+        raise TypeError("Qubit must be an integer index for now.")
+
+    def _resolve_cbit_index(self, cbit) -> int:
+        if isinstance(cbit, int):
+             if cbit < 0 or cbit >= len(self._clbits):
+                raise IndexError(f"Clbit index {cbit} out of range.")
+             return cbit
+        raise TypeError("Clbit must be an integer index for now.")

zena_sdk-0.1.0/circuit/register.py

@@ -0,0 +1,28 @@
+"""
+Quantum and Classical Registers.
+"""
+from typing import Optional
+
+class Register:
+    """Base class for registers."""
+    def __init__(self, size: int, name: Optional[str] = None):
+        if size <= 0:
+            raise ValueError("Register size must be positive")
+        self.size = size
+        self.name = name
+        
+    def __len__(self):
+        return self.size
+        
+    def __repr__(self):
+        return f"{self.__class__.__name__}({self.size}, '{self.name}')"
+
+class QuantumRegister(Register):
+    """Implement a quantum register."""
+    def __init__(self, size: int, name: Optional[str] = "q"):
+        super().__init__(size, name)
+
+class ClassicalRegister(Register):
+    """Implement a classical register."""
+    def __init__(self, size: int, name: Optional[str] = "c"):
+        super().__init__(size, name)

zena_sdk-0.1.0/compiler/__init__.py

@@ -0,0 +1,72 @@
+"""
+Zena Compiler module.
+"""
+from typing import Union, List, Optional
+from ..circuit import QuantumCircuit
+from ..providers.backend import Backend
+
+# Import qsys transpiler
+try:
+    from qsys.transpiler.passes import transpile as qsys_transpile
+except ImportError:
+    qsys_transpile = None
+
+def transpile(circuits: Union[QuantumCircuit, List[QuantumCircuit]],
+              backend: Optional[Backend] = None,
+              **kwargs):
+    """
+    Transpile the circuit(s) for a given backend.
+    
+    Args:
+        circuits: Circuit or list of circuits to transpile.
+        backend: Backend to target (optional).
+        
+    Returns:
+        The transpiled circuit(s).
+    """
+    if not qsys_transpile:
+        print("Warning: qsys transpiler not found. Returning circuit(s) as is.")
+        return circuits
+
+    is_list = isinstance(circuits, list)
+    if not is_list:
+        circuits = [circuits]
+
+    transpiled_circuits = []
+    for qc in circuits:
+        if not hasattr(qc, "_core_circuit") or not qc._core_circuit:
+            transpiled_circuits.append(qc)
+            continue
+            
+        # Call qsys transpiler on the internal core circuit
+        # qsys.transpile expects (core_circuit, backend)
+        # Note: In Phase 2, we passed use_transpiler=False because our Zena Backends
+        # didn't have .target. To make this work, we'll need to pass the wrapped qsys backend
+        # if available, or a default one.
+        
+        # For now, let's just use the opt1q if no backend is provided
+        from qsys.transpiler.opt1q import optimize_1q
+        
+        core_qc = qc._core_circuit
+        
+        if backend:
+            # If backend is provided, we try to use the full qsys transpile
+            # We need to extract the underlying qsys backend from Zena backend if possible
+            # Or just pass the Zena backend if it has the required properties (target, etc.)
+            try:
+                # We expect qsys.transpile to handle cases where backend might be None or simplified
+                # but if it needs .target, we might need a fallback.
+                transpiled_core = qsys_transpile(core_qc, backend, **kwargs)
+            except Exception as e:
+                print(f"Warning: full transpile failed ({e}). Falling back to 1q optimization.")
+                transpiled_core = optimize_1q(core_qc)
+        else:
+            # Default optimization if no backend
+            transpiled_core = optimize_1q(core_qc)
+            
+        # Update the Zena circuit with the transpiled core
+        # In a real SDK, we'd probably return a NEW Zena circuit
+        qc._core_circuit = transpiled_core
+        transpiled_circuits.append(qc)
+
+    return transpiled_circuits[0] if not is_list else transpiled_circuits

zena_sdk-0.1.0/execute.py

@@ -0,0 +1,35 @@
+"""
+Execute function.
+"""
+from .providers.aer import Aer
+from .compiler import transpile
+
+def execute(experiments, backend=None, shots=1024, **kwargs):
+    """
+    Execute a list of circuits or a single circuit on a backend.
+    
+    Args:
+        experiments (QuantumCircuit or list): Circuit(s) to execute.
+        backend (Backend): The backend to execute on.
+        shots (int): Number of shots (default: 1024).
+        
+    Returns:
+        Job: A job object containing the result.
+    """
+    if backend is None:
+        # Default to statevector simulator if none provided
+        backend = Aer.get_backend("statevector_simulator")
+        
+    # Transpile the circuits before execution
+    experiments = transpile(experiments, backend=backend)
+        
+    if not isinstance(experiments, list):
+        experiments = [experiments]
+        
+    # For now, we only support single circuit execution in this simplified wrapper
+    # In full implementation, we would loop and aggregate results
+    if len(experiments) > 1:
+        raise NotImplementedError("Batch execution not yet fully supported in this simplified wrapper.")
+        
+    circuit = experiments[0]
+    return backend.run(circuit, shots=shots, **kwargs)

zena_sdk-0.1.0/providers/__init__.py

@@ -0,0 +1,5 @@
+"""
+Zena Providers module.
+"""
+class Aer:
+    pass

zena_sdk-0.1.0/providers/aer.py

@@ -0,0 +1,71 @@
+"""
+Aer Provider for local simulation.
+"""
+from .backend import Backend
+from .job import Job, Result
+import uuid
+
+# Import the internal execution logic from qsys
+try:
+    from qsys.runtime.execute import execute as qsys_execute
+except ImportError:
+    qsys_execute = None
+
+class StatevectorSimulator(Backend):
+    """Local statevector simulator backend."""
+    
+    @property
+    def name(self):
+        return "statevector_simulator"
+        
+    @property
+    def target(self):
+        """Return a default target for the simulator."""
+        try:
+            from qsys.backends.base import Target
+            # Simulator typically has all-to-all connectivity and standard basis
+            return Target(
+                n_qubits=32, # Theoretical limit for 8GB RAM approx
+                basis_gates={"x", "sx", "rz", "cx", "measure", "h", "y", "z", "s", "sdg", "t", "tdg", "rx", "ry", "swap"},
+                coupling_map=[] # Empty list often means all-to-all in these engines, or we can generate it
+            )
+        except ImportError:
+            return None
+        
+    def run(self, circuit, shots=1024, **kwargs):
+        """Run the circuit using qsys."""
+        if not qsys_execute:
+             raise ImportError("qsys.runtime.execute not available. Cannot run simulation.")
+             
+        # Extract the core qsys circuit
+        if not hasattr(circuit, "_core_circuit") or not circuit._core_circuit:
+             raise ValueError("Circuit has no underlying qsys circuit.")
+             
+        core_qc = circuit._core_circuit
+        
+        # Execute using qsys
+        # qsys.execute returns a dict with 'counts', 'statevector', etc.
+        # We disable the internal qsys transpiler for now to avoid 'backend.target' errors
+        # since we are not yet passing a formal qsys.Backend object.
+        res_data = qsys_execute(core_qc, shots=shots, use_transpiler=False)
+        
+        # Wrap in Result and Job
+        result = Result(res_data)
+        job_id = str(uuid.uuid4())
+        return Job(self, job_id, result)
+
+class AerProvider:
+    """Provider for Aer backends."""
+    
+    def __init__(self):
+        self._backends = {
+            "statevector_simulator": StatevectorSimulator()
+        }
+        
+    def get_backend(self, name="statevector_simulator"):
+        if name not in self._backends:
+            raise ValueError(f"Backend '{name}' not found.")
+        return self._backends[name]
+
+# Global instance
+Aer = AerProvider()

zena_sdk-0.1.0/providers/backend.py

@@ -0,0 +1,18 @@
+"""
+Base Backend Class.
+"""
+from abc import ABC, abstractmethod
+
+class Backend(ABC):
+    """Abstract base class for backends."""
+    
+    @abstractmethod
+    def run(self, circuit, shots=1024, **kwargs):
+        """Run a circuit on the backend."""
+        pass
+    
+    @property
+    @abstractmethod
+    def name(self):
+        """Backend name."""
+        pass

zena_sdk-0.1.0/providers/job.py

@@ -0,0 +1,24 @@
+"""
+Job Class to handle execution status and results.
+"""
+class Job:
+    def __init__(self, backend, job_id, result=None):
+        self._backend = backend
+        self._job_id = job_id
+        self._result = result
+        
+    def result(self):
+        """Return the result of the job."""
+        return self._result
+        
+class Result:
+    def __init__(self, backend_result_dict):
+        self._data = backend_result_dict
+        
+    def get_counts(self):
+        """Return counts from the result."""
+        return self._data.get("counts", {})
+        
+    def get_statevector(self):
+        """Return statevector from the result."""
+        return self._data.get("statevector", [])

zena_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zena-sdk"
+version = "0.1.0"
+description = "A high-level Python SDK for the Zena Quantum Simulator, inspired by Qiskit."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Zena Team", email = "info@zena.quantum" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.20",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["zena"]

zena_sdk-0.1.0/visualization/__init__.py

@@ -0,0 +1,28 @@
+def plot_histogram(data, title=None):
+    """
+    Plot a histogram of counts.
+    
+    Args:
+        data (dict): Counts dictionary (e.g., {'00': 500, '11': 500})
+        title (str): Optional title for the plot.
+    """
+    if title:
+        print(f"\n--- {title} ---")
+    else:
+        print("\n--- Histogram ---")
+        
+    if not data:
+        print("Empty data.")
+        return
+
+    max_val = max(data.values())
+    total = sum(data.values())
+    
+    # Sort keys for consistent display
+    for key in sorted(data.keys()):
+        val = data[key]
+        percentage = (val / total) * 100
+        bar_length = int((val / max_val) * 20)
+        bar = "█" * bar_length
+        print(f"{key:5s} | {bar:<20} | {val:4d} ({percentage:>5.1f}%)")
+    print("-" * 45)