superquantx 0.1.0__py3-none-any.whl

superquantx/config.py

@@ -0,0 +1,326 @@
+"""Global configuration for SuperQuantX.
+
+This module provides configuration management for the SuperQuantX package,
+including backend settings, default parameters, and runtime options.
+"""
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+import yaml
+
+
+logger = logging.getLogger(__name__)
+
+class Config:
+    """Global configuration class for SuperQuantX."""
+
+    def __init__(self) -> None:
+        """Initialize configuration with defaults."""
+        self._config: Dict[str, Any] = {
+            # Backend configuration
+            "backends": {
+                "default": "auto",
+                "auto_selection_strategy": "performance",  # "performance", "cost", "speed", "accuracy"
+                "fallback_backend": "pennylane",
+                "timeout": 300,  # seconds
+                "max_retries": 3,
+            },
+
+            # Algorithm defaults
+            "algorithms": {
+                "default_shots": 1024,
+                "optimization_level": 1,
+                "seed": None,
+                "max_iterations": 1000,
+                "convergence_tolerance": 1e-6,
+            },
+
+            # Visualization settings
+            "visualization": {
+                "backend": "matplotlib",  # "matplotlib", "plotly", "both"
+                "style": "default",
+                "save_figures": False,
+                "figure_format": "png",
+                "dpi": 150,
+            },
+
+            # Benchmarking configuration
+            "benchmarks": {
+                "default_runs": 5,
+                "include_classical": True,
+                "save_results": True,
+                "results_dir": "benchmark_results",
+            },
+
+            # Logging configuration
+            "logging": {
+                "level": "INFO",
+                "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+                "file": None,  # Log file path, None for console only
+            },
+
+            # Cache settings
+            "cache": {
+                "enabled": True,
+                "directory": ".superquantx_cache",
+                "max_size_mb": 1000,
+                "ttl_hours": 24,
+            },
+
+            # Platform-specific settings
+            "platforms": {
+                "ibm": {
+                    "token": None,
+                    "hub": "ibm-q",
+                    "group": "open",
+                    "project": "main",
+                },
+                "braket": {
+                    "s3_folder": None,
+                    "device_arn": None,
+                },
+                "azure": {
+                    "resource_id": None,
+                    "location": None,
+                },
+                "dwave": {
+                    "token": None,
+                    "solver": None,
+                },
+                "rigetti": {
+                    "api_key": None,
+                    "user_id": None,
+                },
+            },
+
+            # Development settings
+            "development": {
+                "debug": False,
+                "profile": False,
+                "warnings": True,
+            },
+        }
+
+        # Load configuration from files
+        self._load_config_files()
+
+        # Override with environment variables
+        self._load_environment_variables()
+
+    def _load_config_files(self) -> None:
+        """Load configuration from YAML/JSON files."""
+        config_paths = [
+            Path.home() / ".superquantx" / "config.yaml",
+            Path.home() / ".superquantx" / "config.yml",
+            Path.home() / ".superquantx" / "config.json",
+            Path.cwd() / "superquantx_config.yaml",
+            Path.cwd() / "superquantx_config.yml",
+            Path.cwd() / "superquantx_config.json",
+        ]
+
+        for config_path in config_paths:
+            if config_path.exists():
+                try:
+                    with open(config_path) as f:
+                        if config_path.suffix.lower() in [".yaml", ".yml"]:
+                            file_config = yaml.safe_load(f)
+                        else:
+                            file_config = json.load(f)
+
+                    if file_config:
+                        self._merge_config(file_config)
+                        logger.info(f"Loaded configuration from {config_path}")
+
+                except Exception as e:
+                    logger.warning(f"Failed to load config from {config_path}: {e}")
+
+    def _load_environment_variables(self) -> None:
+        """Load configuration from environment variables."""
+        env_mappings = {
+            "SUPERQUANTX_DEFAULT_BACKEND": ("backends", "default"),
+            "SUPERQUANTX_DEFAULT_SHOTS": ("algorithms", "default_shots"),
+            "SUPERQUANTX_LOG_LEVEL": ("logging", "level"),
+            "SUPERQUANTX_CACHE_ENABLED": ("cache", "enabled"),
+            "SUPERQUANTX_DEBUG": ("development", "debug"),
+
+            # Platform tokens
+            "IBM_QUANTUM_TOKEN": ("platforms", "ibm", "token"),
+            "AWS_BRAKET_S3_FOLDER": ("platforms", "braket", "s3_folder"),
+            "AZURE_QUANTUM_RESOURCE_ID": ("platforms", "azure", "resource_id"),
+            "DWAVE_API_TOKEN": ("platforms", "dwave", "token"),
+            "RIGETTI_API_KEY": ("platforms", "rigetti", "api_key"),
+        }
+
+        for env_var, config_path in env_mappings.items():
+            value = os.getenv(env_var)
+            if value is not None:
+                self._set_nested_value(config_path, value)
+
+    def _merge_config(self, new_config: Dict[str, Any]) -> None:
+        """Merge new configuration with existing configuration."""
+        def merge_dicts(base: Dict, update: Dict) -> Dict:
+            for key, value in update.items():
+                if key in base and isinstance(base[key], dict) and isinstance(value, dict):
+                    base[key] = merge_dicts(base[key], value)
+                else:
+                    base[key] = value
+            return base
+
+        self._config = merge_dicts(self._config, new_config)
+
+    def _set_nested_value(self, path: tuple, value: Any) -> None:
+        """Set a nested configuration value."""
+        current = self._config
+        for key in path[:-1]:
+            if key not in current:
+                current[key] = {}
+            current = current[key]
+
+        # Type conversion for common types
+        if isinstance(value, str):
+            if value.lower() in ["true", "false"]:
+                value = value.lower() == "true"
+            elif value.isdigit():
+                value = int(value)
+            elif "." in value and value.replace(".", "").isdigit():
+                value = float(value)
+
+        current[path[-1]] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get configuration value using dot notation."""
+        keys = key.split(".")
+        current = self._config
+
+        try:
+            for k in keys:
+                current = current[k]
+            return current
+        except (KeyError, TypeError):
+            return default
+
+    def set(self, key: str, value: Any) -> None:
+        """Set configuration value using dot notation."""
+        keys = key.split(".")
+        current = self._config
+
+        for k in keys[:-1]:
+            if k not in current:
+                current[k] = {}
+            current = current[k]
+
+        current[keys[-1]] = value
+
+    def update(self, updates: Dict[str, Any]) -> None:
+        """Update configuration with a dictionary of values."""
+        self._merge_config(updates)
+
+    def save(self, path: Optional[Union[str, Path]] = None) -> None:
+        """Save current configuration to file."""
+        if path is None:
+            path = Path.home() / ".superquantx" / "config.yaml"
+        else:
+            path = Path(path)
+
+        # Create directory if it doesn't exist
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            with open(path, "w") as f:
+                yaml.dump(self._config, f, default_flow_style=False, indent=2)
+            logger.info(f"Configuration saved to {path}")
+        except Exception as e:
+            logger.error(f"Failed to save configuration to {path}: {e}")
+
+    def reset(self) -> None:
+        """Reset configuration to defaults."""
+        self.__init__()
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Get configuration as dictionary."""
+        return self._config.copy()
+
+    def print_config(self) -> None:
+        """Print current configuration."""
+        import pprint
+        pprint.pprint(self._config, indent=2)
+
+    def validate(self) -> bool:
+        """Validate current configuration."""
+        # Add validation logic here
+        return True
+
+# Global configuration instance
+config = Config()
+
+def configure(
+    backend: Optional[str] = None,
+    shots: Optional[int] = None,
+    debug: Optional[bool] = None,
+    **kwargs
+) -> None:
+    """Configure SuperQuantX settings.
+    
+    Args:
+        backend: Default backend to use
+        shots: Default number of shots for quantum circuits
+        debug: Enable debug mode
+        **kwargs: Additional configuration parameters
+
+    """
+    updates = {}
+
+    if backend is not None:
+        updates["backends.default"] = backend
+
+    if shots is not None:
+        updates["algorithms.default_shots"] = shots
+
+    if debug is not None:
+        updates["development.debug"] = debug
+
+    # Handle additional keyword arguments
+    for key, value in kwargs.items():
+        updates[key] = value
+
+    # Apply updates
+    for key, value in updates.items():
+        config.set(key, value)
+
+    # Setup logging if level changed
+    if "logging.level" in updates:
+        setup_logging()
+
+def setup_logging() -> None:
+    """Setup logging configuration."""
+    level = getattr(logging, config.get("logging.level", "INFO").upper())
+    format_str = config.get("logging.format")
+    log_file = config.get("logging.file")
+
+    # Configure root logger
+    logging.basicConfig(
+        level=level,
+        format=format_str,
+        filename=log_file,
+        filemode="a" if log_file else None,
+        force=True,
+    )
+
+def get_platform_config(platform: str) -> Dict[str, Any]:
+    """Get configuration for a specific platform.
+    
+    Args:
+        platform: Platform name (e.g., 'ibm', 'braket', 'azure')
+        
+    Returns:
+        Platform configuration dictionary
+
+    """
+    return config.get(f"platforms.{platform}", {})
+
+# Initialize logging on import
+setup_logging()

superquantx/exceptions.py

@@ -0,0 +1,287 @@
+"""Custom exceptions for SuperQuantX.
+
+This module defines custom exceptions used throughout the SuperQuantX library
+to provide clear error messages and proper error handling for quantum-agentic
+AI research workflows.
+"""
+
+from typing import Any, Optional
+
+
+class SuperQuantXError(Exception):
+    """Base exception for all SuperQuantX errors."""
+
+    def __init__(self, message: str, error_code: Optional[str] = None) -> None:
+        """Initialize SuperQuantX base exception.
+        
+        Args:
+            message: Human-readable error message
+            error_code: Optional error code for programmatic handling
+
+        """
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+
+    def __str__(self) -> str:
+        """Return string representation of the error."""
+        if self.error_code:
+            return f"[{self.error_code}] {self.message}"
+        return self.message
+
+
+class BackendError(SuperQuantXError):
+    """Raised when quantum backend operations fail."""
+
+    def __init__(
+        self,
+        message: str,
+        backend_name: Optional[str] = None,
+        original_error: Optional[Exception] = None,
+    ) -> None:
+        """Initialize backend error.
+        
+        Args:
+            message: Error description
+            backend_name: Name of the backend that failed
+            original_error: Original exception that caused this error
+
+        """
+        if backend_name:
+            full_message = f"Backend '{backend_name}': {message}"
+        else:
+            full_message = message
+
+        super().__init__(full_message, error_code="BACKEND_ERROR")
+        self.backend_name = backend_name
+        self.original_error = original_error
+
+
+class BackendNotAvailableError(BackendError):
+    """Raised when a required quantum backend is not available."""
+
+    def __init__(self, backend_name: str, missing_dependencies: Optional[list[str]] = None) -> None:
+        """Initialize backend not available error.
+        
+        Args:
+            backend_name: Name of the unavailable backend
+            missing_dependencies: List of missing dependency packages
+
+        """
+        if missing_dependencies:
+            deps = ", ".join(missing_dependencies)
+            message = f"Backend not available. Missing dependencies: {deps}. Install with: pip install superquantx[{backend_name}]"
+        else:
+            message = f"Backend not available. Install with: pip install superquantx[{backend_name}]"
+
+        super().__init__(message, backend_name, error_code="BACKEND_NOT_AVAILABLE")
+        self.missing_dependencies = missing_dependencies or []
+
+
+class AlgorithmError(SuperQuantXError):
+    """Raised when quantum algorithm operations fail."""
+
+    def __init__(
+        self,
+        message: str,
+        algorithm_name: Optional[str] = None,
+        step: Optional[str] = None,
+    ) -> None:
+        """Initialize algorithm error.
+        
+        Args:
+            message: Error description
+            algorithm_name: Name of the algorithm that failed
+            step: Specific step where the error occurred (e.g., 'fit', 'predict')
+
+        """
+        if algorithm_name and step:
+            full_message = f"{algorithm_name}.{step}(): {message}"
+        elif algorithm_name:
+            full_message = f"{algorithm_name}: {message}"
+        else:
+            full_message = message
+
+        super().__init__(full_message, error_code="ALGORITHM_ERROR")
+        self.algorithm_name = algorithm_name
+        self.step = step
+
+
+class NotFittedError(AlgorithmError):
+    """Raised when an algorithm is used before being fitted."""
+
+    def __init__(self, algorithm_name: str) -> None:
+        """Initialize not fitted error.
+        
+        Args:
+            algorithm_name: Name of the algorithm that needs fitting
+
+        """
+        message = "This algorithm instance is not fitted yet. Call 'fit' with appropriate arguments before using this method."
+        super().__init__(message, algorithm_name, error_code="NOT_FITTED")
+
+
+class InvalidParameterError(SuperQuantXError):
+    """Raised when invalid parameters are provided to algorithms or backends."""
+
+    def __init__(
+        self,
+        parameter_name: str,
+        parameter_value: Any,
+        expected_type: Optional[str] = None,
+        valid_values: Optional[list[Any]] = None,
+    ) -> None:
+        """Initialize invalid parameter error.
+        
+        Args:
+            parameter_name: Name of the invalid parameter
+            parameter_value: The invalid value provided
+            expected_type: Expected type description
+            valid_values: List of valid values (for enumerated parameters)
+
+        """
+        if valid_values:
+            valid_str = ", ".join(map(str, valid_values))
+            message = f"Invalid value for parameter '{parameter_name}': {parameter_value}. Valid values are: {valid_str}"
+        elif expected_type:
+            message = f"Invalid type for parameter '{parameter_name}': got {type(parameter_value).__name__}, expected {expected_type}"
+        else:
+            message = f"Invalid value for parameter '{parameter_name}': {parameter_value}"
+
+        super().__init__(message, error_code="INVALID_PARAMETER")
+        self.parameter_name = parameter_name
+        self.parameter_value = parameter_value
+        self.expected_type = expected_type
+        self.valid_values = valid_values
+
+
+class QuantumCircuitError(SuperQuantXError):
+    """Raised when quantum circuit operations fail."""
+
+    def __init__(
+        self,
+        message: str,
+        circuit_info: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize quantum circuit error.
+        
+        Args:
+            message: Error description
+            circuit_info: Dictionary with circuit information (qubits, gates, etc.)
+
+        """
+        super().__init__(message, error_code="CIRCUIT_ERROR")
+        self.circuit_info = circuit_info or {}
+
+
+class ConfigurationError(SuperQuantXError):
+    """Raised when configuration issues are detected."""
+
+    def __init__(self, message: str, config_key: Optional[str] = None) -> None:
+        """Initialize configuration error.
+        
+        Args:
+            message: Error description
+            config_key: The configuration key that caused the error
+
+        """
+        if config_key:
+            full_message = f"Configuration error for '{config_key}': {message}"
+        else:
+            full_message = f"Configuration error: {message}"
+
+        super().__init__(full_message, error_code="CONFIG_ERROR")
+        self.config_key = config_key
+
+
+class ResearchModeError(SuperQuantXError):
+    """Raised when research-only features are used incorrectly."""
+
+    def __init__(self, message: str, feature_name: Optional[str] = None) -> None:
+        """Initialize research mode error.
+        
+        Args:
+            message: Error description
+            feature_name: Name of the research feature
+
+        """
+        warning_prefix = "⚠️  RESEARCH SOFTWARE WARNING: "
+        if feature_name:
+            full_message = f"{warning_prefix}{feature_name}: {message}"
+        else:
+            full_message = f"{warning_prefix}{message}"
+
+        super().__init__(full_message, error_code="RESEARCH_MODE")
+        self.feature_name = feature_name
+
+
+# Utility functions for error handling
+def validate_backend_available(backend_name: str, backend_instance: Any) -> None:
+    """Validate that a backend is available and properly initialized.
+    
+    Args:
+        backend_name: Name of the backend to validate
+        backend_instance: The backend instance to check
+        
+    Raises:
+        BackendNotAvailableError: If backend is not available
+        BackendError: If backend is improperly initialized
+
+    """
+    if backend_instance is None:
+        raise BackendNotAvailableError(backend_name)
+
+    if hasattr(backend_instance, 'is_available') and not backend_instance.is_available():
+        raise BackendNotAvailableError(backend_name)
+
+
+def validate_fitted(algorithm_instance: Any, algorithm_name: str) -> None:
+    """Validate that an algorithm has been fitted.
+    
+    Args:
+        algorithm_instance: The algorithm instance to check
+        algorithm_name: Name of the algorithm
+        
+    Raises:
+        NotFittedError: If algorithm is not fitted
+
+    """
+    if not getattr(algorithm_instance, 'is_fitted', False):
+        raise NotFittedError(algorithm_name)
+
+
+def validate_parameter(
+    parameter_name: str,
+    parameter_value: Any,
+    expected_type: Optional[type] = None,
+    valid_values: Optional[list[Any]] = None,
+    allow_none: bool = False,
+) -> None:
+    """Validate a parameter value.
+    
+    Args:
+        parameter_name: Name of the parameter
+        parameter_value: Value to validate
+        expected_type: Expected Python type
+        valid_values: List of valid values
+        allow_none: Whether None is an acceptable value
+        
+    Raises:
+        InvalidParameterError: If parameter is invalid
+
+    """
+    if parameter_value is None and allow_none:
+        return
+
+    if parameter_value is None and not allow_none:
+        raise InvalidParameterError(parameter_name, parameter_value, "non-None value")
+
+    if expected_type and not isinstance(parameter_value, expected_type):
+        raise InvalidParameterError(
+            parameter_name,
+            parameter_value,
+            expected_type.__name__
+        )
+
+    if valid_values and parameter_value not in valid_values:
+        raise InvalidParameterError(parameter_name, parameter_value, valid_values=valid_values)