Release version 0.3.3

Co-authored-by: Thomas Hoffmann <thomas.hoffmann@quantinuum.com>
Co-authored-by: Dimitri Kartsaklis <dimitri.kartsaklis@quantinuum.com>
Co-authored-by: Nikhil Khatri <nikhil.khatri@quantinuum.com>
Co-authored-by: Charles London <charles.london@quantinuum.com>

Author: 5 people

docs/examples/classical_pipeline.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Rotosolve Optimizer"
+    "# Rotosolve optimizer"
    ]
   },
   {
@@ -195,7 +195,7 @@
     "\n",
     "    initial_loss = loss(trainer.model([train_circuit]), None)\n",
     "\n",
-    "    trainer.fit(train_dataset, logging_step=12)\n",
+    "    trainer.fit(train_dataset, log_interval=12)\n",
     "    losses.append([initial_loss] + trainer.train_epoch_costs)"
    ]
   },
@@ -253,7 +253,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Final Output"
+    "## Final output"
    ]
   },
   {

docs/examples/quantum_pipeline.ipynb

@@ -18,7 +18,10 @@ Concrete implementations of classical and quantum :term:`ansätze <ansatz (plura
 .. inheritance-diagram::
     lambeq.ansatz.IQPAnsatz
     lambeq.ansatz.MPSAnsatz
+    lambeq.ansatz.Sim14Ansatz
+    lambeq.ansatz.Sim15Ansatz
     lambeq.ansatz.SpiderAnsatz
+    lambeq.ansatz.StronglyEntanglingAnsatz
     lambeq.ansatz.Symbol
    :top-classes: lambeq.ansatz.base.Symbol
    :parts: 1
@@ -172,9 +175,11 @@ Provides a selection of :term:`trainers <trainer>`, :term:`models <model>`, and
     lambeq.training.Dataset
     lambeq.training.MSELoss
     lambeq.training.LossFunction
+    lambeq.training.NelderMeadOptimizer
     lambeq.training.NumpyModel
     lambeq.training.PytorchModel
     lambeq.training.PytorchTrainer
+    lambeq.training.RotosolveOptimizer
     lambeq.training.SPSAOptimizer
     lambeq.training.TketModel
     lambeq.training.PennyLaneModel

docs/examples/quantum_pipeline_jax.ipynb

@@ -17,8 +17,11 @@ class TensorAnsatz {
     functor
 }
 class CircuitAnsatz {
-    functor
+    functor: Functor
     ob_map: Mapping[Ty, int]
+    n_layers: int
+    n_single_qubit_params: int
+    discard: bool
 }
 class MPSAnsatz {
     BOND_TYPE
@@ -32,12 +35,12 @@ class SpiderAnsatz {
     split_functor
     tensor_functor
 }
-class IQPAnsatz {
-    discard: bool
-    functor
-    n_layers: int
-    n_single_qubit_params: int
-}
+
+class IQPAnsatz {}
+class StronglyEntanglingAnsatz {}
+class Sim14Ansatz {}
+class Sim15Ansatz {}
+
 class Symbol {
     size: int
     sort_key(order)
@@ -58,6 +61,9 @@ BaseAnsatz <|-- CircuitAnsatz
 TensorAnsatz <|-- MPSAnsatz
 TensorAnsatz <|-- SpiderAnsatz
 CircuitAnsatz <|-- IQPAnsatz
+CircuitAnsatz <|-- StronglyEntanglingAnsatz
+CircuitAnsatz <|-- Sim14Ansatz
+CircuitAnsatz <|-- Sim15Ansatz
 discopy.monoidal.Ty <|-- discopy.rigid.Ty
 
 MPSAnsatz::split_functor *-left- discopy.rigid.Functor
@@ -70,4 +76,6 @@ TensorAnsatz::functor *-- discopy.quantum.circuit.Functor
 IQPAnsatz::functor *-- discopy.quantum.circuit.Functor
 sympy.core.symbol.Symbol <|-- Symbol
 
+BaseAnsatz --> Symbol : uses
+
 @enduml

docs/examples/rotosolve_optimizer.ipynb

@@ -35,6 +35,9 @@ abstract class Trainer {
 
 abstract class Optimizer {
     model
+    loss
+    hyperparams: dict[str, float]
+    bounds
     {abstract} backward()
     {abstract} step()
     {abstract} state_dict()
@@ -76,15 +79,11 @@ class PytorchTrainer {
     optimizer
 }
 
-class SPSAOptimizer {
-    hyperparams
-    loss_fn
-    bounds
-}
+class SPSAOptimizer {}
+class NelderMeadOptimizer {}
+class RotosolveOptimizer {}
 
-class BinaryCrossEntropyLoss {
-  calculate_loss()
-}
+class BinaryCrossEntropyLoss {}
 
 class CrossEntropyLoss {
   calculate_loss()
@@ -108,6 +107,8 @@ Trainer <|-- PytorchTrainer
 Trainer <|-- QuantumTrainer
 
 Optimizer <|-- SPSAOptimizer
+Optimizer <|-- NelderMeadOptimizer
+Optimizer <|-- RotosolveOptimizer
 
 PennyLaneModel -- pennylane
 PennyLaneModel -- pytorch
@@ -120,8 +121,9 @@ Trainer *-- CheckPoint
 CheckPoint --* Model
 Trainer::model *- Model
 Trainer *-u- Dataset
-Model -* Optimizer::model
+QuantumModel -* Optimizer::model
 Optimizer -* QuantumTrainer::optimizer
+LossFunction --* Optimizer::loss
 
 PennyLaneModel -- PytorchTrainer: usedWith
 PytorchModel -- PytorchTrainer: usedWith

docs/package-api.rst

@@ -3,6 +3,30 @@
 Release notes
 =============
 
+.. _rel-0.3.3:
+
+`0.3.3 <https://github.com/CQCL/lambeq/releases/tag/0.3.3>`_
+------------------------------------------------------------
+This update features contributions from participants in `unitaryHACK 2023 <https://unitaryhack.dev/>`_:
+
+- Two new optimisers:
+    - The Nelder-Mead optimiser. (credit: `Gopal Dahale <https://github.com/CQCL/lambeq/pull/104>`_)
+    - The Rotosolve optimiser. (credit: `Ahmed Darwish <https://github.com/CQCL/lambeq/pull/93>`_)
+- A new rewrite rule for handling unknown words. (credit: `WingCode <https://github.com/CQCL/lambeq/pull/105>`_)
+
+Many thanks to all who participated.
+
+This update also contains the following changes:
+
+Added:
+
+- :py:class:`~lambeq.DiagramRewriter` is a new class that rewrites diagrams by looking at the diagram as a whole rather than by using rewrite rules on individual boxes. This includes an example :py:class:`~lambeq.UnifyCodomainRewriter` which adds an extra box to the end of diagrams to change the output to a specified type. (credit: `A.C.E07 <https://github.com/CQCL/lambeq/pull/111>`_)
+- Added an early stopping mechanism to :py:class:`~lambeq.Trainer` using the parameter ``early_stopping_interval``.
+
+Fixed:
+
+- In :py:class:`~lambeq.PennyLaneModel`, SymPy symbols are now substituted during the forward pass so that gradients are back-propagated to the original parameters.
+- A pickling error that prevented CCG trees produced by :py:class:`~lambeq.BobcatParser` from being unpickled has been fixed.
 
 .. _rel-0.3.2:
 

docs/puml/ansatz.puml

@@ -84,6 +84,9 @@ def __init_subclass__(cls) -> None:
     def __new__(cls, value: str) -> FastIntEnum:
         return cls._member_map_[value]
 
+    def __getnewargs__(self) -> tuple[str]:  # type: ignore[override]
+        return (str(self),)
+
     def __repr__(self) -> str:
         return f'{self.__class__.__name__}.{self.names[self]}'
 

docs/puml/img/ansatz.png

@@ -87,7 +87,6 @@ def __init__(self,
         - `fatol`: float, default: 1e-4
             The acceptable level of absolute error in the loss value
             between iterations that indicates convergence.
-        }
 
         Parameters
         ----------
@@ -104,22 +103,21 @@ def __init__(self,
         ------
         ValueError
             - If the hyperparameters are not set correctly, or if the
-            length of `bounds` does not match the number of the model
-            parameters.
+              length of `bounds` does not match the number of the model
+              parameters.
             - If the lower bounds are greater than the upper bounds.
             - If the initial simplex is not a 2D array.
             - If the initial simplex does not have N+1 rows, where N is
-            the number of model parameters.
+              the number of model parameters.
 
-        Warnings
-        --------
+        Warning
             - If the initial model weights are not within the bounds.
 
         References
         ----------
         Gao, Fuchang & Han, Lixing. (2012). Implementing the Nelder-Mead
-        simplex algorithm with adaptive parameters.
-        Computational Optimization and Applications. 51. 259-277.
+        Simplex Algorithm with Adaptive Parameters.
+        `Computational Optimization and Applications`, 51. 259-277.
         10.1007/s10589-010-9329-3.
 
         """

docs/puml/img/training.png

@@ -69,6 +69,7 @@ def __init__(self,
         Model.__init__(self)
         torch.nn.Module.__init__(self)
         self.circuit_map: dict[Circuit, PennyLaneCircuit] = {}
+        self.symbol_weight_map: dict[Symbol, torch.FloatTensor] = {}
         self._probabilities = probabilities
         self._normalize = normalize
         self._diff_method = diff_method
@@ -93,6 +94,7 @@ def _load_checkpoint(self, checkpoint: Checkpoint) -> None:
         self._backend_config = checkpoint['model_backend_config']
         self.circuit_map = checkpoint['model_circuits']
         self.load_state_dict(checkpoint['model_state_dict'])
+        self.symbol_weight_map = dict(zip(self.symbols, self.weights))
 
         for p_circ in self.circuit_map.values():
             p_circ.initialise_device_and_circuit()
@@ -150,10 +152,8 @@ def initialise_weights(self) -> None:
             [torch.nn.Parameter(torch.rand(1).squeeze())
              for _ in self.symbols]
         )
-        symbol_weight_map = dict(zip(self.symbols, self.weights))
 
-        for p_circ in self.circuit_map.values():
-            p_circ.initialise_concrete_params(symbol_weight_map)
+        self.symbol_weight_map = dict(zip(self.symbols, self.weights))
 
     def get_diagram_output(self, diagrams: list[Diagram]) -> torch.Tensor:
         """Evaluate outputs of circuits using PennyLane.
@@ -175,8 +175,12 @@ def get_diagram_output(self, diagrams: list[Diagram]) -> torch.Tensor:
             Resulting tensor.
 
         """
-        circuit_evals = [self.circuit_map[d].eval()
-                         for d in diagrams]
+        circuit_evals = []
+        for d in diagrams:
+            p_circ = self.circuit_map[d]
+            p_circ.initialise_concrete_params(self.symbol_weight_map)
+            circuit_evals.append(p_circ.eval())
+
         if self._normalize:
             if self._probabilities:
                 circuit_evals = [c / torch.sum(c) for c in circuit_evals]

docs/puml/training.puml

@@ -191,11 +191,16 @@ def validation_step(
     def fit(self,
             train_dataset: Dataset,
             val_dataset: Dataset | None = None,
-            evaluation_step: int = 1,
-            logging_step: int = 1) -> None:
+            log_interval: int = 1,
+            eval_interval: int = 1,
+            early_stopping_interval: int | None = None) -> None:
 
         self.model._training = True
 
-        super().fit(train_dataset, val_dataset, evaluation_step, logging_step)
+        super().fit(train_dataset,
+                    val_dataset,
+                    log_interval,
+                    eval_interval,
+                    early_stopping_interval)
 
         self.model._training = False

docs/release_notes.rst

@@ -31,7 +31,7 @@
 
 
 class RotosolveOptimizer(Optimizer):
-    """An Optimizer using the Rotosolve algorithm.
+    """An optimizer using the Rotosolve algorithm.
 
     Rotosolve is an optimizer for parametrized quantum circuits. It
     applies a shift of ±π/2 radians to each parameter, then updates the
@@ -41,7 +41,7 @@ class RotosolveOptimizer(Optimizer):
     This optimizer is designed to work with ansätze that are composed of
     single-qubit rotations, such as the
     :py:class:`.StronglyEntanglingAnsatz`, :py:class:`.Sim14Ansatz`
-    and :py:class:`.Sim14Ansatz`.
+    and :py:class:`.Sim15Ansatz`.
 
     See `Ostaszewski et al.
     <https://quantum-journal.org/papers/q-2021-01-28-391/pdf/>`_ for