Creates a Composite gate helper and pipes extension to simulator.

Also fixes or adds documentation.

Author: dabacon

cirq/docs/gates.md

@@ -100,7 +100,8 @@ One thing about ``CompositeGates`` is that sometimes you want
 to modify the decomposition.  Algorithms that allow this can
 take an ``Extension`` which allows for overriding the 
 ``CompositeGate``.  An example of this is for in 
-``Simulators`` where an optional 
+``Simulators`` where an optional extension can be supplied
+that can be used to override the CompositeGate.
 
 #### TextDiagrammableGate
 
@@ -135,7 +136,7 @@ out of the circuit (TODO: explain this in more detail)
 
 **Exp11Gate** This is a two qubit gate and is a rotation
 about the ``|11><11|`` projector.  It takes a single parameter 
-``half_turns`` and is the gate ``exp(i pi 11 half_turns)``.
+``half_turns`` and is the gate ``exp(i pi |11><11| half_turns)``.
 
 **XmonMeasurementGate** This is a single qubit measurement
 in the computational basis. 

cirq/docs/simulation.md

@@ -138,7 +138,8 @@ for getting it to work with the simulator:
 * Define it directly as an ``XmonGate``.
 * Provide a ``CompositeGate`` made up of ``XmonGates``.
 * Supply an ``Exentension`` to the simulator which converts
-the gate to an ``XmonGate`` (TODO(dabacon): not implemented yet). 
+the gate to an ``XmonGate`` or to a ``CompositeGate`` which 
+itself can be decomposed in ``XmonGates``. 
 
 ### Parameterized Values and Studies
 

cirq/google/sim/xmon_simulator.py

@@ -34,7 +34,9 @@
 
 from cirq.circuits import Circuit
 from cirq.circuits.drop_empty_moments import DropEmptyMoments
+from cirq.extension import Extensions
 from cirq.google import xmon_gates
+from cirq.google import xmon_gate_ext
 from cirq.google.convert_to_xmon_gates import ConvertToXmonGates
 from cirq.google.sim.xmon_stepper import Stepper
 from cirq.ops import raw_types
@@ -119,6 +121,7 @@ def run(
         options: Options = None,
         qubits: Sequence[raw_types.QubitId] = None,
         initial_state: Union[int, np.ndarray] = 0,
+        extensions : Extensions = None,
     ) -> SimulatorTrialResult:
         """Simulates the entire supplied Circuit.
 
@@ -135,12 +138,16 @@ def run(
                 Otherwise  if this is a np.ndarray it is the full initial
                 state. In this case it must be the correct size, be normalized
                 (an L2 norm of 1), and have a dtype of np.complex64.
+            extensions: Extensions that will be applied while trying to
+                decompose the circuit's gates into XmonGates. If None, this uses
+                the default of xmon_gate_ext.
 
         Returns:
             Results for this run.
         """
         return self.run_sweep(circuit, [param_resolver], repetitions, options,
-                              qubits, initial_state)[0]
+                              qubits, initial_state,
+                              extensions or xmon_gate_ext)[0]
 
     def run_sweep(
             self,
@@ -150,6 +157,7 @@ def run_sweep(
             options: Options = None,
             qubits: Sequence[raw_types.QubitId] = None,
             initial_state: Union[int, np.ndarray] = 0,
+            extensions: Extensions = None
     ) -> List[SimulatorTrialResult]:
         """Simulates the entire supplied Circuit.
 
@@ -166,6 +174,9 @@ def run_sweep(
                 Otherwise if this is a np.ndarray it is the full initial state.
                 In this case it must be the correct size, be normalized (an L2
                 norm of 1), and have a dtype of np.complex64.
+            extensions: Extensions that will be applied while trying to
+                decompose the circuit's gates into XmonGates. If None, this uses
+                the default of xmon_gate_ext.
 
         Returns:
             List of trial results for this run, one for each possible parameter
@@ -175,18 +186,20 @@ def run_sweep(
                                         Circuit) else program.to_circuit()
         param_resolvers = self._to_resolvers(params or ParamResolver({}))
 
-        xmon_circuit, keys = self._to_xmon_circuit(circuit)
+        xmon_circuit, keys = self._to_xmon_circuit(circuit,
+                                                   extensions or xmon_gate_ext)
         trial_results = []  # type: List[SimulatorTrialResult]
         for param_resolver in param_resolvers:
             measurements = {
                 k: [] for k in keys}  # type: Dict[str, List[np.ndarray]]
             final_states = []  # type: List[np.ndarray]
             for _ in range(repetitions):
-                all_step_results = simulator_iterator(xmon_circuit,
-                                                      options or Options(),
-                                                      qubits,
-                                                      initial_state,
-                                                      param_resolver)
+                all_step_results = simulator_iterator(
+                    xmon_circuit,
+                    options or Options(),
+                    qubits,
+                    initial_state,
+                    param_resolver)
                 for step_result in all_step_results:
                     for k, v in step_result.measurements.items():
                         measurements[k].append(np.array(v, dtype=bool))
@@ -216,7 +229,8 @@ def moment_steps(
             options: 'Options' = None,
             qubits: Sequence[raw_types.QubitId] = None,
             initial_state: Union[int, np.ndarray]=0,
-            param_resolver: ParamResolver = None) -> Iterator['StepResult']:
+            param_resolver: ParamResolver = None,
+            extensions: Extensions = None) -> Iterator['StepResult']:
         """Returns an iterator of XmonStepResults for each moment simulated.
 
         Args:
@@ -232,20 +246,25 @@ def moment_steps(
                 norm of 1), and have a dtype of np.complex64.
             param_resolver: A ParamResolver for determining values of
                 Symbols.
+            extensions: Extensions that will be applied while trying to
+                decompose the circuit's gates into XmonGates. If None, this
+                uses the default of xmon_gate_ext.
 
         Returns:
             SimulatorIterator that steps through the simulation, simulating
             each moment and returning a StepResult for each moment.
         """
         param_resolver = param_resolver or ParamResolver({})
-        xmon_circuit, _ = self._to_xmon_circuit(program)
+        xmon_circuit, _ = self._to_xmon_circuit(program,
+                                                extensions or xmon_gate_ext)
         return simulator_iterator(xmon_circuit, options or Options(), qubits,
                                   initial_state, param_resolver)
 
-    def _to_xmon_circuit(self, circuit: Circuit) -> Tuple[Circuit, Set[str]]:
+    def _to_xmon_circuit(self, circuit: Circuit,
+        extensions: Extensions = None) -> Tuple[Circuit, Set[str]]:
         # TODO: Use one optimization pass.
         xmon_circuit = Circuit(circuit.moments)
-        ConvertToXmonGates().optimize_circuit(xmon_circuit)
+        ConvertToXmonGates(extensions).optimize_circuit(xmon_circuit)
         DropEmptyMoments().optimize_circuit(xmon_circuit)
         keys = find_measurement_keys(xmon_circuit)
         return xmon_circuit, keys
@@ -256,7 +275,7 @@ def simulator_iterator(
         options: 'Options' = Options(),
         qubits: Sequence[raw_types.QubitId] = None,
         initial_state: Union[int, np.ndarray]=0,
-        param_resolver: ParamResolver = ParamResolver({})
+        param_resolver: ParamResolver = ParamResolver({}),
 ) -> Iterator['StepResult']:
     """Iterator over TrialResults from Moments of a Circuit.
 

cirq/google/sim/xmon_simulator_test.py

@@ -24,6 +24,7 @@
 
 from cirq.circuits import Circuit
 from cirq.devices import UnconstrainedDevice
+from cirq.extension import Extensions
 from cirq.google import (
     ExpWGate, ExpZGate, Exp11Gate, XmonMeasurementGate, XmonQubit,
 )
@@ -412,6 +413,27 @@ def test_unsupported_gate_composite(scheduler):
         _ = run(simulator, circuit, scheduler)
 
 
+@pytest.mark.parametrize('scheduler', SCHEDULERS)
+def test_extensions(scheduler):
+    # We test that an extension is being applied, by created an incorrect
+    # gate with an extension.
+
+    class WrongH(CompositeGate):
+        def default_decompose(
+            self, qubits: Sequence[raw_types.QubitId]) -> op_tree.OP_TREE:
+            return X(Q1)
+
+    extensions = Extensions(desired_to_actual_to_wrapper=
+                            {CompositeGate: {H: lambda e: WrongH()}})
+
+    circuit = Circuit()
+    circuit.append([WrongH()(Q1)])
+
+    simulator = xmon_simulator.Simulator()
+    results =  simulator.run(circuit, qubits=[Q1], extensions=extensions)
+    np.testing.assert_almost_equal(results.final_states[0], np.array([0, -1j]))
+
+
 @pytest.mark.parametrize('scheduler', SCHEDULERS)
 def test_measurement_qubit_order(scheduler):
     circuit = Circuit()

cirq/google/xmon_gates.py

@@ -87,7 +87,10 @@ def parameterized_value_to_proto(
 
 
 class XmonMeasurementGate(XmonGate, ops.MeasurementGate):
-    """Indicates that qubits should be measured, and where the result goes."""
+    """Indicates that qubits should be measured, and where the result goes.
+
+    This measurement is done in the computational basis.
+    """
 
     def to_proto(self, *qubits):
         if len(qubits) == 0:
@@ -108,7 +111,17 @@ class Exp11Gate(XmonGate,
                 ops.InterchangeableQubitsGate,
                 ops.PhaseableGate,
                 PotentialImplementation):
-    """A two-qubit interaction that phases the amplitude of the 11 state."""
+    """A two-qubit interaction that phases the amplitude of the 11 state.
+
+    This gate is exp(i * pi * |11><11|  * half_turn).
+
+    Note that this half_turn parameter is such that a full turn is the
+    identity matrix, in contrast to the single qubit gates, where a full
+    turn is minus identity. The single qubit half-turn gates are defined
+    so that a full turn corresponds to a rotation on the Bloch sphere of a
+    360 degree rotation. For two qubit gates, there isn't a Bloch sphere,
+    so the half_turn corresponds to half of a full rotation in U(4).
+    """
 
     def __init__(self, *positional_args,
                  half_turns: Union[Symbol, float]=1) -> None:
@@ -177,7 +190,23 @@ class ExpWGate(XmonGate,
                ops.PhaseableGate,
                ops.BoundedEffectGate,
                PotentialImplementation):
-    """A rotation around an axis in the XY plane of the Bloch sphere."""
+    """A rotation around an axis in the XY plane of the Bloch sphere.
+
+    This gate is exp(-i * pi * W(axis_half_turn) * half_turn / 2) where
+        W(theta) = cos(pi * theta) X + sin(pi * theta) Y
+     or in matrix form
+       W(theta) = [[0, cos(pi * theta) - i sin(pi * theta)],
+                   [cos(pi * theta) + i sin(pi * theta), 0]]
+
+    Note the half_turn nomenclature here comes from viewing this as a rotation
+    on the Bloch sphere. Two half_turns correspond to a rotation in the
+    bloch sphere of 360 degrees. Note that this is minus identity, not
+    just identity.  Similarly the axis_half_turns refers thinking of rotating
+    the Bloch operator, starting with the operator pointing along the X
+    direction. An axis_half_turn of 1 corresponds to the operator pointing
+    along the -X direction while an axis_half_turn of 0.5 correspond to
+    an operator pointing along the Y direction.
+    """
 
     def __init__(self, *positional_args,
                  half_turns: Union[Symbol, float]=1,
@@ -294,7 +323,16 @@ class ExpZGate(XmonGate,
                ops.SingleQubitGate,
                ops.TextDiagrammableGate,
                PotentialImplementation):
-    """A rotation around the Z axis of the Bloch sphere."""
+    """A rotation around the Z axis of the Bloch sphere.
+
+    This gate is exp(-i * pi * Z * half_turns / 2) where Z is the Z matrix
+        Z = [[1, 0],
+             [0, -1]]
+
+    Note the half_turn nomenclature here comes from viewing this as a rotation
+    on the Bloch sphere. Two half_turns correspond to a rotation in the
+    bloch sphere of 360 degrees.
+    """
 
     def __init__(self, *positional_args,
                  half_turns: Union[Symbol, float]=1) -> None:

cirq/ops/gate_features.py

@@ -17,7 +17,7 @@
 For example: some gates are reversible, some have known matrices, etc.
 """
 
-from typing import Sequence, Tuple, Optional
+from typing import Optional, Sequence, Tuple, Type, Union
 
 import numpy as np
 
@@ -96,6 +96,48 @@ def default_decompose(
         """
 
 
+    @classmethod
+    def from_gates(cls: Type,
+        gates: Union[Sequence[raw_types.Gate], Sequence[
+            Tuple[raw_types.Gate, Tuple[int]]]]) -> 'CompositeGate':
+        """Returns a CompositeGate which decomposes into the given gates.
+
+        Args:
+            gates: Either a sequence of gates or a sequences of (gate, indices)
+                tuples, where indices is a tuple of qubit indices (ints). The
+                first is used when decomposing a gate into a series of gates
+                that all act on the same number of qubits. The second is used
+                when decomposing a gate into a series of gates that may act on
+                differing number of qubits. In this later case the indices
+                is a tuple of qubit indices, describing which qubit the gate
+                acts on.
+
+        Returns:
+            A CompositeGate with a default_decompose that applies the
+            given gates in sequence.
+        """
+        return _CompositeGateImpl(gates)
+
+
+class _CompositeGateImpl(CompositeGate):
+    """Implementation of CompositeGate which uses specific sequence of gates."""
+
+    def __init__(self, gates: Union[Sequence[raw_types.Gate], Sequence[
+        Tuple[raw_types.Gate, Tuple[int]]]]) -> None:
+        self.gates = gates
+
+    def default_decompose(
+        self, qubits: Sequence[raw_types.QubitId]) -> op_tree.OP_TREE:
+        decomposition = []
+        for x in self.gates:
+            if isinstance(x, raw_types.Gate):
+                decomposition.append(x(*qubits))
+            else:
+                gate, indices = x
+                decomposition.append(gate(*map(qubits.__getitem__, indices)))
+        return decomposition
+
+
 class KnownMatrixGate(raw_types.Gate, metaclass=abc.ABCMeta):
     """A gate whose constant non-parameterized effect has a known matrix."""
 

cirq/ops/gate_features_test.py

@@ -105,6 +105,34 @@ def default_decompose(self, qubits):
     assert isinstance(Included(), gate_features.CompositeGate)
 
 
+def test_composite_gate_from_gates():
+    class G1(raw_types.Gate):
+        pass
+    class G2(raw_types.Gate):
+        pass
+
+    gates = [G1(), G2()]
+    composite = gate_features.CompositeGate.from_gates(gates)
+
+    q1 = raw_types.QubitId()
+    assert [gates[0](q1), gates[1](q1)] == composite.default_decompose([q1])
+
+
+def test_composite_gate_from_gate_tuples():
+    class G1(raw_types.Gate):
+        pass
+    class G2(raw_types.Gate):
+        pass
+
+    gates = [(G1(), (0,)), (G2(), (0, 1))]
+    composite = gate_features.CompositeGate.from_gates(gates)
+
+    q1 = raw_types.QubitId()
+    q2 = raw_types.QubitId()
+    assert ([gates[0][0](q1), gates[1][0](q1, q2)]
+            == composite.default_decompose([q1, q2]))
+
+
 def test_self_inverse_is_not_abstract():
     assert isinstance(gate_features.SelfInverseGate(),
                       gate_features.ReversibleGate)