UtilBloq -> _BookkeepingBloq, improve docstring

qualtran/bloqs/util_bloqs.py

@@ -50,11 +50,12 @@
     from qualtran.simulation.classical_sim import ClassicalValT
 
 
-class UtilBloq(Bloq, metaclass=abc.ABCMeta):
-    """Base class for util bloqs.
+class _BookkeepingBloq(Bloq, metaclass=abc.ABCMeta):
+    """Base class for utility bloqs used for bookkeeping.
 
-    1. Trivial controlled - pass through the control register.
-    2. Do not affect T complexity.
+    This bloq:
+    - has trivial controlled versions, which pass through the control register.
+    - does not affect T complexity.
     """
 
     def get_ctrl_system(
@@ -74,7 +75,7 @@ def _t_complexity_(self) -> 'TComplexity':
 
 
 @frozen
-class Split(UtilBloq):
+class Split(_BookkeepingBloq):
     """Split a bitsize `n` register into a length-`n` array-register.
 
     Attributes:
@@ -133,7 +134,7 @@ def wire_symbol(self, reg: Optional[Register], idx: Tuple[int, ...] = tuple()) -
 
 
 @frozen
-class Join(UtilBloq):
+class Join(_BookkeepingBloq):
     """Join a length-`n` array-register into one register of bitsize `n`.
 
     Attributes:
@@ -192,7 +193,7 @@ def wire_symbol(self, reg: Optional[Register], idx: Tuple[int, ...] = tuple()) -
 
 
 @frozen
-class Partition(UtilBloq):
+class Partition(_BookkeepingBloq):
     """Partition a generic index into multiple registers.
 
     Args:
@@ -260,9 +261,7 @@ def add_my_tensors(
 
         tn.add(
             qtn.Tensor(
-                data=np.eye(2**self.n, 2**self.n).reshape(
-                    tuple(unitary_shape) + (2**self.n,)
-                ),
+                data=np.eye(2**self.n, 2**self.n).reshape(tuple(unitary_shape) + (2**self.n,)),
                 inds=soquets + [_incoming['x']],
                 tags=['Partition', tag],
             )
@@ -315,7 +314,7 @@ def wire_symbol(self, reg: Register, idx: Tuple[int, ...] = tuple()) -> 'WireSym
 
 
 @frozen
-class Allocate(UtilBloq):
+class Allocate(_BookkeepingBloq):
     """Allocate an `n` bit register.
 
     Attributes:
@@ -356,7 +355,7 @@ def wire_symbol(self, reg: Register, idx: Tuple[int, ...] = tuple()) -> 'WireSym
 
 
 @frozen
-class Free(UtilBloq):
+class Free(_BookkeepingBloq):
     """Free (i.e. de-allocate) an `n` bit register.
 
     The tensor decomposition assumes the `n` bit register is uncomputed and is in the $|0^{n}>$
@@ -426,7 +425,7 @@ def _t_complexity_(self) -> 'TComplexity':
 
 
 @frozen
-class Cast(UtilBloq):
+class Cast(_BookkeepingBloq):
     """Cast a register from one n-bit QDType to another QDType.