diff --git a/src/bloqade/submission/braket.py b/src/bloqade/submission/braket.py index 02e58d511..186965542 100644 --- a/src/bloqade/submission/braket.py +++ b/src/bloqade/submission/braket.py @@ -1,3 +1,6 @@ +"""Module for `BraketBackend` which represents the functionalities +needed for executing programs on Braket backend""" + import warnings from bloqade.submission.base import SubmissionBackend from bloqade.submission.ir.braket import ( @@ -19,11 +22,23 @@ class BraketBackend(SubmissionBackend): + """Class representing the functionalities needed for executing + programs on Braket backend. + + Attributes: + device_arn (str): AWS arn for quantum program execution. + Defaults to `"arn:aws:braket:us-east-1::device/qpu/quera/Aquila"` + """ + device_arn: str = "arn:aws:braket:us-east-1::device/qpu/quera/Aquila" _device: Optional[AwsDevice] = PrivateAttr(default=None) @property def device(self) -> AwsDevice: + """`AwsDevice`: Amazon Braket implementation of a device. Use this class to + retrieve the latest metadata about the device and to run a quantum task + on the device. + """ if self._device is None: self._device = AwsDevice(self.device_arn) user_agent = f"Bloqade/{bloqade.__version__}" @@ -32,6 +47,16 @@ def device(self) -> AwsDevice: return self._device def get_capabilities(self, use_experimental: bool = False) -> QuEraCapabilities: + """Get the capabilities of the QuEra backend. + + Args: + use_experimental (bool): Whether to use experimental capabilities of + the backend system. Defaults to `False`. + + Returns: + capabilities (`QuEraCapabilities`): capabilities + of the selected QuEra backend. + """ from botocore.exceptions import BotoCoreError, ClientError if use_experimental: @@ -53,20 +78,74 @@ def get_capabilities(self, use_experimental: bool = False) -> QuEraCapabilities: return super().get_capabilities() def submit_task(self, task_ir: QuEraTaskSpecification) -> str: + """Submit the task to the Braket backend. It converts task + IR of the QuEra system to suitable format + accepted by Braket. + + Args: + task_ir (QuEraTaskSpecification): task IR suitable for QuEra backend. + It will be converted to appropriate IR accepted by Braket backend. + + Returns: + task_id (str): Task id as a result of executing + IR on the Braket backend. + """ shots, ahs_program = to_braket_task(task_ir) task = self.device.run(ahs_program, shots=shots) return task.id def task_results(self, task_id: str) -> QuEraTaskResults: + """Get the result of a task previously submitted by using the + task id of Braket backend. + + Args: + task_id (str): task id after executing program on the Braket backend. + + Returns: + task_result (`QuEraTaskResults`): Gets the task result a task + previously submitted using task id of the Braket backend. + + Note: + This is a blocking call, meaning the function will not + return till the task has stopped. + """ return from_braket_task_results(AwsQuantumTask(task_id).result()) def cancel_task(self, task_id: str) -> None: + """Cancels a task previously submitted to the Braket backend. + + Args: + task_id (str): task id after executing program on the Bracket backend. + """ AwsQuantumTask(task_id).cancel() def task_status(self, task_id: str) -> QuEraTaskStatusCode: + """Get the status of a task previously submitted by using + the task id of Braket backend. + + Args: + task_id (str): task id after executing program on the Braket backend. + + Returns: + status_code (QuEraTaskStatusCode): Task status by using the task id + of of a task previously submitted to the Braket backend. + """ return from_braket_status_codes(AwsQuantumTask(task_id).state()) def validate_task(self, task_ir: QuEraTaskSpecification): + """Validates the task submitted to the QuEra backend. + + Args: + task_ir (QuEraTaskSpecification): task IR suitable for + QuEra backend. It will be converted to appropriate + IR accepted by Braket backend. + + Raises: + ValidationError: For tasks that fail validation. + + Note: + Currently, it's a no-op. + """ pass # def validate_task(self, task_ir: QuEraTaskSpecification):