progress

mrmustard/lab_dev/circuits.py

@@ -15,7 +15,39 @@
 # pylint: disable=too-many-branches
 
 """
-A class to quantum circuits.
+A class to represent quantum circuits.
+
+Quantum circuits store a list of ``CircuitComponent``s, without performing any contraction.
+
+.. code-block::
+
+    >>> from mrmustard.lab_dev import BSgate, Sgate, Vacuum, Circuit
+
+    >>> vac = Vacuum([0, 1, 2])
+    >>> s01 = Sgate([0, 1], r=[0.1, 0.2])
+    >>> bs01 = BSgate([0, 1])
+    >>> bs12 = BSgate([1, 2])
+
+    >>> components = [vac, s01, bs01, bs12]
+    >>> circ = Circuit(components)
+    >>> assert circ.components == components
+
+The ``>>`` operator allows appending new components, or even entire circuits.
+
+.. code-block::
+
+    >>> from mrmustard.lab_dev import BSgate, Sgate, Vacuum, Circuit
+
+    >>> vac = Vacuum([0, 1, 2])
+    >>> s01 = Sgate([0, 1], r=[0.1, 0.2])
+    >>> bs01 = BSgate([0, 1])
+    >>> bs12 = BSgate([1, 2])
+
+    >>> circ1 = Circuit() >> vac >> s01
+    >>> circ2 = Circuit([bs01]) >> bs12
+    >>> assert circ1 >> circ2 == Circuit([vac, s01, bs01, bs12])
+
+The operations in a circuit can be contracted using the :class:`~mrmustard.lab_dev.simulator.Simulator`.
 """
 
 from __future__ import annotations

mrmustard/lab_dev/simulator.py

@@ -12,8 +12,66 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
+r"""
 Simulators for quantum circuits.
+
+The simulator allows contracting the components stored in quantum circuits.
+
+.. code-block::
+
+    >>> from mrmustard.lab_dev import *
+    >>> import numpy as np
+
+    >>> # initialize a circuit
+    >>> state = Number(modes=[0, 1], n=[2, 0], cutoffs=2)
+    >>> gate = BSgate([0, 1], theta=np.pi/4)
+    >>> proj1 = Number(modes=[1], n=[0]).dual
+    >>> circuit = Circuit([state, gate, proj1])
+
+    >>> # run the simulation
+    >>> result = Simulator().run(circuit)
+
+    >>> # the simulator returns a component that can be potentially be plugged
+    >>> # into another circuit
+    >>> assert isinstance(result, CircuitComponent)
+
+The simulation is carried out by contracting the components of the given circuit in pairs,
+until only one component is left and returned. In the examples above, the contractions happen
+in a "left-to-right" fashion, meaning that the left-most component in the circuit (``state``)
+is contracted with the one in its right (``gate``), and finally the resulting component is
+contracted with the projector. This provides a simple and convenient way to run simulations,
+but for large circuits, different contraction paths may be more efficient.
+
+The ``path`` attribute of ``Circuit``\s allows customising the contraction order and potentially
+speeding up the simulation. When a ``path`` of the type ``[(i, j), (l, m), ...]`` is given, the
+simulator creates a dictionary of the type ``{0: c0, ..., N: cN}``, where ``[c0, .., cN]``
+is the ``circuit.component`` list. Then:
+
+* The two components ``ci`` and ``cj`` in positions ``i`` and ``j`` are contracted. ``ci`` is
+  replaced by the resulting component ``cj >> cj``, while ``cj`` is popped.
+* The two components ``cl`` and ``cm`` in positions ``l`` and ``m`` are contracted. ``cl`` is
+  replaced by the resulting component ``cl >> cm``, while ``cm`` is popped.
+* Et cetera.
+
+Below is an example where a circuit is simulated in a "right-to-left" fashion:
+
+.. code-block::
+
+    >>> from mrmustard.lab_dev import *
+    >>> import numpy as np
+
+    >>> state = Number(modes=[0, 1], n=[2, 0], cutoffs=2)
+    >>> gate = BSgate([0, 1], theta=np.pi/4)
+    >>> proj01 = Number(modes=[0, 1], n=[2, 0]).dual
+
+    >>> # initialize the circuit and specify a custom path
+    >>> circuit = Circuit([state, gate, proj01])
+    >>> circuit.path = [(1, 2), (0, 1)]
+
+    >>> result = Simulator().run(circuit)
+
+The setter for ``path`` also validates the path using the ``validate_path`` function of
+``Circuit``.
 """
 
 from __future__ import annotations

mrmustard/lab_dev/states/__init__.py

@@ -60,8 +60,8 @@
         >>> assert dm.representation.c.shape == (1,)
 
 In addition to providing these built-in states, Mr Mustard allows initializing custom
-:class:`~mrmustard.lab_dev.states.Ket`\s and :class:`~mrmustard.lab_dev.states.DM`\s via the
-appropriate constructors. The snippet belowe shows how to initialize a ``Ket`` from
+:class:`~mrmustard.lab_dev.states.Ket`\s and :class:`~mrmustard.lab_dev.states.DM`\s with the
+desired representation. The snippet belowe shows how to initialize a ``Ket`` from
 the Bargmann triple of the squeezed vacuum state. Analogous methods exist to initialize
 ``Ket``\s and ``DM``\s from Fock arrays and from quadrature.
 
@@ -71,13 +71,12 @@
         >>> from mrmustard.lab_dev.transformations import Sgate
         >>> from mrmustard.physics import triples
 
-        >>> # write the A, b, c
+        >>> # the A, b, c triple of the squeezed vacuum state
         >>> A, b, c = triples.squeezed_vacuum_state_Abc(r=0.8)
 
-        >>> # use it to generate a ``Ket``
+        >>> # use the tripls to generate a ``Ket``
         >>> my_ket = Ket.from_bargmann(modes=[0], triple=(A, b, c), name="my_ket")
 
-        >>> # let's check
         >>> assert my_ket == Vacuum([0]) >> Sgate([0], r=0.8)
         >>> assert my_ket == SqueezedVacuum([0], r=0.8)
 

mrmustard/lab_dev/transformations/__init__.py

@@ -12,8 +12,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-The classes representing transformations in quantum circuits.
+r"""
+The avaliable transformation.
+
+As for states, Mr Mustard provides a range of built-in transformations, such as:
+
+    .. code-block::
+
+        >>> from mrmustard.lab_dev.states import Dgate, Sgate, Attenuator
+
+        >>> # the displacement gate
+        >>> dgate = Dgate(modes=[0], x=1)
+
+        >>> # the squeezing gate
+        >>> sgate = Sgate(modes=[1, 2], r=0.8)
+
+        >>> # the attenuator channel
+        >>> att = Attenuator(modes=[3], eta=0.9)
+
+All these transformations are of one of two types, namely :class:`~mrmustard.lab_dev.transformations.Unitary` or
+:class:`~mrmustard.lab_dev.transformations.Channel`.
 """
 
 from .base import *