wings-quantum 0.1.0__py3-none-any.whl

wings/__init__.py

@@ -0,0 +1,251 @@
+"""
+Gaussian State Optimizer
+========================
+
+GPU-accelerated variational quantum state preparation for Gaussian wavefunctions.
+
+This package provides high-performance tools for preparing Gaussian quantum states
+using variational quantum algorithms with support for multiple acceleration backends:
+
+- CPU (Qiskit Statevector)
+- GPU (Qiskit Aer)
+- cuStateVec (NVIDIA cuQuantum)
+
+Quick Start
+-----------
+>>> from wings import GaussianOptimizer, OptimizerConfig
+>>>
+>>> # Configure optimization
+>>> config = OptimizerConfig(
+...     n_qubits=8,
+...     sigma=0.5,
+...     use_custatevec=True,  # Enable GPU acceleration
+... )
+>>>
+>>> # Create optimizer and run
+>>> optimizer = GaussianOptimizer(config)
+>>> results = optimizer.optimize_ultra_precision(target_infidelity=1e-10)
+>>> print(f"Fidelity: {results['fidelity']:.12f}")
+
+For production campaigns with thousands of runs:
+
+>>> from wings import run_production_campaign
+>>>
+>>> results = run_production_campaign(
+...     n_qubits=8,
+...     sigma=0.5,
+...     total_runs=1000,
+...     target_infidelity=1e-11,
+... )
+>>> results.print_summary()
+
+Environment Variables
+--------------------
+GSO_BASE_DIR : str
+    Base directory for all data storage (default: ~/.wings)
+GSO_CACHE_DIR : str
+    Directory for coefficient cache
+GSO_CHECKPOINT_DIR : str
+    Directory for optimization checkpoints
+GSO_CAMPAIGN_DIR : str
+    Directory for campaign results
+
+See Also
+--------
+- Documentation: https://gaussian-state-optimizer.readthedocs.io
+- GitHub: https://github.com/yourusername/gaussian-state-optimizer
+"""
+
+__version__ = "0.1.0"
+__author__ = "Joshua M. Courtney"
+__email__ = "joshuamcourtney@gmail.com"
+__license__ = "MIT"
+
+# Version tuple for programmatic comparison
+VERSION = tuple(int(x) for x in __version__.split(".")[:3])
+
+
+# Lazy imports to avoid loading heavy dependencies until needed
+def __getattr__(name: str):
+    """Lazy import of main classes to speed up package import."""
+
+    _public_api = {
+        # Core classes
+        "GaussianOptimizer": ".optimizer",
+        "OptimizerConfig": ".config",
+        "OptimizationPipeline": ".config",
+        "CampaignConfig": ".config",
+        "CampaignResults": ".campaign",
+        "OptimizationManager": ".campaign",
+        "TargetFunction": ".config",
+        # Ansatz classes
+        "DefaultAnsatz": ".ansatz",
+        "CustomHardwareEfficientAnsatz": ".ansatz",
+        "AnsatzProtocol": ".ansatz",
+        # Evaluators
+        "CuStateVecEvaluator": ".evaluators.custatevec",
+        "BatchedCuStateVecEvaluator": ".evaluators.custatevec",
+        "GPUCircuitEvaluator": ".evaluators.gpu",
+        "ThreadSafeCircuitEvaluator": ".evaluators.cpu",
+        "MultiGPUBatchEvaluator": ".evaluators.custatevec",
+        # Convenience functions
+        "run_production_campaign": ".campaign",
+        "quick_optimization": ".campaign",
+        "load_campaign_results": ".campaign",
+        "list_campaigns": ".campaign",
+        # Path configuration
+        "PathConfig": ".paths",
+        "get_path_config": ".paths",
+        # Compatibility
+        "CuQuantumCompat": ".compat",
+        "get_cuda_dtype": ".compat",
+        "get_compute_type": ".compat",
+        "optimize_gaussian_state": ".convenience",
+        "quick_optimize": ".convenience",
+        # Benchmarking
+        "benchmark_gpu": ".benchmarks",
+        "find_gpu_crossover": ".benchmarks",
+        "benchmark_all_backends": ".benchmarks",
+        # Circuit export
+        "build_optimized_circuit": ".export",
+        "export_to_qasm": ".export",
+        "export_to_qasm3": ".export",
+        "save_circuit": ".export",
+    }
+
+    if name in _public_api:
+        import importlib
+
+        module_path = _public_api[name]
+        module = importlib.import_module(module_path, package=__name__)
+        return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# Explicitly define __all__ for `from wings import *`
+__all__ = [
+    # Version info
+    "__version__",
+    "VERSION",
+    # Core classes
+    "GaussianOptimizer",
+    "OptimizerConfig",
+    "OptimizationPipeline",
+    "TargetFunction",
+    "CampaignConfig",
+    "CampaignResults",
+    "OptimizationManager",
+    # Ansatz
+    "DefaultAnsatz",
+    "CustomHardwareEfficientAnsatz",
+    "AnsatzProtocol",
+    # Evaluators
+    "CuStateVecEvaluator",
+    "BatchedCuStateVecEvaluator",
+    "MultiGPUBatchEvaluator",
+    "GPUCircuitEvaluator",
+    "ThreadSafeCircuitEvaluator",
+    # Functions
+    "run_production_campaign",
+    "quick_optimization",
+    "load_campaign_results",
+    "list_campaigns",
+    # Configuration
+    "PathConfig",
+    "get_path_config",
+    # Compatibility
+    "CuQuantumCompat",
+    "get_cuda_dtype",
+    "get_compute_type",
+    "optimize_gaussian_state",
+    "quick_optimize",
+    # Benchmarks
+    "benchmark_gpu",
+    "find_gpu_crossover",
+    "benchmark_all_backends",
+    "build_optimized_circuit",
+    "export_to_qasm",
+    "export_to_qasm3",
+    "save_circuit",
+]
+
+
+def get_backend_info() -> dict:
+    """
+    Get information about available backends.
+
+    Returns
+    -------
+    dict
+        Dictionary containing:
+        - 'cpu': Always True
+        - 'gpu_aer': True if qiskit-aer is available
+        - 'custatevec': True if cuQuantum is available
+        - 'cuda_version': CUDA version string or None
+        - 'gpu_name': GPU device name or None
+    """
+    from typing import Any
+
+    info: dict[str, Any] = {
+        "cpu": True,
+        "gpu_aer": False,
+        "custatevec": False,
+        "cuda_version": None,
+        "gpu_name": None,
+    }
+
+    # Check Qiskit Aer
+    try:
+        from qiskit_aer import AerSimulator
+
+        backend = AerSimulator(method="statevector")
+        info["gpu_aer"] = "GPU" in backend.available_devices()
+    except ImportError:
+        pass
+    except Exception:
+        pass
+
+    # Check cuStateVec
+    try:
+        import cupy as cp
+        from cuquantum.bindings import custatevec
+
+        info["custatevec"] = True
+
+        # Get CUDA info
+        device = cp.cuda.Device(0)
+        info["gpu_name"] = (
+            device.name.decode() if hasattr(device.name, "decode") else str(device.name)
+        )
+
+        cuda_version = cp.cuda.runtime.runtimeGetVersion()
+        major = cuda_version // 1000
+        minor = (cuda_version % 1000) // 10
+        info["cuda_version"] = f"{major}.{minor}"
+    except ImportError:
+        pass
+    except Exception:
+        pass
+
+    return info
+
+
+def print_backend_info() -> None:
+    """Print information about available backends."""
+    info = get_backend_info()
+
+    print("Gaussian State Optimizer - Backend Information")
+    print("=" * 50)
+    print(f"  CPU (Qiskit Statevector): {'✓ Available' if info['cpu'] else '✗ Not available'}")
+    print(f"  GPU (Qiskit Aer):         {'✓ Available' if info['gpu_aer'] else '✗ Not available'}")
+    print(
+        f"  cuStateVec:               {'✓ Available' if info['custatevec'] else '✗ Not available'}"
+    )
+
+    if info["cuda_version"]:
+        print(f"  CUDA Version:             {info['cuda_version']}")
+    if info["gpu_name"]:
+        print(f"  GPU Device:               {info['gpu_name']}")
+
+    print("=" * 50)

wings/adam.py

@@ -0,0 +1,132 @@
+"""Adam optimizer implementations."""
+
+import numpy as np
+
+from .types import FloatArray, ParameterArray
+
+__all__ = [
+    "AdamOptimizer",
+    "AdamWithRestarts",
+]
+
+
+class AdamOptimizer:
+    """
+    Adam optimizer for variational quantum circuits.
+
+    Adam is effective for:
+    - Noisy/stochastic gradients
+    - Escaping shallow local minima via momentum
+    - Adaptive learning rates per parameter
+
+    For VQCs, we combine Adam with exact parameter-shift gradients.
+    """
+
+    def __init__(
+        self,
+        n_params: int,
+        learning_rate: float = 0.01,
+        beta1: float = 0.9,
+        beta2: float = 0.999,
+        epsilon: float = 1e-8,
+        amsgrad: bool = False,
+    ) -> None:
+        self.n_params = n_params
+        self.lr = learning_rate
+        self.beta1 = beta1
+        self.beta2 = beta2
+        self.epsilon = epsilon
+        self.amsgrad = amsgrad
+
+        # Initialize moment estimates
+        self.m = np.zeros(n_params)  # First moment (momentum)
+        self.v = np.zeros(n_params)  # Second moment (RMSprop)
+        self.v_hat_max = np.zeros(n_params)  # For AMSGrad
+        self.t = 0  # Timestep
+
+    def step(self, params: ParameterArray, gradient: FloatArray) -> ParameterArray:
+        """
+        Perform one Adam update step.
+
+        Args:
+            params: Current parameters
+            gradient: Gradient of loss w.r.t. parameters
+
+        Returns:
+            Updated parameters
+        """
+        self.t += 1
+
+        # Update biased first moment estimate
+        self.m = self.beta1 * self.m + (1 - self.beta1) * gradient
+
+        # Update biased second moment estimate
+        self.v = self.beta2 * self.v + (1 - self.beta2) * (gradient**2)
+
+        # Compute bias-corrected estimates
+        m_hat = self.m / (1 - self.beta1**self.t)
+        v_hat = self.v / (1 - self.beta2**self.t)
+
+        if self.amsgrad:
+            # AMSGrad: use maximum of past v_hat values
+            self.v_hat_max = np.maximum(self.v_hat_max, v_hat)
+            v_hat = self.v_hat_max
+
+        # Compute update
+        update = self.lr * m_hat / (np.sqrt(v_hat) + self.epsilon)
+
+        return params - update
+
+    def reset(self) -> None:
+        """Reset optimizer state (for restarts)"""
+        self.m = np.zeros(self.n_params)
+        self.v = np.zeros(self.n_params)
+        self.v_hat_max = np.zeros(self.n_params)
+        self.t = 0
+
+
+class AdamWithRestarts:
+    """
+    Adam optimizer with warm restarts (cosine annealing).
+
+    Learning rate follows cosine schedule and resets periodically,
+    which helps escape local minima.
+    """
+
+    def __init__(
+        self,
+        n_params: int,
+        lr_max: float = 0.05,
+        lr_min: float = 0.001,
+        restart_period: int = 200,  # Steps between restarts
+        restart_mult: float = 1.5,  # Multiply period after each restart
+    ):
+        self.adam = AdamOptimizer(n_params, learning_rate=lr_max)
+        self.lr_max = lr_max
+        self.lr_min = lr_min
+        self.restart_period = restart_period
+        self.restart_mult = restart_mult
+        self.current_period = restart_period
+        self.steps_since_restart = 0
+
+    def get_lr(self) -> float:
+        """Cosine annealing learning rate"""
+        progress = self.steps_since_restart / self.current_period
+        return self.lr_min + 0.5 * (self.lr_max - self.lr_min) * (1 + np.cos(np.pi * progress))
+
+    def step(self, params: np.ndarray, gradient: np.ndarray) -> np.ndarray:
+        """Perform Adam step with cosine LR schedule"""
+        self.steps_since_restart += 1
+
+        # Update learning rate
+        self.adam.lr = self.get_lr()
+
+        # Check for restart
+        if self.steps_since_restart >= self.current_period:
+            self.steps_since_restart = 0
+            self.current_period = int(self.current_period * self.restart_mult)
+            # Partial momentum reset (keep some history)
+            self.adam.m *= 0.5
+            self.adam.v *= 0.8
+
+        return self.adam.step(params, gradient)

wings/ansatz.py

@@ -0,0 +1,207 @@
+from typing import TYPE_CHECKING, Any, Optional, Protocol, Union, runtime_checkable
+
+import numpy as np
+from numpy.typing import NDArray
+from qiskit import QuantumCircuit, QuantumRegister
+from qiskit.circuit import ParameterVector
+
+if TYPE_CHECKING:
+    from .evaluators.custatevec import CuStateVecSimulator
+
+__all__ = [
+    "AnsatzProtocol",
+    "DefaultAnsatz",
+    "CustomHardwareEfficientAnsatz",
+    "get_full_variational_quantum_circuit",  # Deprecated, for backward compat
+]
+
+
+@runtime_checkable
+class AnsatzProtocol(Protocol):
+    """Protocol for custom ansatz implementations."""
+
+    def __call__(
+        self, params: Union[np.ndarray, ParameterVector], n_qubits: int, **_kwargs
+    ) -> QuantumCircuit:
+        """
+        Build parameterized quantum circuit.
+
+        Args:
+            params: Parameter values or ParameterVector
+            n_qubits: Number of qubits
+            **_kwargs: Additional ansatz-specific arguments
+
+        Returns:
+            QuantumCircuit with parameters bound or parameterized
+        """
+        ...
+
+    @property
+    def n_params(self) -> int:
+        """Return number of parameters for given qubit count."""
+        ...
+
+
+class DefaultAnsatz:
+    def __init__(self, n_qubits: int, depth: Optional[int] = None) -> None:
+        self._n_qubits = n_qubits
+        self._depth = depth if depth is not None else n_qubits
+        self._n_params = n_qubits * self._depth
+
+    @property
+    def n_params(self) -> int:
+        return self._n_params
+
+    @property
+    def n_qubits(self) -> int:
+        return self._n_qubits
+
+    @property
+    def layers(self) -> int:
+        return self._depth
+
+    @property
+    def depth(self) -> int:
+        return self._depth
+
+    def __call__(
+        self,
+        params: Union[NDArray[np.float64], ParameterVector],
+        n_qubits: Optional[int] = None,
+        **_kwargs: Any,
+    ) -> QuantumCircuit:
+        """Build the ansatz circuit."""
+        n = n_qubits if n_qubits is not None else self._n_qubits
+        D2 = _kwargs.get("depth", self._depth)
+
+        qr = QuantumRegister(n, name="q")
+        qc = QuantumCircuit(qr)
+
+        # Initial state: |0...01⟩
+        qc.x(n - 1)
+        for i in range(n):
+            qc.ry(params[i], i)
+        for d in range(D2 - 1):
+            for i in range(n - 1):
+                qc.cx(i, i + 1)
+            qc.barrier()
+            for i in range(n):
+                param_idx = n + n * d + i
+                qc.ry(params[param_idx], i)
+
+        return qc
+
+    def get_param_count(self, n_qubits: Optional[int] = None, depth: Optional[int] = None) -> int:
+        """Calculate parameter count for given configuration."""
+        n = n_qubits if n_qubits is not None else self._n_qubits
+        d = depth if depth is not None else self._depth
+        return n * d
+
+
+# Keep old function for backward compatibility
+def get_full_variational_quantum_circuit(thetas, D2, qubits_num, input_state=None):
+    """
+    DEPRECATED: Use DefaultAnsatz class instead.
+
+    Kept for backward compatibility.
+    """
+    ansatz = DefaultAnsatz(qubits_num, depth=D2)
+    return ansatz(thetas, qubits_num, depth=D2)
+
+
+class CustomHardwareEfficientAnsatz:
+    """
+    Example custom ansatz with configurable entanglement pattern.
+
+    Usage:
+        ansatz = CustomHardwareEfficientAnsatz(n_qubits=8, layers=4, entanglement='circular')
+        config = OptimizerConfig(n_qubits=8, ansatz=ansatz)
+        optimizer = GaussianOptimizer(config)
+    """
+
+    def __init__(
+        self,
+        n_qubits: int,
+        layers: int = 4,
+        entanglement: str = "linear",
+        rotation_gates: Optional[list[str]] = None,
+    ) -> None:
+        self._n_qubits = n_qubits
+        self._layers = layers
+        self._entanglement = entanglement
+        self._rotation_gates = rotation_gates or ["ry"]
+
+        # Calculate parameter count
+        rotations_per_layer = n_qubits * len(self._rotation_gates)
+        self._n_params = rotations_per_layer * layers
+
+    @property
+    def n_params(self) -> int:
+        return self._n_params
+
+    @property
+    def depth(self) -> int:
+        return self._layers
+
+    def __call__(
+        self, params: Union[np.ndarray, ParameterVector], n_qubits: int = None, **_kwargs
+    ) -> QuantumCircuit:
+        n = n_qubits or self._n_qubits
+        qc = QuantumCircuit(n)
+
+        param_idx = 0
+        for layer in range(self._layers):
+            # Rotation block
+            for qubit in range(n):
+                for gate_name in self._rotation_gates:
+                    if gate_name == "ry":
+                        qc.ry(params[param_idx], qubit)
+                    elif gate_name == "rx":
+                        qc.rx(params[param_idx], qubit)
+                    elif gate_name == "rz":
+                        qc.rz(params[param_idx], qubit)
+                    param_idx += 1
+
+            # Entanglement block (skip on last layer)
+            if layer < self._layers - 1:
+                if self._entanglement == "linear":
+                    for i in range(n - 1):
+                        qc.cx(i, i + 1)
+                elif self._entanglement == "circular":
+                    for i in range(n - 1):
+                        qc.cx(i, i + 1)
+                    qc.cx(n - 1, 0)
+                elif self._entanglement == "full":
+                    for i in range(n):
+                        for j in range(i + 1, n):
+                            qc.cx(i, j)
+
+        return qc
+
+    def apply_custatevec(
+        self, simulator: "CuStateVecSimulator", params: NDArray[np.float64]
+    ) -> None:
+        """Native cuStateVec implementation for speed."""
+        n = self._n_qubits
+        param_idx = 0
+
+        simulator.reset_state()
+
+        for layer in range(self._layers):
+            # Rotations
+            for qubit in range(n):
+                for gate_name in self._rotation_gates:
+                    if gate_name == "ry":
+                        simulator.apply_ry(float(params[param_idx]), qubit)
+                    # Add rx, rz if simulator supports them
+                    param_idx += 1
+
+            # Entanglement
+            if layer < self._layers - 1:
+                if self._entanglement == "linear":
+                    for i in range(n - 1):
+                        simulator.apply_cnot(i, i + 1)
+                elif self._entanglement == "circular":
+                    for i in range(n - 1):
+                        simulator.apply_cnot(i, i + 1)
+                    simulator.apply_cnot(n - 1, 0)