qadence 1.9.1__py3-none-any.whl → 1.10.0__py3-none-any.whl

qadence/ml_tools/callbacks/callback.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import math
+from logging import getLogger
 from typing import Any, Callable
 
 from qadence.ml_tools.callbacks.saveload import load_checkpoint, write_checkpoint
@@ -12,6 +14,8 @@ from qadence.ml_tools.stages import TrainingStage
 CallbackFunction = Callable[..., Any]
 CallbackConditionFunction = Callable[..., bool]
 
+logger = getLogger("ml_tools")
+
 
 class Callback:
     """Base class for defining various training callbacks.
@@ -258,7 +262,7 @@ class WriteMetrics(Callback):
             writer (BaseWriter ): The writer object for logging.
         """
         opt_result = trainer.opt_result
-        writer.write(opt_result)
+        writer.write(opt_result.iteration, opt_result.metrics)
 
 
 class PlotMetrics(Callback):
@@ -449,3 +453,323 @@ class LogModelTracker(Callback):
         writer.log_model(
             model, trainer.train_dataloader, trainer.val_dataloader, trainer.test_dataloader
         )
+
+
+class LRSchedulerStepDecay(Callback):
+    """
+    Reduces the learning rate by a factor at regular intervals.
+
+    This callback adjusts the learning rate by multiplying it with a decay factor
+    after a specified number of iterations. The learning rate is updated as:
+        lr = lr * gamma
+
+    Example Usage in `TrainConfig`:
+    To use `LRSchedulerStepDecay`, include it in the `callbacks` list when setting
+    up your `TrainConfig`:
+    ```python exec="on" source="material-block" result="json"
+    from qadence.ml_tools import TrainConfig
+    from qadence.ml_tools.callbacks import LRSchedulerStepDecay
+
+    # Create an instance of the LRSchedulerStepDecay callback
+    lr_step_decay = LRSchedulerStepDecay(on="train_epoch_end",
+                                         called_every=100,
+                                         gamma=0.5)
+
+    config = TrainConfig(
+        max_iter=10000,
+        # Print metrics every 1000 training epochs
+        print_every=1000,
+        # Add the custom callback
+        callbacks=[lr_step_decay]
+    )
+    ```
+    """
+
+    def __init__(self, on: str, called_every: int, gamma: float = 0.5):
+        """Initializes the LRSchedulerStepDecay callback.
+
+        Args:
+            on (str): The event to trigger the callback.
+            called_every (int): Frequency of callback calls in terms of iterations.
+            gamma (float, optional): The decay factor applied to the learning rate.
+                A value < 1 reduces the learning rate over time. Default is 0.5.
+        """
+        super().__init__(on=on, called_every=called_every)
+        self.gamma = gamma
+
+    def run_callback(self, trainer: Any, config: TrainConfig, writer: BaseWriter) -> None:
+        """
+        Runs the callback to apply step decay to the learning rate.
+
+        Args:
+            trainer (Any): The training object.
+            config (TrainConfig): The configuration object.
+            writer (BaseWriter): The writer object for logging.
+        """
+        for param_group in trainer.optimizer.param_groups:
+            param_group["lr"] *= self.gamma
+
+
+class LRSchedulerCyclic(Callback):
+    """
+    Applies a cyclic learning rate schedule during training.
+
+    This callback oscillates the learning rate between a minimum (base_lr)
+    and a maximum (max_lr) over a defined cycle length (step_size). The learning
+    rate follows a triangular wave pattern.
+
+    Example Usage in `TrainConfig`:
+    To use `LRSchedulerCyclic`, include it in the `callbacks` list when setting
+    up your `TrainConfig`:
+    ```python exec="on" source="material-block" result="json"
+    from qadence.ml_tools import TrainConfig
+    from qadence.ml_tools.callbacks import LRSchedulerCyclic
+
+    # Create an instance of the LRSchedulerCyclic callback
+    lr_cyclic = LRSchedulerCyclic(on="train_batch_end",
+                                  called_every=1,
+                                  base_lr=0.001,
+                                  max_lr=0.01,
+                                  step_size=2000)
+
+    config = TrainConfig(
+        max_iter=10000,
+        # Print metrics every 1000 training epochs
+        print_every=1000,
+        # Add the custom callback
+        callbacks=[lr_cyclic]
+    )
+    ```
+    """
+
+    def __init__(self, on: str, called_every: int, base_lr: float, max_lr: float, step_size: int):
+        """Initializes the LRSchedulerCyclic callback.
+
+        Args:
+            on (str): The event to trigger the callback.
+            called_every (int): Frequency of callback calls in terms of iterations.
+            base_lr (float): The minimum learning rate.
+            max_lr (float): The maximum learning rate.
+            step_size (int): Number of iterations for half a cycle.
+        """
+        super().__init__(on=on, called_every=called_every)
+        self.base_lr = base_lr
+        self.max_lr = max_lr
+        self.step_size = step_size
+
+    def run_callback(self, trainer: Any, config: TrainConfig, writer: BaseWriter) -> None:
+        """
+        Adjusts the learning rate cyclically.
+
+        Args:
+            trainer (Any): The training object.
+            config (TrainConfig): The configuration object.
+            writer (BaseWriter): The writer object for logging.
+        """
+        cycle = trainer.opt_result.iteration // (2 * self.step_size)
+        x = abs(trainer.opt_result.iteration / self.step_size - 2 * cycle - 1)
+        scale = max(0, (1 - x))
+        new_lr = self.base_lr + (self.max_lr - self.base_lr) * scale
+        for param_group in trainer.optimizer.param_groups:
+            param_group["lr"] = new_lr
+
+
+class LRSchedulerCosineAnnealing(Callback):
+    """
+    Applies cosine annealing to the learning rate during training.
+
+    This callback decreases the learning rate following a cosine curve,
+    starting from the initial learning rate and annealing to a minimum (min_lr).
+
+    Example Usage in `TrainConfig`:
+    To use `LRSchedulerCosineAnnealing`, include it in the `callbacks` list
+    when setting up your `TrainConfig`:
+    ```python exec="on" source="material-block" result="json"
+    from qadence.ml_tools import TrainConfig
+    from qadence.ml_tools.callbacks import LRSchedulerCosineAnnealing
+
+    # Create an instance of the LRSchedulerCosineAnnealing callback
+    lr_cosine = LRSchedulerCosineAnnealing(on="train_batch_end",
+                                           called_every=1,
+                                           t_max=5000,
+                                           min_lr=1e-6)
+
+    config = TrainConfig(
+        max_iter=10000,
+        # Print metrics every 1000 training epochs
+        print_every=1000,
+        # Add the custom callback
+        callbacks=[lr_cosine]
+    )
+    ```
+    """
+
+    def __init__(self, on: str, called_every: int, t_max: int, min_lr: float = 0.0):
+        """Initializes the LRSchedulerCosineAnnealing callback.
+
+        Args:
+            on (str): The event to trigger the callback.
+            called_every (int): Frequency of callback calls in terms of iterations.
+            t_max (int): The total number of iterations for one annealing cycle.
+            min_lr (float, optional): The minimum learning rate. Default is 0.0.
+        """
+        super().__init__(on=on, called_every=called_every)
+        self.t_max = t_max
+        self.min_lr = min_lr
+
+    def run_callback(self, trainer: Any, config: TrainConfig, writer: BaseWriter) -> None:
+        """
+        Adjusts the learning rate using cosine annealing.
+
+        Args:
+            trainer (Any): The training object.
+            config (TrainConfig): The configuration object.
+            writer (BaseWriter): The writer object for logging.
+        """
+        for param_group in trainer.optimizer.param_groups:
+            max_lr = param_group["lr"]
+            new_lr = (
+                self.min_lr
+                + (max_lr - self.min_lr)
+                * (1 + math.cos(math.pi * trainer.opt_result.iteration / self.t_max))
+                / 2
+            )
+            param_group["lr"] = new_lr
+
+
+class EarlyStopping(Callback):
+    """
+    Stops training when a monitored metric has not improved for a specified number of epochs.
+
+    This callback monitors a specified metric (e.g., validation loss or accuracy). If the metric
+    does not improve for a given patience period, training is stopped.
+
+    Example Usage in `TrainConfig`:
+    To use `EarlyStopping`, include it in the `callbacks` list when setting up your `TrainConfig`:
+    ```python exec="on" source="material-block" result="json"
+    from qadence.ml_tools import TrainConfig
+    from qadence.ml_tools.callbacks import EarlyStopping
+
+    # Create an instance of the EarlyStopping callback
+    early_stopping = EarlyStopping(on="val_epoch_end",
+                                   called_every=1,
+                                   monitor="val_loss",
+                                   patience=5,
+                                   mode="min")
+
+    config = TrainConfig(
+        max_iter=10000,
+        print_every=1000,
+        callbacks=[early_stopping]
+    )
+    ```
+    """
+
+    def __init__(
+        self, on: str, called_every: int, monitor: str, patience: int = 5, mode: str = "min"
+    ):
+        """Initializes the EarlyStopping callback.
+
+        Args:
+            on (str): The event to trigger the callback (e.g., "val_epoch_end").
+            called_every (int): Frequency of callback calls in terms of iterations.
+            monitor (str): The metric to monitor (e.g., "val_loss" or "train_loss").
+                All metrics returned by optimize step are available to monitor.
+                Please add "val_" and "train_" strings at the start of the metric name.
+            patience (int, optional): Number of iterations to wait for improvement. Default is 5.
+            mode (str, optional): Whether to minimize ("min") or maximize ("max") the metric.
+                Default is "min".
+        """
+        super().__init__(on=on, called_every=called_every)
+        self.monitor = monitor
+        self.patience = patience
+        self.mode = mode
+        self.best_value = float("inf") if mode == "min" else -float("inf")
+        self.counter = 0
+
+    def run_callback(self, trainer: Any, config: TrainConfig, writer: BaseWriter) -> None:
+        """
+        Monitors the metric and stops training if no improvement is observed.
+
+        Args:
+            trainer (Any): The training object.
+            config (TrainConfig): The configuration object.
+            writer (BaseWriter): The writer object for logging.
+        """
+        current_value = trainer.opt_result.metrics.get(self.monitor)
+        if current_value is None:
+            raise ValueError(f"Metric '{self.monitor}' is not available in the trainer's metrics.")
+
+        if (self.mode == "min" and current_value < self.best_value) or (
+            self.mode == "max" and current_value > self.best_value
+        ):
+            self.best_value = current_value
+            self.counter = 0
+        else:
+            self.counter += 1
+
+        if self.counter >= self.patience:
+            logger.info(
+                f"EarlyStopping: No improvement in '{self.monitor}' for {self.patience} epochs. "
+                "Stopping training."
+            )
+            trainer.stop_training = True
+
+
+class GradientMonitoring(Callback):
+    """
+    Logs gradient statistics (e.g., mean, standard deviation, max) during training.
+
+    This callback monitors and logs statistics about the gradients of the model parameters
+    to help debug or optimize the training process.
+
+    Example Usage in `TrainConfig`:
+    To use `GradientMonitoring`, include it in the `callbacks` list when
+    setting up your `TrainConfig`:
+    ```python exec="on" source="material-block" result="json"
+    from qadence.ml_tools import TrainConfig
+    from qadence.ml_tools.callbacks import GradientMonitoring
+
+    # Create an instance of the GradientMonitoring callback
+    gradient_monitoring = GradientMonitoring(on="train_batch_end", called_every=10)
+
+    config = TrainConfig(
+        max_iter=10000,
+        print_every=1000,
+        callbacks=[gradient_monitoring]
+    )
+    ```
+    """
+
+    def __init__(self, on: str, called_every: int = 1):
+        """Initializes the GradientMonitoring callback.
+
+        Args:
+            on (str): The event to trigger the callback (e.g., "train_batch_end").
+            called_every (int): Frequency of callback calls in terms of iterations.
+        """
+        super().__init__(on=on, called_every=called_every)
+
+    def run_callback(self, trainer: Any, config: TrainConfig, writer: BaseWriter) -> None:
+        """
+        Logs gradient statistics.
+
+        Args:
+            trainer (Any): The training object.
+            config (TrainConfig): The configuration object.
+            writer (BaseWriter): The writer object for logging.
+        """
+        gradient_stats = {}
+        for name, param in trainer.model.named_parameters():
+            if param.grad is not None:
+                grad = param.grad
+                gradient_stats.update(
+                    {
+                        name + "_mean": grad.mean().item(),
+                        name + "_std": grad.std().item(),
+                        name + "_max": grad.max().item(),
+                        name + "_min": grad.min().item(),
+                    }
+                )
+
+        writer.write(trainer.opt_result.iteration, gradient_stats)

qadence/ml_tools/callbacks/writer_registry.py

@@ -60,12 +60,14 @@ class BaseWriter(ABC):
         raise NotImplementedError("Writers must implement a close method.")
 
     @abstractmethod
-    def write(self, result: OptimizeResult) -> None:
+    def write(self, iteration: int, metrics: dict) -> None:
         """
         Logs the results of the current iteration.
 
         Args:
-            result (OptimizeResult): The optimization results to log.
+            iteration (int): The current training iteration.
+            metrics (dict): A dictionary of metrics to log, where keys are metric names
+                            and values are the corresponding metric values.
         """
         raise NotImplementedError("Writers must implement a write method.")
 
@@ -166,23 +168,22 @@ class TensorBoardWriter(BaseWriter):
         if self.writer:
             self.writer.close()
 
-    def write(self, result: OptimizeResult) -> None:
+    def write(self, iteration: int, metrics: dict) -> None:
         """
         Logs the results of the current iteration to TensorBoard.
 
         Args:
-            result (OptimizeResult): The optimization results to log.
+            iteration (int): The current training iteration.
+            metrics (dict): A dictionary of metrics to log, where keys are metric names
+                            and values are the corresponding metric values.
         """
-        # Not writing loss as loss is available in the metrics
-        # if result.loss is not None:
-        #     self.writer.add_scalar("loss", float(result.loss), result.iteration)
         if self.writer:
-            for key, value in result.metrics.items():
-                self.writer.add_scalar(key, value, result.iteration)
+            for key, value in metrics.items():
+                self.writer.add_scalar(key, value, iteration)
         else:
             raise RuntimeError(
                 "The writer is not initialized."
-                "Please call the 'writer.open()' method before writing"
+                "Please call the 'writer.open()' method before writing."
             )
 
     def log_hyperparams(self, hyperparams: dict) -> None:
@@ -305,22 +306,21 @@ class MLFlowWriter(BaseWriter):
         if self.run:
             self.mlflow.end_run()
 
-    def write(self, result: OptimizeResult) -> None:
+    def write(self, iteration: int, metrics: dict) -> None:
         """
         Logs the results of the current iteration to MLflow.
 
         Args:
-            result (OptimizeResult): The optimization results to log.
+            iteration (int): The current training iteration.
+            metrics (dict): A dictionary of metrics to log, where keys are metric names
+                            and values are the corresponding metric values.
         """
-        # Not writing loss as loss is available in the metrics
-        # if result.loss is not None:
-        #     self.mlflow.log_metric("loss", float(result.loss), step=result.iteration)
         if self.mlflow:
-            self.mlflow.log_metrics(result.metrics, step=result.iteration)
+            self.mlflow.log_metrics(metrics, step=iteration)
         else:
             raise RuntimeError(
                 "The writer is not initialized."
-                "Please call the 'writer.open()' method before writing"
+                "Please call the 'writer.open()' method before writing."
             )
 
     def log_hyperparams(self, hyperparams: dict) -> None:

qadence/ml_tools/constructors.py

@@ -13,13 +13,13 @@ from qadence.constructors import (
     analog_feature_map,
     feature_map,
     hamiltonian_factory,
-    identity_initialized_ansatz,
+    iia,
     rydberg_feature_map,
     rydberg_hea,
     rydberg_tower_feature_map,
 )
-from qadence.constructors.ansatze import hea_digital, hea_sDAQC
 from qadence.constructors.hamiltonians import ObservableConfig, TDetuning
+from qadence.constructors.hea import hea_digital, hea_sDAQC
 from qadence.measurements import Measurements
 from qadence.noise import NoiseHandler
 from qadence.operations import CNOT, RX, RY, I, N, Z
@@ -107,7 +107,8 @@ def _encode_features_series_digital(
     )
 
     support_arrays = {
-        key: support for key, support in zip(config.inputs, support_arrays_list)  # type: ignore[union-attr, arg-type]
+        key: support
+        for key, support in zip(config.inputs, support_arrays_list)  # type: ignore[union-attr, arg-type]
     }
 
     num_uploads = {key: value + 1 for key, value in config.num_repeats.items()}  # type: ignore[union-attr]
@@ -163,7 +164,8 @@ def _encode_features_parallel_digital(
     )
 
     support_arrays = {
-        key: support for key, support in zip(config.inputs, support_arrays_list)  # type: ignore[union-attr, arg-type]
+        key: support
+        for key, support in zip(config.inputs, support_arrays_list)  # type: ignore[union-attr, arg-type]
     }
 
     num_uploads = {key: value + 1 for key, value in config.num_repeats.items()}  # type: ignore[union-attr]
@@ -412,7 +414,7 @@ def _create_iia_digital(
     entangler = config.strategy_args.get("entangler", CNOT)
     periodic = config.strategy_args.get("periodic", False)
 
-    return identity_initialized_ansatz(
+    return iia(
         n_qubits=num_qubits,
         depth=config.depth,
         param_prefix=config.param_prefix,
@@ -441,7 +443,7 @@ def _create_iia_sdaqc(
     entangler = config.strategy_args.get("entangler", CNOT)
     periodic = config.strategy_args.get("periodic", False)
 
-    return identity_initialized_ansatz(
+    return iia(
         n_qubits=num_qubits,
         depth=config.depth,
         param_prefix=config.param_prefix,

qadence/ml_tools/trainer.py

@@ -281,6 +281,7 @@ class Trainer(BaseTrainer):
         self.device: torch_device | None = device
         self.dtype: torch_dtype | None = dtype
         self.data_dtype: torch_dtype | None = None
+        self.stop_training: bool = False
         if self.dtype:
             self.data_dtype = float64 if (self.dtype == complex128) else float32
 
@@ -321,6 +322,7 @@ class Trainer(BaseTrainer):
         The callback_manager.start_training takes care of loading checkpoint,
         and setting up the writer.
         """
+        self.stop_training = False
         self.config_manager.initialize_config()
         self.callback_manager.start_training(trainer=self)
 
@@ -377,25 +379,26 @@ class Trainer(BaseTrainer):
             for epoch in range(
                 self.global_step, self.global_step + self.config_manager.config.max_iter + 1
             ):
-                try:
-                    self.current_epoch = epoch
-                    self.on_train_epoch_start()
-                    train_epoch_loss_metrics = self.run_training(self.train_dataloader)
-                    train_losses.append(train_epoch_loss_metrics)
-                    self.on_train_epoch_end(train_epoch_loss_metrics)
-
-                    # Run validation periodically if specified
-                    if self.perform_val and self.current_epoch % self.config.val_every == 0:
-                        self.on_val_epoch_start()
-                        val_epoch_loss_metrics = self.run_validation(self.val_dataloader)
-                        val_losses.append(val_epoch_loss_metrics)
-                        self.on_val_epoch_end(val_epoch_loss_metrics)
-                        self.progress.update(val_task, advance=1)
-
-                    self.progress.update(train_task, advance=1)
-                except KeyboardInterrupt:
-                    logger.info("Terminating training gracefully after the current iteration.")
-                    break
+                if not self.stop_training:
+                    try:
+                        self.current_epoch = epoch
+                        self.on_train_epoch_start()
+                        train_epoch_loss_metrics = self.run_training(self.train_dataloader)
+                        train_losses.append(train_epoch_loss_metrics)
+                        self.on_train_epoch_end(train_epoch_loss_metrics)
+
+                        # Run validation periodically if specified
+                        if self.perform_val and self.current_epoch % self.config.val_every == 0:
+                            self.on_val_epoch_start()
+                            val_epoch_loss_metrics = self.run_validation(self.val_dataloader)
+                            val_losses.append(val_epoch_loss_metrics)
+                            self.on_val_epoch_end(val_epoch_loss_metrics)
+                            self.progress.update(val_task, advance=1)
+
+                        self.progress.update(train_task, advance=1)
+                    except KeyboardInterrupt:
+                        logger.info("Terminating training gracefully after the current iteration.")
+                        break
 
         self.on_train_end(train_losses, val_losses)
         return train_losses
@@ -629,10 +632,12 @@ class Trainer(BaseTrainer):
 
     def build_optimize_result(
         self,
-        result: None
-        | tuple[torch.Tensor, dict[Any, Any]]
-        | list[tuple[torch.Tensor, dict[Any, Any]]]
-        | list[list[tuple[torch.Tensor, dict[Any, Any]]]],
+        result: (
+            None
+            | tuple[torch.Tensor, dict[Any, Any]]
+            | list[tuple[torch.Tensor, dict[Any, Any]]]
+            | list[list[tuple[torch.Tensor, dict[Any, Any]]]]
+        ),
     ) -> None:
         """
         Builds and stores the optimization result by calculating the average loss and metrics.

qadence/operations/control_ops.py

@@ -119,9 +119,7 @@ class MCRX(ParametricControlBlock):
 
     @property
     def eigenvalues_generator(self) -> Tensor:
-        return torch.cat(
-            (torch.zeros(2**self.n_qubits - 2), torch.tensor([1, -1], dtype=cdouble))
-        )
+        return torch.cat((torch.zeros(2**self.n_qubits - 2), torch.tensor([1, -1], dtype=cdouble)))
 
     @property
     def eigenvalues(self) -> Tensor:
@@ -164,9 +162,7 @@ class MCRY(ParametricControlBlock):
 
     @property
     def eigenvalues_generator(self) -> Tensor:
-        return torch.cat(
-            (torch.zeros(2**self.n_qubits - 2), torch.tensor([1, -1], dtype=cdouble))
-        )
+        return torch.cat((torch.zeros(2**self.n_qubits - 2), torch.tensor([1, -1], dtype=cdouble)))
 
     @property
     def eigenvalues(self) -> Tensor:
@@ -205,9 +201,7 @@ class MCRZ(ParametricControlBlock):
 
     @property
     def eigenvalues_generator(self) -> Tensor:
-        return torch.cat(
-            (torch.zeros(2**self.n_qubits - 2), torch.tensor([1, -1], dtype=cdouble))
-        )
+        return torch.cat((torch.zeros(2**self.n_qubits - 2), torch.tensor([1, -1], dtype=cdouble)))
 
     @property
     def eigenvalues(self) -> Tensor: