Refactor AsciiDiagrammableGate into TextDiagrammableGate (#293)

- Find all places where docs/code says "ASCII" and replace it with "text" as appropriate
- Split to_text_diagram_drawer out of circuit.to_text_diagram
- Rename ascii_wire_symbols to text_diagram_wire_symbols
- Rename ascii_exponent to text_diagram_exponent
- Add optional qubit_count argument to text_diagram_wire_symbols
- Add optional use_unicode_characters argument to text_diagram_wire_symbols
- Remove unused XmonQubit try_parse_from_text method

Author: Strilanc

cirq/__init__.py

@@ -78,7 +78,6 @@
 )
 
 from cirq.ops import (
-    AsciiDiagrammableGate,
     BoundedEffectGate,
     CNOT,
     CNotGate,
@@ -112,6 +111,7 @@
     SWAP,
     SwapGate,
     T,
+    TextDiagrammableGate,
     transform_op_tree,
     TwoQubitGate,
     TwoQubitMatrixGate,

cirq/circuits/circuit.py

@@ -402,10 +402,10 @@ def to_text_diagram(
         """Returns text containing a diagram describing the circuit.
 
         Args:
-            ext: For extending gates to implement AsciiDiagrammableGate.
-            use_unicode_characters: Activates the use of cleaner-looking
-                unicode box-drawing characters for lines.
-            transpose: Arranges the wires vertically instead of horizontally.
+            ext: For extending gates to implement TextDiagrammableGate.
+            use_unicode_characters: Determines if unicode characters are
+                allowed (as opposed to ascii-only diagrams).
+            transpose: Arranges qubit wires vertically instead of horizontally.
             qubit_order_key: Transforms each qubit into a key that determines
                 how the qubits are ordered in the diagram. Qubits with lower
                 keys come first. Defaults to the qubit's __str__, but augmented
@@ -414,7 +414,43 @@ def to_text_diagram(
                 "name2").
 
         Returns:
-            The ascii diagram.
+            The text diagram.
+        """
+
+        diagram = self.to_text_diagram_drawer(
+            ext=ext,
+            qubit_name_suffix='' if transpose else ': ',
+            qubit_order_key=qubit_order_key)
+
+        if transpose:
+            return diagram.transpose().render(
+                crossing_char='─' if use_unicode_characters else '-',
+                use_unicode_characters=use_unicode_characters)
+        return diagram.render(
+            crossing_char='┼' if use_unicode_characters else '|',
+            horizontal_spacing=3,
+            use_unicode_characters=use_unicode_characters)
+
+    def to_text_diagram_drawer(
+            self,
+            ext: Extensions = Extensions(),
+            qubit_name_suffix: str = '',
+            qubit_order_key: Callable[[QubitId], Any] = None
+    ) -> TextDiagramDrawer:
+        """Returns a TextDiagramDrawer with the circuit drawn into it.
+
+        Args:
+            ext: For extending gates to implement TextDiagrammableGate.
+            qubit_name_suffix: Appended to qubit names in the diagram.
+            qubit_order_key: Transforms each qubit into a key that determines
+                how the qubits are ordered in the diagram. Qubits with lower
+                keys come first. Defaults to the qubit's __str__, but augmented
+                so that lexicographic ordering will respect the order of
+                integers within the string (e.g. "name10" will come after
+                "name2").
+
+        Returns:
+            The TextDiagramDrawer instance.
         """
         if qubit_order_key is None:
             qubit_order_key = _str_lexicographic_respecting_int_order
@@ -432,7 +468,7 @@ def to_text_diagram(
 
         diagram = TextDiagramDrawer()
         for q, i in qubit_map.items():
-            diagram.write(0, i, str(q) + ('' if transpose else ': '))
+            diagram.write(0, i, str(q) + qubit_name_suffix)
 
         for moment in [Moment()] * 2 + self.moments + [Moment()]:
             _draw_moment_in_diagram(moment, ext, qubit_map, diagram)
@@ -441,28 +477,21 @@ def to_text_diagram(
         for i in qubit_map.values():
             diagram.horizontal_line(i, 0, w)
 
-        if transpose:
-            return diagram.transpose().render(
-                crossing_char='─' if use_unicode_characters else '-',
-                use_unicode_characters=use_unicode_characters)
-        return diagram.render(
-            crossing_char='┼' if use_unicode_characters else '|',
-            horizontal_spacing=3,
-            use_unicode_characters=use_unicode_characters)
+        return diagram
 
 
 def _get_operation_text_diagram_symbols(op: ops.Operation, ext: Extensions
                                         ) -> Iterable[str]:
-    ascii_gate = ext.try_cast(op.gate, ops.AsciiDiagrammableGate)
-    if ascii_gate is not None:
-        wire_symbols = ascii_gate.ascii_wire_symbols()
+    text_diagram_gate = ext.try_cast(op.gate, ops.TextDiagrammableGate)
+    if text_diagram_gate is not None:
+        wire_symbols = text_diagram_gate.text_diagram_wire_symbols()
         if len(op.qubits) == len(wire_symbols):
             return wire_symbols
         elif len(wire_symbols) == 1:
             return len(op.qubits) * wire_symbols
         else:
             raise ValueError(
-                'Multi-qubit operation with AsciiDiagrammableGate {} that '
+                'Multi-qubit operation with TextDiagrammableGate {} that '
                 'requires {} qubits but found {} qubits'.format(
                     repr(op.gate), len(wire_symbols), len(op.qubits)))
 
@@ -474,10 +503,10 @@ def _get_operation_text_diagram_symbols(op: ops.Operation, ext: Extensions
 
 def _get_operation_text_diagram_exponent(op: ops.Operation,
                                          ext: Extensions) -> Optional[str]:
-    ascii_gate = ext.try_cast(op.gate, ops.AsciiDiagrammableGate)
-    if ascii_gate is None:
+    text_diagram_gate = ext.try_cast(op.gate, ops.TextDiagrammableGate)
+    if text_diagram_gate is None:
         return None
-    exponent = ascii_gate.ascii_exponent()
+    exponent = text_diagram_gate.text_diagram_exponent()
     if exponent == 1:
         return None
     if isinstance(exponent, float):

cirq/circuits/circuit_test.py

@@ -581,16 +581,18 @@ def __repr__(self):
             """.strip()
 
     # Succeeds with extension.
-    class FGateAsAscii(ops.AsciiDiagrammableGate):
+    class FGateAsText(ops.TextDiagrammableGate):
         def __init__(self, f_gate):
             self.f_gate = f_gate
 
-        def ascii_wire_symbols(self):
+        def text_diagram_wire_symbols(self,
+                                      qubit_count=None,
+                                      use_unicode_characters=True):
             return 'F'
 
     diagram = c.to_text_diagram(Extensions({
-        ops.AsciiDiagrammableGate: {
-           FGate: FGateAsAscii
+        ops.TextDiagrammableGate: {
+           FGate: FGateAsText
         }
     }), use_unicode_characters=False)
 
@@ -627,8 +629,10 @@ def test_to_text_diagram_multi_qubit_gate():
 
 
 def test_to_text_diagram_many_qubits_gate_but_multiple_wire_symbols():
-    class BadGate(ops.AsciiDiagrammableGate):
-        def ascii_wire_symbols(self):
+    class BadGate(ops.TextDiagrammableGate):
+        def text_diagram_wire_symbols(self,
+                                      qubit_count=None,
+                                      use_unicode_characters=True):
             return 'a', 'a'
     q1 = ops.NamedQubit('(0, 0)')
     q2 = ops.NamedQubit('(0, 1)')
@@ -641,14 +645,16 @@ def ascii_wire_symbols(self):
 def test_to_text_diagram_parameterized_value():
     q = ops.NamedQubit('cube')
 
-    class PGate(ops.AsciiDiagrammableGate):
+    class PGate(ops.TextDiagrammableGate):
         def __init__(self, val):
             self.val = val
 
-        def ascii_wire_symbols(self):
+        def text_diagram_wire_symbols(self,
+                                      qubit_count=None,
+                                      use_unicode_characters=True):
             return 'P',
 
-        def ascii_exponent(self):
+        def text_diagram_exponent(self):
             return self.val
 
     c = Circuit.from_ops(

cirq/circuits/text_diagram_drawer.py

@@ -93,7 +93,7 @@ def render(self,
                vertical_spacing: int = 1,
                crossing_char: str = None,
                use_unicode_characters: bool = True) -> str:
-        """Outputs ascii text containing the ascii diagram."""
+        """Outputs text containing the diagram."""
 
         pipe = '│' if use_unicode_characters else '|'
         dash = '─' if use_unicode_characters else '-'

cirq/docs/circuits.md

@@ -82,7 +82,7 @@ moment1 = cirq.circuits.Moment([cz12])
 circuit = cirq.circuits.Circuit((moment0, moment1))
 
 print(circuit)
-# prints the ascii diagram for the circuit:
+# prints the text diagram for the circuit:
 # (0, 0): ───Z───────
 #            │
 # (0, 1): ───Z───Z───

cirq/docs/gates.md

@@ -102,12 +102,12 @@ take an ``Extension`` which allows for overriding the
 ``CompositeGate``.  An example of this is for in 
 ``Simulators`` where an optional 
 
-#### AsciiDiagramableGate
+#### TextDiagrammableGate
 
-Ascii diagrams of ``Circuits`` are actually quite useful for 
-visualizing the moment structure of a ``Circuit``. In order
-for this to display in a compact form, it is best practice
-to implement his feature.
+Text diagrams of ``Circuits`` are actually quite useful for
+visualizing the moment structure of a ``Circuit``. Gates that
+implement this feature can specify compact representations to
+use in the diagram (e.g. '×' instead of 'SWAP').
 
 ### XmonGates
 

cirq/google/xmon_gates.py

@@ -104,7 +104,7 @@ def __repr__(self):
 
 
 class Exp11Gate(XmonGate,
-                ops.AsciiDiagrammableGate,
+                ops.TextDiagrammableGate,
                 ops.InterchangeableQubitsGate,
                 ops.PhaseableGate,
                 PotentialImplementation):
@@ -142,10 +142,12 @@ def matrix(self):
             raise ValueError("Don't have a known matrix.")
         return ops.Rot11Gate(half_turns=self.half_turns).matrix()
 
-    def ascii_wire_symbols(self):
+    def text_diagram_wire_symbols(self,
+                                  qubit_count=None,
+                                  use_unicode_characters=True):
         return 'Z', 'Z'
 
-    def ascii_exponent(self):
+    def text_diagram_exponent(self):
         return self.half_turns
 
     def __str__(self):
@@ -171,7 +173,7 @@ def __hash__(self):
 
 class ExpWGate(XmonGate,
                ops.SingleQubitGate,
-               ops.AsciiDiagrammableGate,
+               ops.TextDiagrammableGate,
                ops.PhaseableGate,
                ops.BoundedEffectGate,
                PotentialImplementation):
@@ -242,18 +244,20 @@ def trace_distance_bound(self):
             return 1
         return abs(self.half_turns) * 3.5
 
-    def ascii_wire_symbols(self):
+    def text_diagram_wire_symbols(self,
+                                  qubit_count=None,
+                                  use_unicode_characters=True):
         if self.axis_half_turns == 0:
             return 'X',
         if self.axis_half_turns == 0.5:
             return 'Y',
         return 'W({})'.format(self.axis_half_turns),
 
-    def ascii_exponent(self):
+    def text_diagram_exponent(self):
         return self.half_turns
 
     def __str__(self):
-        base = self.ascii_wire_symbols()[0]
+        base = self.text_diagram_wire_symbols()[0]
         if self.half_turns == 1:
             return base
         return '{}^{}'.format(base, self.half_turns)
@@ -288,7 +292,7 @@ def __hash__(self):
 
 class ExpZGate(XmonGate,
                ops.SingleQubitGate,
-               ops.AsciiDiagrammableGate,
+               ops.TextDiagrammableGate,
                PotentialImplementation):
     """A rotation around the Z axis of the Bloch sphere."""
 
@@ -297,14 +301,16 @@ def __init__(self, *positional_args,
         assert not positional_args
         self.half_turns = _canonicalize_half_turns(half_turns)
 
-    def ascii_wire_symbols(self):
+    def text_diagram_wire_symbols(self,
+                                  qubit_count=None,
+                                  use_unicode_characters=True):
         if self.half_turns in [-0.25, 0.25]:
             return 'T'
         if self.half_turns in [-0.5, 0.5]:
             return 'S'
         return 'Z',
 
-    def ascii_exponent(self):
+    def text_diagram_exponent(self):
         if self.half_turns in [0.25, 0.5]:
             return 1
         if self.half_turns in [-0.5, -0.25]:

cirq/google/xmon_qubit.py

@@ -11,7 +11,6 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-import re
 
 from cirq.api.google.v1 import operations_pb2
 from cirq.ops import QubitId
@@ -44,13 +43,6 @@ def __repr__(self):
     def __str__(self):
         return '({}, {})'.format(self.row, self.col)
 
-    @staticmethod
-    def try_parse_from_ascii(text):
-        if re.match('\\(\\s*\\d+,\\s*\\d+\\s*\\)', text):
-            a, b = text[1:-1].split(',')
-            return XmonQubit(int(a.strip()), int(b.strip()))
-        return None
-
     def to_proto(
             self, out: operations_pb2.Qubit = None) -> operations_pb2.Qubit:
         """Return the proto form, mutating supplied form if supplied."""

cirq/ops/__init__.py

@@ -35,7 +35,6 @@
     Z,
 )
 from cirq.ops.gate_features import (
-    AsciiDiagrammableGate,
     BoundedEffectGate,
     CompositeGate,
     ExtrapolatableGate,
@@ -44,6 +43,7 @@
     ReversibleGate,
     SelfInverseGate,
     SingleQubitGate,
+    TextDiagrammableGate,
     TwoQubitGate,
 )
 from cirq.ops.matrix_gates import (