wings-quantum 0.1.0__py3-none-any.whl

wings/paths.py

@@ -0,0 +1,295 @@
+import getpass
+import os
+from pathlib import Path
+from typing import Optional
+
+__all__ = [
+    "PathConfig",
+    "get_path_config",
+    "LIB_DIR",
+    "CACHE_DIR",
+    "OUTPUT_DIR",
+    "DATA_DIR",
+    "CHECKPOINT_DIR",
+    "CAMPAIGN_DIR",
+]
+
+
+class PathConfig:
+    """
+    Portable path configuration that works across HPC, local, and cloud systems.
+
+    Resolution order for each path:
+    1. Environment variable (if set)
+    2. HPC-specific path (if exists)
+    3. Cross-platform default (always works)
+
+    Environment variables:
+        GSO_LIB_DIR        - Library/dependency storage
+        GSO_CACHE_DIR      - Coefficient cache
+        GSO_OUTPUT_DIR     - Simulation outputs
+        GSO_DATA_DIR       - Simulation data
+        GSO_CHECKPOINT_DIR - Optimization checkpoints
+        GSO_CAMPAIGN_DIR   - Campaign results
+        GSO_BASE_DIR       - Override base directory for all paths
+
+    Usage:
+        paths = PathConfig()
+        print(paths.cache_dir)  # Returns appropriate path for current system
+
+        # Or with custom base:
+        paths = PathConfig(base_dir="/custom/path")
+    """
+
+    def __init__(self, base_dir: Optional[str] = None, verbose: bool = True):
+        self._verbose = verbose
+        self._username = getpass.getuser()
+
+        # Determine base directory
+        self._base_dir = self._resolve_base_dir(base_dir)
+
+        # Initialize all paths
+        self._lib_dir: Optional[Path] = None
+        self._cache_dir: Optional[Path] = None
+        self._output_dir: Optional[Path] = None
+        self._data_dir: Optional[Path] = None
+        self._checkpoint_dir: Optional[Path] = None
+        self._campaign_dir: Optional[Path] = None
+
+        # Lazily initialized
+        self._initialized = False
+
+    def _resolve_base_dir(self, override: Optional[str]) -> Path:
+        """Determine the base directory for all paths."""
+        # 1. Explicit override
+        if override is not None:
+            return Path(override)
+
+        # 2. Environment variable
+        env_base = os.environ.get("GSO_BASE_DIR")
+        if env_base:
+            return Path(env_base)
+
+        # 3. HPC scratch directory (common patterns)
+        hpc_scratch_patterns = [
+            f"/scratch/{self._username}",  # SLURM standard
+            f"/scratch/users/{self._username}",  # Some clusters
+            f"/work/{self._username}",  # PBS/Torque
+            f"/gpfs/scratch/{self._username}",  # GPFS-based
+            f"/lustre/scratch/{self._username}",  # Lustre-based
+            os.environ.get("SCRATCH", ""),  # $SCRATCH env var
+            os.environ.get("WORK", ""),  # $WORK env var
+        ]
+
+        for pattern in hpc_scratch_patterns:
+            if pattern and Path(pattern).exists():
+                if self._verbose:
+                    print(f"Detected HPC scratch directory: {pattern}")
+                return Path(pattern)
+
+        # 4. Cross-platform default: user's home directory
+        home = Path.home()
+        default_base = home / ".wings"
+
+        if self._verbose:
+            print(f"Using default base directory: {default_base}")
+
+        return default_base
+
+    def _get_path(
+        self, env_var: str, subdir: str, hpc_alternatives: Optional[list[str]] = None
+    ) -> Path:
+        """
+        Resolve a path with environment override and HPC detection.
+
+        Args:
+            env_var: Environment variable name to check
+            subdir: Subdirectory name under base_dir
+            hpc_alternatives: Alternative HPC paths to check
+        """
+        # 1. Environment variable override
+        env_value = os.environ.get(env_var)
+        if env_value:
+            return Path(env_value)
+
+        # 2. Check HPC alternatives
+        if hpc_alternatives:
+            for alt in hpc_alternatives:
+                alt_path = Path(alt.format(username=self._username))
+                if alt_path.parent.exists():
+                    return alt_path
+
+        # 3. Default: subdirectory of base
+        return self._base_dir / subdir
+
+    def _ensure_initialized(self) -> None:
+        """Lazily initialize and create all directories."""
+        if self._initialized:
+            return
+
+        # Resolve all paths
+        self._lib_dir = self._get_path("GSO_LIB_DIR", "lib", ["/home/{username}/lib"])
+
+        self._cache_dir = self._get_path(
+            "GSO_CACHE_DIR", "cache/coefficients", ["/scratch/{username}/coefficient_cache"]
+        )
+
+        self._output_dir = self._get_path(
+            "GSO_OUTPUT_DIR", "output", ["/scratch/{username}/simulation_output"]
+        )
+
+        self._data_dir = self._get_path(
+            "GSO_DATA_DIR", "data", ["/scratch/{username}/simulation_data"]
+        )
+
+        self._checkpoint_dir = self._get_path(
+            "GSO_CHECKPOINT_DIR", "checkpoints", ["/scratch/{username}/optimization_checkpoints"]
+        )
+
+        self._campaign_dir = self._get_path(
+            "GSO_CAMPAIGN_DIR", "campaigns", ["/scratch/{username}/optimization_campaigns"]
+        )
+
+        # Create all directories
+        all_dirs = [
+            self._lib_dir,
+            self._cache_dir,
+            self._output_dir,
+            self._data_dir,
+            self._checkpoint_dir,
+            self._campaign_dir,
+        ]
+
+        for directory in all_dirs:
+            try:
+                directory.mkdir(parents=True, exist_ok=True)
+                if self._verbose:
+                    print(f"Created/verified directory: {directory}")
+            except PermissionError as e:
+                print(f"Warning: Cannot create {directory}: {e}")
+                print(f"  Set {self._env_var_for_path(directory)} to override")
+
+        self._initialized = True
+
+    def _env_var_for_path(self, path: Path) -> str:
+        """Get the environment variable name for a path (for error messages)."""
+        mapping = {
+            self._lib_dir: "GSO_LIB_DIR",
+            self._cache_dir: "GSO_CACHE_DIR",
+            self._output_dir: "GSO_OUTPUT_DIR",
+            self._data_dir: "GSO_DATA_DIR",
+            self._checkpoint_dir: "GSO_CHECKPOINT_DIR",
+            self._campaign_dir: "GSO_CAMPAIGN_DIR",
+        }
+        return mapping.get(path, "GSO_BASE_DIR")
+
+    @property
+    def lib_dir(self) -> Path:
+        self._ensure_initialized()
+        return self._lib_dir
+
+    @property
+    def cache_dir(self) -> Path:
+        self._ensure_initialized()
+        return self._cache_dir
+
+    @property
+    def output_dir(self) -> Path:
+        self._ensure_initialized()
+        return self._output_dir
+
+    @property
+    def data_dir(self) -> Path:
+        self._ensure_initialized()
+        return self._data_dir
+
+    @property
+    def checkpoint_dir(self) -> Path:
+        self._ensure_initialized()
+        return self._checkpoint_dir
+
+    @property
+    def campaign_dir(self) -> Path:
+        self._ensure_initialized()
+        return self._campaign_dir
+
+    def summary(self) -> str:
+        """Return a summary of all configured paths."""
+        self._ensure_initialized()
+        lines = [
+            "Path Configuration:",
+            f"  Base:        {self._base_dir}",
+            f"  Library:     {self._lib_dir}",
+            f"  Cache:       {self._cache_dir}",
+            f"  Output:      {self._output_dir}",
+            f"  Data:        {self._data_dir}",
+            f"  Checkpoints: {self._checkpoint_dir}",
+            f"  Campaigns:   {self._campaign_dir}",
+        ]
+        return "\n".join(lines)
+
+
+# Initialize global path configuration
+# This replaces the old hardcoded paths
+_path_config: Optional[PathConfig] = None
+
+
+def get_path_config(base_dir: Optional[str] = None, verbose: bool = True) -> PathConfig:
+    """
+    Get or create the global path configuration.
+
+    Call with base_dir to override on first use:
+        paths = get_path_config(base_dir="/my/custom/path")
+
+    Subsequent calls return the same instance:
+        paths = get_path_config()  # Returns existing config
+    """
+    global _path_config
+    if _path_config is None:
+        _path_config = PathConfig(base_dir=base_dir, verbose=verbose)
+    return _path_config
+
+
+# For backward compatibility, create module-level path variables
+# These are now properties that resolve lazily
+class _LazyPath:
+    """Descriptor for lazy path resolution with backward compatibility."""
+
+    def __init__(self, attr_name: str):
+        self.attr_name = attr_name
+
+    def __get__(self, obj, objtype=None) -> Path:
+        return getattr(get_path_config(verbose=False), self.attr_name)
+
+
+class _PathNamespace:
+    """Namespace providing backward-compatible path access."""
+
+    lib_dir = _LazyPath("lib_dir")
+    cache_dir = _LazyPath("cache_dir")
+    output_dir = _LazyPath("output_dir")
+    data_dir = _LazyPath("data_dir")
+    checkpoint_dir = _LazyPath("checkpoint_dir")
+    campaign_dir = _LazyPath("campaign_dir")
+
+
+_paths = _PathNamespace()
+
+# Backward-compatible module-level constants
+# These now dynamically resolve to the correct paths
+LIB_DIR = property(lambda _self: get_path_config(verbose=False).lib_dir)
+CACHE_DIR = property(lambda _self: get_path_config(verbose=False).cache_dir)
+OUTPUT_DIR = property(lambda _self: get_path_config(verbose=False).output_dir)
+DATA_DIR = property(lambda _self: get_path_config(verbose=False).data_dir)
+CHECKPOINT_DIR = property(lambda _self: get_path_config(verbose=False).checkpoint_dir)
+CAMPAIGN_DIR = property(lambda _self: get_path_config(verbose=False).campaign_dir)
+
+# Actually, for true backward compatibility at module level, use this simpler approach:
+# Initialize paths on module load
+_pc = get_path_config(verbose=False)
+LIB_DIR = _pc.lib_dir
+CACHE_DIR = _pc.cache_dir
+OUTPUT_DIR = _pc.output_dir
+DATA_DIR = _pc.data_dir
+CHECKPOINT_DIR = _pc.checkpoint_dir
+CAMPAIGN_DIR = _pc.campaign_dir

wings/py.typed

@@ -0,0 +1,2 @@
+# PEP 561 marker file
+# This file indicates that the package supports type checking

wings/results.py

@@ -0,0 +1,255 @@
+"""Result classes for optimization campaigns."""
+
+import json
+import os
+import pickle
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .config import CampaignConfig
+
+__all__ = [
+    "RunResult",
+    "CampaignResults",
+]
+
+
+@dataclass
+class RunResult:
+    run_id: int
+    fidelity: float
+    infidelity: float
+    params: NDArray[np.float64]
+    circuit_std: float
+    circuit_mean: float
+    time_seconds: float
+    n_evaluations: int
+    strategy: str
+    seed: int
+    success: bool
+    error_message: Optional[str] = None
+
+    def to_dict(self) -> dict:
+        """Convert to serializable dictionary"""
+        return {
+            "run_id": self.run_id,
+            "strategy": self.strategy,
+            "seed": self.seed,
+            "fidelity": float(self.fidelity),
+            "infidelity": float(self.infidelity),
+            "params": self.params.tolist() if self.params is not None else None,
+            "circuit_std": float(self.circuit_std) if self.circuit_std else None,
+            "circuit_mean": float(self.circuit_mean) if self.circuit_mean else None,
+            "n_evaluations": self.n_evaluations,
+            "time_seconds": float(self.time_seconds),
+            "success": self.success,
+            "error_message": self.error_message,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RunResult":
+        """Create from dictionary"""
+        d = d.copy()
+        if d.get("params") is not None:
+            d["params"] = np.array(d["params"])
+        return cls(**d)
+
+
+class CampaignResults:
+    """
+    Aggregates and analyzes results from optimization campaign.
+
+    Tracks:
+    - All run results
+    - Best results found
+    - Statistics across runs
+    - Convergence analysis
+    """
+
+    def __init__(self, config: CampaignConfig) -> None:
+        self.config: CampaignConfig = config
+        self.results: list[RunResult] = []
+        self._top_results: list[RunResult] = []
+        self.best_result: Optional[RunResult] = None
+        self.completed_runs: int = 0
+        self.failed_runs: int = 0
+        self.start_time: Optional[float] = None
+        self.end_time: Optional[float] = None
+
+        # Track top N results
+        self._top_n = config.save_top_n_results
+
+    def add_result(self, result: RunResult) -> None:
+        """Add a run result and update tracking"""
+        self.results.append(result)
+        self.completed_runs += 1
+
+        if not result.success:
+            self.failed_runs += 1
+            return
+
+        # Update best result
+        if self.best_result is None or result.fidelity > self.best_result.fidelity:
+            self.best_result = result
+            if self.config.verbose >= 1:
+                print(
+                    f"   New best: Run {result.run_id}, F={result.fidelity:.12f}, "
+                    f"1-F={result.infidelity:.3e}"
+                )
+
+        # Update top N
+        self._update_top_results(result)
+
+    def _update_top_results(self, result: RunResult):
+        """Maintain sorted list of top N results"""
+        self._top_results.append(result)
+        self._top_results.sort(key=lambda x: x.fidelity, reverse=True)
+        if len(self._top_results) > self._top_n:
+            self._top_results = self._top_results[: self._top_n]
+
+    def get_top_results(self, n: int = None) -> list[RunResult]:
+        """Get top N results by fidelity"""
+        if n is None:
+            n = self._top_n
+        return self._top_results[:n]
+
+    def get_statistics(self) -> dict[str, Any]:
+        """Compute statistics across all successful runs"""
+        successful = [r for r in self.results if r.success]
+
+        if not successful:
+            return {"error": "No successful runs"}
+
+        fidelities = np.array([r.fidelity for r in successful])
+        infidelities = 1 - fidelities
+        times = np.array([r.time_seconds for r in successful])
+        evals = np.array([r.n_evaluations for r in successful])
+
+        # Strategy breakdown
+        strategy_stats = {}
+        for strategy in self.config.strategy_weights:
+            strat_results = [r for r in successful if r.strategy == strategy]
+            if strat_results:
+                strat_fids = [r.fidelity for r in strat_results]
+                strategy_stats[strategy] = {
+                    "count": len(strat_results),
+                    "best_fidelity": max(strat_fids),
+                    "mean_fidelity": np.mean(strat_fids),
+                    "std_fidelity": np.std(strat_fids),
+                }
+
+        return {
+            "total_runs": len(self.results),
+            "successful_runs": len(successful),
+            "failed_runs": self.failed_runs,
+            "success_rate": len(successful) / len(self.results) if self.results else 0,
+            "best_fidelity": float(np.max(fidelities)),
+            "best_infidelity": float(np.min(infidelities)),
+            "mean_fidelity": float(np.mean(fidelities)),
+            "std_fidelity": float(np.std(fidelities)),
+            "median_fidelity": float(np.median(fidelities)),
+            "fidelity_percentiles": {
+                "50": float(np.percentile(fidelities, 50)),
+                "90": float(np.percentile(fidelities, 90)),
+                "95": float(np.percentile(fidelities, 95)),
+                "99": float(np.percentile(fidelities, 99)),
+                "99.9": float(np.percentile(fidelities, 99.9)),
+            },
+            "total_time_seconds": float(np.sum(times)),
+            "mean_time_per_run": float(np.mean(times)),
+            "total_evaluations": int(np.sum(evals)),
+            "mean_evaluations_per_run": float(np.mean(evals)),
+            "strategy_breakdown": strategy_stats,
+            "target_achieved": self.best_result.fidelity >= self.config.target_fidelity
+            if self.best_result
+            else False,
+            "runs_above_target": int(np.sum(fidelities >= self.config.target_fidelity)),
+            "runs_above_acceptable": int(np.sum(infidelities <= self.config.acceptable_infidelity)),
+        }
+
+    def print_summary(self):
+        """Print human-readable summary"""
+        stats = self.get_statistics()
+
+        print("\n" + "=" * 80)
+        print("CAMPAIGN RESULTS SUMMARY")
+        print("=" * 80)
+
+        print(
+            f"\nRuns: {stats['successful_runs']}/{stats['total_runs']} successful "
+            f"({stats['success_rate'] * 100:.1f}%)"
+        )
+
+        print("\nBest Result:")
+        print(f"  Fidelity:     {stats['best_fidelity']:.15f}")
+        print(f"  Infidelity:   {stats['best_infidelity']:.3e}")
+        print(f"  Target:       {self.config.target_infidelity:.0e}")
+        print(f"  Achieved:     {' YES' if stats['target_achieved'] else ' NO'}")
+
+        print("\nFidelity Distribution:")
+        print(f"  Mean:         {stats['mean_fidelity']:.10f}")
+        print(f"  Std:          {stats['std_fidelity']:.3e}")
+        print(f"  Median:       {stats['median_fidelity']:.10f}")
+
+        print("\nFidelity Percentiles:")
+        for pct, val in stats["fidelity_percentiles"].items():
+            print(f"  {pct}%:".ljust(10) + f"{val:.12f}")
+
+        print("\nRuns Meeting Targets:")
+        print(
+            f"  Above target ({self.config.target_infidelity:.0e}):     {stats['runs_above_target']}"
+        )
+        print(
+            f"  Above acceptable ({self.config.acceptable_infidelity:.0e}): {stats['runs_above_acceptable']}"
+        )
+
+        print("\nComputation:")
+        print(f"  Total time:        {stats['total_time_seconds'] / 3600:.2f} hours")
+        print(f"  Mean time/run:     {stats['mean_time_per_run']:.1f}s")
+        print(f"  Total evaluations: {stats['total_evaluations']:,}")
+
+        print("\nStrategy Performance:")
+        for strat, strat_stats in stats["strategy_breakdown"].items():
+            print(f"  {strat}:")
+            print(
+                f"    Runs: {strat_stats['count']}, "
+                f"Best: {strat_stats['best_fidelity']:.10f}, "
+                f"Mean: {strat_stats['mean_fidelity']:.8f}"
+            )
+
+        print("=" * 80)
+
+    def save(self, filepath: str = None):
+        """Save results to disk"""
+        if filepath is None:
+            filepath = os.path.join(self.config.output_dir, "campaign_results.pkl")
+
+        # Save full pickle
+        with open(filepath, "wb") as f:
+            pickle.dump(self, f)
+
+        # Save JSON summary (without params to save space)
+        json_path = filepath.replace(".pkl", "_summary.json")
+        summary = {
+            "config": self.config.to_dict(),
+            "statistics": self.get_statistics(),
+            "best_result": self.best_result.to_dict() if self.best_result else None,
+            "top_results": [r.to_dict() for r in self._top_results],
+        }
+        with open(json_path, "w") as f:
+            json.dump(summary, f, indent=2, default=str)
+
+        # Save best params as numpy
+        if self.best_result is not None:
+            np.save(filepath.replace(".pkl", "_best_params.npy"), self.best_result.params)
+
+        return filepath
+
+    @classmethod
+    def load(cls, filepath: str) -> "CampaignResults":
+        """Load results from disk"""
+        with open(filepath, "rb") as f:
+            return pickle.load(f)

wings/types.py

@@ -0,0 +1,14 @@
+import numpy as np
+from numpy.typing import NDArray
+
+# Type aliases for clarity
+ComplexArray = NDArray[np.complex128]
+FloatArray = NDArray[np.float64]
+ParameterArray = NDArray[np.float64]
+
+__all__ = [
+    "ComplexArray",
+    "FloatArray",
+    "ParameterArray",
+    "NDArray",
+]