qex 0.1.1__py3-none-any.whl

qex-0.1.1.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: qex
+Version: 0.1.1
+Summary: A lightweight experiment-runner and lab notebook for quantum computing
+Author: qlab contributors
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/AndreaPallotta/qlab
+Project-URL: Documentation, https://github.com/AndreaPallotta/qlab#readme
+Project-URL: Repository, https://github.com/AndreaPallotta/qlab
+Project-URL: Issues, https://github.com/AndreaPallotta/qlab/issues
+Keywords: quantum,quantum-computing,cirq,experiments,quantum-simulation,bloch-sphere
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: cirq>=1.6.1
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# qlab
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/AndreaPallotta/qlab/main/assets/logo.png" alt="qlab logo" width="200"/>
+</div>
+
+A lightweight experiment-runner and lab notebook for quantum computing, built on top of Cirq.
+
+## Overview
+
+`qlab` is designed for running quantum experiments, tracking results, and visualizing outcomes. It focuses on reproducibility, persistence, and visualization rather than being a general-purpose quantum framework.
+
+**Key Features:**
+- 🧪 **Experiment Management**: Define parametric quantum circuits and run them systematically
+- 💾 **Result Persistence**: Store runs, results, and metadata in SQLite
+- 📊 **Visualization**: Automatic Bloch sphere visualization for 1-qubit states
+- 🔬 **Reproducibility**: All parameters and results are stored for later analysis
+- 🚀 **Simple API**: Minimal, opinionated design focused on experiments
+
+## Installation
+
+```bash
+pip install qex
+```
+
+## Quick Start
+
+```python
+from qlab import CirqBackend, Runner, ResultStore
+from qlab.demos import hadamard_experiment
+from pathlib import Path
+
+# Setup
+backend = CirqBackend()
+runner = Runner(backend)
+store = ResultStore(Path("qlab_data/qlab.db"))
+
+# Run an experiment
+experiment = hadamard_experiment()
+record = runner.run(experiment, params={})
+
+# Persist results
+store.save_run(record)
+
+# Retrieve and view
+runs = store.list_runs(experiment_name="hadamard")
+rho = runs[0].get_density_matrix()
+print(f"Density matrix:\n{rho}")
+
+store.close()
+```
+
+## Built-in Experiments
+
+`qlab` includes three demo experiments for validation:
+
+- **X Gate**: `|0⟩ → X → |1⟩` - Simple bit flip
+- **Hadamard**: `|0⟩ → H → superposition` - Creates equal superposition
+- **Ry Sweep**: `|0⟩ → Ry(θ)` - Rotation around Y-axis with parameter `theta`
+
+## Documentation
+
+- **[API Reference](API.md)**: Complete API documentation
+- **[Design Specification](DESIGN.md)**: Architecture and design decisions
+- **[Database Schema](SCHEMA.md)**: SQLite schema documentation
+- **[Bloch Sphere Contract](BLOCH_CONTRACT.md)**: Visualization math and interface
+
+## Current Scope (MVP)
+
+- ✅ 1-qubit experiments only
+- ✅ Ideal simulation (no noise)
+- ✅ Density matrix results
+- ✅ SQLite persistence
+- ✅ Bloch sphere HTML visualization
+- ✅ Cirq-based backend
+
+## Requirements
+
+- Python >= 3.12
+- Cirq >= 1.6.1
+- NumPy >= 1.24.0
+
+## License
+
+Apache License 2.0
+
+## Contributing
+
+Contributions are welcome! Please see the [Design Specification](DESIGN.md) for architecture details and constraints.

qex-0.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+qlab/__init__.py,sha256=47G37bkDpMm9lyMFWKVYyM9ELKJo65apPh41sTQYIV4,477
+qlab/backend.py,sha256=V7TASI-SSCNK9AApvD6d2C1LabB7XB1xNyH-I4h65qI,2383
+qlab/bloch.py,sha256=J34uLDZ07HgfMPs7ANV4aeGLSZB2LUU7QylxyKdrw2E,5903
+qlab/demos.py,sha256=AFNovp2NnhvBftmAkwxNPs--gOQFqX7gglwXsLki6kQ,1704
+qlab/experiment.py,sha256=PjPMb4N8T3oyx0bSyZ5Vl7uKqKh_vp16bpt-9nSTnuE,1458
+qlab/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qlab/runner.py,sha256=iHk6eGm61eZxlgQmeFKWPCZD0ziLjKh39ZlEijAdgnQ,3535
+qlab/store.py,sha256=GgpkSXf61AS9dQZ01ajHsqGAskF4bEwWqknSZQl_vnA,8837
+qex-0.1.1.dist-info/METADATA,sha256=KdqNuy-sJP4s8QQ6Dd8OvsMcHeK2u95C9Kc6qoAuGwY,3963
+qex-0.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+qex-0.1.1.dist-info/top_level.txt,sha256=XdHlK9uLEScGqteqlmIiXaMKp12rVhyoXvdhS_TTvdg,5
+qex-0.1.1.dist-info/RECORD,,

qex-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

qex-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+qlab

qlab/__init__.py

@@ -0,0 +1,20 @@
+"""
+qlab: A lightweight experiment-runner and lab notebook for quantum computing.
+
+Built on top of Cirq, focused on experiments, runs, reproducibility, and visualization.
+"""
+
+from qlab.experiment import Experiment
+from qlab.backend import Backend, CirqBackend
+from qlab.runner import Runner
+from qlab.store import ResultStore, RunRecord
+
+__version__ = "0.1.0"
+__all__ = [
+    "Experiment",
+    "Backend",
+    "CirqBackend",
+    "Runner",
+    "ResultStore",
+    "RunRecord",
+]

qlab/backend.py

@@ -0,0 +1,89 @@
+"""
+Backend abstraction: interface for executing quantum circuits.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any
+import cirq
+import numpy as np
+
+
+class Backend(ABC):
+    """
+    Abstract interface for executing quantum circuits.
+    
+    A backend executes a circuit and returns the final density matrix.
+    For MVP, all backends must support 1-qubit circuits only.
+    """
+    
+    @abstractmethod
+    def run(self, circuit: cirq.Circuit) -> np.ndarray:
+        """
+        Execute a circuit and return the final density matrix.
+        
+        Args:
+            circuit: A Cirq Circuit (must be 1-qubit for MVP).
+            
+        Returns:
+            A 2x2 density matrix as a numpy array (complex dtype).
+        """
+        pass
+    
+    @abstractmethod
+    def get_name(self) -> str:
+        """
+        Get the name/identifier of this backend.
+        
+        Returns:
+            Backend name string.
+        """
+        pass
+
+
+class CirqBackend(Backend):
+    """
+    Concrete backend using Cirq's ideal simulator.
+    
+    Uses Cirq's Simulator for ideal (noiseless) simulation.
+    Results are returned as density matrices derived from statevectors.
+    """
+    
+    def __init__(self):
+        """
+        Initialize the Cirq ideal simulator backend.
+        """
+        self._simulator = cirq.Simulator()
+    
+    def run(self, circuit: cirq.Circuit) -> np.ndarray:
+        """
+        Execute circuit on ideal Cirq simulator and return density matrix.
+        
+        Args:
+            circuit: A Cirq Circuit (must be 1-qubit for MVP).
+            
+        Returns:
+            2x2 density matrix (complex dtype).
+        """
+        # Validate 1-qubit constraint
+        qubits = circuit.all_qubits()
+        if len(qubits) != 1:
+            raise ValueError(f"Circuit must have exactly 1 qubit, got {len(qubits)}")
+        
+        # Run simulation to get final state
+        result = self._simulator.simulate(circuit)
+        statevector = result.final_state_vector
+        
+        # Convert statevector to density matrix: |ψ⟩⟨ψ|
+        # For 1 qubit, statevector is length 2
+        rho = np.outer(statevector, np.conj(statevector))
+        
+        return rho
+    
+    def get_name(self) -> str:
+        """
+        Get backend name.
+        
+        Returns:
+            "cirq_ideal"
+        """
+        return "cirq_ideal"

qlab/bloch.py

@@ -0,0 +1,176 @@
+"""
+Bloch sphere visualization: density matrix → (x,y,z) coordinates → HTML artifact.
+"""
+
+from typing import Tuple
+import numpy as np
+
+
+def density_matrix_to_bloch(rho: np.ndarray) -> Tuple[float, float, float]:
+    """
+    Convert a 1-qubit density matrix to Bloch sphere coordinates (x, y, z).
+    
+    For a density matrix ρ, the Bloch vector is computed as:
+        x = Tr(ρ · σ_x)
+        y = Tr(ρ · σ_y)
+        z = Tr(ρ · σ_z)
+    
+    where σ_x, σ_y, σ_z are the Pauli matrices.
+    
+    Args:
+        rho: 2x2 density matrix (complex dtype).
+            Must be a valid density matrix (Hermitian, trace=1, positive semidefinite).
+    
+    Returns:
+        Tuple of (x, y, z) coordinates as real floats.
+        Coordinates are guaranteed to satisfy x² + y² + z² ≤ 1.
+    """
+    # Pauli matrices
+    sigma_x = np.array([[0, 1], [1, 0]], dtype=complex)
+    sigma_y = np.array([[0, -1j], [1j, 0]], dtype=complex)
+    sigma_z = np.array([[1, 0], [0, -1]], dtype=complex)
+    
+    # Compute Bloch coordinates: Tr(ρ · σ_i)
+    x = np.real(np.trace(rho @ sigma_x))
+    y = np.real(np.trace(rho @ sigma_y))
+    z = np.real(np.trace(rho @ sigma_z))
+    
+    return (float(x), float(y), float(z))
+
+
+def bloch_to_html(x: float, y: float, z: float, title: str = "Bloch Sphere") -> str:
+    """
+    Generate an HTML artifact visualizing a point on the Bloch sphere.
+    
+    The HTML should:
+    - Render a 3D Bloch sphere
+    - Mark the point (x, y, z) on the sphere
+    - Display the coordinates
+    - Be self-contained (no external dependencies, or use CDN for 3D library)
+    - Be viewable in a browser
+    
+    Args:
+        x: X coordinate on Bloch sphere.
+        y: Y coordinate on Bloch sphere.
+        z: Z coordinate on Bloch sphere.
+        title: Optional title for the visualization.
+    
+    Returns:
+        Complete HTML string that can be saved to a file and opened in a browser.
+    """
+    # Use Three.js via CDN for 3D visualization
+    html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{title}</title>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r128/three.min.js"></script>
+    <style>
+        body {{
+            margin: 0;
+            font-family: Arial, sans-serif;
+            background: #1a1a1a;
+            color: #fff;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            padding: 20px;
+        }}
+        #container {{
+            width: 800px;
+            height: 600px;
+            border: 2px solid #444;
+            border-radius: 8px;
+            margin: 20px 0;
+        }}
+        #info {{
+            text-align: center;
+            margin: 10px 0;
+        }}
+        .coord {{
+            display: inline-block;
+            margin: 0 15px;
+            font-family: monospace;
+        }}
+    </style>
+</head>
+<body>
+    <h1>{title}</h1>
+    <div id="container"></div>
+    <div id="info">
+        <div class="coord">x = {x:.4f}</div>
+        <div class="coord">y = {y:.4f}</div>
+        <div class="coord">z = {z:.4f}</div>
+    </div>
+    <script>
+        // Scene setup
+        const scene = new THREE.Scene();
+        const camera = new THREE.PerspectiveCamera(75, 800/600, 0.1, 1000);
+        const renderer = new THREE.WebGLRenderer({{ antialias: true }});
+        renderer.setSize(800, 600);
+        document.getElementById('container').appendChild(renderer.domElement);
+        
+        // Lighting
+        const ambientLight = new THREE.AmbientLight(0x404040, 0.6);
+        scene.add(ambientLight);
+        const directionalLight = new THREE.DirectionalLight(0xffffff, 0.8);
+        directionalLight.position.set(5, 5, 5);
+        scene.add(directionalLight);
+        
+        // Bloch sphere (unit sphere)
+        const sphereGeometry = new THREE.SphereGeometry(1, 32, 32);
+        const sphereMaterial = new THREE.MeshPhongMaterial({{
+            color: 0x4a90e2,
+            transparent: true,
+            opacity: 0.3,
+            side: THREE.DoubleSide,
+            wireframe: false
+        }});
+        const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
+        scene.add(sphere);
+        
+        // Wireframe overlay
+        const wireframe = new THREE.WireframeGeometry(sphereGeometry);
+        const wireframeLine = new THREE.LineSegments(wireframe, new THREE.LineBasicMaterial({{ color: 0xffffff, opacity: 0.2 }}));
+        scene.add(wireframeLine);
+        
+        // Axes
+        const axesHelper = new THREE.AxesHelper(1.2);
+        scene.add(axesHelper);
+        
+        // Point marker
+        const pointGeometry = new THREE.SphereGeometry(0.05, 16, 16);
+        const pointMaterial = new THREE.MeshPhongMaterial({{ color: 0xff4444 }});
+        const point = new THREE.Mesh(pointGeometry, pointMaterial);
+        point.position.set({x}, {y}, {z});
+        scene.add(point);
+        
+        // Line from origin to point
+        const lineGeometry = new THREE.BufferGeometry().setFromPoints([
+            new THREE.Vector3(0, 0, 0),
+            new THREE.Vector3({x}, {y}, {z})
+        ]);
+        const lineMaterial = new THREE.LineBasicMaterial({{ color: 0xff4444, linewidth: 2 }});
+        const line = new THREE.Line(lineGeometry, lineMaterial);
+        scene.add(line);
+        
+        // Camera position
+        camera.position.set(2.5, 2.5, 2.5);
+        camera.lookAt(0, 0, 0);
+        
+        // Animation loop
+        let angle = 0;
+        function animate() {{
+            requestAnimationFrame(animate);
+            angle += 0.01;
+            camera.position.x = 2.5 * Math.cos(angle);
+            camera.position.z = 2.5 * Math.sin(angle);
+            camera.lookAt(0, 0, 0);
+            renderer.render(scene, camera);
+        }}
+        animate();
+    </script>
+</body>
+</html>"""
+    return html

qlab/demos.py

@@ -0,0 +1,59 @@
+"""
+Built-in demo experiments for validation.
+"""
+
+from typing import Dict, Any
+import cirq
+from qlab.experiment import Experiment
+
+
+def x_gate_experiment() -> Experiment:
+    """
+    Demo: |0⟩ → X → |1⟩
+    
+    Simple X gate that flips |0⟩ to |1⟩.
+    
+    Returns:
+        Experiment with no parameters.
+    """
+    def builder(qubit: cirq.Qid, params: Dict[str, Any]) -> cirq.Circuit:
+        """Build circuit: X gate on qubit."""
+        return cirq.Circuit(cirq.X(qubit))
+    
+    return Experiment(name="x_gate", builder=builder)
+
+
+def hadamard_experiment() -> Experiment:
+    """
+    Demo: |0⟩ → H → superposition
+    
+    Hadamard gate creating equal superposition |+⟩ = (|0⟩ + |1⟩)/√2.
+    
+    Returns:
+        Experiment with no parameters.
+    """
+    def builder(qubit: cirq.Qid, params: Dict[str, Any]) -> cirq.Circuit:
+        """Build circuit: Hadamard gate on qubit."""
+        return cirq.Circuit(cirq.H(qubit))
+    
+    return Experiment(name="hadamard", builder=builder)
+
+
+def ry_sweep_experiment() -> Experiment:
+    """
+    Demo: |0⟩ → Ry(θ) sweep
+    
+    Rotation around Y-axis with parameter θ.
+    This experiment expects params = {"theta": float}.
+    
+    Returns:
+        Experiment that takes "theta" parameter (in radians).
+    """
+    def builder(qubit: cirq.Qid, params: Dict[str, Any]) -> cirq.Circuit:
+        """Build circuit: Ry(theta) rotation on qubit."""
+        theta = params.get("theta", 0.0)
+        if not isinstance(theta, (int, float)):
+            raise ValueError(f"theta must be a number, got {type(theta)}")
+        return cirq.Circuit(cirq.ry(theta)(qubit))
+    
+    return Experiment(name="ry_sweep", builder=builder)

qlab/experiment.py

@@ -0,0 +1,45 @@
+"""
+Experiment abstraction: parametric circuit builder.
+"""
+
+from typing import Callable, Dict, Any
+import cirq
+
+
+class Experiment:
+    """
+    An experiment defines a parametric quantum circuit builder.
+    
+    An experiment has a name and a function that builds a Cirq circuit
+    from parameters. The circuit must be 1-qubit for MVP.
+    
+    Attributes:
+        name: Unique identifier for the experiment.
+        builder: Function that takes parameters and returns a Cirq Circuit.
+                 Must accept a single qubit as first argument.
+    """
+    
+    def __init__(self, name: str, builder: Callable[[cirq.Qid, Dict[str, Any]], cirq.Circuit]):
+        """
+        Initialize an experiment.
+        
+        Args:
+            name: Unique name for the experiment.
+            builder: Function signature: (qubit: cirq.Qid, params: Dict[str, Any]) -> cirq.Circuit
+                     The builder must create a 1-qubit circuit.
+        """
+        self.name = name
+        self.builder = builder
+    
+    def build_circuit(self, qubit: cirq.Qid, params: Dict[str, Any]) -> cirq.Circuit:
+        """
+        Build the circuit for this experiment with given parameters.
+        
+        Args:
+            qubit: The single qubit to operate on.
+            params: Parameter dictionary for the experiment.
+            
+        Returns:
+            A Cirq Circuit operating on the given qubit.
+        """
+        return self.builder(qubit, params)

qlab/runner.py

@@ -0,0 +1,106 @@
+"""
+Runner: executes experiments with parameters and configuration.
+"""
+
+import time
+import uuid
+from typing import Dict, Any, Optional
+from pathlib import Path
+import cirq
+import numpy as np
+from qlab.experiment import Experiment
+from qlab.backend import Backend
+from qlab.store import RunRecord  # type: ignore
+from qlab.bloch import density_matrix_to_bloch, bloch_to_html
+
+
+class Runner:
+    """
+    Executes an experiment with given parameters and backend configuration.
+    
+    The runner coordinates experiment execution, result computation,
+    and artifact generation. It does not handle persistence (that's ResultStore's job).
+    """
+    
+    def __init__(self, backend: Backend, base_dir: Optional[Path] = None):
+        """
+        Initialize a runner with a backend.
+        
+        Args:
+            backend: The backend to use for circuit execution.
+            base_dir: Base directory for storing results and artifacts.
+                     If None, defaults to current directory.
+        """
+        self.backend = backend
+        self.base_dir = Path(base_dir) if base_dir else Path.cwd()
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        (self.base_dir / "results").mkdir(exist_ok=True)
+        (self.base_dir / "artifacts").mkdir(exist_ok=True)
+    
+    def run(
+        self,
+        experiment: Experiment,
+        params: Dict[str, Any],
+        config: Optional[Dict[str, Any]] = None
+    ) -> RunRecord:
+        """
+        Execute an experiment and return a run record.
+        
+        Args:
+            experiment: The experiment to run.
+            params: Parameters for the experiment's circuit builder.
+            config: Optional configuration (e.g., qubit selection, metadata).
+                   Defaults to using a single qubit.
+                   
+        Returns:
+            RunRecord containing:
+            - Experiment name and parameters
+            - Density matrix result
+            - Generated artifacts (e.g., Bloch sphere HTML)
+            - Metadata (timestamp, backend name, etc.)
+        """
+        config = config or {}
+        
+        # Generate run ID
+        run_id = str(uuid.uuid4())
+        timestamp = time.time()
+        
+        # Create qubit (default to GridQubit(0, 0) if not specified)
+        qubit = config.get("qubit", cirq.GridQubit(0, 0))
+        
+        # Build circuit
+        circuit = experiment.build_circuit(qubit, params)
+        
+        # Execute circuit
+        rho = self.backend.run(circuit)
+        
+        # Save density matrix
+        rho_path = f"results/{run_id}_rho.npy"
+        np.save(self.base_dir / rho_path, rho)
+        
+        # Generate Bloch sphere visualization
+        x, y, z = density_matrix_to_bloch(rho)
+        html_content = bloch_to_html(x, y, z, title=f"{experiment.name} - {run_id[:8]}")
+        html_path = f"artifacts/{run_id}_bloch.html"
+        (self.base_dir / html_path).write_text(html_content)
+        
+        # Create artifacts dict
+        artifacts = {"bloch_sphere": html_path}
+        
+        # Build metadata
+        metadata = config.get("metadata", {})
+        metadata["qubit"] = str(qubit)
+        
+        # Create RunRecord
+        record = RunRecord(
+            run_id=run_id,
+            experiment_name=experiment.name,
+            params=params,
+            backend_name=self.backend.get_name(),
+            timestamp=timestamp,
+            density_matrix_path=rho_path,
+            artifacts=artifacts,
+            metadata=metadata
+        )
+        
+        return record

qlab/store.py

@@ -0,0 +1,269 @@
+"""
+ResultStore: SQLite persistence for runs, results, and artifacts.
+"""
+
+from typing import List, Optional, Dict, Any
+from pathlib import Path
+import json
+import sqlite3
+import numpy as np
+import uuid
+
+
+class RunRecord:
+    """
+    Metadata and references for a single experiment run.
+    
+    Contains:
+    - Run ID (UUID or auto-increment)
+    - Experiment name
+    - Parameters dictionary (JSON-serializable)
+    - Backend name
+    - Timestamp
+    - Path to density matrix file (numpy .npy)
+    - Path to artifacts (e.g., Bloch sphere HTML)
+    - Additional metadata
+    """
+    
+    def __init__(
+        self,
+        run_id: str,
+        experiment_name: str,
+        params: Dict[str, Any],
+        backend_name: str,
+        timestamp: float,
+        density_matrix_path: str,
+        artifacts: Dict[str, str],  # artifact_name -> file_path
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize a run record.
+        
+        Args:
+            run_id: Unique identifier for this run.
+            experiment_name: Name of the experiment.
+            params: Parameters used for this run.
+            backend_name: Name of the backend used.
+            timestamp: Unix timestamp of when run was executed.
+            density_matrix_path: Path to saved density matrix (.npy file).
+            artifacts: Dictionary mapping artifact names to file paths.
+            metadata: Optional additional metadata.
+        """
+        self.run_id = run_id
+        self.experiment_name = experiment_name
+        self.params = params
+        self.backend_name = backend_name
+        self.timestamp = timestamp
+        self.density_matrix_path = density_matrix_path
+        self.artifacts = artifacts
+        self.metadata = metadata or {}
+        self._base_dir: Optional[Path] = None  # Set by ResultStore when loading
+    
+    def set_base_dir(self, base_dir: Path) -> None:
+        """Set the base directory for resolving relative paths."""
+        self._base_dir = base_dir
+    
+    def get_density_matrix(self) -> np.ndarray:
+        """
+        Load and return the density matrix for this run.
+        
+        Returns:
+            2x2 density matrix (complex dtype).
+        """
+        if self._base_dir is None:
+            raise ValueError("Base directory not set. Use ResultStore.get_run() to load records.")
+        full_path = self._base_dir / self.density_matrix_path
+        return np.load(full_path)
+
+
+class ResultStore:
+    """
+    SQLite-based persistence layer for experiment runs.
+    
+    Stores run metadata, density matrices, and artifact references.
+    Provides query interface for retrieving runs.
+    """
+    
+    def __init__(self, db_path: Path):
+        """
+        Initialize the result store.
+        
+        Args:
+            db_path: Path to SQLite database file.
+                    If file doesn't exist, it will be created with schema.
+        """
+        self.db_path = Path(db_path).resolve()
+        self.base_dir = self.db_path.parent
+        self.conn = sqlite3.connect(str(self.db_path))
+        self.conn.row_factory = sqlite3.Row
+        self._initialize_schema()
+        self._ensure_directories()
+    
+    def _initialize_schema(self) -> None:
+        """Create database tables if they don't exist."""
+        cursor = self.conn.cursor()
+        
+        # Create runs table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS runs (
+                run_id TEXT PRIMARY KEY,
+                experiment_name TEXT NOT NULL,
+                params TEXT NOT NULL,
+                backend_name TEXT NOT NULL,
+                timestamp REAL NOT NULL,
+                density_matrix_path TEXT NOT NULL,
+                metadata TEXT
+            )
+        """)
+        
+        # Create artifacts table
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS artifacts (
+                artifact_id INTEGER PRIMARY KEY AUTOINCREMENT,
+                run_id TEXT NOT NULL,
+                artifact_name TEXT NOT NULL,
+                artifact_path TEXT NOT NULL,
+                artifact_type TEXT NOT NULL,
+                FOREIGN KEY (run_id) REFERENCES runs(run_id)
+            )
+        """)
+        
+        # Create indexes
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_runs_experiment_name 
+            ON runs(experiment_name)
+        """)
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_runs_timestamp 
+            ON runs(timestamp)
+        """)
+        cursor.execute("""
+            CREATE INDEX IF NOT EXISTS idx_artifacts_run_id 
+            ON artifacts(run_id)
+        """)
+        
+        self.conn.commit()
+    
+    def _ensure_directories(self) -> None:
+        """Create results and artifacts directories if they don't exist."""
+        (self.base_dir / "results").mkdir(parents=True, exist_ok=True)
+        (self.base_dir / "artifacts").mkdir(parents=True, exist_ok=True)
+    
+    def save_run(self, record: RunRecord) -> None:
+        """
+        Persist a run record to the database.
+        
+        Args:
+            record: The RunRecord to save.
+        """
+        cursor = self.conn.cursor()
+        
+        # Save run metadata
+        cursor.execute("""
+            INSERT INTO runs (run_id, experiment_name, params, backend_name, 
+                           timestamp, density_matrix_path, metadata)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """, (
+            record.run_id,
+            record.experiment_name,
+            json.dumps(record.params),
+            record.backend_name,
+            record.timestamp,
+            record.density_matrix_path,
+            json.dumps(record.metadata) if record.metadata else None
+        ))
+        
+        # Save artifacts
+        for artifact_name, artifact_path in record.artifacts.items():
+            # Determine artifact type from extension
+            artifact_type = "text/html" if artifact_path.endswith(".html") else "application/octet-stream"
+            cursor.execute("""
+                INSERT INTO artifacts (run_id, artifact_name, artifact_path, artifact_type)
+                VALUES (?, ?, ?, ?)
+            """, (record.run_id, artifact_name, artifact_path, artifact_type))
+        
+        self.conn.commit()
+    
+    def get_run(self, run_id: str) -> Optional[RunRecord]:
+        """
+        Retrieve a run record by ID.
+        
+        Args:
+            run_id: The run ID to look up.
+            
+        Returns:
+            RunRecord if found, None otherwise.
+        """
+        cursor = self.conn.cursor()
+        
+        # Get run metadata
+        cursor.execute("SELECT * FROM runs WHERE run_id = ?", (run_id,))
+        row = cursor.fetchone()
+        if row is None:
+            return None
+        
+        # Get artifacts
+        cursor.execute("""
+            SELECT artifact_name, artifact_path 
+            FROM artifacts 
+            WHERE run_id = ?
+        """, (run_id,))
+        artifacts = {row["artifact_name"]: row["artifact_path"] for row in cursor.fetchall()}
+        
+        # Build RunRecord
+        record = RunRecord(
+            run_id=row["run_id"],
+            experiment_name=row["experiment_name"],
+            params=json.loads(row["params"]),
+            backend_name=row["backend_name"],
+            timestamp=row["timestamp"],
+            density_matrix_path=row["density_matrix_path"],
+            artifacts=artifacts,
+            metadata=json.loads(row["metadata"]) if row["metadata"] else None
+        )
+        record.set_base_dir(self.base_dir)
+        return record
+    
+    def list_runs(
+        self,
+        experiment_name: Optional[str] = None,
+        limit: Optional[int] = None
+    ) -> List[RunRecord]:
+        """
+        List run records, optionally filtered by experiment name.
+        
+        Args:
+            experiment_name: Optional filter by experiment name.
+            limit: Optional maximum number of records to return.
+            
+        Returns:
+            List of RunRecord objects, ordered by timestamp (newest first).
+        """
+        cursor = self.conn.cursor()
+        
+        query = "SELECT run_id FROM runs"
+        params = []
+        if experiment_name:
+            query += " WHERE experiment_name = ?"
+            params.append(experiment_name)
+        query += " ORDER BY timestamp DESC"
+        if limit:
+            query += " LIMIT ?"
+            params.append(limit)
+        
+        cursor.execute(query, params)
+        run_ids = [row["run_id"] for row in cursor.fetchall()]
+        
+        records = []
+        for run_id in run_ids:
+            record = self.get_run(run_id)
+            if record:
+                records.append(record)
+        
+        return records
+    
+    def close(self) -> None:
+        """
+        Close the database connection.
+        """
+        self.conn.close()