cqlib-qml 0.1.0b1__py3-none-any.whl

cqlib_qml/__init__.py

@@ -0,0 +1,58 @@
+# cqlib_qml/__init__.py
+"""
+Cqlib-QML: Quantum machine learning package based on Cqlib.
+
+This package provides quantum machine learning building blocks on top of
+the `cqlib <https://github.com/cq-lib/cqlib>`_ quantum computing library,
+including data encoders, parameterized quantum circuits (ansatz),
+differentiators, neural network models, and quantum algorithms.
+
+Available Subpackages:
+    - algorithms: Quantum machine learning algorithms (QKM, QSVM, VQC).
+    - ansatz: Parameterized quantum circuits (HEAnsatz, BasicQNN, CRADL, CRAML).
+    - data: Classical data loading and preprocessing utilities.
+    - differentiator: Gradient computation strategies (adjoint, parameter-shift).
+    - encoder: Quantum data encoders (Amplitude, Angle, Basis, FRQI, NEQR).
+    - layer: Hybrid quantum-classical layers (Linear, activations).
+    - models: Quantum neural network models (QNN, HQNN).
+    - utils: Gradient matrix computation and other utilities.
+
+Examples:
+    >>> import numpy as np
+    >>> from cqlib_qml.ansatz import HEAnsatz
+    >>> from cqlib_qml.models import QNN
+    >>>
+    >>> ansatz = HEAnsatz(n_qubits=4, d=2, layers=["RY", "CX"])
+    >>> ansatz.set_measurement(readouts=[0])
+    >>> model = QNN(ansatz=ansatz)
+"""
+
+from . import algorithms, ansatz, data, differentiator, encoder, layer, models, utils
+from .loss import BCELoss, CrossEntropy, HingeLoss, LossFun, MSELoss, SoftmaxCrossEntropy
+from .optimizer import AdaGrad, Adam, OptimizerBase, OptimizerInitializer, RMSProp, SGD
+
+__version__ = "0.1.0-beta.1"
+
+__all__ = [
+    "algorithms",
+    "ansatz",
+    "data",
+    "differentiator",
+    "encoder",
+    "layer",
+    "models",
+    "utils",
+    "LossFun",
+    "HingeLoss",
+    "MSELoss",
+    "BCELoss",
+    "CrossEntropy",
+    "SoftmaxCrossEntropy",
+    "OptimizerBase",
+    "OptimizerInitializer",
+    "SGD",
+    "AdaGrad",
+    "RMSProp",
+    "Adam",
+    "__version__",
+]

cqlib_qml/_configuration.py

@@ -0,0 +1,53 @@
+"""Parse constructor-like configuration without evaluating Python code."""
+import ast
+import inspect
+
+
+def parse_configuration(value, registry, nested=None):
+    """Accept a registered name or keyword-only call with literal values.
+
+    Nested calls are restricted to the supplied scheduler registry. Attribute
+    access, positional arguments and expanded arguments are never evaluated.
+    """
+    try:
+        tree = ast.parse(value.strip(), mode='eval').body
+    except (SyntaxError, TypeError, AttributeError) as exc:
+        raise ValueError(f'Invalid configuration: {value!r}') from exc
+
+    def construct(node, constructors):
+        if isinstance(node, ast.Name):
+            name, keywords = node.id, []
+        elif isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and not node.args:
+            name, keywords = node.func.id, node.keywords
+        else:
+            raise ValueError('Configuration must be a registered name or keyword-only call')
+        constructor = constructors.get(name.casefold())
+        if constructor is None:
+            raise ValueError(f'Unsupported configuration name: {name}')
+        allowed = {key for key, parameter in inspect.signature(constructor).parameters.items()
+                   if parameter.kind in (parameter.POSITIONAL_OR_KEYWORD, parameter.KEYWORD_ONLY)}
+        kwargs = {}
+        for keyword in keywords:
+            key = keyword.arg
+            if key not in allowed or key in kwargs:
+                raise ValueError(f'Unknown or duplicate parameter: {key}')
+            if isinstance(keyword.value, ast.Call) and key == 'lr_scheduler' and nested:
+                kwargs[key] = construct(keyword.value, nested)
+            else:
+                try:
+                    kwargs[key] = ast.literal_eval(keyword.value)
+                except (ValueError, TypeError) as exc:
+                    raise ValueError(f'Parameter {key} must be a literal') from exc
+        return constructor(**kwargs)
+
+    return construct(tree, registry)
+
+
+def same_parameter_value(old, new):
+    """Compare scalar configurations without assuming array equality is scalar."""
+    if old is new:
+        return True
+    try:
+        return bool(old == new)
+    except (TypeError, ValueError):
+        return False

cqlib_qml/_numerics.py

@@ -0,0 +1,31 @@
+"""Internal scaling helpers that avoid complex reciprocal overflow."""
+import numpy as np
+
+
+def scaled_vector(vector):
+    """Return a vector at unit component scale and its real scale factor.
+
+    Divide real and imaginary components separately: complex division can
+    overflow its reciprocal for a finite, subnormal real denominator.
+    Exact zero is returned unchanged with scale zero.
+    """
+    vector = np.asarray(vector)
+    if not np.isfinite(vector).all():
+        raise ValueError("Vector components must be finite.")
+    scale = max(np.max(np.abs(vector.real), initial=0.),
+                np.max(np.abs(vector.imag), initial=0.))
+    if scale == 0:
+        return vector.copy(), scale
+    if np.iscomplexobj(vector):
+        scaled = np.empty(vector.shape, dtype=np.complex128)
+        scaled.real = vector.real / scale
+        scaled.imag = vector.imag / scale
+    else:
+        scaled = vector / scale
+    return scaled, scale
+
+
+def stable_norm(vector):
+    """Compute a Euclidean norm without squaring unscaled components."""
+    scaled, scale = scaled_vector(vector)
+    return scale * np.linalg.norm(scaled)

cqlib_qml/algorithms/HQNN_classification.py

@@ -0,0 +1,265 @@
+# cqlib_qml/algorithms/HQNN_classification.py
+"""
+Hybrid Quantum Neural Network for classification tasks.
+
+This module provides a complete training pipeline for Hybrid Quantum Neural Networks
+(HQNNs) on classification problems. It includes training and validation loops with
+checkpoint saving, TensorBoard logging, and configuration management.
+
+The HQNN combines a parameterized quantum circuit (ansatz) with a classical
+fully-connected layer, leveraging the strengths of both quantum and classical
+computing paradigms.
+
+Examples:
+    >>> from cqlib_qml.algorithms.HQNN_classification import train, validate
+    >>> from cqlib_qml.models import HQNN
+    >>> from cqlib_qml.ansatz import HEAnsatz
+    >>> from cqlib_qml.encoder import FRQI
+    >>>
+    >>> # Setup model
+    >>> ansatz = HEAnsatz(n_qubits=5, d=3, layers=["RY", "CX"])
+    >>> model = HQNN(ansatz=ansatz, out_dim=3)
+    >>>
+    >>> # Train
+    >>> for epoch in range(EPOCHS):
+    ...     train(epoch, 0, model, train_loader, loss_fun, model_path, EPOCHS, tb)
+    ...     validate(epoch, model, test_loader, loss_fun, BATCH_SIZE, tb)
+"""
+
+import time
+from pathlib import Path
+import tqdm
+import yaml
+import numpy as np
+from typing import Optional, Any
+
+from cqlib_qml.data.data_preprocess import get_mnist_dataloader
+from cqlib_qml.models import HQNN
+from cqlib_qml.ansatz import *
+from cqlib_qml.encoder import *
+from cqlib_qml.loss import *
+from cqlib_qml.optimizer import *
+
+try:
+    import torch.utils.tensorboard
+
+    TENSORBOARD_AVAILABLE = True
+except ImportError:
+    TENSORBOARD_AVAILABLE = False
+
+
+def train(
+    ep: int,
+    it_start: int,
+    net: HQNN,
+    train_loader,
+    loss_fun,
+    model_path: str,
+    total_epochs: int,
+    tb: Optional[Any] = None,
+) -> None:
+    """
+    Train the HQNN model for one epoch.
+
+    This function iterates through the training data, computes forward and
+    backward passes, updates model parameters, and logs training metrics.
+
+    Args:
+        ep (int): Current epoch number (0-indexed).
+        it_start (int): Starting iteration index within the epoch. Used for
+            resuming training from a checkpoint.
+        net (HQNN): The Hybrid Quantum Neural Network model to train.
+        train_loader: DataLoader for training data.
+        loss_fun: Loss function instance.
+        model_path (str): Path to save checkpoints.
+        total_epochs (int): Total number of epochs for training.
+        tb (optional): TensorBoard SummaryWriter instance for logging.
+            If None, logging is disabled. Defaults to None.
+
+    Note:
+        The function uses the global variable `EPOCH` defined in the main script
+        for determining the latest checkpoint.
+
+    Examples:
+        >>> for epoch in range(10):
+        ...     train(epoch, 0, model, train_loader, loss_fun, "./checkpoints/", 10, tensorboard_writer)
+    """
+    loader = tqdm.tqdm(train_loader, desc="Training epoch {}".format(ep + 1), leave=True)
+    for it, (x_train, y_train) in enumerate(loader):
+        if it < it_start:
+            continue
+        it_start = 0
+        expectations = net.forward(x_train)  # (batch_size, n_classes)
+        # Prepare labels for CrossEntropy loss
+        y_true = np.zeros(expectations.shape)
+        for i in range(len(y_train)):
+            idx = y_train[i]
+            y_true[i, idx] = 1
+        y_pred = expectations
+
+        # Compute loss
+        loss = loss_fun(y_pred, y_true)
+        # Optimize: backward pass and parameter update
+        net.backward(loss_fun.grads())
+        net.update(cur_loss=loss)
+        net.zero_grad()
+
+        # Compute accuracy
+        correct = sum(y_pred.argmax(axis=1) == y_train)
+        accuracy = correct / len(y_train)
+        loader.set_postfix(it=it, loss="{:.3f}".format(loss), accuracy="{:.3f}".format(accuracy))
+        # Log metrics
+        if tb is not None:
+            tb.add_scalar("train/loss", loss, ep * len(loader) + it)
+            tb.add_scalar("train/accuracy", accuracy, ep * len(loader) + it)
+        # Save checkpoint
+        latest = (ep + 1) == total_epochs and (it + 1) == len(loader)
+        if (it != 0 and it % 30 == 0) or latest:
+            net.save_checkpoint(model_path, ep, it, latest)
+
+
+def validate(ep: int, net: HQNN, test_loader, loss_fun, batch_size: int, tb: Optional[Any] = None) -> tuple:
+    """
+    Validate the HQNN model on the test dataset.
+
+    This function evaluates the model's performance on the test set and
+    computes average loss and accuracy across all batches.
+
+    Args:
+        ep (int): Current epoch number (0-indexed).
+        net (HQNN): The Hybrid Quantum Neural Network model to validate.
+        test_loader: DataLoader for test data.
+        loss_fun: Loss function instance.
+        batch_size (int): Batch size used in the dataloader.
+        tb (optional): TensorBoard SummaryWriter instance for logging.
+            If None, logging is disabled. Defaults to None.
+
+    Returns:
+        tuple: (avg_loss, avg_acc) where:
+            - avg_loss (float): Average loss over the validation set.
+            - avg_acc (float): Average accuracy over the validation set.
+
+    Note:
+        Model is evaluated in non-trainable mode.
+
+    Examples:
+        >>> avg_loss, avg_acc = validate(epoch, model, test_loader, loss_fun, 32, tensorboard_writer)
+        >>> print(f"Validation: loss={avg_loss:.4f}, acc={avg_acc:.4f}")
+    """
+    loader_val = tqdm.tqdm(test_loader, desc="Validating epoch {}".format(ep + 1), leave=True)
+    total_loss = 0.0
+    total_samples = 0
+    total_correct = 0
+    for it, (x_test, y_test) in enumerate(loader_val):
+        expectations_val = net.forward(x_test, trainable=False)
+        # Prepare labels for CrossEntropy loss
+        y_true_val = np.zeros(expectations_val.shape)
+        for i in range(len(y_test)):
+            idx = y_test[i]
+            y_true_val[i, idx] = 1
+        y_pred_val = expectations_val
+
+        loss_val = loss_fun(y_pred_val, y_true_val)
+        count = len(y_test)
+        total_samples += count
+        total_loss += loss_val if getattr(loss_fun, "reduction", "mean") == "sum" else loss_val * count
+
+        # Compute accuracy
+        correct_val = sum(y_pred_val.argmax(axis=1) == y_test)
+        total_correct += correct_val
+        accuracy_val = correct_val / len(y_test)
+        loader_val.set_postfix(
+            it=it,
+            loss="{:.3f}".format(loss_val),
+            accuracy="{:.3f}".format(accuracy_val),
+        )
+
+    if not total_samples:
+        raise ValueError("Validation dataset must not be empty")
+    avg_loss = total_loss / total_samples
+    avg_acc = total_correct / total_samples
+    if tb is not None:
+        tb.add_scalar("validation/loss", avg_loss, ep)
+        tb.add_scalar("validation/accuracy", avg_acc, ep)
+    print("Validation Average Loss: {}, Accuracy: {}".format(avg_loss, avg_acc))
+    return avg_loss, avg_acc
+
+
+if __name__ == "__main__":
+    """
+    Main execution block for training HQNN on MNIST dataset.
+
+    This script demonstrates a complete training pipeline including:
+        1. Data loading and preprocessing (MNIST with FRQI encoding)
+        2. Model initialization (HEAnsatz + HQNN)
+        3. Training loop with progress tracking
+        4. Validation and checkpoint saving
+        5. Configuration logging
+
+    Configuration:
+        - Dataset: MNIST (classes 0, 1, 2)
+        - Image size: 4x4 pixels
+        - Grayscale: 2 levels
+        - Encoding: FRQI (Flexible Representation of Quantum Images)
+        - Ansatz: HEAnsatz (Hardware-Efficient)
+        - Loss: SoftmaxCrossEntropy
+        - Optimizer: Adam (lr=0.01)
+        - Epochs: 10
+        - Batch size: 32
+    """
+    # Training parameters
+    EPOCH = 10
+    BATCH_SIZE = 32
+    LR = 0.01
+    SEED = 0
+    ep_start = 0
+    it_start = 0
+    np.random.seed(SEED)
+
+    classes = [0, 1, 2]
+    RESIZE = (4, 4)
+    GRAYSCALE = 2
+    n_pixels = RESIZE[0] * RESIZE[1]
+    # Initialize encoder, loss function, and optimizer
+    encoding = FRQI(n_pixels, GRAYSCALE)
+    loss_fun = SoftmaxCrossEntropy()
+    optimizer = Adam(lr=LR)
+
+    # Setup quantum circuit parameters
+    pos_qubits = int(np.log2(n_pixels))
+    color_qubits = 1
+    n_qubits = pos_qubits + color_qubits
+
+    # Initialize ansatz and model
+    ansatz = HEAnsatz(n_qubits, d=5, layers=["RZ", "RY", "RZ", "CX"])
+    train_loader, test_loader = get_mnist_dataloader(classes, RESIZE, encoding, BATCH_SIZE, GRAYSCALE)
+    net = HQNN(ansatz=ansatz, out_dim=len(classes), optimizer=optimizer)
+
+    # Setup logging and checkpoint directories
+    now_time = time.strftime("%Y-%m-%d-%H_%M_%S", time.localtime(time.time()))
+    model_path = "./HQNN_MNIST_" + now_time + "/"
+    Path(model_path).mkdir(parents=True, exist_ok=True)
+    tb = torch.utils.tensorboard.SummaryWriter(log_dir=model_path + "logs") if TENSORBOARD_AVAILABLE else None
+
+    # Save configuration
+    config = {
+        "classes": str(classes),
+        "encoding": str(encoding),
+        "ansatz": str(ansatz),
+        "grayscale": GRAYSCALE,
+        "resize": str(RESIZE),
+        "LR": LR,
+        "loss_fun": str(loss_fun),
+        "seed": SEED,
+    }
+    with open(model_path + "config.yaml", "w") as config_file:
+        config_file.write(yaml.dump(config))
+
+    # Training loop
+    for ep in range(ep_start, EPOCH):
+        if ep > ep_start:
+            it_start = 0
+        train(ep, it_start, net, train_loader, loss_fun, model_path, EPOCH, tb)
+        avg_loss, avg_acc = validate(ep, net, test_loader, loss_fun, BATCH_SIZE, tb)
+        with open(model_path + "result.yaml", "a") as result_file:
+            result_file.write("Validation Average Loss: {}, Accuracy: {}\n".format(avg_loss, avg_acc))