Fix Grover circuit drawing: labeled Dicke†/Dicke boxes and clean register names

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

Author: Copilot

README.md

@@ -171,26 +171,37 @@ Assuming all-to-all connectivity of qubits, one can minimize the depth of the ci
 
 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:
+For example, a Grover mixer over 3 independent Dicke sub-registers (each with 4 qubits, Hamming weight k=2) 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)
+	dicke  = initialstates.Dicke(2)        # Dicke state with k=2 excitations
+	dicke.setNumQubits(4)                   # 4-qubit register per block
+	grover = mixers.Grover(dicke)           # Grover mixer over the Dicke feasible space
+	tensor = initialstates.Tensor(grover, 3)  # 3 independent copies (12 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.
+`Grover` inherits the qubit count from its sub-circuit, so no extra `setNumQubits`
+call is needed for the mixer itself.
 
-![Lego circuit](images/lego_circuit.png "Lego circuit: three Grover blocks on 6 qubits")
+![Lego circuit](images/lego_circuit.png "Lego circuit: three Grover blocks on 12 qubits")
 
 Each sub-circuit is shown as a labelled block in the drawing so the "lego" structure
 is immediately visible.
 
+To inspect the internal structure of a single Grover block, draw it directly:
+
+	grover.create_circuit()
+	grover.circuit.draw('mpl')
+
+![Grover circuit](images/grover_circuit.png "Grover mixer: Dicke† – X^n – C^{n-1}Phase – X^n – Dicke")
+
+The Grover mixer is constructed as U_S† X^n C^{n-1}P X^n U_S, where the Dicke
+state-preparation circuit U_S and its inverse are each shown as a single labelled
+box (`Dicke†` / `Dicke`).
+
 ### Annotating circuits
 
 Every component (initial state or mixer) carries a `label` attribute that is used as

images/grover_circuit.png

@@ -50,7 +50,7 @@ def create_circuit(self) -> None:
         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)
+        qr = QuantumRegister(self.N_qubits, name="q")
         self.circuit = QuantumCircuit(qr)
         n = self.subcircuit.N_qubits
         for i in range(self.num):

images/lego_circuit.png

@@ -63,7 +63,7 @@ def create_circuit(self):
         sub_label = getattr(self.subcircuit, "label", self.subcircuit.__class__.__name__)
         n = self.subcircuit.N_qubits
 
-        qr = QuantumRegister(n)
+        qr = QuantumRegister(n, name="q")
         self.circuit = QuantumCircuit(qr)
 
         # US^\dagger — shown as a labelled box (e.g. "Dicke†")

qaoa/initialstates/tensor_initialstate.py

@@ -49,6 +49,32 @@ def test_grover_mixer_circuit_has_params(self):
         mixer.create_circuit()
         self.assertGreater(len(mixer.circuit.parameters), 0)
 
+    def test_grover_shows_labeled_subcircuit_instructions(self):
+        """Grover circuit should show US† and US as labeled instructions."""
+        from qaoa.mixers import Grover
+        from qaoa.initialstates import Dicke
+
+        grover = Grover(Dicke(2))
+        grover.create_circuit()
+        labels = [
+            getattr(instr.operation, "label", None)
+            for instr in grover.circuit.data
+        ]
+        # The first instruction should be US† labelled "Dicke†"
+        self.assertEqual(labels[0], "Dicke\u2020")
+        # The last instruction should be US labelled "Dicke"
+        self.assertEqual(labels[-1], "Dicke")
+
+    def test_grover_circuit_register_name(self):
+        """Grover circuit should use the register name 'q' for clean qubit labels."""
+        from qaoa.mixers import Grover
+        from qaoa.initialstates import Dicke
+
+        grover = Grover(Dicke(2))
+        grover.create_circuit()
+        reg_names = {q._register.name for q in grover.circuit.qubits}
+        self.assertEqual(reg_names, {"q"})
+
 
 class TestXMultiAngleMixer(unittest.TestCase):
     """Tests for the XMultiAngle mixer."""