Builder docstrings

src/bloqade/builder/backend/__init__.py

@@ -4,6 +4,19 @@
 
 
 class BackendRoute(QuEraService, BraketService, BloqadeService):
+    """
+    Specify the backend to run your program on via a string
+    (versus more formal builder syntax) of specifying the vendor/product first
+    (Bloqade/Braket) and narrowing it down
+    (e.g: ...device("quera.aquila") versus ...quera.aquila())
+    - You can pass the following arguments:
+        - `"braket.aquila"`
+        - `"braket.local_emulator"`
+        - `"bloqade.python"`
+        - `"bloqade.julia"`
+
+    """
+
     def device(self, name: str, *args, **kwargs):
         if name == "quera.aquila":
             dev = self.quera.aquila

src/bloqade/builder/backend/bloqade.py

@@ -5,26 +5,24 @@ class BloqadeService(Builder):
     @property
     def bloqade(self):
         """
-        - Specify bloqade emulator
-        - Possible Next:
+        Specify the Bloqade backend.
 
-            -> `...bloqade.python`
-                :: Bloqade python backend
-
-            -> `...bloqade.julia`
-                :: Bloqade julia backend
+        - Possible Next Steps:
+            - `...bloqade.python()`: target submission to the Bloqade python backend
+            - `...bloqade.julia()`: (CURRENTLY NOT IMPLEMENTED!)target
+                submission to the Bloqade.jl backend
         """
         return BloqadeDeviceRoute(self)
 
 
 class BloqadeDeviceRoute(Builder):
     def python(self):
         """
-        - Specify bloqade python backend
-        - Possible Next:
+        Specify the Bloqade Python backend.
 
-            -> `...python().run(shots, ...)`
-                :: Run the current program using bloqade python backend
+        - Possible Next Steps:
+            - `...python().run(shots)`:
+                to submit to the python emulator and await results
         """
         return self.parse().bloqade.python()
 

src/bloqade/builder/backend/braket.py

@@ -5,54 +5,49 @@ class BraketService(Builder):
     @property
     def braket(self):
         """
-        - Specify braket service
-        - Possible Next:
+        Specify the Braket backend. This allows you to access the AWS Braket local
+        emulator OR go submit things to QuEra hardware on AWS Braket service.
 
-            -> `...braket.aquila`
-                :: Aquila QPU, via braket service
-
-            -> `...braket.local_emulator`
-                :: braket local emulator backend
+        - Possible Next Steps are:
+            - `...braket.aquila()`: target submission to the QuEra Aquila QPU
+            - `...braket.local_emulator()`: target submission to the Braket
+            local emulator
         """
         return BraketDeviceRoute(self)
 
 
 class BraketDeviceRoute(Builder):
     def aquila(self):
         """
-        Specify QuEra's Aquila QPU
-
-        Return:
-            BraketHardwareRoutine
-
-        - Possible Next:
-
-            -> `...aquila().submit`
-                :: submit aync remote job
+        Specify QuEra's Aquila QPU on Braket to submit your program to.
 
-            -> `...aquila().run`
-                :: submit job and wait until job finished
-                and results returned
+        The number of shots you specify in the subsequent `.run` method will either:
+            - dictate the number of times your program is run
+            - dictate the number of times per parameter your program is run if
+              you have a variable with batch assignments/intend to conduct
+              a parameter sweep
 
-            -> `...aquila().__callable__`
-                :: submit job and wait until job finished
-                and results returned
 
+        - Possible next steps are:
+            - `...aquila().run(shots)`: To submit to hardware and WAIT for
+                results (blocking)
+            - `...aquila().run_async(shots)`: To submit to hardware and immediately
+                allow for other operations to occur
         """
         return self.parse().braket.aquila()
 
     def local_emulator(self):
         """
-        Using Braket local emulator
-
-        Return:
-            BraketLocalEmulatorRoutine
-
-
-        - Possible Next:
-
-            -> `...local_emulator().run`
-                :: run on local emulator
+        Specify the Braket local emulator to submit your program to.
+
+        - The number of shots you specify in the subsequent `.run` method will either:
+            - dictate the number of times your program is run
+            - dictate the number of times per parameter your program is run if
+              you have a variable with batch assignments/intend to
+              conduct a parameter sweep
+        - Possible next steps are:
+            - `...local_emulator().run(shots)`: to submit to the emulator
+                and await results
 
         """
         return self.parse().braket.local_emulator()

src/bloqade/builder/coupling.py

@@ -4,20 +4,28 @@
 
 class LevelCoupling(Builder):
     @property
-    def detuning(self) -> Detuning:
+    def detuning(
+        self,
+    ) -> Detuning:  # field is summation of one or more drives,
+        # waveform + spatial modulation = drive
         """
-        - Specify the Detuning field
-        - Next-step: <SpacialModulation>
-        - Possible Next:
+        Specify the [`Detuning`][bloqade.builder.field.Detuning]
+         [`Field`][bloqade.builder.Field] of your program.
 
-            -> `...detuning.location(int)`
-                :: Address atom at specific location
+        A "field" is a summation of one or more "drives", with a drive being the sum
+        of a waveform and spatial modulation.
 
-            -> `...detuning.uniform`
-                :: Address all atoms in register
+        You are currently building the spatial modulation component and will be
+        able to specify a waveform.
 
-            -> `...detuning.var(str)`
-                :: Address atom at location labeled by variable
+        - You can do this by:
+            - `...detuning.uniform`: To address all atoms in the field
+            - `...detuning.location(int)`: To address an atom at a specific
+                location via index
+            - `...detuning.var(str)`
+                - To address an atom at a specific location via variable
+                - To address multiple atoms at specific locations by specifying
+                    a single variable and then assigning it a list of coordinates
 
         """
 
@@ -26,15 +34,16 @@ def detuning(self) -> Detuning:
     @property
     def rabi(self) -> Rabi:
         """
-        - Specify the Rabi term/field.
-        - Possible Next:
+        Specify the complex-valued [`Rabi`][bloqade.builder.field.Rabi]
+        field of your program.
 
-            -> `...rabi.amplitude`
-                :: address rabi amplitude
-
-            -> `...rabi.phase`
-                :: address rabi phase
+        The Rabi field is composed of a real-valued Amplitude and Phase field.
 
+        - Next possible steps to build your program are
+          creating the [`RabiAmplitude`][bloqade.builder.field.RabiAmplitude] field
+          and [`RabiPhase`][bloqade.builder.field.RabiAmplitude] field of the field:
+            - `...rabi.amplitude`: To create the Rabi amplitude field
+            - `...rabi.phase`: To create the Rabi phase field
 
         """
 

src/bloqade/builder/drive.py

@@ -5,59 +5,28 @@ class Drive:
     @property
     def rydberg(self) -> Rydberg:
         """
-        - Specify the Rydberg level coupling.
-        - Possible Next:
-
-            -> `...rydberg.rabi`
-                :: address rabi term
-
-            -> `...rydberg.detuning`
-                :: address detuning field
-
-        Examples:
-            >>> node = bloqade.start.rydberg
-            >>> type(node)
-            <class 'bloqade.builder.coupling.Rydberg'>
-
-            - Rydberg level coupling have two reachable field nodes:
-
-                - detuning term (See also [`Detuning`][bloqade.builder.field.Detuning])
-                - rabi term (See also [`Rabi`][bloqade.builder.field.Rabi])
-
-            >>> ryd_detune = bloqade.start.rydberg.detuning
-            >>> ryd_rabi = bloqade.start.rydberg.rabi
-
-        See [`Rydberg`][bloqade.builder.coupling.Rydberg] for more details.
+        Address the Rydberg level coupling in your program.
+
+        - Next possible steps to build your program are specifying the
+          [`Rabi`][bloqade.builder.field.Rabi] field or
+          [`Detuning`][bloqade.builder.field.Detuning] field.
+            - `...rydberg.rabi`: for Rabi field
+            - `...rydberg.detuning`: for Detuning field
+        - In the absence of a field you the value is set to zero by default.
         """
         return Rydberg(self)
 
     @property
     def hyperfine(self) -> Hyperfine:
         """
-        - Specify the Hyperfile level coupling.
-        - Possible Next:
-
-            -> `...hyperfine.rabi`
-                :: address rabi term
-
-            -> `...hyperfine.detuning`
-                :: address detuning field
-
-
-        Examples:
-            >>> node = bloqade.start.hyperfine
-            >>> type(node)
-            <class 'bloqade.builder.coupling.Hyperfine'>
-
-            - Hyperfine level coupling have two reachable field nodes:
-
-                - detuning term (See also [`Detuning`][bloqade.builder.field.Detuning])
-                - rabi term (See also [`Rabi`][bloqade.builder.field.Rabi])
-
-            >>> hyp_detune = bloqade.start.hyperfine.detuning
-            >>> hyp_rabi = bloqade.start.hyperfine.rabi
+        Address the Hyperfine level coupling in your program.
 
+        - Next possible steps to build your program are specifying the
+          [`Rabi`][bloqade.builder.field.Rabi] field or
+          [`Detuning`][bloqade.builder.field.Detuning] field.
+            - `...hyperfine.rabi`: for Rabi field
+            - `...hyperfine.detuning`: for Detuning field
+        - In the absence of a field you the value is set to zero by default.
 
-        See [Hyperfine][bloqade.builder.coupling.Hyperfine] for more details.
         """
         return Hyperfine(self)