Tutorials for lab_dev and physics

.github/CHANGELOG.md

@@ -427,7 +427,7 @@ cutoff of the first detector is equal to 1, the resulting density matrix is now
 
   ```python
   from mrmustard.lab import Vacuum, Dgate, Ggate
-  from mrmustard.physics import fidelity
+  from mrmustard.physics.utils import fidelity
   from mrmustard.training.trainer import map_trainer
 
   def make_circ(x=0.):

README.md

@@ -248,7 +248,7 @@ We can turn any simulation in Mr Mustard into an optimization by marking which p
 ```python
 from mrmustard import math
 from mrmustard.lab import Dgate, Ggate, Attenuator, Vacuum, Coherent, DisplacedSqueezed
-from mrmustard.physics import fidelity
+from mrmustard.physics.utils import fidelity
 from mrmustard.training import Optimizer
 
 math.change_backend("tensorflow")

doc/code/lab_dev.rst

@@ -1,14 +1,19 @@
 mrmustard.lab_dev
 =================
 
+.. currentmodule:: mrmustard.lab_dev
+
+.. automodapi:: mrmustard.lab_dev
+    :no-heading:
+    :include-all-objects:
+
 .. toctree::
     :maxdepth: 1
 
     lab_dev/wires
     lab_dev/circuit_components
+    lab_dev/circuit_components_utils
     lab_dev/states
     lab_dev/transformations
     lab_dev/circuits
     lab_dev/simulator
-
-.. currentmodule:: mrmustard.lab_dev

doc/code/lab_dev/circuit_components_utils.rst

@@ -0,0 +1,8 @@
+mrmustard.lab_dev.circuit_components_utils
+==========================================
+
+.. currentmodule:: mrmustard.lab_dev.circuit_components_utils
+
+.. automodapi:: mrmustard.lab_dev.circuit_components_utils
+    :no-heading:
+    :include-all-objects:

doc/code/physics.rst

@@ -1,22 +1,15 @@
 mrmustard.physics
 =================
 
+.. currentmodule:: mrmustard.physics
+
+.. automodapi:: mrmustard.physics
+    :no-heading:
+    :include-all-objects:
+
 .. toctree::
     :maxdepth: 1
 
     physics/ansatze
     physics/representations
-    physics/converters
-
-.. toctree::
-    :maxdepth: 1
-
-    physics/bargmann
-    physics/utils/fock_calculations
-    physics/utils/gaussian_calculations
-
-.. currentmodule:: mrmustard.physics
-
-.. automodapi:: mrmustard.physics
-    :no-heading:
-    :include-all-objects:
+    physics/converters

doc/code/physics/ansatze.rst

@@ -1,4 +1,4 @@
-The representations' Ansatze
+The Ansatze of the representation
 ============================
 
 .. currentmodule:: mrmustard.physics.ansatze

doc/code/physics/bargmann.rst

@@ -1,9 +1,14 @@
-Calculations on Bargmann objects
-================================
+The Bargmann representation theory
+==========================================
+.. currentmodule:: mrmustard.physics.bargmann
+
+.. automodapi:: mrmustard.physics.bargmann
+    :no-heading:
+    :include-all-objects:
 
 .. toctree::
     :maxdepth: 1
 
     utils/triples
-    utils/bargmann_calculations
     utils/gaussian_integral
+

doc/code/physics/converters.rst

@@ -1,6 +1,5 @@
-The Converters between different Representations
+The converters between different representations
 ==========================================
-
 .. currentmodule:: mrmustard.physics.converters
 
 .. automodapi:: mrmustard.physics.converters

doc/code/physics/fock.rst

@@ -0,0 +1,10 @@
+The Fock representation theory
+==========================================
+
+.. currentmodule:: mrmustard.physics.fock
+
+.. automodapi:: mrmustard.physics.fock
+    :no-heading:
+    :include-all-objects:
+
+This section of functions is the helper function section to calculate properties of object in Fock representation, which needs to be rearranged and possibly be moved under Fock representation class.

doc/code/physics/representations.rst

@@ -1,8 +1,14 @@
-The Fock-Bargmann and Fock Representations
+The representations of quantum objects
 ==========================================
 
 .. currentmodule:: mrmustard.physics.representations
 
 .. automodapi:: mrmustard.physics.representations
     :no-heading:
-    :include-all-objects:
+    :include-all-objects:
+
+.. toctree::
+    :maxdepth: 1
+
+    bargmann
+    fock

doc/code/physics/utils/gaussian_integral.rst

@@ -1,5 +1,5 @@
 Calculations on Gaussian Integrals
-================================
+==================================
 
 .. currentmodule:: mrmustard.physics.gaussian_integrals
 

doc/development/development_guide.rst

@@ -38,7 +38,7 @@ The ``-e`` flag ensures that edits to the source code will be reflected when
 importing Mr Mustard in Python.
 
 Increased numerical stability using Julia [optional]
-------------------
+----------------------------------------------------
 Converting phase space objects to Fock space can be numerically unstable due to accumulating floating point errors.
 To resolve this, the conversion can be performed with extended-precision arithmetic. To use this feature,
 an installation of `Julia <https://github.com/JuliaLang/juliaup#installation>`_ is required (version 1.9.3 recommended).

doc/introduction/basic_reference.md

@@ -205,7 +205,7 @@ displaced squeezed state.
 ```python
 from mrmustard import math
 from mrmustard.lab import Dgate, Ggate, Attenuator, Vacuum, Coherent, DisplacedSqueezed
-from mrmustard.physics import fidelity
+from mrmustard.physics.utils import fidelity
 from mrmustard.training import Optimizer
 
 math.change_backend("tensorflow")

mrmustard/lab/abstract/state.py

@@ -387,7 +387,7 @@ def primal(self, other: Union[State, Transformation]) -> State:
         ``self``: ``other << self`` is like ``self >> other^dual``.
 
         Note that the returned state is not normalized. To normalize a state you can use
-        ``mrmustard.physics.normalize``.
+        ``mrmustard.physics.utils.normalize``.
         """
         # import pdb
 

mrmustard/lab_dev/__init__.py

@@ -13,13 +13,117 @@
 # limitations under the License.
 
 r"""
-The lab module in development.
-"""
+The :mod:`~mrmustard.lab_dev` module contains all the objects that would normally be found in a photonic lab, such as:
+
+* Several useful states, such as :class:`~mrmustard.lab_dev.states.Vacuum`,
+  :class:`~mrmustard.lab_dev.states.Coherent`, and :class:`~mrmustard.lab_dev.states.SqueezedVacuum`.
+
+* The gates routinely performed in optical experiments, including
+  :class:`~mrmustard.lab_dev.transformations.Dgate`, :class:`~mrmustard.lab_dev.transformations.Sgate`,
+  and :class:`~mrmustard.lab_dev.transformations.BSgate`.
+
+* Typical noise channels such as the :class:`~mrmustard.lab_dev.transformations.Attenuator`.
+
+* Detectors (currently in development).
+
+Additionally, it enables users to initialize custom states, gates, channels, and measurements.
+
+The ``>>`` operator allows combining these objects together with intuitive, paper-style syntax.
+
+.. code-block::
+
+    >>> from mrmustard.lab_dev import *
+    >>> from mrmustard import settings
+    >>> import numpy as np
+
+    >>> settings.AUTOCUTOFF_MAX_CUTOFF = 40
+
+    >>> # initialize three single-mode states with one, zero, and zero photons, respectively
+    >>> s0 = Number(modes=[0], n=1)
+    >>> s1 = Number(modes=[1], n=0)
+    >>> s2 = Number(modes=[2], n=0)
+
+    >>> # initialize 50/50 beam splitters between modes (0, 1) and (1, 2)
+    >>> bs01 = BSgate(modes=[0, 1], theta=np.pi/4)
+    >>> bs12 = BSgate(modes=[1, 2], theta=np.pi/4)
+
+    >>> # simulate the result of an experiment where the three states are sent through
+    >>> # the beam splitters
+    >>> result = s0 >> s1 >> s2 >> bs01 >> bs12
+
+    >>> # calculate expectation values on the resulting state
+    >>> assert np.allclose(result.expectation(Number(modes=[0], n=0)), 0.5)
+    >>> assert np.allclose(result.expectation(Number(modes=[0], n=1)), 0.5)
+    >>> assert np.allclose(result.expectation(Number(modes=[0], n=2)), 0)
+    >>> assert np.allclose(result.expectation(Number(modes=[0, 1, 2], n=[0, 1, 0])), 0.25)
+
+While :mod:`~mrmustard.lab_dev` is designed to be intuitive and easy to use, proficient users can take advantage
+of several features to speed up their computations. For example, using
+:class:`~mrmustard.lab_dev.circuits.Circuit`\s and the :class:`~mrmustard.lab_dev.simulator.Simulator`,
+they can take advantage of built-in tensor network functionality to run circuits more efficiently.
+
+.. code-block::
+
+    >>> from mrmustard.lab_dev import *
+    >>> from mrmustard import settings
+    >>> import numpy as np
+
+    >>> settings.AUTOCUTOFF_MAX_CUTOFF = 40
+
+    >>> # initialize three single-mode states with one, zero, and zero photons, respectively
+    >>> s0 = Number(modes=[0], n=1)
+    >>> s1 = Number(modes=[1], n=0)
+    >>> s2 = Number(modes=[2], n=0)
+
+    >>> # initialize 50/50 beam splitters between modes (0, 1) and (1, 2)
+    >>> bs01 = BSgate(modes=[0, 1], theta=np.pi/4)
+    >>> bs12 = BSgate(modes=[1, 2], theta=np.pi/4)
+
+    >>> # initialize projectors for modes 1 and 2
+    >>> p1 = Number(modes=[1], n=0).dual
+    >>> p2 = Number(modes=[2], n=0).dual
+
+    >>> # initialize a circuit
+    >>> circ = Circuit([s0, s1, s2, bs01, bs12, p1, p2])
+
+    >>> # specify a "contraction path" for the circuit above -- i.e., in what order you'd
+    >>> # like to combine its components via ``>>``
+    >>> circ.path = [(4, 5), (4, 6), (2, 4), (0, 3), (1, 0), (1, 2)]
+
+    >>> # run the circuit -- the `Simulator` will follow the circuit's path
+    >>> result = Simulator().run(circ)
+    >>> assert result == s0 >> s1 >> s2 >> bs01 >> bs12 >> p1 >> p2
+
+    >>> # every path leads to the same result, but some paths are faster than others.
+    >>> # for example, selecting this path leads to a simulation time of about 17ms on a
+    >>> # typical laptop ...
+    >>> circ.path = [(4, 5), (4, 6), (2, 4), (0, 3), (1, 0), (1, 2)]
+    >>> assert result == Simulator().run(circ)
+
+    >>> # ... while with this path, the simulation time drops to about 7ms.
+    >>> circ.path = [(0, 1), (0, 2), (0, 3), (0, 4), (0, 5), (0, 6)]
+    >>> assert result == Simulator().run(circ)
+
+Check out our guides to learn more about :mod:`~mrmustard.lab_dev` and its core functionalities:
+
+* The :mod:`~mrmustard.lab_dev.circuit_components` guide introduces the
+  :class:`~mrmustard.lab_dev.circuit_components.CircuitComponent` class, which is the parent of
+  every state, gate, channel, and measurement object in :mod:`~mrmustard.lab_dev`.
+* The :mod:`~mrmustard.lab_dev.states` guide illustrates how to initialize states.
+* The :mod:`~mrmustard.lab_dev.transformations` guide shows how to initialize unitary gates and
+  channels.
+* :mod:`~mrmustard.lab_dev.circuits` tells you everything you need to know about circuits.
+* The :mod:`~mrmustard.lab_dev.simulator` page shows how to use the simulator object and discusses
+  how to select the best paths for your circuits.
+* For more advanced functionality, take a look at the :mod:`~mrmustard.lab_dev.circuit_components`
+  module, which contains a series of maps (e.g., the trace-out operation) expressed as circuit
+  components.
+  """
 
 from .circuit_components import *
 from .circuit_components_utils import *
 from .circuits import *
 from .states import *
 from .simulator import *
 from .transformations import *
-from .wires import Wires
+from .wires import *