Fix setNumQubits requirement, add annotation support, update README with lego example

Co-authored-by: fgfuchs <2428162+fgfuchs@users.noreply.github.com>

Author: Copilot

README.md

@@ -166,15 +166,58 @@ Assuming all-to-all connectivity of qubits, one can minimize the depth of the ci
 ![this graph](images/minimal_depth.png  "Edge Coloring")
 
 
+***
+### Building circuits like Lego
+
+Components can be freely composed ("lego style") to build more complex circuits without needing to configure qubit counts manually.
+
+For example, a Grover mixer over 3 independent Dicke-2 sub-registers can be assembled like this:
+
+	from qaoa import initialstates, mixers
+
+	dicke  = initialstates.Dicke(2)       # Dicke state with k=2 excitations
+	grover = mixers.Grover(dicke)          # Grover mixer over the Dicke feasible space
+	tensor = initialstates.Tensor(grover, 3)  # 3 independent copies (6 qubits total)
+
+	tensor.create_circuit()
+	tensor.circuit.draw('mpl')
+
+`Dicke(k)` automatically sets `N_qubits = k` (the minimum needed register), and
+`Grover` inherits that qubit count from its sub-circuit, so no explicit
+`setNumQubits` call is required.
+
+![Lego circuit](images/lego_circuit.png "Lego circuit: three Grover blocks on 6 qubits")
+
+Each sub-circuit is shown as a labelled block in the drawing so the "lego" structure
+is immediately visible.
+
+### Annotating circuits
+
+Every component (initial state or mixer) carries a `label` attribute that is used as
+the circuit name when `create_circuit()` is called.  The label defaults to the class
+name but can be customised at construction time (for `Dicke`, `Grover`, and `Tensor`)
+or by setting the attribute before calling `create_circuit()`:
+
+	dicke = initialstates.Dicke(2, label="Dicke-2")
+	dicke.create_circuit()
+	print(dicke.circuit.name)   # → "Dicke-2"
+
+	xy = mixers.XY()
+	xy.label = "XY-ring"
+	xy.setNumQubits(4)
+	xy.create_circuit()
+	print(xy.circuit.name)      # → "XY-ring"
+
 ***
 ### Tensorize mixers
 To tensorize a mixer, i.e. decomposing the mixer into a tensor product of unitaries that is 
-performed on each qubit, one can call the tensor class with the arguments of mixer and number of qubits in subpart.
+performed on each qubit, one can call the `Tensor` class with the sub-circuit and the number of copies.
 
 For example, for the standard MaxCut problem above where the X mixer was used, one could find the tensor by writing:
 
-	tensorized_mixer = Tensor(mixer.X(), number_of_qubits_of_subpart)
-<!--find out the number of qubits we want here -->
+	x_mixer = mixers.X()
+	x_mixer.setNumQubits(number_of_qubits_of_subpart)
+	tensorized_mixer = initialstates.Tensor(x_mixer, number_of_copies)
 
 ***
 ### Talk to an agent

images/lego_circuit.png

@@ -12,16 +12,24 @@ class BaseInitialState(ABC):
     Attributes:
         circuit (QuantumCircuit): The quantum circuit representing the initial state.
         N_qubits (int): The number of qubits in the quantum circuit.
+        label (str): A human-readable annotation for this component, used as the
+            circuit name when ``create_circuit`` is called.  Defaults to the
+            class name.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, label: str | None = None) -> None:
         """
         Initializes a BaseInitialState object.
 
-        The `circuit` attribute is set to None initially, and `N_qubits`
-        is not defined until `setNumQubits` is called.
+        The ``circuit`` attribute is set to None initially, and ``N_qubits``
+        is not defined until ``setNumQubits`` is called.
+
+        Args:
+            label (str | None): Optional annotation label for this component.
+                Defaults to the class name when *None*.
         """
         self.circuit = None
+        self.label = label if label is not None else self.__class__.__name__
 
     def setNumQubits(self, n):
         """
@@ -55,6 +63,55 @@ def create_circuit(self):
         ```
     """
 
+    def __init_subclass__(cls, **kwargs):
+        """
+        Automatically equips every concrete subclass with two behaviours:
+
+        1. **Default label** – if the subclass ``__init__`` does *not* call
+           ``super().__init__()``, the instance will still get a ``label``
+           attribute (set to the class name) after ``__init__`` returns.
+        2. **Circuit annotation** – after ``create_circuit`` returns the
+           ``circuit.name`` attribute is set to ``self.label`` so that
+           circuit drawings show the component name.
+        """
+        super().__init_subclass__(**kwargs)
+
+        # Wrap __init__ to guarantee self.label exists even when super() is
+        # not called by the subclass.
+        if "__init__" in cls.__dict__:
+            _orig_init = cls.__dict__["__init__"]
+
+            def _make_init_wrapper(f):
+                def _wrapped_init(self, *args, **kwargs):
+                    f(self, *args, **kwargs)
+                    if not hasattr(self, "label"):
+                        self.label = self.__class__.__name__
+
+                _wrapped_init.__doc__ = f.__doc__
+                _wrapped_init.__name__ = f.__name__
+                return _wrapped_init
+
+            setattr(cls, "__init__", _make_init_wrapper(_orig_init))
+
+        # Wrap create_circuit to set circuit.name from self.label.
+        if "create_circuit" in cls.__dict__:
+            _orig_cc = cls.__dict__["create_circuit"]
+            if not getattr(_orig_cc, "__isabstractmethod__", False):
+
+                def _make_cc_wrapper(f):
+                    def _wrapped_cc(self, *args, **kwargs):
+                        f(self, *args, **kwargs)
+                        if self.circuit is not None:
+                            self.circuit.name = getattr(
+                                self, "label", self.__class__.__name__
+                            )
+
+                    _wrapped_cc.__doc__ = f.__doc__
+                    _wrapped_cc.__name__ = f.__name__
+                    return _wrapped_cc
+
+                setattr(cls, "create_circuit", _make_cc_wrapper(_orig_cc))
+
     @abstractmethod
     def create_circuit(self):
         """

qaoa/initialstates/base_initialstate.py

@@ -19,13 +19,18 @@ class Dicke(InitialState):
     Methods:
         create_circuit(): Creates the circuit to prepare the Dicke states.
     """
-    def __init__(self, k) -> None:
+    def __init__(self, k, label: str | None = None) -> None:
         """
         Args:
             k (int): The Hamming weight of the Dicke states.
+            label (str | None): Optional annotation label.  Defaults to
+                ``"Dicke"``.
         """
-        super().__init__()
+        super().__init__(label=label)
         self.k = k
+        # Default N_qubits to k (minimum register needed for k excitations).
+        # Can be overridden via setNumQubits().
+        self.N_qubits = k
 
     def create_circuit(self):
         """

qaoa/initialstates/dicke_initialstate.py

@@ -10,31 +10,48 @@ class Tensor(InitialState):
     """
     Tensor initial state.
 
-    Subclass of the `IntialState` class that creates a tensor out of a circuit.
+    Subclass of the `InitialState` class that creates a tensor product of
+    *num* copies of a sub-circuit (initial state **or** mixer) placed
+    side-by-side on disjoint qubit registers.
+
+    When drawn, each copy is shown as a labelled box using the sub-circuit's
+    own ``label`` attribute, making the "lego" structure immediately visible.
 
     Attributions:
         subcircuit (InitialState): The circuit that is to be tensorised.
-        num (int): Number of qubits of the subpart .
+        num (int): Number of copies of the sub-circuit.
 
     Methods:
-        create_circuit(): 
+        create_circuit(): Creates the tensorised circuit.
     """
-    def __init__(self, subcircuit: InitialState, num: int) -> None:
+
+    def __init__(self, subcircuit: InitialState, num: int, label: str | None = None) -> None:
         """
         Args:
             subcircuit (InitialState): The circuit that is to be tensorised.
-            num (int): Number of qubits of the subpart #subN_qubits.
+            num (int): Number of copies of the sub-circuit.
+            label (str | None): Optional annotation label.  Defaults to
+                ``"Tensor"``.
         """
+        super().__init__(label=label)
         self.num = num
         self.subcircuit = subcircuit
         self.N_qubits = self.num * self.subcircuit.N_qubits
 
     def create_circuit(self) -> None:
         """
-        Creates a circuit that tensorises a given subcircuit.
+        Creates a circuit that places *num* copies of the sub-circuit on
+        disjoint qubit registers.
+
+        Each copy is wrapped as a labelled instruction so that circuit
+        drawings show named "lego" blocks instead of raw gates.
         """
         self.subcircuit.create_circuit()
-        self.circuit = self.subcircuit.circuit
-        for v in range(self.num - 1):
-            self.subcircuit.create_circuit()  # self.subcircuit.circuit.qregs)
-            self.circuit.tensor(self.subcircuit.circuit, inplace=True)
+        sub_label = getattr(self.subcircuit, "label", self.subcircuit.__class__.__name__)
+        sub_instr = self.subcircuit.circuit.to_instruction(label=sub_label)
+
+        qr = QuantumRegister(self.N_qubits)
+        self.circuit = QuantumCircuit(qr)
+        n = self.subcircuit.N_qubits
+        for i in range(self.num):
+            self.circuit.append(sub_instr, list(range(i * n, (i + 1) * n)))

qaoa/initialstates/tensor_initialstate.py

@@ -12,16 +12,24 @@ class MixerBase(ABC):
     Attributes:
         circuit (QuantumCircuit): The quantum circuit associated with the mixer.
         N_qubits (int): The number of qubits in the mixer circuit.
+        label (str): A human-readable annotation for this component, used as the
+            circuit name when ``create_circuit`` is called.  Defaults to the
+            class name.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, label: str | None = None) -> None:
         """
         Initializes a MixerBase object.
 
-        The `circuit` attribute is set to None initially, and `N_qubits`
-        is not defined until `setNumQubits` is called.
+        The ``circuit`` attribute is set to None initially, and ``N_qubits``
+        is not defined until ``setNumQubits`` is called.
+
+        Args:
+            label (str | None): Optional annotation label for this component.
+                Defaults to the class name when *None*.
         """
         self.circuit = None
+        self.label = label if label is not None else self.__class__.__name__
 
     def setNumQubits(self, n):
         """
@@ -61,6 +69,55 @@ def create_circuit(self):
         ```
     """
 
+    def __init_subclass__(cls, **kwargs):
+        """
+        Automatically equips every concrete subclass with two behaviours:
+
+        1. **Default label** – if the subclass ``__init__`` does *not* call
+           ``super().__init__()``, the instance will still get a ``label``
+           attribute (set to the class name) after ``__init__`` returns.
+        2. **Circuit annotation** – after ``create_circuit`` returns the
+           ``circuit.name`` attribute is set to ``self.label`` so that
+           circuit drawings show the component name.
+        """
+        super().__init_subclass__(**kwargs)
+
+        # Wrap __init__ to guarantee self.label exists even when super() is
+        # not called by the subclass.
+        if "__init__" in cls.__dict__:
+            _orig_init = cls.__dict__["__init__"]
+
+            def _make_init_wrapper(f):
+                def _wrapped_init(self, *args, **kwargs):
+                    f(self, *args, **kwargs)
+                    if not hasattr(self, "label"):
+                        self.label = self.__class__.__name__
+
+                _wrapped_init.__doc__ = f.__doc__
+                _wrapped_init.__name__ = f.__name__
+                return _wrapped_init
+
+            setattr(cls, "__init__", _make_init_wrapper(_orig_init))
+
+        # Wrap create_circuit to set circuit.name from self.label.
+        if "create_circuit" in cls.__dict__:
+            _orig_cc = cls.__dict__["create_circuit"]
+            if not getattr(_orig_cc, "__isabstractmethod__", False):
+
+                def _make_cc_wrapper(f):
+                    def _wrapped_cc(self, *args, **kwargs):
+                        f(self, *args, **kwargs)
+                        if self.circuit is not None:
+                            self.circuit.name = getattr(
+                                self, "label", self.__class__.__name__
+                            )
+
+                    _wrapped_cc.__doc__ = f.__doc__
+                    _wrapped_cc.__name__ = f.__name__
+                    return _wrapped_cc
+
+                setattr(cls, "create_circuit", _make_cc_wrapper(_orig_cc))
+
     @abstractmethod
     def create_circuit(self):
         """

qaoa/mixers/base_mixer.py

@@ -21,15 +21,24 @@ class Grover(Mixer):
         create_circuit(): Constructs the Grover mixer circuit using the subcircuit.
     """
 
-    def __init__(self, subcircuit: InitialState) -> None:
+    def __init__(self, subcircuit: InitialState, label: str | None = None) -> None:
         """
         Initializes the Grover mixer.
 
         Args:
-            subcircuit (InitialState): The initial state circuit.
+            subcircuit (InitialState): The initial state circuit.  If the
+                subcircuit already has ``N_qubits`` set the Grover mixer
+                inherits it automatically so that ``setNumQubits`` does not
+                need to be called separately.
+            label (str | None): Optional annotation label.  Defaults to
+                ``"Grover"``.
         """
+        super().__init__(label=label)
         self.subcircuit = subcircuit
         self.mixer_param = Parameter("x_beta")
+        # Inherit N_qubits from the subcircuit when it is already known.
+        if hasattr(subcircuit, "N_qubits"):
+            self.N_qubits = subcircuit.N_qubits
 
     def create_circuit(self):
         r"""
@@ -40,7 +49,10 @@ def create_circuit(self):
         The Grover mixer has the form US^\dagger X^n C^{n-1}Phase X^n US.
         """
 
-        self.subcircuit.setNumQubits(self.N_qubits)
+        # Only update the subcircuit's qubit count when it differs from our own,
+        # preserving any N_qubits that was already set on the subcircuit.
+        if not hasattr(self.subcircuit, "N_qubits") or self.subcircuit.N_qubits != self.N_qubits:
+            self.subcircuit.setNumQubits(self.N_qubits)
         self.subcircuit.create_circuit()
         US = self.subcircuit.circuit