Algorithms API Reference

Unverified examples

This page predates the current release and parts of it describe planned or older API. Only 1 of 6 code snippets on this page run as-is today. For verified, runnable code see the Quick Start, the Showcase and the Backends guide.

SuperQuantX provides a comprehensive collection of quantum algorithms for machine learning, optimization, cryptography, and simulation. All algorithms support multiple quantum backends and provide unified interfaces for easy integration.

Base Classes

Base Algorithm

superquantx.algorithms.BaseQuantumAlgorithm

BaseQuantumAlgorithm(backend: str | Any, shots: int = 1024, seed: int | None = None, optimization_level: int = 1, **kwargs)

Bases: ABC

Abstract base class for all quantum machine learning algorithms.

This class defines the common interface that all quantum algorithms must implement, providing consistency across different algorithm types and backends.

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend to use for computation	required
shots	int	Number of measurement shots (default: 1024)	1024
seed	int | None	Random seed for reproducibility	None
optimization_level	int	Circuit optimization level (0-3)	1
**kwargs		Additional algorithm-specific parameters	{}

Initialize the quantum algorithm.

Source code in src/superquantx/algorithms/base_algorithm.py

def __init__(
    self,
    backend: str | Any,
    shots: int = 1024,
    seed: int | None = None,
    optimization_level: int = 1,
    **kwargs
) -> None:
    """Initialize the quantum algorithm."""
    self.backend = self._initialize_backend(backend)
    self.shots = shots
    self.seed = seed
    self.optimization_level = optimization_level

    # Algorithm state
    self.is_fitted = False
    self.training_history = []
    self.best_params = None
    self.best_score = None

    # Store additional parameters
    self.algorithm_params = kwargs

    # Performance tracking
    self.execution_times = []
    self.backend_stats = {}

    logger.info(f"Initialized {self.__class__.__name__} with backend {type(self.backend).__name__}")

Functions

fit abstractmethod

fit(X: ndarray, y: ndarray | None = None, **kwargs) -> BaseQuantumAlgorithm

Train the quantum algorithm.

Parameters:

Name	Type	Description	Default
X	ndarray	Training data features	required
y	ndarray | None	Training data labels (for supervised learning)	None
**kwargs		Additional training parameters	{}

Returns:

Type	Description
BaseQuantumAlgorithm	Self for method chaining

Source code in src/superquantx/algorithms/base_algorithm.py

@abstractmethod
def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> 'BaseQuantumAlgorithm':
    """Train the quantum algorithm.

    Args:
        X: Training data features
        y: Training data labels (for supervised learning)
        **kwargs: Additional training parameters

    Returns:
        Self for method chaining

    """
    pass

predict abstractmethod

predict(X: ndarray, **kwargs) -> np.ndarray

Make predictions using the trained algorithm.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data for prediction	required
**kwargs		Additional prediction parameters	{}

Returns:

Type	Description
ndarray	Predictions array

Source code in src/superquantx/algorithms/base_algorithm.py

@abstractmethod
def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Make predictions using the trained algorithm.

    Args:
        X: Input data for prediction
        **kwargs: Additional prediction parameters

    Returns:
        Predictions array

    """
    pass

score

score(X: ndarray, y: ndarray, **kwargs) -> float

Compute the algorithm's score on the given test data.

Parameters:

Name	Type	Description	Default
X	ndarray	Test data features	required
y	ndarray	True test data labels	required
**kwargs		Additional scoring parameters	{}

Returns:

Type	Description
float	Algorithm score (higher is better)

Source code in src/superquantx/algorithms/base_algorithm.py

def score(self, X: np.ndarray, y: np.ndarray, **kwargs) -> float:
    """Compute the algorithm's score on the given test data.

    Args:
        X: Test data features
        y: True test data labels
        **kwargs: Additional scoring parameters

    Returns:
        Algorithm score (higher is better)

    """
    predictions = self.predict(X, **kwargs)
    return self._compute_score(predictions, y)

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get algorithm parameters.

Parameters:

Name	Type	Description	Default
deep	bool	Whether to return deep copy of parameters	True

Returns:

Type	Description
dict[str, Any]	Parameter dictionary

Source code in src/superquantx/algorithms/base_algorithm.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get algorithm parameters.

    Args:
        deep: Whether to return deep copy of parameters

    Returns:
        Parameter dictionary

    """
    params = {
        'backend': self.backend,
        'shots': self.shots,
        'seed': self.seed,
        'optimization_level': self.optimization_level,
    }
    params.update(self.algorithm_params)
    return params

set_params

set_params(**params) -> BaseQuantumAlgorithm

Set algorithm parameters.

Parameters:

Name	Type	Description	Default
**params		Parameters to set	{}

Returns:

Type	Description
BaseQuantumAlgorithm	Self for method chaining

Source code in src/superquantx/algorithms/base_algorithm.py

def set_params(self, **params) -> 'BaseQuantumAlgorithm':
    """Set algorithm parameters.

    Args:
        **params: Parameters to set

    Returns:
        Self for method chaining

    """
    for key, value in params.items():
        if hasattr(self, key):
            setattr(self, key, value)
        else:
            self.algorithm_params[key] = value
    return self

save_model

save_model(filepath: str) -> None

Save the trained model to disk.

Parameters:

Name	Type	Description	Default
filepath	str	Path where to save the model	required

Source code in src/superquantx/algorithms/base_algorithm.py

def save_model(self, filepath: str) -> None:
    """Save the trained model to disk.

    Args:
        filepath: Path where to save the model

    """
    import pickle

    if not self.is_fitted:
        logger.warning("Model is not fitted yet. Saving unfitted model.")

    model_data = {
        'class': self.__class__.__name__,
        'params': self.get_params(),
        'is_fitted': self.is_fitted,
        'training_history': self.training_history,
        'best_params': self.best_params,
        'best_score': self.best_score,
    }

    with open(filepath, 'wb') as f:
        pickle.dump(model_data, f)

    logger.info(f"Model saved to {filepath}")

load_model classmethod

load_model(filepath: str) -> BaseQuantumAlgorithm

Load a trained model from disk.

Parameters:

Name	Type	Description	Default
filepath	str	Path to the saved model	required

Returns:

Type	Description
BaseQuantumAlgorithm	Loaded algorithm instance

Source code in src/superquantx/algorithms/base_algorithm.py

@classmethod
def load_model(cls, filepath: str) -> 'BaseQuantumAlgorithm':
    """Load a trained model from disk.

    Args:
        filepath: Path to the saved model

    Returns:
        Loaded algorithm instance

    """
    import pickle

    with open(filepath, 'rb') as f:
        model_data = pickle.load(f)

    # Create new instance with saved parameters
    instance = cls(**model_data['params'])
    instance.is_fitted = model_data['is_fitted']
    instance.training_history = model_data['training_history']
    instance.best_params = model_data['best_params']
    instance.best_score = model_data['best_score']

    logger.info(f"Model loaded from {filepath}")
    return instance

benchmark

benchmark(X: ndarray, y: ndarray | None = None, runs: int = 5) -> dict[str, Any]

Benchmark algorithm performance.

Parameters:

Name	Type	Description	Default
X	ndarray	Test data	required
y	ndarray | None	Test labels (optional)	None
runs	int	Number of benchmark runs	5

Returns:

Type	Description
dict[str, Any]	Benchmark results dictionary

Source code in src/superquantx/algorithms/base_algorithm.py

def benchmark(self, X: np.ndarray, y: np.ndarray | None = None, runs: int = 5) -> dict[str, Any]:
    """Benchmark algorithm performance.

    Args:
        X: Test data
        y: Test labels (optional)
        runs: Number of benchmark runs

    Returns:
        Benchmark results dictionary

    """
    execution_times = []
    scores = []

    for i in range(runs):
        start_time = time.time()

        if y is not None:
            score = self.score(X, y)
            scores.append(score)
        else:
            self.predict(X)

        execution_time = time.time() - start_time
        execution_times.append(execution_time)

    results = {
        'execution_times': execution_times,
        'mean_execution_time': np.mean(execution_times),
        'std_execution_time': np.std(execution_times),
        'min_execution_time': np.min(execution_times),
        'max_execution_time': np.max(execution_times),
    }

    if scores:
        results.update({
            'scores': scores,
            'mean_score': np.mean(scores),
            'std_score': np.std(scores),
            'min_score': np.min(scores),
            'max_score': np.max(scores),
        })

    return results

get_circuit_info

get_circuit_info() -> dict[str, Any]

Get information about the quantum circuit.

Returns:

Type	Description
dict[str, Any]	Circuit information dictionary

Source code in src/superquantx/algorithms/base_algorithm.py

def get_circuit_info(self) -> dict[str, Any]:
    """Get information about the quantum circuit.

    Returns:
        Circuit information dictionary

    """
    return {
        'backend': type(self.backend).__name__,
        'shots': self.shots,
        'optimization_level': self.optimization_level,
    }

reset

reset() -> None

Reset algorithm to untrained state.

Source code in src/superquantx/algorithms/base_algorithm.py

def reset(self) -> None:
    """Reset algorithm to untrained state."""
    self.is_fitted = False
    self.training_history = []
    self.best_params = None
    self.best_score = None
    self.execution_times = []
    self.backend_stats = {}

    logger.info(f"Reset {self.__class__.__name__} to untrained state")

Quantum Result

superquantx.algorithms.QuantumResult dataclass

QuantumResult(result: Any, metadata: dict[str, Any], execution_time: float, backend_info: dict[str, Any], error: str | None = None, intermediate_results: dict[str, Any] | None = None)

Container for quantum algorithm results.

This class provides a standardized way to return results from quantum algorithms, including the main result, metadata, and performance metrics.

Attributes:

Name	Type	Description
result	Any	The main algorithm result
metadata	dict[str, Any]	Additional information about the computation
execution_time	float	Time taken to execute the algorithm (seconds)
backend_info	dict[str, Any]	Information about the backend used
error	str | None	Error information if computation failed
intermediate_results	dict[str, Any] | None	Optional intermediate results for debugging

Machine Learning Algorithms

Quantum Support Vector Machine

superquantx.algorithms.QuantumSVM

QuantumSVM(backend: str | Any, feature_map: str | Any | None = 'ZZFeatureMap', feature_map_reps: int = 2, C: float = 1.0, gamma: float | None = None, quantum_kernel: Callable | None = None, shots: int = 1024, normalize_data: bool = True, auto_feature_map_mode: str = 'auto', **kwargs)

Bases: SupervisedQuantumAlgorithm

Quantum Support Vector Machine for classification.

This implementation uses quantum feature maps to transform data into a high-dimensional Hilbert space where linear separation is possible. The quantum kernel is computed using quantum circuits.

The algorithm works by: 1. Encoding classical data into quantum states using feature maps 2. Computing quantum kernels between data points 3. Training a classical SVM using the quantum kernel matrix

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for circuit execution	required
feature_map	str | Any | None	Feature map name ('ZZFeatureMap', 'PauliFeatureMap', 'AmplitudeMap', 'AngleEncoding', 'ZFeatureMap'), a custom object, or "auto" / None to select via the Qmes-inspired recommender.	'ZZFeatureMap'
feature_map_reps	int	Number of repetitions in the feature map	2
C	float	Regularization parameter for SVM	1.0
gamma	float | None	Quantum kernel bandwidth. Features are multiplied by gamma before encoding (after standardisation). Tuning it matters: small bandwidths avoid exponential kernel concentration (Shaydulin and Wild, 2022). None means 1.0.	None
quantum_kernel	Callable | None	Custom quantum kernel function	None
shots	int	Number of measurement shots	1024
auto_feature_map_mode	str	When feature_map is auto/None, selection mode (auto, qmes, or heuristic).	'auto'
**kwargs		Additional parameters	{}

Example

qsvm = QuantumSVM(backend='pennylane', feature_map='ZZFeatureMap') qsvm.fit(X_train, y_train) predictions = qsvm.predict(X_test) accuracy = qsvm.score(X_test, y_test)

Spike: automatic encoding selection (Qmes if installed, else heuristic)

qsvm_auto = QuantumSVM(backend='simulator', feature_map='auto') qsvm_auto.fit(X_train, y_train)

Source code in src/superquantx/algorithms/quantum_svm.py

def __init__(
    self,
    backend: str | Any,
    feature_map: str | Any | None = 'ZZFeatureMap',
    feature_map_reps: int = 2,
    C: float = 1.0,
    gamma: float | None = None,
    quantum_kernel: Callable | None = None,
    shots: int = 1024,
    normalize_data: bool = True,
    auto_feature_map_mode: str = 'auto',
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)

    self.feature_map = feature_map
    self.feature_map_reps = feature_map_reps
    self.C = C
    self.gamma = gamma
    self.quantum_kernel = quantum_kernel
    self.normalize_data = normalize_data
    self.auto_feature_map_mode = auto_feature_map_mode

    # Classical components
    self.svm = None
    self.scaler = StandardScaler() if normalize_data else None

    # Quantum components
    self.kernel_matrix_ = None
    self.feature_map_circuit_ = None
    self.selected_feature_map_: str | Any | None = None
    self.feature_map_recommendation_: dict[str, Any] | None = None

    # Training data storage (needed for kernel computation)
    self.X_train_ = None

    logger.info(
        f"Initialized QuantumSVM with feature_map={feature_map}, "
        f"reps={feature_map_reps}"
    )

Functions

fit

fit(X: ndarray, y: ndarray, **kwargs) -> QuantumSVM

Train the quantum SVM.

Parameters:

Name	Type	Description	Default
X	ndarray	Training data features	required
y	ndarray	Training data labels	required
**kwargs		Additional training parameters	{}

Returns:

Type	Description
QuantumSVM	Self for method chaining

Source code in src/superquantx/algorithms/quantum_svm.py

def fit(self, X: np.ndarray, y: np.ndarray, **kwargs) -> 'QuantumSVM':
    """Train the quantum SVM.

    Args:
        X: Training data features
        y: Training data labels
        **kwargs: Additional training parameters

    Returns:
        Self for method chaining

    """
    logger.info(f"Training QuantumSVM on {X.shape[0]} samples with {X.shape[1]} features")

    # Validate and preprocess data
    super().fit(X, y, **kwargs)

    if self.normalize_data:
        X = self.scaler.fit_transform(X)

    self.X_train_ = X.copy()

    # Resolve auto/manual feature map, then build the circuit
    resolved = self._resolve_feature_map_name(X, y)
    self.feature_map_circuit_ = self._create_feature_map(X.shape[1], resolved)

    # Compute quantum kernel matrix
    logger.info("Computing quantum kernel matrix...")
    self.kernel_matrix_ = self._compute_quantum_kernel(X)

    # Train classical SVM with quantum kernel
    self.svm = SVC(
        kernel='precomputed',
        C=self.C,
    )

    self.svm.fit(self.kernel_matrix_, y)
    self.is_fitted = True

    # Training accuracy straight from the training kernel (X is already scaled)
    train_predictions = self.svm.predict(self.kernel_matrix_)
    train_accuracy = accuracy_score(y, train_predictions)

    self.training_history.append({
        'train_accuracy': train_accuracy,
        'n_support_vectors': self.svm.n_support_,
        'kernel_matrix_shape': self.kernel_matrix_.shape,
        'selected_feature_map': self.selected_feature_map_,
        'feature_map_recommendation': self.feature_map_recommendation_,
    })

    logger.info(f"Training completed. Accuracy: {train_accuracy:.3f}, "
               f"Support vectors: {sum(self.svm.n_support_)}")

    return self

predict

predict(X: ndarray, **kwargs) -> np.ndarray

Make predictions using the trained quantum SVM.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data for prediction	required
**kwargs		Additional prediction parameters	{}

Returns:

Type	Description
ndarray	Predicted labels

Source code in src/superquantx/algorithms/quantum_svm.py

def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Make predictions using the trained quantum SVM.

    Args:
        X: Input data for prediction
        **kwargs: Additional prediction parameters

    Returns:
        Predicted labels

    """
    if not self.is_fitted:
        raise ValueError("Model must be fitted before making predictions")

    if self.normalize_data:
        X = self.scaler.transform(X)

    # Compute kernel matrix between test data and training data
    test_kernel = self._compute_quantum_kernel(X, self.X_train_)

    # Make predictions using the trained SVM
    predictions = self.svm.predict(test_kernel)

    return predictions

predict_proba

predict_proba(X: ndarray, **kwargs) -> np.ndarray

Predict class probabilities.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data for prediction	required
**kwargs		Additional parameters	{}

Returns:

Type	Description
ndarray	Predicted class probabilities

Source code in src/superquantx/algorithms/quantum_svm.py

def predict_proba(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Predict class probabilities.

    Args:
        X: Input data for prediction
        **kwargs: Additional parameters

    Returns:
        Predicted class probabilities

    """
    if not self.is_fitted:
        raise ValueError("Model must be fitted before making predictions")

    if self.normalize_data:
        X = self.scaler.transform(X)

    test_kernel = self._compute_quantum_kernel(X, self.X_train_)

    # Need to recreate SVM with probability=True for probabilities
    if not hasattr(self.svm, 'predict_proba'):
        logger.warning("Probability prediction not available, returning decision scores")
        return self.svm.decision_function(test_kernel)

    return self.svm.predict_proba(test_kernel)

decision_function

decision_function(X: ndarray) -> np.ndarray

Compute decision function values.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data	required

Returns:

Type	Description
ndarray	Decision function values

Source code in src/superquantx/algorithms/quantum_svm.py

def decision_function(self, X: np.ndarray) -> np.ndarray:
    """Compute decision function values.

    Args:
        X: Input data

    Returns:
        Decision function values

    """
    if not self.is_fitted:
        raise ValueError("Model must be fitted before computing decision function")

    if self.normalize_data:
        X = self.scaler.transform(X)

    test_kernel = self._compute_quantum_kernel(X, self.X_train_)
    return self.svm.decision_function(test_kernel)

get_support_vectors

get_support_vectors() -> np.ndarray

Get support vectors from the trained model.

Source code in src/superquantx/algorithms/quantum_svm.py

def get_support_vectors(self) -> np.ndarray:
    """Get support vectors from the trained model."""
    if not self.is_fitted:
        raise ValueError("Model must be fitted to get support vectors")

    return self.X_train_[self.svm.support_]

get_quantum_kernel_matrix

get_quantum_kernel_matrix(X: ndarray | None = None) -> np.ndarray

Get the quantum kernel matrix.

Parameters:

Name	Type	Description	Default
X	ndarray | None	Data to compute kernel matrix for (default: training data)	None

Returns:

Type	Description
ndarray	Quantum kernel matrix

Source code in src/superquantx/algorithms/quantum_svm.py

def get_quantum_kernel_matrix(self, X: np.ndarray | None = None) -> np.ndarray:
    """Get the quantum kernel matrix.

    Args:
        X: Data to compute kernel matrix for (default: training data)

    Returns:
        Quantum kernel matrix

    """
    if X is None:
        if self.kernel_matrix_ is None:
            raise ValueError("No kernel matrix available")
        return self.kernel_matrix_
    else:
        if self.normalize_data:
            X = self.scaler.transform(X)
        return self._compute_quantum_kernel(X)

analyze_kernel

analyze_kernel() -> dict[str, Any]

Analyze properties of the quantum kernel.

Returns:

Type	Description
dict[str, Any]	Dictionary with kernel analysis results

Source code in src/superquantx/algorithms/quantum_svm.py

def analyze_kernel(self) -> dict[str, Any]:
    """Analyze properties of the quantum kernel.

    Returns:
        Dictionary with kernel analysis results

    """
    if self.kernel_matrix_ is None:
        raise ValueError("Model must be fitted to analyze kernel")

    K = self.kernel_matrix_

    # Compute kernel properties
    eigenvalues = np.linalg.eigvals(K)

    analysis = {
        'kernel_shape': K.shape,
        'kernel_rank': np.linalg.matrix_rank(K),
        'condition_number': np.linalg.cond(K),
        'trace': np.trace(K),
        'frobenius_norm': np.linalg.norm(K, 'fro'),
        'eigenvalue_stats': {
            'mean': np.mean(eigenvalues),
            'std': np.std(eigenvalues),
            'min': np.min(eigenvalues),
            'max': np.max(eigenvalues),
        },
        'is_positive_definite': np.all(eigenvalues > 0),
    }

    return analysis

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get algorithm parameters.

Source code in src/superquantx/algorithms/quantum_svm.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get algorithm parameters."""
    params = super().get_params(deep)
    params.update({
        'feature_map': self.feature_map,
        'feature_map_reps': self.feature_map_reps,
        'C': self.C,
        'gamma': self.gamma,
        'normalize_data': self.normalize_data,
        'auto_feature_map_mode': self.auto_feature_map_mode,
    })
    return params

set_params

set_params(**params) -> QuantumSVM

Set algorithm parameters.

Source code in src/superquantx/algorithms/quantum_svm.py

def set_params(self, **params) -> 'QuantumSVM':
    """Set algorithm parameters."""
    if self.is_fitted and any(key in params for key in
                             ['feature_map', 'feature_map_reps', 'C', 'gamma']):
        logger.warning("Changing core parameters requires refitting the model")
        self.is_fitted = False

    return super().set_params(**params)

Quantum Neural Network

superquantx.algorithms.QuantumNN

QuantumNN(backend: str | Any, n_layers: int = 3, architecture: str = 'hybrid', encoding: str = 'angle', entanglement: str = 'linear', measurement: str = 'expectation', optimizer: str = 'adam', learning_rate: float = 0.01, batch_size: int = 32, max_epochs: int = 100, shots: int = 1024, task_type: str = 'classification', **kwargs)

Bases: SupervisedQuantumAlgorithm

Quantum Neural Network for classification and regression.

This implementation uses parameterized quantum circuits as neural network layers, with classical optimization to train the quantum parameters.

The network can be configured with different architectures: - Pure quantum: Only quantum layers - Hybrid: Combination of quantum and classical layers - Variational: Variational quantum circuits with measurement

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for circuit execution	required
n_layers	int	Number of quantum layers	3
architecture	str	Network architecture ('pure', 'hybrid', 'variational')	'hybrid'
encoding	str	Data encoding method ('amplitude', 'angle', 'basis')	'angle'
entanglement	str	Entanglement pattern ('linear', 'circular', 'full')	'linear'
measurement	str	Measurement strategy ('expectation', 'sampling', 'statevector')	'expectation'
optimizer	str	Classical optimizer for training	'adam'
learning_rate	float	Learning rate for training	0.01
batch_size	int	Training batch size	32
shots	int	Number of measurement shots	1024
**kwargs		Additional parameters	{}

Example

qnn = QuantumNN(backend='pennylane', n_layers=3, architecture='hybrid') qnn.fit(X_train, y_train) predictions = qnn.predict(X_test) accuracy = qnn.score(X_test, y_test)

Source code in src/superquantx/algorithms/quantum_nn.py

def __init__(
    self,
    backend: str | Any,
    n_layers: int = 3,
    architecture: str = 'hybrid',
    encoding: str = 'angle',
    entanglement: str = 'linear',
    measurement: str = 'expectation',
    optimizer: str = 'adam',
    learning_rate: float = 0.01,
    batch_size: int = 32,
    max_epochs: int = 100,
    shots: int = 1024,
    task_type: str = 'classification',
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)

    self.n_layers = n_layers
    self.architecture = architecture
    self.encoding = encoding
    self.entanglement = entanglement
    self.measurement = measurement
    self.optimizer_name = optimizer
    self.learning_rate = learning_rate
    self.batch_size = batch_size
    self.max_epochs = max_epochs
    self.task_type = task_type

    # Network components
    self.quantum_layers = []
    self.classical_layers = []
    self.n_qubits = None
    self.n_params = None

    # Training components
    self.weights = None
    self.encoder = LabelEncoder() if task_type == 'classification' else None
    self.scaler = StandardScaler()
    self.optimizer = None

    # Training history
    self.loss_history = []
    self.accuracy_history = []

    logger.info(f"Initialized QuantumNN with {n_layers} layers, architecture={architecture}")

Functions

fit

fit(X: ndarray, y: ndarray, **kwargs) -> QuantumNN

Train the quantum neural network.

Parameters:

Name	Type	Description	Default
X	ndarray	Training data features	required
y	ndarray	Training data labels	required
**kwargs		Additional training parameters	{}

Returns:

Type	Description
QuantumNN	Self for method chaining

Source code in src/superquantx/algorithms/quantum_nn.py

def fit(self, X: np.ndarray, y: np.ndarray, **kwargs) -> 'QuantumNN':
    """Train the quantum neural network.

    Args:
        X: Training data features
        y: Training data labels
        **kwargs: Additional training parameters

    Returns:
        Self for method chaining

    """
    logger.info(f"Training QuantumNN on {X.shape[0]} samples with {X.shape[1]} features")

    # Validate and preprocess data
    super().fit(X, y, **kwargs)

    # Set number of classes for classification BEFORE building network
    if self.task_type == 'classification':
        unique_classes = np.unique(y)
        self.n_classes_ = len(unique_classes)
        logger.info(f"Detected {self.n_classes_} classes for classification: {unique_classes}")

    # Scale features
    X = self.scaler.fit_transform(X)

    # Encode labels for classification after setting n_classes_
    if self.task_type == 'classification' and self.encoder:
        y = self.encoder.fit_transform(y)

    # Determine network architecture
    self.n_qubits = self._determine_qubits(X.shape[1])
    self._build_network()

    # Reset training history
    self.loss_history = []
    self.accuracy_history = []

    logger.info(f"Training network with {self.n_qubits} qubits and {self.n_params} parameters")

    # Training loop
    for epoch in range(self.max_epochs):
        epoch_losses = []
        epoch_accuracies = []

        # Mini-batch training
        for i in range(0, len(X), self.batch_size):
            X_batch = X[i:i + self.batch_size]
            y_batch = y[i:i + self.batch_size]

            # Forward pass
            y_pred = self._forward_pass(X_batch, self.weights)

            # Compute loss
            loss = self._compute_loss(y_batch, y_pred)
            epoch_losses.append(loss)

            # Compute accuracy for classification
            if self.task_type == 'classification':
                y_pred_labels = np.argmax(y_pred, axis=1)
                accuracy = accuracy_score(y_batch, y_pred_labels)
                epoch_accuracies.append(accuracy)

            # Compute gradients and update weights
            gradients = self._compute_gradients(X_batch, y_batch, self.weights)
            self._update_weights(gradients)

        # Record epoch statistics
        epoch_loss = np.mean(epoch_losses)
        self.loss_history.append(epoch_loss)

        if self.task_type == 'classification' and epoch_accuracies:
            epoch_accuracy = np.mean(epoch_accuracies)
            self.accuracy_history.append(epoch_accuracy)

            if epoch % 10 == 0:
                logger.info(f"Epoch {epoch}: Loss = {epoch_loss:.4f}, Accuracy = {epoch_accuracy:.4f}")
        else:
            if epoch % 10 == 0:
                logger.info(f"Epoch {epoch}: Loss = {epoch_loss:.4f}")

        # Early stopping check
        if len(self.loss_history) > 10 and self._check_early_stopping():
            logger.info(f"Early stopping at epoch {epoch}")
            break

    self.is_fitted = True

    # Final training statistics
    final_loss = self.loss_history[-1]
    logger.info(f"Training completed. Final loss: {final_loss:.4f}")

    return self

predict

predict(X: ndarray, **kwargs) -> np.ndarray

Make predictions using the trained quantum neural network.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data for prediction	required
**kwargs		Additional prediction parameters	{}

Returns:

Type	Description
ndarray	Predicted labels or values

Source code in src/superquantx/algorithms/quantum_nn.py

def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Make predictions using the trained quantum neural network.

    Args:
        X: Input data for prediction
        **kwargs: Additional prediction parameters

    Returns:
        Predicted labels or values

    """
    if not self.is_fitted:
        raise ValueError("Model must be fitted before making predictions")

    # Scale features
    X = self.scaler.transform(X)

    # Forward pass
    y_pred = self._forward_pass(X, self.weights)

    if self.task_type == 'classification':
        # Return class labels
        predictions = np.argmax(y_pred, axis=1)
        if self.encoder:
            predictions = self.encoder.inverse_transform(predictions)
        return predictions
    else:
        # Return continuous values for regression
        return y_pred.flatten()

predict_proba

predict_proba(X: ndarray, **kwargs) -> np.ndarray

Predict class probabilities.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data for prediction	required
**kwargs		Additional parameters	{}

Returns:

Type	Description
ndarray	Predicted class probabilities

Source code in src/superquantx/algorithms/quantum_nn.py

def predict_proba(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Predict class probabilities.

    Args:
        X: Input data for prediction
        **kwargs: Additional parameters

    Returns:
        Predicted class probabilities

    """
    if self.task_type != 'classification':
        raise ValueError("predict_proba only available for classification tasks")

    if not self.is_fitted:
        raise ValueError("Model must be fitted before making predictions")

    # Scale features
    X = self.scaler.transform(X)

    # Forward pass returns probabilities for classification
    return self._forward_pass(X, self.weights)

get_circuit_depth

get_circuit_depth() -> int

Get the depth of the quantum circuit.

Source code in src/superquantx/algorithms/quantum_nn.py

def get_circuit_depth(self) -> int:
    """Get the depth of the quantum circuit."""
    if hasattr(self.backend, 'get_circuit_depth'):
        return self.backend.get_circuit_depth(self.quantum_layers)
    else:
        return self.n_layers * 2  # Estimate

get_training_history

get_training_history() -> dict[str, list[float]]

Get training history.

Source code in src/superquantx/algorithms/quantum_nn.py

def get_training_history(self) -> dict[str, list[float]]:
    """Get training history."""
    history = {'loss': self.loss_history}
    if self.accuracy_history:
        history['accuracy'] = self.accuracy_history
    return history

analyze_expressivity

analyze_expressivity() -> dict[str, Any]

Analyze the expressivity of the quantum neural network.

Source code in src/superquantx/algorithms/quantum_nn.py

def analyze_expressivity(self) -> dict[str, Any]:
    """Analyze the expressivity of the quantum neural network."""
    analysis = {
        'n_qubits': self.n_qubits,
        'n_layers': self.n_layers,
        'n_parameters': self.n_params,
        'circuit_depth': self.get_circuit_depth(),
        'entanglement_pattern': self.entanglement,
        'encoding_method': self.encoding,
    }

    # Estimate expressivity metrics
    analysis.update({
        'parameter_space_dimension': self.n_params,
        'hilbert_space_dimension': 2**self.n_qubits,
        'expressivity_ratio': self.n_params / (2**self.n_qubits),
    })

    return analysis

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get quantum neural network parameters.

Source code in src/superquantx/algorithms/quantum_nn.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get quantum neural network parameters."""
    params = super().get_params(deep)
    params.update({
        'n_layers': self.n_layers,
        'architecture': self.architecture,
        'encoding': self.encoding,
        'entanglement': self.entanglement,
        'measurement': self.measurement,
        'optimizer': self.optimizer_name,
        'learning_rate': self.learning_rate,
        'batch_size': self.batch_size,
        'max_epochs': self.max_epochs,
        'task_type': self.task_type,
    })
    return params

set_params

set_params(**params) -> QuantumNN

Set quantum neural network parameters.

Source code in src/superquantx/algorithms/quantum_nn.py

def set_params(self, **params) -> 'QuantumNN':
    """Set quantum neural network parameters."""
    if self.is_fitted and any(key in params for key in
                             ['n_layers', 'architecture', 'encoding', 'entanglement']):
        logger.warning("Changing core parameters requires refitting the model")
        self.is_fitted = False

    return super().set_params(**params)

superquantx.algorithms.QuantumNeuralNetwork module-attribute

QuantumNeuralNetwork = QuantumNN

Hybrid Classifier

superquantx.algorithms.HybridClassifier

HybridClassifier(backend: str | Any, hybrid_mode: str = 'ensemble', quantum_algorithms: list[str] | None = None, classical_algorithms: list[str] | None = None, quantum_weight: float = 0.5, feature_selection: bool = False, meta_learner: str = 'logistic_regression', shots: int = 1024, normalize_data: bool = True, **kwargs)

Bases: SupervisedQuantumAlgorithm

Hybrid Classical-Quantum Classifier.

This classifier combines classical and quantum machine learning algorithms to leverage the strengths of both approaches. It can operate in different modes: - Ensemble: Combines predictions from multiple quantum and classical models - Sequential: Uses quantum features as input to classical models - Voting: Majority voting among quantum and classical predictions - Stacking: Uses meta-learner to combine quantum and classical predictions

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for quantum components	required
hybrid_mode	str	Mode of operation ('ensemble', 'sequential', 'voting', 'stacking')	'ensemble'
quantum_algorithms	list[str] | None	List of quantum algorithms to include	None
classical_algorithms	list[str] | None	List of classical algorithms to include	None
quantum_weight	float	Weight for quantum predictions (0-1)	0.5
feature_selection	bool	Whether to use quantum feature selection	False
meta_learner	str	Meta-learning algorithm for stacking mode	'logistic_regression'
shots	int	Number of measurement shots	1024
**kwargs		Additional parameters	{}

Example

hybrid = HybridClassifier( ... backend='pennylane', ... hybrid_mode='ensemble', ... quantum_algorithms=['quantum_svm', 'quantum_nn'], ... classical_algorithms=['random_forest', 'svm'] ... ) hybrid.fit(X_train, y_train) predictions = hybrid.predict(X_test)

Source code in src/superquantx/algorithms/hybrid_classifier.py

def __init__(
    self,
    backend: str | Any,
    hybrid_mode: str = 'ensemble',
    quantum_algorithms: list[str] | None = None,
    classical_algorithms: list[str] | None = None,
    quantum_weight: float = 0.5,
    feature_selection: bool = False,
    meta_learner: str = 'logistic_regression',
    shots: int = 1024,
    normalize_data: bool = True,
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)

    self.hybrid_mode = hybrid_mode
    self.quantum_algorithms = quantum_algorithms or ['quantum_svm']
    self.classical_algorithms = classical_algorithms or ['random_forest']
    self.quantum_weight = quantum_weight
    self.feature_selection = feature_selection
    self.meta_learner_name = meta_learner
    self.normalize_data = normalize_data

    # Initialize models
    self.quantum_models = {}
    self.classical_models = {}
    self.meta_learner = None
    self.feature_selector = None

    # Data preprocessing
    self.scaler = StandardScaler() if normalize_data else None
    self.label_encoder = LabelEncoder()

    # Model performance tracking
    self.quantum_scores = {}
    self.classical_scores = {}
    self.hybrid_score = None
    self.feature_importance_ = None

    self._initialize_models()

    logger.info(f"Initialized HybridClassifier with mode={hybrid_mode}")
    logger.info(f"Quantum algorithms: {self.quantum_algorithms}")
    logger.info(f"Classical algorithms: {self.classical_algorithms}")

Functions

fit

fit(X: ndarray, y: ndarray, **kwargs) -> HybridClassifier

Train the hybrid classifier.

Parameters:

Name	Type	Description	Default
X	ndarray	Training data features	required
y	ndarray	Training data labels	required
**kwargs		Additional training parameters	{}

Returns:

Type	Description
HybridClassifier	Self for method chaining

Source code in src/superquantx/algorithms/hybrid_classifier.py

def fit(self, X: np.ndarray, y: np.ndarray, **kwargs) -> 'HybridClassifier':
    """Train the hybrid classifier.

    Args:
        X: Training data features
        y: Training data labels
        **kwargs: Additional training parameters

    Returns:
        Self for method chaining

    """
    logger.info(f"Training HybridClassifier on {X.shape[0]} samples with {X.shape[1]} features")

    # Validate and preprocess data
    super().fit(X, y, **kwargs)

    # Normalize features
    if self.normalize_data:
        X = self.scaler.fit_transform(X)

    # Encode labels
    y_encoded = self.label_encoder.fit_transform(y)

    # Apply feature selection
    X_selected = self._apply_feature_selection(X, y_encoded)

    # Train quantum models
    self.quantum_scores = self._train_quantum_models(X_selected, y_encoded)

    # Train classical models
    self.classical_scores = self._train_classical_models(X_selected, y_encoded)

    # Train meta-learner for stacking mode
    if self.hybrid_mode == 'stacking' and self.meta_learner is not None:
        logger.info("Training meta-learner for stacking")

        # Get base model predictions for meta-training
        quantum_preds, classical_preds = self._get_base_predictions(X_selected)

        meta_features = []
        if len(quantum_preds) > 0:
            for pred_proba in quantum_preds:
                meta_features.append(pred_proba)
        if len(classical_preds) > 0:
            for pred_proba in classical_preds:
                meta_features.append(pred_proba)

        if meta_features:
            meta_X = np.concatenate(meta_features, axis=1)
            self.meta_learner.fit(meta_X, y_encoded)

    # Train sequential model if needed
    if self.hybrid_mode == 'sequential':
        # Retrain classical models with quantum features
        quantum_features = []

        for name, model in self.quantum_models.items():
            try:
                if hasattr(model, 'transform'):
                    features = model.transform(X_selected)
                elif hasattr(model, 'decision_function'):
                    features = model.decision_function(X_selected)
                    if len(features.shape) == 1:
                        features = features.reshape(-1, 1)
                else:
                    features = model.predict_proba(X_selected)

                quantum_features.append(features)

            except Exception as e:
                logger.error(f"Failed to extract features from {name}: {e}")

        if quantum_features:
            quantum_feature_matrix = np.concatenate(quantum_features, axis=1)

            # Retrain classical models with quantum features
            for name, model in self.classical_models.items():
                try:
                    model.fit(quantum_feature_matrix, y_encoded)
                except Exception as e:
                    logger.error(f"Failed to retrain {name} with quantum features: {e}")

    self.is_fitted = True

    # Compute hybrid performance
    predictions = self.predict(X)
    self.hybrid_score = accuracy_score(y, predictions)

    logger.info(f"Hybrid classifier training completed. Accuracy: {self.hybrid_score:.4f}")

    return self

predict

predict(X: ndarray, **kwargs) -> np.ndarray

Make predictions using the hybrid classifier.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data for prediction	required
**kwargs		Additional prediction parameters	{}

Returns:

Type	Description
ndarray	Predicted labels

Source code in src/superquantx/algorithms/hybrid_classifier.py

def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Make predictions using the hybrid classifier.

    Args:
        X: Input data for prediction
        **kwargs: Additional prediction parameters

    Returns:
        Predicted labels

    """
    if not self.is_fitted:
        raise ValueError("Model must be fitted before making predictions")

    # Normalize features
    if self.normalize_data:
        X = self.scaler.transform(X)

    # Apply feature selection
    X_selected = self._apply_feature_selection(X)

    # Make predictions based on hybrid mode
    if self.hybrid_mode == 'ensemble':
        predictions = self._ensemble_predict(X_selected)
    elif self.hybrid_mode == 'voting':
        predictions = self._voting_predict(X_selected)
    elif self.hybrid_mode == 'sequential':
        predictions = self._sequential_predict(X_selected)
    elif self.hybrid_mode == 'stacking':
        predictions = self._stacking_predict(X_selected)
    else:
        raise ValueError(f"Unknown hybrid mode: {self.hybrid_mode}")

    # Decode labels
    return self.label_encoder.inverse_transform(predictions)

predict_proba

predict_proba(X: ndarray, **kwargs) -> np.ndarray

Predict class probabilities.

Parameters:

Name	Type	Description	Default
X	ndarray	Input data for prediction	required
**kwargs		Additional parameters	{}

Returns:

Type	Description
ndarray	Predicted class probabilities

Source code in src/superquantx/algorithms/hybrid_classifier.py

def predict_proba(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Predict class probabilities.

    Args:
        X: Input data for prediction
        **kwargs: Additional parameters

    Returns:
        Predicted class probabilities

    """
    if not self.is_fitted:
        raise ValueError("Model must be fitted before making predictions")

    # Normalize features
    if self.normalize_data:
        X = self.scaler.transform(X)

    # Apply feature selection
    X_selected = self._apply_feature_selection(X)

    # Get base predictions
    quantum_preds, classical_preds = self._get_base_predictions(X_selected)

    if self.hybrid_mode == 'ensemble':
        # Weighted average of probabilities
        combined_pred = np.zeros((X.shape[0], self.n_classes_))

        if len(quantum_preds) > 0:
            quantum_avg = np.mean(quantum_preds, axis=0)
            combined_pred += self.quantum_weight * quantum_avg

        if len(classical_preds) > 0:
            classical_avg = np.mean(classical_preds, axis=0)
            combined_pred += (1 - self.quantum_weight) * classical_avg

        return combined_pred

    elif self.hybrid_mode == 'stacking' and self.meta_learner is not None:
        # Use meta-learner probabilities
        meta_features = []

        if len(quantum_preds) > 0:
            for pred_proba in quantum_preds:
                meta_features.append(pred_proba)
        if len(classical_preds) > 0:
            for pred_proba in classical_preds:
                meta_features.append(pred_proba)

        if meta_features:
            meta_X = np.concatenate(meta_features, axis=1)
            if hasattr(self.meta_learner, 'predict_proba'):
                return self.meta_learner.predict_proba(meta_X)

    # Fallback: convert predictions to probabilities
    predictions = self.predict(X)
    pred_encoded = self.label_encoder.transform(predictions)
    prob_matrix = np.zeros((len(predictions), self.n_classes_))
    prob_matrix[np.arange(len(predictions)), pred_encoded] = 1.0

    return prob_matrix

get_model_performance

get_model_performance() -> dict[str, Any]

Get detailed performance metrics for all models.

Source code in src/superquantx/algorithms/hybrid_classifier.py

def get_model_performance(self) -> dict[str, Any]:
    """Get detailed performance metrics for all models."""
    performance = {
        'quantum_scores': self.quantum_scores.copy(),
        'classical_scores': self.classical_scores.copy(),
        'hybrid_score': self.hybrid_score,
        'hybrid_mode': self.hybrid_mode,
    }

    # Add quantum advantage metrics
    if self.quantum_scores and self.classical_scores:
        best_quantum = max(self.quantum_scores.values()) if self.quantum_scores else 0
        best_classical = max(self.classical_scores.values()) if self.classical_scores else 0

        performance.update({
            'best_quantum_score': best_quantum,
            'best_classical_score': best_classical,
            'quantum_advantage': best_quantum - best_classical,
            'hybrid_vs_best_quantum': self.hybrid_score - best_quantum if self.hybrid_score else 0,
            'hybrid_vs_best_classical': self.hybrid_score - best_classical if self.hybrid_score else 0,
        })

    return performance

get_feature_importance

get_feature_importance() -> np.ndarray | None

Get feature importance from feature selection.

Source code in src/superquantx/algorithms/hybrid_classifier.py

def get_feature_importance(self) -> np.ndarray | None:
    """Get feature importance from feature selection."""
    return self.feature_importance_

cross_validate

cross_validate(X: ndarray, y: ndarray, cv: int = 5) -> dict[str, Any]

Perform cross-validation on the hybrid classifier.

Source code in src/superquantx/algorithms/hybrid_classifier.py

def cross_validate(self, X: np.ndarray, y: np.ndarray, cv: int = 5) -> dict[str, Any]:
    """Perform cross-validation on the hybrid classifier."""
    if not self.is_fitted:
        raise ValueError("Model must be fitted before cross-validation")

    try:
        scores = cross_val_score(self, X, y, cv=cv, scoring='accuracy')

        return {
            'cv_scores': scores.tolist(),
            'cv_mean': np.mean(scores),
            'cv_std': np.std(scores),
            'cv_min': np.min(scores),
            'cv_max': np.max(scores),
        }

    except Exception as e:
        logger.error(f"Cross-validation failed: {e}")
        return {'error': str(e)}

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get hybrid classifier parameters.

Source code in src/superquantx/algorithms/hybrid_classifier.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get hybrid classifier parameters."""
    params = super().get_params(deep)
    params.update({
        'hybrid_mode': self.hybrid_mode,
        'quantum_algorithms': self.quantum_algorithms,
        'classical_algorithms': self.classical_algorithms,
        'quantum_weight': self.quantum_weight,
        'feature_selection': self.feature_selection,
        'meta_learner': self.meta_learner_name,
        'normalize_data': self.normalize_data,
    })
    return params

set_params

set_params(**params) -> HybridClassifier

Set hybrid classifier parameters.

Source code in src/superquantx/algorithms/hybrid_classifier.py

def set_params(self, **params) -> 'HybridClassifier':
    """Set hybrid classifier parameters."""
    if self.is_fitted and any(key in params for key in
                             ['hybrid_mode', 'quantum_algorithms', 'classical_algorithms']):
        logger.warning("Changing core parameters requires refitting the model")
        self.is_fitted = False

    return super().set_params(**params)

Quantum Principal Component Analysis

superquantx.algorithms.QuantumPCA

QuantumPCA(backend: str | Any, n_components: int = 2, method: str = 'vqe', encoding: str = 'amplitude', max_iterations: int = 1000, tolerance: float = 1e-06, shots: int = 1024, classical_fallback: bool = True, normalize_data: bool = True, **kwargs)

Bases: UnsupervisedQuantumAlgorithm

Quantum Principal Component Analysis for dimensionality reduction.

This implementation uses quantum algorithms to perform PCA, potentially offering exponential speedup for certain types of data matrices.

The algorithm can use different quantum approaches: - Quantum Matrix Inversion: For density matrix diagonalization - Variational Quantum Eigensolver: For finding principal eigenvectors - Quantum Phase Estimation: For eigenvalue extraction - Quantum Singular Value Decomposition: Direct SVD approach

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for circuit execution	required
n_components	int	Number of principal components to extract	2
method	str	Quantum method ('vqe', 'phase_estimation', 'matrix_inversion', 'qsvd')	'vqe'
encoding	str	Data encoding method ('amplitude', 'dense', 'sparse')	'amplitude'
max_iterations	int	Maximum iterations for variational methods	1000
tolerance	float	Convergence tolerance	1e-06
shots	int	Number of measurement shots	1024
classical_fallback	bool	Use classical PCA if quantum fails	True
**kwargs		Additional parameters	{}

Example

qpca = QuantumPCA(backend='pennylane', n_components=3, method='vqe') qpca.fit(X_train) X_reduced = qpca.transform(X_test) X_reconstructed = qpca.inverse_transform(X_reduced)

Source code in src/superquantx/algorithms/quantum_pca.py

def __init__(
    self,
    backend: str | Any,
    n_components: int = 2,
    method: str = 'vqe',
    encoding: str = 'amplitude',
    max_iterations: int = 1000,
    tolerance: float = 1e-6,
    shots: int = 1024,
    classical_fallback: bool = True,
    normalize_data: bool = True,
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)

    self.n_components = n_components
    self.method = method
    self.encoding = encoding
    self.max_iterations = max_iterations
    self.tolerance = tolerance
    self.classical_fallback = classical_fallback
    self.normalize_data = normalize_data

    # PCA components
    self.components_ = None
    self.eigenvalues_ = None
    self.mean_ = None
    self.explained_variance_ = None
    self.explained_variance_ratio_ = None

    # Quantum-specific attributes
    self.density_matrix_ = None
    self.quantum_state_ = None
    self.n_qubits = None

    # Classical components for fallback/comparison
    self.scaler = StandardScaler() if normalize_data else None
    self.classical_pca = PCA(n_components=n_components)

    # Method-specific parameters
    self.vqe_params = None
    self.convergence_history = []

    logger.info(f"Initialized QuantumPCA with method={method}, n_components={n_components}")

Functions

fit

fit(X: ndarray, y: ndarray | None = None, **kwargs) -> QuantumPCA

Fit quantum PCA to the data.

Parameters:

Name	Type	Description	Default
X	ndarray	Training data	required
y	ndarray | None	Ignored (unsupervised learning)	None
**kwargs		Additional fitting parameters	{}

Returns:

Type	Description
QuantumPCA	Self for method chaining

Source code in src/superquantx/algorithms/quantum_pca.py

def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> 'QuantumPCA':
    """Fit quantum PCA to the data.

    Args:
        X: Training data
        y: Ignored (unsupervised learning)
        **kwargs: Additional fitting parameters

    Returns:
        Self for method chaining

    """
    logger.info(f"Fitting QuantumPCA to data of shape {X.shape}")

    # Validate and preprocess data
    super().fit(X, y, **kwargs)

    # Prepare data
    X_processed = self._prepare_data_matrix(X)

    # Determine quantum circuit size
    self.n_qubits = self._determine_qubits(X.shape[1])

    # Choose quantum method
    if self.method == 'vqe':
        density_matrix = self._create_density_matrix(X_processed)
        eigenvalues, eigenvectors = self._quantum_eigensolver_vqe(density_matrix)
    elif self.method == 'phase_estimation':
        density_matrix = self._create_density_matrix(X_processed)
        eigenvalues, eigenvectors = self._quantum_phase_estimation(density_matrix)
    elif self.method == 'matrix_inversion':
        density_matrix = self._create_density_matrix(X_processed)
        eigenvalues, eigenvectors = self._quantum_matrix_inversion(density_matrix)
    elif self.method == 'qsvd':
        eigenvalues, eigenvectors = self._quantum_svd(X_processed)
    else:
        raise ValueError(f"Unknown quantum PCA method: {self.method}")

    # Store results
    self.eigenvalues_ = eigenvalues
    self.components_ = eigenvectors.T  # Store as rows
    self.explained_variance_ = eigenvalues

    # Calculate explained variance ratio
    total_variance = np.sum(eigenvalues) if np.sum(eigenvalues) > 0 else 1.0
    self.explained_variance_ratio_ = eigenvalues / total_variance

    # Fit classical PCA for comparison/fallback
    if self.classical_fallback:
        try:
            self.classical_pca.fit(X_processed)
        except Exception as e:
            logger.warning(f"Classical PCA fitting failed: {e}")

    self.is_fitted = True

    logger.info(f"Quantum PCA completed. Explained variance ratio: {self.explained_variance_ratio_}")

    return self

transform

transform(X: ndarray) -> np.ndarray

Transform data to lower dimensional space.

Parameters:

Name	Type	Description	Default
X	ndarray	Data to transform	required

Returns:

Type	Description
ndarray	Transformed data

Source code in src/superquantx/algorithms/quantum_pca.py

def transform(self, X: np.ndarray) -> np.ndarray:
    """Transform data to lower dimensional space.

    Args:
        X: Data to transform

    Returns:
        Transformed data

    """
    if not self.is_fitted:
        raise ValueError("QuantumPCA must be fitted before transform")

    # Preprocess data
    if self.normalize_data:
        X = self.scaler.transform(X)

    # Center data
    X_centered = X - self.mean_

    # Project onto principal components
    X_transformed = X_centered @ self.components_.T

    return X_transformed

inverse_transform

inverse_transform(X_transformed: ndarray) -> np.ndarray

Reconstruct data from lower dimensional representation.

Parameters:

Name	Type	Description	Default
X_transformed	ndarray	Transformed data	required

Returns:

Type	Description
ndarray	Reconstructed data

Source code in src/superquantx/algorithms/quantum_pca.py

def inverse_transform(self, X_transformed: np.ndarray) -> np.ndarray:
    """Reconstruct data from lower dimensional representation.

    Args:
        X_transformed: Transformed data

    Returns:
        Reconstructed data

    """
    if not self.is_fitted:
        raise ValueError("QuantumPCA must be fitted before inverse_transform")

    # Reconstruct in original space
    X_reconstructed = X_transformed @ self.components_

    # Add back the mean
    X_reconstructed += self.mean_

    # Inverse scaling if applied
    if self.normalize_data:
        X_reconstructed = self.scaler.inverse_transform(X_reconstructed)

    return X_reconstructed

fit_transform

fit_transform(X: ndarray, y: ndarray | None = None) -> np.ndarray

Fit PCA and transform data in one step.

Source code in src/superquantx/algorithms/quantum_pca.py

def fit_transform(self, X: np.ndarray, y: np.ndarray | None = None) -> np.ndarray:
    """Fit PCA and transform data in one step."""
    return self.fit(X, y).transform(X)

predict

predict(X: ndarray, **kwargs) -> np.ndarray

Transform data (alias for transform method).

Source code in src/superquantx/algorithms/quantum_pca.py

def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Transform data (alias for transform method)."""
    return self.transform(X)

get_quantum_advantage_metrics

get_quantum_advantage_metrics() -> dict[str, Any]

Analyze potential quantum advantage.

Source code in src/superquantx/algorithms/quantum_pca.py

def get_quantum_advantage_metrics(self) -> dict[str, Any]:
    """Analyze potential quantum advantage."""
    if not self.is_fitted:
        raise ValueError("Must fit model first")

    n_features = self.components_.shape[1]

    metrics = {
        'data_dimension': n_features,
        'reduced_dimension': self.n_components,
        'compression_ratio': n_features / self.n_components,
        'quantum_circuit_qubits': self.n_qubits,
        'quantum_vs_classical_qubits': self.n_qubits / int(np.ceil(np.log2(n_features))),
    }

    # Potential speedup estimates (theoretical)
    classical_complexity = n_features ** 3  # O(d^3) for eigendecomposition
    quantum_complexity = self.n_qubits ** 2 * np.log(n_features)  # Estimated quantum complexity

    metrics.update({
        'classical_complexity_estimate': classical_complexity,
        'quantum_complexity_estimate': quantum_complexity,
        'theoretical_speedup': classical_complexity / quantum_complexity if quantum_complexity > 0 else 1,
    })

    return metrics

compare_with_classical

compare_with_classical(X: ndarray) -> dict[str, Any]

Compare quantum PCA results with classical PCA.

Source code in src/superquantx/algorithms/quantum_pca.py

def compare_with_classical(self, X: np.ndarray) -> dict[str, Any]:
    """Compare quantum PCA results with classical PCA."""
    if not self.is_fitted or not hasattr(self.classical_pca, 'components_'):
        raise ValueError("Both quantum and classical PCA must be fitted")

    # Transform data with both methods
    X_quantum = self.transform(X)
    X_classical = self.classical_pca.transform(X - self.mean_)

    # Compute reconstruction errors
    X_quantum_reconstructed = self.inverse_transform(X_quantum)
    X_classical_reconstructed = self.classical_pca.inverse_transform(X_classical) + self.mean_

    quantum_error = np.mean((X - X_quantum_reconstructed) ** 2)
    classical_error = np.mean((X - X_classical_reconstructed) ** 2)

    # Compare explained variance
    quantum_var_ratio = np.sum(self.explained_variance_ratio_)
    classical_var_ratio = np.sum(self.classical_pca.explained_variance_ratio_)

    # Component similarity (using absolute cosine similarity)
    component_similarities = []
    min_components = min(self.n_components, len(self.classical_pca.components_))

    for i in range(min_components):
        # Cosine similarity between components
        cos_sim = np.abs(np.dot(self.components_[i], self.classical_pca.components_[i]))
        cos_sim /= (np.linalg.norm(self.components_[i]) * np.linalg.norm(self.classical_pca.components_[i]))
        component_similarities.append(cos_sim)

    return {
        'quantum_reconstruction_error': quantum_error,
        'classical_reconstruction_error': classical_error,
        'error_ratio': quantum_error / classical_error if classical_error > 0 else float('inf'),
        'quantum_variance_explained': quantum_var_ratio,
        'classical_variance_explained': classical_var_ratio,
        'variance_explained_ratio': quantum_var_ratio / classical_var_ratio if classical_var_ratio > 0 else float('inf'),
        'component_similarities': component_similarities,
        'mean_component_similarity': np.mean(component_similarities) if component_similarities else 0,
    }

analyze_convergence

analyze_convergence() -> dict[str, Any]

Analyze convergence properties of the quantum algorithm.

Source code in src/superquantx/algorithms/quantum_pca.py

def analyze_convergence(self) -> dict[str, Any]:
    """Analyze convergence properties of the quantum algorithm."""
    if not self.convergence_history:
        return {'message': 'No convergence history available'}

    convergence_data = np.array(self.convergence_history)

    return {
        'total_iterations': len(convergence_data),
        'final_cost': convergence_data[-1],
        'initial_cost': convergence_data[0],
        'cost_reduction': convergence_data[0] - convergence_data[-1],
        'converged': abs(convergence_data[-1] - convergence_data[-2]) < self.tolerance if len(convergence_data) > 1 else False,
        'convergence_rate': np.mean(np.diff(convergence_data)) if len(convergence_data) > 1 else 0,
    }

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get quantum PCA parameters.

Source code in src/superquantx/algorithms/quantum_pca.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get quantum PCA parameters."""
    params = super().get_params(deep)
    params.update({
        'n_components': self.n_components,
        'method': self.method,
        'encoding': self.encoding,
        'max_iterations': self.max_iterations,
        'tolerance': self.tolerance,
        'classical_fallback': self.classical_fallback,
        'normalize_data': self.normalize_data,
    })
    return params

set_params

set_params(**params) -> QuantumPCA

Set quantum PCA parameters.

Source code in src/superquantx/algorithms/quantum_pca.py

def set_params(self, **params) -> 'QuantumPCA':
    """Set quantum PCA parameters."""
    if self.is_fitted and any(key in params for key in
                             ['n_components', 'method', 'encoding']):
        logger.warning("Changing core parameters requires refitting the model")
        self.is_fitted = False

    return super().set_params(**params)

Quantum K-Means

superquantx.algorithms.QuantumKMeans

QuantumKMeans(backend: str | Any, n_clusters: int = 3, method: str = 'distance', distance_metric: str = 'euclidean', encoding: str = 'amplitude', max_iterations: int = 300, tolerance: float = 0.0001, init_method: str = 'k-means++', shots: int = 1024, classical_fallback: bool = True, normalize_data: bool = True, random_state: int | None = None, **kwargs)

Bases: UnsupervisedQuantumAlgorithm

Quantum K-Means clustering algorithm.

This implementation uses quantum algorithms to perform K-means clustering, potentially offering speedup for high-dimensional data through quantum distance calculations and amplitude estimation.

The algorithm can use different quantum approaches: - Quantum Distance Calculation: Use quantum circuits to compute distances - Quantum Amplitude Estimation: For probabilistic distance measurements - Variational Quantum Clustering: Use VQC for cluster optimization - Quantum Annealing: For global cluster optimization

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for circuit execution	required
n_clusters	int	Number of clusters (k)	3
method	str	Quantum method ('distance', 'amplitude', 'variational', 'annealing')	'distance'
distance_metric	str	Distance metric ('euclidean', 'manhattan', 'quantum')	'euclidean'
encoding	str	Data encoding method ('amplitude', 'angle', 'dense')	'amplitude'
max_iterations	int	Maximum iterations for clustering	300
tolerance	float	Convergence tolerance	0.0001
init_method	str	Centroid initialization ('random', 'k-means++', 'quantum')	'k-means++'
shots	int	Number of measurement shots	1024
classical_fallback	bool	Use classical K-means if quantum fails	True
**kwargs		Additional parameters	{}

Example

qkmeans = QuantumKMeans(backend='pennylane', n_clusters=3, method='distance') qkmeans.fit(X_train) labels = qkmeans.predict(X_test) centroids = qkmeans.cluster_centers_

Source code in src/superquantx/algorithms/quantum_kmeans.py

def __init__(
    self,
    backend: str | Any,
    n_clusters: int = 3,
    method: str = 'distance',
    distance_metric: str = 'euclidean',
    encoding: str = 'amplitude',
    max_iterations: int = 300,
    tolerance: float = 1e-4,
    init_method: str = 'k-means++',
    shots: int = 1024,
    classical_fallback: bool = True,
    normalize_data: bool = True,
    random_state: int | None = None,
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)

    self.n_clusters = n_clusters
    self.method = method
    self.distance_metric = distance_metric
    self.encoding = encoding
    self.max_iterations = max_iterations
    self.tolerance = tolerance
    self.init_method = init_method
    self.classical_fallback = classical_fallback
    self.normalize_data = normalize_data
    self.random_state = random_state

    # Clustering results
    self.cluster_centers_ = None
    self.labels_ = None
    self.inertia_ = None
    self.n_iter_ = None

    # Quantum-specific attributes
    self.n_qubits = None
    self.quantum_distances_ = None
    self.convergence_history = []

    # Classical components
    self.scaler = StandardScaler() if normalize_data else None
    self.classical_kmeans = KMeans(
        n_clusters=n_clusters,
        max_iter=max_iterations,
        tol=tolerance,
        random_state=random_state
    )

    # Set random seed
    if random_state is not None:
        np.random.seed(random_state)

    logger.info(f"Initialized QuantumKMeans with method={method}, n_clusters={n_clusters}")

Functions

fit

fit(X: ndarray, y: ndarray | None = None, **kwargs) -> QuantumKMeans

Fit quantum K-means to the data.

Parameters:

Name	Type	Description	Default
X	ndarray	Training data	required
y	ndarray | None	Ignored (unsupervised learning)	None
**kwargs		Additional fitting parameters	{}

Returns:

Type	Description
QuantumKMeans	Self for method chaining

Source code in src/superquantx/algorithms/quantum_kmeans.py

def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> 'QuantumKMeans':
    """Fit quantum K-means to the data.

    Args:
        X: Training data
        y: Ignored (unsupervised learning)
        **kwargs: Additional fitting parameters

    Returns:
        Self for method chaining

    """
    logger.info(f"Fitting QuantumKMeans to data of shape {X.shape}")

    # Validate and preprocess data
    super().fit(X, y, **kwargs)

    # Normalize data if specified
    if self.normalize_data:
        X = self.scaler.fit_transform(X)

    # Determine quantum circuit requirements
    self.n_qubits = self._determine_qubits(X.shape[1])

    # Initialize centroids
    centroids = self._initialize_centroids(X)

    # Reset convergence history
    self.convergence_history = []

    # Main K-means iteration loop
    for iteration in range(self.max_iterations):
        # Store old centroids for convergence check
        old_centroids = centroids.copy()

        # Compute distances and assign clusters
        distances = self._compute_distances_batch(X, centroids)
        labels = self._assign_clusters(distances)

        # Update centroids
        centroids = self._update_centroids(X, labels)

        # Compute inertia
        inertia = self._compute_inertia(X, labels, centroids)
        self.convergence_history.append(inertia)

        # Check convergence
        if self._check_convergence(old_centroids, centroids):
            logger.info(f"Converged after {iteration + 1} iterations")
            break

        if iteration % 10 == 0:
            logger.info(f"Iteration {iteration}: Inertia = {inertia:.6f}")

    # Store final results
    self.cluster_centers_ = centroids
    self.labels_ = labels
    self.inertia_ = inertia
    self.n_iter_ = iteration + 1

    # Fit classical K-means for comparison
    if self.classical_fallback:
        try:
            self.classical_kmeans.fit(X)
        except Exception as e:
            logger.warning(f"Classical K-means fitting failed: {e}")

    self.is_fitted = True

    logger.info(f"Quantum K-means completed. Final inertia: {self.inertia_:.6f}")

    return self

predict

predict(X: ndarray, **kwargs) -> np.ndarray

Predict cluster labels for new data.

Parameters:

Name	Type	Description	Default
X	ndarray	Data to cluster	required
**kwargs		Additional parameters	{}

Returns:

Type	Description
ndarray	Cluster labels

Source code in src/superquantx/algorithms/quantum_kmeans.py

def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Predict cluster labels for new data.

    Args:
        X: Data to cluster
        **kwargs: Additional parameters

    Returns:
        Cluster labels

    """
    if not self.is_fitted:
        raise ValueError("QuantumKMeans must be fitted before prediction")

    # Normalize data if specified
    if self.normalize_data:
        X = self.scaler.transform(X)

    # Compute distances to centroids
    distances = self._compute_distances_batch(X, self.cluster_centers_)

    # Assign to nearest cluster
    return self._assign_clusters(distances)

fit_predict

fit_predict(X: ndarray, y: ndarray | None = None) -> np.ndarray

Fit K-means and return cluster labels.

Source code in src/superquantx/algorithms/quantum_kmeans.py

def fit_predict(self, X: np.ndarray, y: np.ndarray | None = None) -> np.ndarray:
    """Fit K-means and return cluster labels."""
    return self.fit(X, y).labels_

transform

transform(X: ndarray) -> np.ndarray

Transform data to cluster-distance space.

Source code in src/superquantx/algorithms/quantum_kmeans.py

def transform(self, X: np.ndarray) -> np.ndarray:
    """Transform data to cluster-distance space."""
    if not self.is_fitted:
        raise ValueError("QuantumKMeans must be fitted before transform")

    # Normalize data if specified
    if self.normalize_data:
        X = self.scaler.transform(X)

    # Return distances to all centroids
    return self._compute_distances_batch(X, self.cluster_centers_)

get_quantum_advantage_metrics

get_quantum_advantage_metrics() -> dict[str, Any]

Analyze potential quantum advantage.

Source code in src/superquantx/algorithms/quantum_kmeans.py

def get_quantum_advantage_metrics(self) -> dict[str, Any]:
    """Analyze potential quantum advantage."""
    if not self.is_fitted:
        raise ValueError("Must fit model first")

    n_features = self.cluster_centers_.shape[1]
    n_samples = self.n_samples_

    metrics = {
        'data_dimension': n_features,
        'n_samples': n_samples,
        'n_clusters': self.n_clusters,
        'quantum_circuit_qubits': self.n_qubits,
        'encoding_efficiency': n_features / self.n_qubits if self.n_qubits > 0 else 1,
    }

    # Complexity estimates
    classical_complexity = n_samples * self.n_clusters * n_features * self.n_iter_
    quantum_complexity = n_samples * self.n_clusters * self.n_qubits * self.shots * self.n_iter_

    metrics.update({
        'classical_complexity_estimate': classical_complexity,
        'quantum_complexity_estimate': quantum_complexity,
        'theoretical_speedup': classical_complexity / quantum_complexity if quantum_complexity > 0 else 1,
    })

    return metrics

compare_with_classical

compare_with_classical(X: ndarray, y_true: ndarray | None = None) -> dict[str, Any]

Compare quantum K-means results with classical K-means.

Source code in src/superquantx/algorithms/quantum_kmeans.py

def compare_with_classical(self, X: np.ndarray, y_true: np.ndarray | None = None) -> dict[str, Any]:
    """Compare quantum K-means results with classical K-means."""
    if not self.is_fitted or not hasattr(self.classical_kmeans, 'cluster_centers_'):
        raise ValueError("Both quantum and classical K-means must be fitted")

    # Get predictions from both methods
    quantum_labels = self.predict(X)
    classical_labels = self.classical_kmeans.predict(X if not self.normalize_data
                                                    else self.scaler.transform(X))

    comparison = {
        'quantum_inertia': self.inertia_,
        'classical_inertia': self.classical_kmeans.inertia_,
        'inertia_ratio': self.inertia_ / self.classical_kmeans.inertia_ if self.classical_kmeans.inertia_ > 0 else float('inf'),
        'quantum_iterations': self.n_iter_,
        'classical_iterations': self.classical_kmeans.n_iter_,
    }

    # Compute silhouette scores
    try:
        if len(np.unique(quantum_labels)) > 1:
            quantum_silhouette = silhouette_score(X, quantum_labels)
            comparison['quantum_silhouette'] = quantum_silhouette

        if len(np.unique(classical_labels)) > 1:
            classical_silhouette = silhouette_score(X, classical_labels)
            comparison['classical_silhouette'] = classical_silhouette

        if 'quantum_silhouette' in comparison and 'classical_silhouette' in comparison:
            comparison['silhouette_ratio'] = quantum_silhouette / classical_silhouette

    except Exception as e:
        logger.warning(f"Silhouette score computation failed: {e}")

    # Compare with ground truth if available
    if y_true is not None:
        try:
            quantum_ari = adjusted_rand_score(y_true, quantum_labels)
            classical_ari = adjusted_rand_score(y_true, classical_labels)

            comparison.update({
                'quantum_adjusted_rand_score': quantum_ari,
                'classical_adjusted_rand_score': classical_ari,
                'ari_ratio': quantum_ari / classical_ari if classical_ari != 0 else float('inf'),
            })

        except Exception as e:
            logger.warning(f"Adjusted rand score computation failed: {e}")

    # Compare centroid similarities
    centroid_distances = []
    for i in range(min(len(self.cluster_centers_), len(self.classical_kmeans.cluster_centers_))):
        dist = np.linalg.norm(self.cluster_centers_[i] - self.classical_kmeans.cluster_centers_[i])
        centroid_distances.append(dist)

    if centroid_distances:
        comparison.update({
            'centroid_distances': centroid_distances,
            'mean_centroid_distance': np.mean(centroid_distances),
            'max_centroid_distance': np.max(centroid_distances),
        })

    return comparison

analyze_convergence

analyze_convergence() -> dict[str, Any]

Analyze convergence properties.

Source code in src/superquantx/algorithms/quantum_kmeans.py

def analyze_convergence(self) -> dict[str, Any]:
    """Analyze convergence properties."""
    if not self.convergence_history:
        return {'message': 'No convergence history available'}

    inertias = np.array(self.convergence_history)

    return {
        'total_iterations': len(inertias),
        'final_inertia': inertias[-1],
        'initial_inertia': inertias[0],
        'inertia_reduction': inertias[0] - inertias[-1] if len(inertias) > 0 else 0,
        'convergence_rate': np.mean(np.diff(inertias)) if len(inertias) > 1 else 0,
        'converged': len(inertias) < self.max_iterations,
        'inertia_variance': np.var(inertias[-10:]) if len(inertias) >= 10 else np.var(inertias),
    }

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get quantum K-means parameters.

Source code in src/superquantx/algorithms/quantum_kmeans.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get quantum K-means parameters."""
    params = super().get_params(deep)
    params.update({
        'n_clusters': self.n_clusters,
        'method': self.method,
        'distance_metric': self.distance_metric,
        'encoding': self.encoding,
        'max_iterations': self.max_iterations,
        'tolerance': self.tolerance,
        'init_method': self.init_method,
        'classical_fallback': self.classical_fallback,
        'normalize_data': self.normalize_data,
        'random_state': self.random_state,
    })
    return params

set_params

set_params(**params) -> QuantumKMeans

Set quantum K-means parameters.

Source code in src/superquantx/algorithms/quantum_kmeans.py

def set_params(self, **params) -> 'QuantumKMeans':
    """Set quantum K-means parameters."""
    if self.is_fitted and any(key in params for key in
                             ['n_clusters', 'method', 'distance_metric', 'encoding']):
        logger.warning("Changing core parameters requires refitting the model")
        self.is_fitted = False

    return super().set_params(**params)

Optimization Algorithms

Variational Quantum Eigensolver

superquantx.algorithms.VQE

VQE(hamiltonian: ndarray | Any, ansatz: str | Callable = 'RealAmplitudes', backend: str | Any = 'simulator', optimizer: str = 'COBYLA', shots: int = 1024, maxiter: int = 1000, initial_params: ndarray | None = None, include_custom_gates: bool = False, client=None, reps: int = 1, **kwargs)

Bases: OptimizationQuantumAlgorithm

Variational Quantum Eigensolver for finding ground states.

VQE is a hybrid quantum-classical algorithm that uses a parameterized quantum circuit (ansatz) to find the ground state energy of a given Hamiltonian by minimizing the expectation value.

The algorithm works by: 1. Preparing a parameterized quantum state |ψ(θ)⟩ 2. Measuring the expectation value ⟨ψ(θ)|H|ψ(θ)⟩ 3. Classically optimizing parameters θ to minimize energy 4. Iterating until convergence

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for circuit execution	'simulator'
hamiltonian	ndarray | Any	Target Hamiltonian (matrix or operator)	required
ansatz	str | Callable	Parameterized circuit ansatz ('UCCSD', 'RealAmplitudes', etc.)	'RealAmplitudes'
optimizer	str	Classical optimizer ('COBYLA', 'L-BFGS-B', etc.)	'COBYLA'
shots	int	Number of measurement shots	1024
maxiter	int	Maximum optimization iterations	1000
initial_params	ndarray | None	Initial parameter values	None
**kwargs		Additional parameters	{}

Example

Define H2 molecule Hamiltonian

H2_hamiltonian = create_h2_hamiltonian(bond_distance=0.74) vqe = VQE(backend='pennylane', hamiltonian=H2_hamiltonian, ansatz='UCCSD') result = vqe.optimize() ground_energy = result.result['optimal_value']

Source code in src/superquantx/algorithms/vqe.py

def __init__(
    self,
    hamiltonian: np.ndarray | Any,
    ansatz: str | Callable = 'RealAmplitudes',
    backend: str | Any = 'simulator',
    optimizer: str = 'COBYLA',
    shots: int = 1024,
    maxiter: int = 1000,
    initial_params: np.ndarray | None = None,
    include_custom_gates: bool = False,
    client = None,
    reps: int = 1,
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)
    self.reps = reps

    self.hamiltonian = hamiltonian
    self.ansatz = ansatz
    self.optimizer = optimizer
    self.maxiter = maxiter
    self.initial_params = initial_params
    self.include_custom_gates = include_custom_gates
    self.client = client

    # VQE-specific attributes
    self.n_qubits = None
    self.n_params = None
    self.ansatz_circuit = None
    self.hamiltonian_terms = None
    self.hamiltonian_matrix = None

    # Convergence tracking
    self.energy_history = []
    self.gradient_history = []
    self.convergence_threshold = 1e-6

    self._initialize_hamiltonian()

    logger.info(f"Initialized VQE with ansatz={ansatz}, optimizer={optimizer}")

Functions

exact_ground_energy

exact_ground_energy() -> float

Classical baseline: lowest eigenvalue from exact diagonalisation.

Source code in src/superquantx/algorithms/vqe.py

def exact_ground_energy(self) -> float:
    """Classical baseline: lowest eigenvalue from exact diagonalisation."""
    return float(np.linalg.eigvalsh(self.hamiltonian_matrix)[0])

fit

fit(X: ndarray | None = None, y: ndarray | None = None, **kwargs) -> VQE

Fit VQE (setup for optimization).

Parameters:

Name	Type	Description	Default
X	ndarray | None	Optional Hamiltonian, if none was given to the constructor	None
y	ndarray | None	Not used in VQE	None
**kwargs		Additional parameters	{}

Returns:

Type	Description
VQE	Self for method chaining

Source code in src/superquantx/algorithms/vqe.py

def fit(self, X: np.ndarray | None = None, y: np.ndarray | None = None, **kwargs) -> 'VQE':
    """Fit VQE (setup for optimization).

    Args:
        X: Optional Hamiltonian, if none was given to the constructor
        y: Not used in VQE
        **kwargs: Additional parameters

    Returns:
        Self for method chaining

    """
    if X is not None:
        self.hamiltonian = X
        self._initialize_hamiltonian()
    if self.hamiltonian_matrix is None:
        raise ValueError("VQE needs a Hamiltonian: pass it to the constructor or fit()")
    logger.info(f"Setting up VQE for {self.n_qubits} qubits")

    # Determine number of parameters based on ansatz
    self.n_params = self._get_ansatz_param_count()

    # Initialize parameters if not provided
    if self.initial_params is None:
        self.initial_params = self._generate_initial_params()

    # Reset histories
    self.energy_history = []
    self.gradient_history = []
    self.optimization_history_ = []

    self.is_fitted = True
    return self

predict

predict(X: ndarray | None = None, **kwargs) -> np.ndarray

Return the optimised state vector (qubit 0 most significant).

Source code in src/superquantx/algorithms/vqe.py

def predict(self, X: np.ndarray | None = None, **kwargs) -> np.ndarray:
    """Return the optimised state vector (qubit 0 most significant)."""
    if self.optimal_params_ is None:
        raise ValueError("VQE must be optimized before prediction")
    circuit = self._create_ansatz_circuit(self.optimal_params_)
    return self.backend.statevector_big_endian(circuit)

get_energy_landscape

get_energy_landscape(param_indices: list[int], param_ranges: list[tuple[float, float]], resolution: int = 20) -> dict[str, Any]

Compute energy landscape for visualization.

Parameters:

Name	Type	Description	Default
param_indices	list[int]	Indices of parameters to vary	required
param_ranges	list[tuple[float, float]]	Ranges for each parameter	required
resolution	int	Number of points per dimension	20

Returns:

Type	Description
dict[str, Any]	Dictionary with landscape data

Source code in src/superquantx/algorithms/vqe.py

def get_energy_landscape(self, param_indices: list[int], param_ranges: list[tuple[float, float]],
                       resolution: int = 20) -> dict[str, Any]:
    """Compute energy landscape for visualization.

    Args:
        param_indices: Indices of parameters to vary
        param_ranges: Ranges for each parameter
        resolution: Number of points per dimension

    Returns:
        Dictionary with landscape data

    """
    if len(param_indices) != 2:
        raise ValueError("Energy landscape visualization supports only 2 parameters")

    if self.optimal_params_ is None:
        raise ValueError("VQE must be optimized to compute landscape")

    param1_range = np.linspace(*param_ranges[0], resolution)
    param2_range = np.linspace(*param_ranges[1], resolution)

    landscape = np.zeros((resolution, resolution))
    base_params = self.optimal_params_.copy()

    for i, p1 in enumerate(param1_range):
        for j, p2 in enumerate(param2_range):
            params = base_params.copy()
            params[param_indices[0]] = p1
            params[param_indices[1]] = p2
            landscape[i, j] = self._compute_expectation_value(params)

    return {
        'param1_range': param1_range,
        'param2_range': param2_range,
        'landscape': landscape,
        'optimal_params': self.optimal_params_[param_indices],
        'param_indices': param_indices
    }

analyze_convergence

analyze_convergence() -> dict[str, Any]

Analyze VQE convergence properties.

Returns:

Type	Description
dict[str, Any]	Convergence analysis results

Source code in src/superquantx/algorithms/vqe.py

def analyze_convergence(self) -> dict[str, Any]:
    """Analyze VQE convergence properties.

    Returns:
        Convergence analysis results

    """
    if not self.energy_history:
        raise ValueError("No optimization history available")

    energies = np.array(self.energy_history)
    gradients = np.array(self.gradient_history) if self.gradient_history else None

    # Basic convergence metrics
    analysis = {
        'final_energy': energies[-1],
        'energy_variance': np.var(energies[-10:]) if len(energies) >= 10 else np.var(energies),
        'total_iterations': len(energies),
        'energy_change': abs(energies[-1] - energies[0]) if len(energies) > 1 else 0,
    }

    # Convergence detection
    if len(energies) >= 10:
        recent_change = abs(energies[-1] - energies[-10])
        analysis['converged'] = recent_change < self.convergence_threshold
    else:
        analysis['converged'] = False

    # Gradient analysis
    if gradients is not None and len(gradients) > 0:
        analysis.update({
            'final_gradient_norm': gradients[-1],
            'gradient_trend': 'decreasing' if gradients[-1] < gradients[0] else 'increasing',
            'min_gradient_norm': np.min(gradients),
        })

    # Identify plateaus and oscillations
    if len(energies) >= 20:
        # Check for plateaus (little change over many iterations)
        plateau_threshold = self.convergence_threshold * 10
        recent_energies = energies[-20:]
        energy_std = np.std(recent_energies)
        analysis['plateau_detected'] = energy_std < plateau_threshold

        # Check for oscillations
        energy_diff = np.diff(energies[-20:])
        sign_changes = np.sum(np.diff(np.sign(energy_diff)) != 0)
        analysis['oscillation_detected'] = sign_changes > len(energy_diff) * 0.7

    return analysis

compare_with_exact

compare_with_exact(exact_ground_energy: float) -> dict[str, Any]

Compare VQE result with exact ground state energy.

Parameters:

Name	Type	Description	Default
exact_ground_energy	float	Known exact ground state energy	required

Returns:

Type	Description
dict[str, Any]	Comparison analysis

Source code in src/superquantx/algorithms/vqe.py

def compare_with_exact(self, exact_ground_energy: float) -> dict[str, Any]:
    """Compare VQE result with exact ground state energy.

    Args:
        exact_ground_energy: Known exact ground state energy

    Returns:
        Comparison analysis

    """
    if self.optimal_value_ is None:
        raise ValueError("VQE must be optimized for comparison")

    error = abs(self.optimal_value_ - exact_ground_energy)
    relative_error = error / abs(exact_ground_energy) if exact_ground_energy != 0 else float('inf')

    return {
        'vqe_energy': self.optimal_value_,
        'exact_energy': exact_ground_energy,
        'absolute_error': error,
        'relative_error': relative_error,
        'chemical_accuracy': error < 1.6e-3,  # 1 kcal/mol in Hartree
        'energy_above_ground': max(0, self.optimal_value_ - exact_ground_energy)
    }

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get VQE parameters.

Source code in src/superquantx/algorithms/vqe.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get VQE parameters."""
    params = super().get_params(deep)
    params.update({
        'ansatz': self.ansatz,
        'optimizer': self.optimizer,
        'maxiter': self.maxiter,
        'include_custom_gates': self.include_custom_gates,
        'convergence_threshold': self.convergence_threshold,
    })
    return params

set_params

set_params(**params) -> VQE

Set VQE parameters.

Source code in src/superquantx/algorithms/vqe.py

def set_params(self, **params) -> 'VQE':
    """Set VQE parameters."""
    if self.is_fitted and any(key in params for key in ['ansatz', 'hamiltonian']):
        logger.warning("Changing core parameters requires refitting the model")
        self.is_fitted = False

    return super().set_params(**params)

find_ground_state

find_ground_state() -> float

Find the ground state energy of the Hamiltonian.

This is a convenience method that combines fit() and _run_optimization() to find the ground state energy in a single call.

Returns:

Type	Description
float	Ground state energy

Example

vqe = VQE(backend='simulator', hamiltonian=hamiltonian) ground_energy = vqe.find_ground_state()

Source code in src/superquantx/algorithms/vqe.py

def find_ground_state(self) -> float:
    """Find the ground state energy of the Hamiltonian.

    This is a convenience method that combines fit() and _run_optimization()
    to find the ground state energy in a single call.

    Returns:
        Ground state energy

    Example:
        >>> vqe = VQE(backend='simulator', hamiltonian=hamiltonian)
        >>> ground_energy = vqe.find_ground_state()
    """
    # Fit if not already fitted
    if not self.is_fitted:
        self.fit()

    # Run optimization
    self._run_optimization()

    # Return the optimal energy
    return self.optimal_value_

superquantx.algorithms.create_vqe_for_molecule

create_vqe_for_molecule(molecule_name: str, bond_distance: float | None = None, backend: str = 'simulator', ansatz: str = 'RealAmplitudes', optimizer: str = 'COBYLA', client=None, **kwargs) -> VQE

Create a VQE instance for a small molecule.

Only H2 in STO-3G at its equilibrium bond length (0.735 Angstrom) ships with the library. Other molecules or bond lengths need a Hamiltonian from a chemistry package (e.g. PySCF + OpenFermion or Qiskit Nature) passed to :class:VQE directly.

Source code in src/superquantx/algorithms/vqe.py

def create_vqe_for_molecule(
    molecule_name: str,
    bond_distance: float | None = None,
    backend: str = 'simulator',
    ansatz: str = 'RealAmplitudes',
    optimizer: str = 'COBYLA',
    client = None,
    **kwargs,
) -> VQE:
    """Create a VQE instance for a small molecule.

    Only H2 in STO-3G at its equilibrium bond length (0.735 Angstrom) ships
    with the library. Other molecules or bond lengths need a Hamiltonian from
    a chemistry package (e.g. PySCF + OpenFermion or Qiskit Nature) passed to
    :class:`VQE` directly.
    """
    if molecule_name.upper() != 'H2':
        raise NotImplementedError(
            f"No built-in Hamiltonian for {molecule_name}. Build one with a chemistry "
            "package and pass it to VQE(hamiltonian=...)."
        )
    if bond_distance is not None and abs(bond_distance - 0.735) > 0.02:
        raise NotImplementedError(
            "Only the H2 equilibrium geometry (0.735 Angstrom) is built in."
        )
    return VQE(
        hamiltonian=dict(H2_STO3G_0735),
        ansatz=ansatz,
        backend=backend,
        optimizer=optimizer,
        client=client,
        **kwargs,
    )

Quantum Approximate Optimization Algorithm

superquantx.algorithms.QAOA

QAOA(backend: str | Any, p: int = 1, problem_hamiltonian: Callable | None = None, mixer_hamiltonian: Callable | None = None, initial_state: str = 'uniform_superposition', optimizer: str = 'COBYLA', shots: int = 1024, maxiter: int = 1000, n_restarts: int = 3, **kwargs)

Bases: OptimizationQuantumAlgorithm

Quantum Approximate Optimization Algorithm for combinatorial optimization.

QAOA is a hybrid quantum-classical algorithm that alternates between quantum evolution and classical parameter optimization to find approximate solutions to combinatorial optimization problems.

The algorithm works by: 1. Preparing an initial superposition state 2. Applying alternating problem and mixer Hamiltonians 3. Measuring the quantum state 4. Classically optimizing the parameters

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for circuit execution	required
p	int	Number of QAOA layers (depth)	1
problem_hamiltonian	Callable | None	Problem Hamiltonian function	None
mixer_hamiltonian	Callable | None	Mixer Hamiltonian function	None
initial_state	str	Initial quantum state preparation	'uniform_superposition'
optimizer	str	Classical optimizer ('COBYLA', 'L-BFGS-B', etc.)	'COBYLA'
shots	int	Number of measurement shots	1024
maxiter	int	Maximum optimization iterations	1000
**kwargs		Additional parameters	{}

Example

Define Max-Cut problem

def problem_ham(gamma, graph): ... return create_maxcut_hamiltonian(gamma, graph) qaoa = QAOA(backend='pennylane', p=2, problem_hamiltonian=problem_ham) result = qaoa.optimize(graph_data)

Source code in src/superquantx/algorithms/qaoa.py

def __init__(
    self,
    backend: str | Any,
    p: int = 1,
    problem_hamiltonian: Callable | None = None,
    mixer_hamiltonian: Callable | None = None,
    initial_state: str = 'uniform_superposition',
    optimizer: str = 'COBYLA',
    shots: int = 1024,
    maxiter: int = 1000,
    n_restarts: int = 3,
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)

    self.p = p
    self.n_restarts = n_restarts
    self.problem_hamiltonian = problem_hamiltonian
    self.mixer_hamiltonian = mixer_hamiltonian or self._default_mixer
    self.initial_state = initial_state
    self.optimizer = optimizer
    self.maxiter = maxiter

    # QAOA-specific parameters
    self.n_qubits = None
    self.problem_instance = None
    self.circuit = None

    # Parameter bounds
    self.gamma_bounds = (0, 2*np.pi)
    self.beta_bounds = (0, np.pi)

    logger.info(f"Initialized QAOA with p={p}, optimizer={optimizer}")

Functions

fit

fit(X: ndarray, y: ndarray | None = None, **kwargs) -> QAOA

Fit QAOA to problem instance.

Parameters:

Name	Type	Description	Default
X	ndarray	Problem instance data (e.g., adjacency matrix for Max-Cut)	required
y	ndarray | None	Not used in QAOA	None
**kwargs		Additional parameters	{}

Returns:

Type	Description
QAOA	Self for method chaining

Source code in src/superquantx/algorithms/qaoa.py

def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> 'QAOA':
    """Fit QAOA to problem instance.

    Args:
        X: Problem instance data (e.g., adjacency matrix for Max-Cut)
        y: Not used in QAOA
        **kwargs: Additional parameters

    Returns:
        Self for method chaining

    """
    logger.info(f"Fitting QAOA to problem instance of shape {X.shape}")

    self.problem_instance = X
    self.n_qubits = self._infer_qubits(X)

    # Reset optimization history
    self.optimization_history_ = []

    self.is_fitted = True
    return self

predict

predict(X: ndarray | None = None, **kwargs) -> np.ndarray

Sample the optimised circuit and return the best sampled partition.

Entry i of the returned 0/1 array is the side of node i.

Source code in src/superquantx/algorithms/qaoa.py

def predict(self, X: np.ndarray | None = None, **kwargs) -> np.ndarray:
    """Sample the optimised circuit and return the best sampled partition.

    Entry i of the returned 0/1 array is the side of node i.
    """
    if not self.is_fitted or self.optimal_params_ is None:
        raise ValueError("QAOA must be fitted and optimized before prediction")
    circuit = self._create_qaoa_circuit(self.optimal_params_)
    samples = self.backend.sample_circuit(circuit, shots=self.shots)
    unique = np.unique(samples, axis=0)
    values = [cut_value(self.problem_instance, row) for row in unique]
    return unique[int(np.argmax(values))]

solve

solve(adjacency: ndarray) -> dict[str, Any]

Fit, optimise and sample in one call, with an exact classical check.

Returns the QAOA partition and cut, the brute-force optimum, and the approximation ratio of the expected QAOA cut.

Source code in src/superquantx/algorithms/qaoa.py

def solve(self, adjacency: np.ndarray) -> dict[str, Any]:
    """Fit, optimise and sample in one call, with an exact classical check.

    Returns the QAOA partition and cut, the brute-force optimum, and the
    approximation ratio of the expected QAOA cut.
    """
    self.fit(np.asarray(adjacency, dtype=float))
    result = self._run_optimization(None)
    bits = self.predict()
    best_bits, best_cut = brute_force_maxcut(self.problem_instance)
    return {
        'bitstring': ''.join(str(int(b)) for b in bits),
        'cut_value': cut_value(self.problem_instance, bits),
        'expected_cut': self.optimal_value_,
        'classical_bitstring': ''.join(str(int(b)) for b in best_bits),
        'classical_optimum': best_cut,
        'approximation_ratio': self.optimal_value_ / best_cut if best_cut else float('nan'),
        'optimal_params': self.optimal_params_,
        'n_evaluations': result['n_iterations'],
    }

get_optimization_landscape

get_optimization_landscape(param_range: tuple[float, float], resolution: int = 50) -> dict[str, Any]

Compute optimization landscape for visualization.

Parameters:

Name	Type	Description	Default
param_range	tuple[float, float]	Range of parameters to explore	required
resolution	int	Number of points per dimension	50

Returns:

Type	Description
dict[str, Any]	Dictionary with landscape data

Source code in src/superquantx/algorithms/qaoa.py

def get_optimization_landscape(self, param_range: tuple[float, float], resolution: int = 50) -> dict[str, Any]:
    """Compute optimization landscape for visualization.

    Args:
        param_range: Range of parameters to explore
        resolution: Number of points per dimension

    Returns:
        Dictionary with landscape data

    """
    if self.p != 1:
        logger.warning("Landscape visualization only supported for p=1")
        return {}

    gamma_range = np.linspace(*param_range, resolution)
    beta_range = np.linspace(*param_range, resolution)

    landscape = np.zeros((resolution, resolution))

    for i, gamma in enumerate(gamma_range):
        for j, beta in enumerate(beta_range):
            params = np.array([gamma, beta])
            landscape[i, j] = -self._objective_function(params)

    return {
        'gamma_range': gamma_range,
        'beta_range': beta_range,
        'landscape': landscape,
        'optimal_params': self.optimal_params_ if hasattr(self, 'optimal_params_') else None
    }

analyze_solution_quality

analyze_solution_quality(true_optimum: float | None = None) -> dict[str, Any]

Analyze quality of QAOA solution.

Parameters:

Name	Type	Description	Default
true_optimum	float | None	Known optimal value for comparison	None

Returns:

Type	Description
dict[str, Any]	Analysis results

Source code in src/superquantx/algorithms/qaoa.py

def analyze_solution_quality(self, true_optimum: float | None = None) -> dict[str, Any]:
    """Analyze quality of QAOA solution.

    Args:
        true_optimum: Known optimal value for comparison

    Returns:
        Analysis results

    """
    if self.optimal_value_ is None:
        raise ValueError("No optimal solution available")

    analysis = {
        'qaoa_value': self.optimal_value_,
        'n_layers': self.p,
        'n_parameters': 2 * self.p,
        'optimization_iterations': len(self.optimization_history_),
    }

    if true_optimum is not None:
        approximation_ratio = self.optimal_value_ / true_optimum
        analysis.update({
            'true_optimum': true_optimum,
            'approximation_ratio': approximation_ratio,
            'relative_error': abs(1 - approximation_ratio),
        })

    # Analyze convergence
    if len(self.optimization_history_) > 1:
        costs = [-entry['cost'] for entry in self.optimization_history_]
        analysis.update({
            'convergence_achieved': costs[-1] == max(costs),
            'improvement_over_random': self.optimal_value_ - np.mean(costs[:5]) if len(costs) >= 5 else 0,
            'final_cost_variance': np.var(costs[-10:]) if len(costs) >= 10 else 0,
        })

    return analysis

get_params

get_params(deep: bool = True) -> dict[str, Any]

Get QAOA parameters.

Source code in src/superquantx/algorithms/qaoa.py

def get_params(self, deep: bool = True) -> dict[str, Any]:
    """Get QAOA parameters."""
    params = super().get_params(deep)
    params.update({
        'p': self.p,
        'optimizer': self.optimizer,
        'initial_state': self.initial_state,
        'maxiter': self.maxiter,
        'gamma_bounds': self.gamma_bounds,
        'beta_bounds': self.beta_bounds,
    })
    return params

set_params

set_params(**params) -> QAOA

Set QAOA parameters.

Source code in src/superquantx/algorithms/qaoa.py

def set_params(self, **params) -> 'QAOA':
    """Set QAOA parameters."""
    if self.is_fitted and any(key in params for key in ['p', 'problem_hamiltonian', 'mixer_hamiltonian']):
        logger.warning("Changing core parameters requires refitting the model")
        self.is_fitted = False

    return super().set_params(**params)

Quantum Agents

Base Quantum Agent

superquantx.algorithms.quantum_agents.QuantumAgent

QuantumAgent(backend: str | Any, agent_config: dict[str, Any] | None = None, shots: int = 1024, **kwargs)

Bases: BaseQuantumAlgorithm, ABC

Base class for quantum agents.

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend for circuit execution	required
agent_config	dict[str, Any] | None	Configuration dictionary for the agent	None
shots	int	Number of measurement shots	1024
**kwargs		Additional parameters (for example seed)	{}

Source code in src/superquantx/algorithms/quantum_agents.py

def __init__(
    self,
    backend: str | Any,
    agent_config: dict[str, Any] | None = None,
    shots: int = 1024,
    **kwargs
) -> None:
    super().__init__(backend=backend, shots=shots, **kwargs)
    self.agent_config = agent_config or {}
    self.algorithms: dict[str, Any] = {}
    self.results_history: list[Any] = []
    self.performance_metrics: dict[str, Any] = {}
    self._initialize_agent()
    logger.info("Initialized %s", self.__class__.__name__)

Functions

solve abstractmethod

solve(problem_instance: Any, **kwargs) -> QuantumResult

Solve a problem using the quantum agent.

Source code in src/superquantx/algorithms/quantum_agents.py

@abstractmethod
def solve(self, problem_instance: Any, **kwargs) -> QuantumResult:
    """Solve a problem using the quantum agent."""

get_agent_info

get_agent_info() -> dict[str, Any]

Get information about the agent and its algorithms.

Source code in src/superquantx/algorithms/quantum_agents.py

def get_agent_info(self) -> dict[str, Any]:
    """Get information about the agent and its algorithms."""
    return {
        'agent_type': self.__class__.__name__,
        'algorithms': list(self.algorithms.keys()),
        'config': self.agent_config,
        'backend': type(self.backend).__name__,
        'performance_metrics': self.performance_metrics,
    }

Specialized Agents

superquantx.algorithms.quantum_agents.QuantumPortfolioAgent

QuantumPortfolioAgent(backend: str | Any, n_select: int | None = None, risk_aversion: float = 1.0, reps: int = 2, alpha: float = 0.25, n_restarts: int = 5, maxiter: int = 300, **kwargs)

Bases: QuantumAgent

Pick k of n assets with CVaR-VQE, checked against exact classical answers.

The selection problem is encoded as a diagonal Ising Hamiltonian whose ground state is the best equal-weight k-asset portfolio. A RealAmplitudes circuit is trained on the chosen backend to minimise the CVaR of the energy (the mean of the best alpha fraction of outcomes, Barkoutsos et al., Quantum 4, 256 (2020)), which works much better than the plain expectation for combinatorial problems. shots samples are drawn from the final state and the best sampled selection is returned. Two classical references are always computed in the same call: the brute-force optimum of the same QUBO and a long-only Markowitz solution with continuous weights. Practical up to about 10 assets (2^n statevector).

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend	required
n_select	int | None	Number of assets to hold (default: half the assets)	None
risk_aversion	float	Weight of the variance term	1.0
reps	int	Ansatz repetitions	2
alpha	float	CVaR fraction (1.0 is ordinary VQE)	0.25
n_restarts	int	Optimizer restarts from different seeds	5
maxiter	int	Optimizer iterations per restart	300
**kwargs		seed and other base parameters	{}

Example

agent = QuantumPortfolioAgent(backend='simulator', n_select=2, seed=0) res = agent.solve(returns) # returns: (periods x assets) res.result['selected_assets'], res.result['matches_classical_optimum']

Source code in src/superquantx/algorithms/quantum_agents.py

def __init__(
    self,
    backend: str | Any,
    n_select: int | None = None,
    risk_aversion: float = 1.0,
    reps: int = 2,
    alpha: float = 0.25,
    n_restarts: int = 5,
    maxiter: int = 300,
    **kwargs
) -> None:
    if not 0.0 < alpha <= 1.0:
        raise ValueError("alpha must be in (0, 1]")
    self.alpha = alpha
    self.n_select = n_select
    self.risk_aversion = risk_aversion
    self.reps = reps
    self.n_restarts = n_restarts
    self.maxiter = maxiter
    super().__init__(backend=backend, agent_config={
        'n_select': n_select, 'risk_aversion': risk_aversion, 'reps': reps,
    }, **kwargs)
    self.expected_returns = None
    self.covariance_matrix = None
    self.optimal_weights = None

Functions

fit

fit(X: ndarray, y: ndarray | None = None, **kwargs) -> QuantumPortfolioAgent

Estimate mean returns and covariance from a (periods x assets) matrix.

Source code in src/superquantx/algorithms/quantum_agents.py

def fit(self, X: np.ndarray, y: np.ndarray | None = None, **kwargs) -> QuantumPortfolioAgent:
    """Estimate mean returns and covariance from a (periods x assets) matrix."""
    X = np.asarray(X, dtype=float)
    if X.ndim != 2 or X.shape[1] < 2:
        raise ValueError("Pass historical returns as a (periods x assets) matrix")
    self.expected_returns = X.mean(axis=0)
    self.covariance_matrix = np.cov(X.T)
    self.is_fitted = True
    return self

solve

solve(problem_instance: ndarray | None = None, **kwargs) -> QuantumResult

Select assets with VQE and report the classical checks.

Parameters:

Name	Type	Description	Default
problem_instance	ndarray | None	Optional returns matrix; refits the agent if given.	None

Returns:

Type	Description
QuantumResult	QuantumResult whose result has the quantum selection and weights,
QuantumResult	its objective, the brute-force optimum, whether they match, the
QuantumResult	probability VQE puts on the optimal selection, and a classical
QuantumResult	Markowitz reference.

Source code in src/superquantx/algorithms/quantum_agents.py

def solve(self, problem_instance: np.ndarray | None = None, **kwargs) -> QuantumResult:
    """Select assets with VQE and report the classical checks.

    Args:
        problem_instance: Optional returns matrix; refits the agent if given.

    Returns:
        QuantumResult whose ``result`` has the quantum selection and weights,
        its objective, the brute-force optimum, whether they match, the
        probability VQE puts on the optimal selection, and a classical
        Markowitz reference.

    """
    start = time.time()
    if problem_instance is not None:
        self.fit(problem_instance)
    if not self.is_fitted:
        raise ValueError("Call fit(returns) or pass returns to solve()")

    n = len(self.expected_returns)
    k = self.n_select or max(1, n // 2)
    values = portfolio_qubo_values(self.expected_returns, self.covariance_matrix, k,
                                   self.risk_aversion)
    # Rescale so feasible selections span [0, 1]: same ground state, but the
    # optimizer sees the differences that matter instead of the penalty wall.
    feasible = np.array([bin(i).count('1') == k for i in range(2 ** n)])
    spread = max(values[feasible].max() - values[feasible].min(), 1e-12)
    H = np.diag((values - values.min()) / spread)

    order = np.argsort(H.diagonal())
    h_sorted = H.diagonal()[order]
    n_params = self.backend.ansatz_param_count('RealAmplitudes', n, reps=self.reps)

    def probabilities(params):
        circuit = self.backend.create_ansatz('RealAmplitudes', n, params, reps=self.reps)
        return np.abs(self.backend.statevector_big_endian(circuit)) ** 2

    def cvar(params):
        # Mean energy of the best alpha fraction of the distribution (exact, from probabilities).
        p_sorted = probabilities(params)[order]
        cum = np.cumsum(p_sorted)
        take = np.clip(self.alpha - (cum - p_sorted), 0.0, p_sorted)
        return float(np.sum(take * h_sorted) / self.alpha)

    base_seed = 0 if self.seed is None else self.seed
    best = None
    for r in range(max(1, self.n_restarts)):
        x0 = np.random.default_rng(base_seed + r).uniform(-np.pi, np.pi, n_params)
        res = minimize(cvar, x0, method='COBYLA', options={'maxiter': self.maxiter})
        if best is None or res.fun < best.fun:
            best = res
    probs = probabilities(best.x)
    probs = probs / probs.sum()
    samples = np.random.default_rng(base_seed).choice(len(probs), size=self.shots, p=probs)
    q_index = int(samples[np.argmin(values[samples])])
    c_index = int(np.argmin(values))
    self.optimal_params_ = best.x

    def bits(i):
        return np.array([(i >> (n - 1 - j)) & 1 for j in range(n)])

    q_bits, c_bits = bits(q_index), bits(c_index)
    weights = q_bits / max(1, q_bits.sum())
    self.optimal_weights = weights

    result = {
        'selected_assets': [int(i) for i in np.flatnonzero(q_bits)],
        'weights': weights,
        'objective': float(values[q_index]),
        'cvar_rescaled': float(best.fun),
        'shots': self.shots,
        'feasible': bool(q_bits.sum() == k),
        'classical_selected_assets': [int(i) for i in np.flatnonzero(c_bits)],
        'classical_objective': float(values[c_index]),
        'matches_classical_optimum': bool(q_index == c_index),
        'objective_gap': float(values[q_index] - values[c_index]),
        'probability_of_optimum': float(probs[c_index]),
        'optimum_sampled': bool(np.any(samples == c_index)),
        'markowitz_reference': self._markowitz(),
        **self._metrics(weights),
    }
    self.performance_metrics = {k_: result[k_] for k_ in
                                ('matches_classical_optimum', 'probability_of_optimum')}
    return self._result(result, start, n_assets=n, n_select=k,
                        method='CVaR-VQE on a mean-variance QUBO; brute force check',
                        n_evaluations=int(best.nfev))

predict

predict(X: ndarray | None = None, **kwargs) -> np.ndarray

Return the equal weights of the VQE selection.

Source code in src/superquantx/algorithms/quantum_agents.py

def predict(self, X: np.ndarray | None = None, **kwargs) -> np.ndarray:
    """Return the equal weights of the VQE selection."""
    if self.optimal_weights is None:
        self.solve(X)
    return self.optimal_weights

superquantx.algorithms.quantum_agents.QuantumOptimizationAgent

QuantumOptimizationAgent(backend: str | Any, problem_type: str = 'combinatorial', p: int = 2, algorithms: list[str] | None = None, maxiter: int = 200, n_restarts: int = 3, reps: int = 2, **kwargs)

Bases: QuantumAgent

Solve small optimisation problems with QAOA or VQE plus an exact classical check.

• problem_type='combinatorial': solve(adjacency) runs weighted MaxCut with QAOA and compares against brute force.
• problem_type='continuous': solve(hamiltonian) runs VQE and compares against exact diagonalisation.

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend	required
problem_type	str	'combinatorial' or 'continuous'	'combinatorial'
p	int	QAOA layers	2
**kwargs		Base parameters and extra QAOA/VQE options (maxiter, n_restarts for QAOA, reps for VQE)	{}

Source code in src/superquantx/algorithms/quantum_agents.py

def __init__(
    self,
    backend: str | Any,
    problem_type: str = 'combinatorial',
    p: int = 2,
    algorithms: list[str] | None = None,
    maxiter: int = 200,
    n_restarts: int = 3,
    reps: int = 2,
    **kwargs
) -> None:
    if problem_type not in ('combinatorial', 'continuous'):
        raise ValueError("problem_type must be 'combinatorial' or 'continuous'")
    self.problem_type = problem_type
    self.p = p
    self.maxiter = maxiter
    self.n_restarts = n_restarts
    self.reps = reps
    self.available_algorithms = algorithms or (
        ['qaoa'] if problem_type == 'combinatorial' else ['vqe'])
    super().__init__(backend=backend, agent_config={
        'problem_type': problem_type, 'p': p, 'algorithms': self.available_algorithms,
    }, **kwargs)
    self.problem_instance = None

Functions

fit

fit(X: Any, y: ndarray | None = None, **kwargs) -> QuantumOptimizationAgent

Store the problem: an adjacency matrix or a Hamiltonian.

Source code in src/superquantx/algorithms/quantum_agents.py

def fit(self, X: Any, y: np.ndarray | None = None, **kwargs) -> QuantumOptimizationAgent:
    """Store the problem: an adjacency matrix or a Hamiltonian."""
    self.problem_instance = X
    self.is_fitted = True
    return self

solve

solve(problem_instance: Any = None, **kwargs) -> QuantumResult

Solve and return the quantum answer with its exact classical check.

Source code in src/superquantx/algorithms/quantum_agents.py

def solve(self, problem_instance: Any = None, **kwargs) -> QuantumResult:
    """Solve and return the quantum answer with its exact classical check."""
    start = time.time()
    if problem_instance is not None:
        self.fit(problem_instance)
    if self.problem_instance is None:
        raise ValueError("Pass an adjacency matrix (combinatorial) or Hamiltonian (continuous)")

    if self.problem_type == 'combinatorial':
        out = self.algorithms['qaoa'].solve(np.asarray(self.problem_instance, dtype=float))
        out['matches_classical_optimum'] = bool(
            np.isclose(out['cut_value'], out['classical_optimum']))
        return self._result(out, start, problem_type='maxcut', algorithm_used='QAOA',
                            classical_check='brute force')

    vqe = self.algorithms['vqe']
    vqe.fit(self.problem_instance)
    opt = vqe._run_optimization()
    out = {
        'ground_energy': opt['ground_energy'],
        'exact_energy': opt['exact_energy'],
        'error': abs(opt['ground_energy'] - opt['exact_energy']),
        'optimal_params': opt['optimal_params'],
        'n_evaluations': opt['n_iterations'],
    }
    return self._result(out, start, problem_type='ground_state', algorithm_used='VQE',
                        classical_check='exact diagonalisation')

predict

predict(X: Any = None, **kwargs) -> np.ndarray

MaxCut partition (combinatorial) or energy (continuous).

Source code in src/superquantx/algorithms/quantum_agents.py

def predict(self, X: Any = None, **kwargs) -> np.ndarray:
    """MaxCut partition (combinatorial) or energy (continuous)."""
    res = self.solve(X)
    if self.problem_type == 'combinatorial':
        return np.array([int(b) for b in res.result['bitstring']])
    return np.array([res.result['ground_energy']])

superquantx.algorithms.quantum_agents.QuantumClassificationAgent

QuantumClassificationAgent(backend: str | Any, algorithms: list[str] | None = None, ensemble_method: str = 'voting', cv: int = 5, **kwargs)

Bases: QuantumAgent

Train quantum classifiers and benchmark them against tuned classical models.

solve((X, y)) runs :func:superquantx.benchmarks.compare_to_classical on the first algorithm (QuantumSVM by default) so that the reported accuracy is a cross-validated test accuracy next to a tuned RBF SVM and a logistic regression on identical folds, then refits on all the data.

Parameters:

Name	Type	Description	Default
backend	str | Any	Quantum backend	required
algorithms	list[str] | None	Any of 'quantum_svm', 'quantum_nn', 'hybrid'	None
ensemble_method	str	'voting', 'weighted' or 'best' (used by predict when several algorithms are trained)	'voting'
cv	int	Folds for the benchmark in solve	5
**kwargs		Base parameters	{}

Source code in src/superquantx/algorithms/quantum_agents.py

def __init__(
    self,
    backend: str | Any,
    algorithms: list[str] | None = None,
    ensemble_method: str = 'voting',
    cv: int = 5,
    **kwargs
) -> None:
    self.available_algorithms = algorithms or ['quantum_svm']
    self.ensemble_method = ensemble_method
    self.cv = cv
    super().__init__(backend=backend, agent_config={
        'algorithms': self.available_algorithms, 'ensemble_method': ensemble_method,
    }, **kwargs)

Functions

fit

fit(X: ndarray, y: ndarray, **kwargs) -> QuantumClassificationAgent

Fit every algorithm. Errors propagate; nothing is silently scored as 0.

Source code in src/superquantx/algorithms/quantum_agents.py

def fit(self, X: np.ndarray, y: np.ndarray, **kwargs) -> QuantumClassificationAgent:
    """Fit every algorithm. Errors propagate; nothing is silently scored as 0."""
    for name, algorithm in self.algorithms.items():
        algorithm.fit(X, y)
        self.performance_metrics[name] = {
            'train_accuracy': float(accuracy_score(y, algorithm.predict(X)))
        }
    self.is_fitted = True
    return self

predict

predict(X: ndarray, **kwargs) -> np.ndarray

Predict with one algorithm, or combine several.

Source code in src/superquantx/algorithms/quantum_agents.py

def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
    """Predict with one algorithm, or combine several."""
    if not self.is_fitted:
        raise ValueError("Agent must be fitted before prediction")
    preds = {name: np.asarray(a.predict(X)) for name, a in self.algorithms.items()}
    if len(preds) == 1:
        return next(iter(preds.values()))
    if self.ensemble_method == 'best':
        best = max(self.performance_metrics,
                   key=lambda n: self.performance_metrics[n]['train_accuracy'])
        return preds[best]
    weights = {n: (self.performance_metrics[n]['train_accuracy']
                   if self.ensemble_method == 'weighted' else 1.0) for n in preds}
    out = []
    for i in range(len(X)):
        votes: dict[Any, float] = {}
        for n, p in preds.items():
            votes[p[i]] = votes.get(p[i], 0.0) + weights[n]
        out.append(max(votes.items(), key=lambda kv: kv[1])[0])
    return np.array(out)

solve

solve(problem_instance: tuple[ndarray, ndarray], **kwargs) -> QuantumResult

Benchmark against classical baselines with CV, then fit on all data.

Keyword arguments are passed to compare_to_classical.

Source code in src/superquantx/algorithms/quantum_agents.py

def solve(self, problem_instance: tuple[np.ndarray, np.ndarray], **kwargs) -> QuantumResult:
    """Benchmark against classical baselines with CV, then fit on all data.

    Keyword arguments are passed to ``compare_to_classical``.
    """
    from ..benchmarks import compare_to_classical

    start = time.time()
    X, y = problem_instance
    name, algorithm = next(iter(self.algorithms.items()))
    kwargs.setdefault('cv', self.cv)
    kwargs.setdefault('seed', 0 if self.seed is None else self.seed)
    benchmark = compare_to_classical(X, y, algorithm, **kwargs)
    self.fit(X, y)
    result = {
        'algorithm': name,
        'cv_accuracy': benchmark.quantum.accuracy_mean,
        'cv_accuracy_std': benchmark.quantum.accuracy_std,
        'best_classical': benchmark.best_classical.name,
        'best_classical_cv_accuracy': benchmark.best_classical.accuracy_mean,
        'delta_vs_best_classical': benchmark.delta_vs_best_classical,
        'p_value': benchmark.p_value_vs_best_classical,
        'verdict': benchmark.verdict,
        'benchmark': benchmark,
        'train_accuracy': self.performance_metrics[name]['train_accuracy'],
    }
    return self._result(result, start, n_samples=len(X), n_features=X.shape[1],
                        n_classes=len(np.unique(y)), algorithms_used=list(self.algorithms))

Examples and Usage Patterns

Machine Learning Example

import numpy as np
from sklearn.datasets import make_classification
import superquantx as sqx

# Generate sample data
X, y = make_classification(
    n_samples=100, 
    n_features=4, 
    n_classes=2, 
    random_state=42
)

# Split data
X_train, X_test = X[:80], X[80:]
y_train, y_test = y[:80], y[80:]

# Create and train Quantum SVM
qsvm = sqx.QuantumSVM(
    backend='simulator',
    feature_map='ZFeatureMap',
    num_features=4
)

qsvm.fit(X_train, y_train)
predictions = qsvm.predict(X_test)
accuracy = qsvm.score(X_test, y_test)

print(f"Quantum SVM Accuracy: {accuracy:.3f}")

VQE Molecule Example

import superquantx as sqx

# Create VQE for H2 molecule
vqe = sqx.create_vqe_for_molecule(
    molecule='H2',
    bond_length=0.735,  # Angstroms
    backend='simulator'
)

# Find ground state
ground_energy = vqe.find_ground_state()
print(f"H2 Ground State Energy: {ground_energy:.6f} Ha")

# Get optimized parameters
optimal_params = vqe.get_optimal_parameters()
print(f"Optimal parameters: {optimal_params}")

QAOA Optimization Example

import superquantx as sqx

# Define Max-Cut problem
edges = [(0, 1), (1, 2), (2, 3), (3, 0), (0, 2)]

qaoa = sqx.QAOA(
    problem_type='max_cut',
    graph_edges=edges,
    layers=3,
    backend='simulator'
)

# Solve optimization problem
solution = qaoa.solve()
optimal_value = qaoa.get_optimal_value()

print(f"Max-Cut Solution: {solution}")
print(f"Cut Value: {optimal_value}")

Quantum Agent Example

import superquantx as sqx

# Create quantum portfolio optimization agent
portfolio_agent = sqx.QuantumPortfolioAgent(
    backend='simulator',
    risk_tolerance=0.1,
    optimization_method='qaoa'
)

# Sample portfolio data
assets = ['AAPL', 'GOOGL', 'MSFT', 'TSLA']
returns = [0.12, 0.15, 0.08, 0.20]
risks = [0.05, 0.10, 0.03, 0.15]

# Optimize portfolio
optimal_weights = portfolio_agent.optimize_portfolio(
    assets=assets,
    expected_returns=returns,
    risk_estimates=risks,
    budget=10000
)

print("Optimal Portfolio:")
for asset, weight in zip(assets, optimal_weights):
    print(f"{asset}: {weight:.2%}")

Best Practices

Algorithm Selection

1. For Classification: Use QuantumSVM for small datasets, QuantumNN for complex patterns
2. For Optimization: Use VQE for chemistry problems, QAOA for combinatorial optimization
3. For Autonomous Tasks: Use specialized QuantumAgent implementations

Backend Optimization

# Choose appropriate backend for algorithm
algorithms_backends = {
    'QuantumSVM': 'pennylane',      # Best autodiff support
    'VQE': 'qiskit',                # Good hardware access
    'QAOA': 'cirq',                 # Flexible circuit construction
    'QuantumAgents': 'simulator',    # Fast prototyping
}

# Use backend-specific optimizations
qsvm = sqx.QuantumSVM(
    backend='pennylane',
    feature_map='ZZFeatureMap',     # More expressive for PennyLane
    optimization_level=2
)

Performance Monitoring

import time
import superquantx as sqx

# Benchmark different algorithms
def benchmark_algorithm(algorithm_class, X, y, **kwargs):
    start_time = time.time()

    algorithm = algorithm_class(**kwargs)
    algorithm.fit(X, y)
    predictions = algorithm.predict(X)

    execution_time = time.time() - start_time
    accuracy = algorithm.score(X, y)

    return {
        'accuracy': accuracy,
        'time': execution_time,
        'algorithm': algorithm_class.__name__
    }

# Compare algorithms
algorithms = [sqx.QuantumSVM, sqx.QuantumNN, sqx.HybridClassifier]
results = []

for algo in algorithms:
    result = benchmark_algorithm(algo, X_train, y_train, backend='simulator')
    results.append(result)
    print(f"{result['algorithm']}: {result['accuracy']:.3f} accuracy in {result['time']:.2f}s")

---

For complete algorithm implementations and advanced usage patterns, see: - Backend Integration Guide - Tutorial Examples - User Guide