From 2fb193e6785c55d004eb65ab1151ebebdf4dd0cd Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Fri, 31 May 2024 20:32:20 -0700 Subject: [PATCH 1/5] Doc --- src/bloqade/submission/braket.py | 70 ++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/src/bloqade/submission/braket.py b/src/bloqade/submission/braket.py index 02e58d511..b50c3d3fe 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,22 @@ 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: + """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 +46,14 @@ 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: + An object to the type `QuEraCapabilities`, representing the capabilities + of the selected QuEra backend. + """ from botocore.exceptions import BotoCoreError, ClientError if use_experimental: @@ -53,20 +75,68 @@ 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(Intermediate Representation) of the QuEra system to suitable format + accepted by Braket. + + Args: + task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + suitable for QuEra backend. It will be converted to appropriate + IR(Intermediate Represetation) accepted by Braket backend + + Returns: + Task id as a result of executing IR(Intermediate Represetation) + 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 the task by using the task id of Braket backend. + + Args: + task_id (str): task id after executing program on the Braket backend. + + Returns: + Task result of the type `QuEraTaskResults` from task id + of the Braket backend. + """ return from_braket_task_results(AwsQuantumTask(task_id).result()) def cancel_task(self, task_id: str) -> None: + """Cancels the task 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 the task submitted by using the task id of Braket backend. + + Args: + task_id (str): task id after executing program on the Braket backend. + + Returns: + Task status of the type `QuEraTaskStatusCode` by using the task id + of 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(Intermediate Represetation) + suitable for QuEra backend. It will be converted to appropriate + IR(Intermediate Representation) accepted by Braket backend. + + Raises: + ValidationError: For tasks that fail validation. + + Notes: + Currently, it's a no-op. + """ pass # def validate_task(self, task_ir: QuEraTaskSpecification): From a421e25cbc879717e3290e763290630eca62fe28 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Mon, 3 Jun 2024 17:40:17 -0700 Subject: [PATCH 2/5] Fix formatting --- src/bloqade/submission/braket.py | 56 +++++++++++++++++--------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/src/bloqade/submission/braket.py b/src/bloqade/submission/braket.py index b50c3d3fe..564ba3169 100644 --- a/src/bloqade/submission/braket.py +++ b/src/bloqade/submission/braket.py @@ -26,8 +26,8 @@ class BraketBackend(SubmissionBackend): 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): 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" @@ -35,8 +35,9 @@ class BraketBackend(SubmissionBackend): @property def device(self) -> 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. + """`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) @@ -47,12 +48,14 @@ def device(self) -> AwsDevice: 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`. + use_experimental (bool): Whether to use experimental capabilities of + the backend system. Defaults to `False`. + Returns: - An object to the type `QuEraCapabilities`, representing the capabilities - of the selected QuEra backend. + capabilities (`QuEraCapabilities`): capabilities + of the selected QuEra backend. """ from botocore.exceptions import BotoCoreError, ClientError @@ -80,13 +83,13 @@ def submit_task(self, task_ir: QuEraTaskSpecification) -> str: accepted by Braket. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) - suitable for QuEra backend. It will be converted to appropriate - IR(Intermediate Represetation) accepted by Braket backend + task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + suitable for QuEra backend. It will be converted to appropriate + IR(Intermediate Represetation) accepted by Braket backend Returns: - Task id as a result of executing IR(Intermediate Represetation) - on the Braket backend. + task_id (str): Task id as a result of executing + IR(Intermediate Represetation) on the Braket backend. """ shots, ahs_program = to_braket_task(task_ir) task = self.device.run(ahs_program, shots=shots) @@ -96,18 +99,19 @@ def task_results(self, task_id: str) -> QuEraTaskResults: """Get the result of the task by using the task id of Braket backend. Args: - task_id (str): task id after executing program on the Braket backend. + task_id (str): task id after executing program on the Braket backend. Returns: - Task result of the type `QuEraTaskResults` from task id - of the Braket backend. + task_result (`QuEraTaskResults`): Gets the task result using task id + of the Braket backend. """ return from_braket_task_results(AwsQuantumTask(task_id).result()) def cancel_task(self, task_id: str) -> None: """Cancels the task submitted to the Braket backend. + Args: - task_id (str): task id after executing program on the Bracket backend. + task_id (str): task id after executing program on the Bracket backend. """ AwsQuantumTask(task_id).cancel() @@ -115,11 +119,11 @@ def task_status(self, task_id: str) -> QuEraTaskStatusCode: """Get the status of the task submitted by using the task id of Braket backend. Args: - task_id (str): task id after executing program on the Braket backend. + task_id (str): task id after executing program on the Braket backend. Returns: - Task status of the type `QuEraTaskStatusCode` by using the task id - of the Braket backend. + status_code (QuEraTaskStatusCode): Task status by using the task id + of the Braket backend. """ return from_braket_status_codes(AwsQuantumTask(task_id).state()) @@ -127,15 +131,15 @@ def validate_task(self, task_ir: QuEraTaskSpecification): """Validates the task submitted to the QuEra backend. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) - suitable for QuEra backend. It will be converted to appropriate - IR(Intermediate Representation) accepted by Braket backend. + task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + suitable for QuEra backend. It will be converted to appropriate + IR(Intermediate Representation) accepted by Braket backend. Raises: - ValidationError: For tasks that fail validation. + ValidationError: For tasks that fail validation. - Notes: - Currently, it's a no-op. + Note: + Currently, it's a no-op. """ pass From a0c7733cd7fd6201c40b8a3e587f635c878fb6e4 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Wed, 5 Jun 2024 12:31:35 -0700 Subject: [PATCH 3/5] PR feedback: use IR synonym --- src/bloqade/submission/braket.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/src/bloqade/submission/braket.py b/src/bloqade/submission/braket.py index 564ba3169..3d5c93812 100644 --- a/src/bloqade/submission/braket.py +++ b/src/bloqade/submission/braket.py @@ -79,17 +79,16 @@ def get_capabilities(self, use_experimental: bool = False) -> QuEraCapabilities: def submit_task(self, task_ir: QuEraTaskSpecification) -> str: """Submit the task to the Braket backend. It converts task - IR(Intermediate Representation) of the QuEra system to suitable format + IR of the QuEra system to suitable format accepted by Braket. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) - suitable for QuEra backend. It will be converted to appropriate - IR(Intermediate Represetation) accepted by Braket backend + 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(Intermediate Represetation) on the Braket backend. + IR on the Braket backend. """ shots, ahs_program = to_braket_task(task_ir) task = self.device.run(ahs_program, shots=shots) @@ -131,9 +130,9 @@ def validate_task(self, task_ir: QuEraTaskSpecification): """Validates the task submitted to the QuEra backend. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) - suitable for QuEra backend. It will be converted to appropriate - IR(Intermediate Representation) accepted by Braket backend. + 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. From b251ad5b1c96a94ae1528bec382a11a6fbf705bb Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Tue, 11 Jun 2024 01:01:05 -0700 Subject: [PATCH 4/5] PR feedback --- src/bloqade/submission/braket.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/src/bloqade/submission/braket.py b/src/bloqade/submission/braket.py index 3d5c93812..2f275746a 100644 --- a/src/bloqade/submission/braket.py +++ b/src/bloqade/submission/braket.py @@ -95,19 +95,20 @@ def submit_task(self, task_ir: QuEraTaskSpecification) -> str: return task.id def task_results(self, task_id: str) -> QuEraTaskResults: - """Get the result of the task by using the task id of Braket backend. + """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 using task id - of the Braket backend. + task_result (`QuEraTaskResults`): Gets the task result a task + previously submitted using task id of the Braket backend. """ return from_braket_task_results(AwsQuantumTask(task_id).result()) def cancel_task(self, task_id: str) -> None: - """Cancels the task submitted to the Braket backend. + """Cancels a task previously submitted to the Braket backend. Args: task_id (str): task id after executing program on the Bracket backend. @@ -115,14 +116,15 @@ def cancel_task(self, task_id: str) -> None: AwsQuantumTask(task_id).cancel() def task_status(self, task_id: str) -> QuEraTaskStatusCode: - """Get the status of the task submitted by using the task id of Braket backend. + """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 the Braket backend. + of of a task previously submitted to the Braket backend. """ return from_braket_status_codes(AwsQuantumTask(task_id).state()) From 1267da43e576a5370c4c0acebc1713162c6a9b44 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Tue, 11 Jun 2024 01:04:25 -0700 Subject: [PATCH 5/5] Add note about blocking call --- src/bloqade/submission/braket.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/bloqade/submission/braket.py b/src/bloqade/submission/braket.py index 2f275746a..186965542 100644 --- a/src/bloqade/submission/braket.py +++ b/src/bloqade/submission/braket.py @@ -104,6 +104,10 @@ def task_results(self, task_id: str) -> QuEraTaskResults: 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())