Khwu/docs alpha

src/bloqade/builder/backend/bloqade.py

@@ -4,6 +4,16 @@
 class BloqadeService(Builder):
     @property
     def bloqade(self):
+        """
+        - Specify bloqade emulator
+        - Possible Next:
+
+            -> `...bloqade.python`
+                :: Bloqade python backend
+
+            -> `...bloqade.julia`
+                :: Bloqade julia backend
+        """
         return BloqadeDeviceRoute(self)
 
 

src/bloqade/builder/backend/braket.py

@@ -4,16 +4,59 @@
 class BraketService(Builder):
     @property
     def braket(self):
+        """
+        - Specify braket service
+        - Possible Next:
+
+            -> `...braket.aquila`
+                :: Aquila QPU, via braket service
+
+            -> `...braket.local_emulator`
+                :: braket local emulator backend
+        """
         return BraketDeviceRoute(self)
 
 
 class BraketDeviceRoute(Builder):
     def aquila(self):
+        """
+        Specify QuEra's Aquila QPU
+
+        Return:
+            BraketHardwareRoutine
+
+        - Possible Next:
+
+            -> `...aquila().submit`
+                :: submit aync remote job
+
+            -> `...aquila().run`
+                :: submit job and wait until job finished
+                and results returned
+
+            -> `...aquila().__callable__`
+                :: submit job and wait until job finished
+                and results returned
+
+        """
         from bloqade.ir.routine.base import Routine
 
         return Routine(self).braket.aquila()
 
     def local_emulator(self):
+        """
+        Using Braket local emulator
+
+        Return:
+            BraketLocalEmulatorRoutine
+
+
+        - Possible Next:
+
+            -> `...local_emulator().run`
+                :: run on local emulator
+
+        """
         from bloqade.ir.routine.base import Routine
 
         return Routine(self).braket.local_emulator()

src/bloqade/builder/backend/quera.py

@@ -4,26 +4,130 @@
 class QuEraService(Builder):
     @property
     def quera(self):
+        """
+        - Specify Quera backend
+        - Possible Next:
+
+            -> `...quera.aquila`
+                :: Aquila QPU
+
+            -> `...quera.mock`
+                :: mock backend, meant for testings
+
+            -> `...quera.device`
+                :: QuEra QPU, specifiy by config_file
+
+        """
         return QuEraDeviceRoute(self)
 
 
 class QuEraDeviceRoute(Builder):
     def device(self, config_file: str | None = None, **api_config):
+        """
+        Specify QuEra's QPU device,
+
+        Args:
+            config_file (str): file that speficy the target hardware
+
+        Return:
+            QuEraHardwareRoutine
+
+        - Possible Next:
+
+            -> `...device().submit`
+                :: submit aync remote job
+
+            -> `...device().run`
+                :: submit job and wait until job finished
+                and results returned
+
+            -> `...device().__callable__`
+                :: submit job and wait until job finished
+                and results returned
+
+
+        """
         from bloqade.ir.routine.base import Routine
 
         return Routine(self).quera.device(config_file, **api_config)
 
     def aquila(self):
+        """
+        Specify QuEra's Aquila QPU
+
+        Return:
+            QuEraHardwareRoutine
+
+
+        - Possible Next:
+
+            -> `...aquila().submit`
+                :: submit aync remote job
+
+            -> `...aquila().run`
+                :: submit job and wait until job finished
+                and results returned
+
+            -> `...aquila().__callable__`
+                :: submit job and wait until job finished
+                and results returned
+
+
+        """
         from bloqade.ir.routine.base import Routine
 
         return Routine(self).quera.aquila()
 
     def cloud_mock(self):
+        """
+        Specify QuEra's Remote Mock QPU
+
+        Return:
+            QuEraHardwareRoutine
+
+        - Possible Next:
+
+            -> `...aquila().submit`
+                :: submit aync remote job
+
+            -> `...aquila().run`
+                :: submit job and wait until job finished
+                and results returned
+
+            -> `...aquila().__callable__`
+                :: submit job and wait until job finished
+                and results returned
+
+
+
+        """
         from bloqade.ir.routine.base import Routine
 
         return Routine(self).quera.cloud_mock()
 
     def mock(self, state_file: str = ".mock_state.txt"):
+        """
+        Specify mock, testing locally.
+
+        Return:
+            QuEraHardwareRoutine
+
+        - Possible Next:
+
+            -> `...aquila().submit`
+                :: submit aync remote job
+
+            -> `...aquila().run`
+                :: submit job and wait until job finished
+                and results returned
+
+            -> `...aquila().__callable__`
+                :: submit job and wait until job finished
+                and results returned
+
+
+
+        """
         from bloqade.ir.routine.base import Routine
 
         return Routine(self).quera.mock(state_file)

src/bloqade/ir/routine/braket.py

@@ -32,6 +32,20 @@ def compile(
         args: Tuple[Real, ...] = (),
         name: str | None = None,
     ) -> RemoteBatch:
+        """
+        Compile to a RemoteBatch, which contain
+            Braket backend specific tasks.
+
+        Args:
+            shots (int): number of shots
+            args (Tuple): additional arguments
+            name (str): custom name of the batch
+
+        Return:
+            RemoteBatch
+
+        """
+
         ## fall passes here ###
         from bloqade.codegen.common.assign_variables import AssignAnalogCircuit
         from bloqade.codegen.common.assignment_scan import AssignmentScan
@@ -73,6 +87,24 @@ def submit(
         shuffle: bool = False,
         **kwargs,
     ) -> RemoteBatch:
+        """
+        Compile to a RemoteBatch, which contain
+        Braket backend specific tasks, and submit to Braket.
+
+        Note:
+            This is async.
+
+        Args:
+            shots (int): number of shots
+            args (Tuple): additional arguments
+            name (str): custom name of the batch
+            shuffle (bool): shuffle the order of jobs
+
+        Return:
+            RemoteBatch
+
+        """
+
         batch = self.compile(shots, args, name)
         batch._submit(shuffle, **kwargs)
         return batch
@@ -85,6 +117,26 @@ def run(
         shuffle: bool = False,
         **kwargs,
     ) -> RemoteBatch:
+        """
+        Compile to a RemoteBatch, which contain
+        Braket backend specific tasks, submit to Braket,
+        and wait until the results are coming back.
+
+        Note:
+            This is sync, and will wait until remote results
+            finished.
+
+        Args:
+            shots (int): number of shots
+            args (Tuple): additional arguments
+            name (str): custom name of the batch
+            shuffle (bool): shuffle the order of jobs
+
+        Return:
+            RemoteBatch
+
+        """
+
         batch = self.submit(shots, args, name, shuffle, **kwargs)
         batch.pull()
         return batch
@@ -97,6 +149,25 @@ def __call__(
         shuffle: bool = False,
         **kwargs,
     ):
+        """
+        Compile to a RemoteBatch, which contain
+        Braket backend specific tasks, submit to Braket,
+        and wait until the results are coming back.
+
+        Note:
+            This is sync, and will wait until remote results
+            finished.
+
+        Args:
+            shots (int): number of shots
+            args: additional arguments for flatten variables.
+            name (str): custom name of the batch
+            shuffle (bool): shuffle the order of jobs
+
+        Return:
+            RemoteBatch
+
+        """
         return self.run(shots, args, name, shuffle, **kwargs)
 
 
@@ -105,6 +176,18 @@ class BraketLocalEmulatorRoutine(RoutineBase):
     def compile(
         self, shots: int, args: Tuple[Real, ...] = (), name: str | None = None
     ) -> LocalBatch:
+        """
+        Compile to a LocalBatch, which contain tasks to run on local emulator.
+
+        Args:
+            shots (int): number of shots
+            args: additional arguments for flatten variables.
+            name (str): custom name for the batch
+
+        Return:
+            LocalBatch
+
+        """
         ## fall passes here ###
         from bloqade.ir import ParallelRegister
         from bloqade.codegen.common.assign_variables import AssignAnalogCircuit
@@ -149,6 +232,25 @@ def run(
         num_workers: int | None = None,
         **kwargs,
     ) -> LocalBatch:
+        """
+        Compile to a LocalBatch, and run.
+        The LocalBatch contain tasks to run on local emulator.
+
+        Note:
+            This is sync, and will wait until remote results
+            finished.
+
+        Args:
+            shots (int): number of shots
+            args: additional arguments for flatten variables.
+            multiprocessing (bool): enable multi-process
+            num_workers (int): number of workers to run the emulator
+
+        Return:
+            LocalBatch
+
+        """
+
         batch = self.compile(shots, args, name)
         batch._run(multiprocessing=multiprocessing, num_workers=num_workers, **kwargs)
         return batch

src/bloqade/ir/routine/quera.py

@@ -47,7 +47,21 @@ def compile(
         args: Tuple[Real, ...] = (),
         name: str | None = None,
     ) -> RemoteBatch:
+        """
+        Compile to a RemoteBatch, which contain
+            QuEra backend specific tasks.
+
+        Args:
+            shots (int): number of shots
+            args (Tuple): additional arguments
+            name (str): custom name of the batch
+
+        Return:
+            RemoteBatch
+
+        """
         from bloqade.codegen.common.assign_variables import AssignAnalogCircuit
+
         from bloqade.codegen.common.assignment_scan import AssignmentScan
         from bloqade.codegen.hardware.quera import QuEraCodeGen
 
@@ -81,6 +95,21 @@ def submit(
         shuffle: bool = False,
         **kwargs,
     ) -> RemoteBatch:
+        """
+        Compile to a RemoteBatch, which contain
+            QuEra backend specific tasks,
+            and submit through QuEra service.
+
+        Args:
+            shots (int): number of shots
+            args (Tuple): additional arguments
+            name (str): custom name of the batch
+            shuffle (bool): shuffle the order of jobs
+
+        Return:
+            RemoteBatch
+
+        """
         batch = self.compile(shots, args, name)
         batch._submit(shuffle, **kwargs)
         return batch