Adding the sampler to the API reference (pasqal-io#392)

andreabasiliorava · Aug 5, 2022 · d60fc2c · d60fc2c
1 parent 094ab4b
commit d60fc2c
Show file tree

Hide file tree

Showing 7 changed files with 28 additions and 16 deletions.
diff --git a/docs/source/apidoc/creation.rst → docs/source/apidoc/core.rst b/docs/source/apidoc/creation.rst → docs/source/apidoc/core.rst
@@ -1,5 +1,5 @@
 ************************
-Pulse Sequence Creation
+Core Features
 ************************
 
 Sequence
@@ -99,3 +99,13 @@ Channels
 .. automodule:: pulser.channels
    :members:
    :show-inheritance:
+
+
+Sampler
+------------------
+.. automodule:: pulser.sampler.sampler
+   :members:
+
+.. automodule:: pulser.sampler.samples
+   :members:
+
diff --git a/docs/source/apidoc/pulser.rst b/docs/source/apidoc/pulser.rst
@@ -4,5 +4,5 @@ API Reference
 .. toctree::
    :maxdepth: 3
 
-   creation
-   emulation
+   core
+   simulation
diff --git a/docs/source/apidoc/emulation.rst → docs/source/apidoc/simulation.rst b/docs/source/apidoc/emulation.rst → docs/source/apidoc/simulation.rst
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -17,7 +17,7 @@ installed, then use ``pip``: ::
 
 The standard ``pulser`` distribution will install the core ``pulser`` package
 and the ``pulser_simulation`` extension package, which is required if you want
-to access the :doc:`apidoc/emulation` features.
+to access the :doc:`apidoc/simulation` features.
 
 If you wish to install only the core ``pulser`` features, you can instead run: ::
 

diff --git a/pulser-core/pulser/sampler/__init__.py b/pulser-core/pulser/sampler/__init__.py
@@ -12,12 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Module sampler enables the sampling of pulser sequences.
+"""The sampler module enables the sampling of pulser sequences.
 
-Samples of a sequence are needed for plotting and simulation.
-
-  Typical usage:
-
-  sampler.sample(sequence)
+The samples of a sequence are organized in channels and are used for
+plotting and simulation.
 """
 from pulser.sampler.sampler import sample
diff --git a/pulser-core/pulser/sampler/sampler.py b/pulser-core/pulser/sampler/sampler.py
@@ -1,4 +1,4 @@
-"""Defines the main function for sequence sampling."""
+"""The main function for sequence sampling."""
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Optional

diff --git a/pulser-core/pulser/sampler/samples.py b/pulser-core/pulser/sampler/samples.py
@@ -1,4 +1,4 @@
-"""Contains dataclasses for samples and some helper functions."""
+"""Dataclasses for storing and processing the samples."""
 from __future__ import annotations
 
 from collections import defaultdict
@@ -107,7 +107,7 @@ def extend_duration(self, new_duration: int) -> ChannelSamples:
                 Must be greater than or equal to the current duration.
 
         Returns:
-            The extend channel samples.
+            The extended channel samples.
         """
         extension = new_duration - self.duration
         if extension < 0:
@@ -125,7 +125,7 @@ def extend_duration(self, new_duration: int) -> ChannelSamples:
     def is_empty(self) -> bool:
         """Whether the channel is effectively empty.
 
-        We consider the channel to be empty if all amplitude and detuning
+        The channel is considered empty if all amplitude and detuning
         samples are zero.
         """
         return np.count_nonzero(self.amp) + np.count_nonzero(self.det) == 0
@@ -136,7 +136,7 @@ def modulate(
         """Modulates the samples for a given channel.
 
         It assumes that the phase starts at its initial value and is kept at
-        its final value.The same could potentially be done for the detuning,
+        its final value. The same could potentially be done for the detuning,
         but it's not as safe of an assumption so it's not done for now.
 
         Args:
@@ -157,7 +157,7 @@ def modulate(
 
 @dataclass
 class SequenceSamples:
-    """Gather samples of a sequence with useful info."""
+    """Gather samples for each channel in a sequence."""
 
     channels: list[str]
     samples_list: list[ChannelSamples]
@@ -192,6 +192,11 @@ def to_nested_dict(self, all_local: bool = False) -> dict:
         Args:
             all_local: Forces all samples to be distributed by their
                 individual targets, even when applied by a global channel.
+
+        Returns:
+            A nested dictionary splitting the samples according to their
+            addressing ('Global' or 'Local'), the targeted basis
+            and, in the 'Local' case, the targeted qubit.
         """
         bases = {ch_obj.basis for ch_obj in self._ch_objs.values()}
         in_xy = False