From 2cb99d91bd46046ce0afd0e50cd1eb0b9bdc06c5 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Fri, 31 May 2024 20:07:38 -0700 Subject: [PATCH 1/9] Doc --- src/bloqade/submission/quera.py | 91 +++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index f437c66a1..e86148f99 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -1,3 +1,6 @@ +"""Module to host QueraBackend class that hosts different functionalities +representing the backend of the QuEra system(s).""" + from pydantic.v1 import PrivateAttr from bloqade.submission.base import SubmissionBackend, ValidationError from bloqade.submission.ir.task_specification import ( @@ -12,6 +15,34 @@ class QuEraBackend(SubmissionBackend): + """Class to represent QuEra backend. + + Attributes: + api_hostname (str): API of the host. + qpu_id (str): QPU id. + api_stage (str): API version. Defaults to "v0" + virtual_queue (Optional[str]) = Virtual queue in QuEra backend. + Defaults to `None`. + proxy (Optional[str]): proxy for Quera backend. Defaults to `None`. + # Sigv4Request arguments + region (Optional[str]): Sigv4Request argument for region of QuEra backend. + Defaults to `None`. + access_key (Optional[str]): Sigv4Request argument representing the access + key required to access QuEra backend. Defaults to `None`. + secret_key (Optional[str]): Sigv4Request argument representing the secret + key required to access QuEra backend. Defaults to `None`. + session_token (Optional[str]): Sigv4Request argument representing the session + token of the QuEra backend. Defaults to `None`. + session_expires (Optional[int]) = Sigv4Request argument representing the + expiration timestamp for the session on QuEra backend. Defaults to `None`. + role_arn (Optional[str]) = Role of the user accessing QuEra backend. + Defaults to `None`. + role_session_name (Optional[str]) = Role session name for QuEra backend. + Defaults to `None`. + profile (Optional[str]) = User profile for QuEra backend. + Defaults to `None`. + """ + api_hostname: str qpu_id: str api_stage: str = "v0" @@ -42,27 +73,77 @@ def queue_api(self): return self._queue_api 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 QuEra system. Defaults to `False`. + + Returns: + An object to the type `QuEraCapabilities`, representing the capabilities + of the selected QuEra backend. + """ try: return QuEraCapabilities(**self.queue_api.get_capabilities()) except BaseException: return super().get_capabilities(use_experimental) def submit_task(self, task_ir: QuEraTaskSpecification) -> str: + """Submit the task to the QuEra backend. + + Args: + task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + to be executed on the QuEra backend. + + Returns: + Task id as a result of executing IR(Intermediate Represetation) + on the QuEra backend. + """ return self.queue_api.submit_task( task_ir.json(by_alias=True, exclude_none=True, exclude_unset=True) ) def task_results(self, task_id: str) -> QuEraTaskResults: + """Submit the task to the QuEra backend. + + Args: + task_id (str): task id after executing program on the QuEra backend. + + Returns: + Task result of the task by using the task id. + """ return QuEraTaskResults(**self.queue_api.poll_task_results(task_id)) def cancel_task(self, task_id: str): + """Cancels the task submitted to the QuEra backend. + + Args: + task_id (str): task id after executing program on the QuEra backend. + """ self.queue_api.cancel_task_in_queue(task_id) def task_status(self, task_id: str) -> QuEraTaskStatusCode: + """Get the task status of the task submitted to the QuEra backend. + + Args: + task_id (str): task id after executing program on the QuEra backend. + + Returns: + Task status of the task by using the task id. + """ return_body = self.queue_api.get_task_status_in_queue(task_id) return QuEraTaskStatusCode(return_body) def validate_task(self, task_ir: QuEraTaskSpecification): + """Validates the task submitted to the QuEra backend. + + Args: + task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + to be executed on the QuEra backend. + + Raises: + ValidationError: For tasks that fail validation. + """ try: self.queue_api.validate_task( task_ir.json(by_alias=True, exclude_none=True, exclude_unset=True) @@ -73,6 +154,16 @@ def validate_task(self, task_ir: QuEraTaskSpecification): def update_credential( self, access_key: str = None, secret_key: str = None, session_token: str = None ): + """Update the credentials + + Args: + access_key (Optional[str]): Sigv4Request argument representing the access + key required to access QuEra backend. Defaults to `None`. + secret_key (Optional[str]): Sigv4Request argument representing the secret + key required to access QuEra backend. Defaults to `None`. + session_token (Optional[str]): Sigv4Request argument representing the session + token of the QuEra backend. Defaults to `None`. + """ if secret_key is not None: self.secret_key = secret_key if access_key is not None: From fe7b9dd05886fbcda57ea2536640730e5e350aed Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Fri, 31 May 2024 20:38:41 -0700 Subject: [PATCH 2/9] Minor edit --- src/bloqade/submission/quera.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index e86148f99..864f7ed62 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -104,7 +104,8 @@ def submit_task(self, task_ir: QuEraTaskSpecification) -> str: ) def task_results(self, task_id: str) -> QuEraTaskResults: - """Submit the task to the QuEra backend. + """Get the status of the task submitted to the QuEra backend + by using the task id. Args: task_id (str): task id after executing program on the QuEra backend. @@ -123,7 +124,8 @@ def cancel_task(self, task_id: str): self.queue_api.cancel_task_in_queue(task_id) def task_status(self, task_id: str) -> QuEraTaskStatusCode: - """Get the task status of the task submitted to the QuEra backend. + """Get the status of the task submitted to the QuEra backend + by using the task id. Args: task_id (str): task id after executing program on the QuEra backend. From 909760f2f2a43fd39e008e3c72a4fea69baa04d9 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Mon, 3 Jun 2024 18:03:29 -0700 Subject: [PATCH 3/9] formatting fixes --- src/bloqade/submission/quera.py | 92 +++++++++++++++++---------------- 1 file changed, 47 insertions(+), 45 deletions(-) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index 864f7ed62..f97b3ed04 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -18,29 +18,29 @@ class QuEraBackend(SubmissionBackend): """Class to represent QuEra backend. Attributes: - api_hostname (str): API of the host. - qpu_id (str): QPU id. - api_stage (str): API version. Defaults to "v0" - virtual_queue (Optional[str]) = Virtual queue in QuEra backend. - Defaults to `None`. - proxy (Optional[str]): proxy for Quera backend. Defaults to `None`. - # Sigv4Request arguments - region (Optional[str]): Sigv4Request argument for region of QuEra backend. - Defaults to `None`. - access_key (Optional[str]): Sigv4Request argument representing the access - key required to access QuEra backend. Defaults to `None`. - secret_key (Optional[str]): Sigv4Request argument representing the secret - key required to access QuEra backend. Defaults to `None`. - session_token (Optional[str]): Sigv4Request argument representing the session - token of the QuEra backend. Defaults to `None`. - session_expires (Optional[int]) = Sigv4Request argument representing the - expiration timestamp for the session on QuEra backend. Defaults to `None`. - role_arn (Optional[str]) = Role of the user accessing QuEra backend. - Defaults to `None`. - role_session_name (Optional[str]) = Role session name for QuEra backend. - Defaults to `None`. - profile (Optional[str]) = User profile for QuEra backend. - Defaults to `None`. + api_hostname (str): API of the host. + qpu_id (str): QPU id. + api_stage (str): API version. Defaults to "v0" + virtual_queue (Optional[str]) = Virtual queue in QuEra backend. + Defaults to `None`. + proxy (Optional[str]): proxy for Quera backend. Defaults to `None`. + # Sigv4Request arguments + region (Optional[str]): Sigv4Request argument for region of QuEra backend. + Defaults to `None`. + access_key (Optional[str]): Sigv4Request argument representing the access + key required to access QuEra backend. Defaults to `None`. + secret_key (Optional[str]): Sigv4Request argument representing the secret + key required to access QuEra backend. Defaults to `None`. + session_token (Optional[str]): Sigv4Request argument representing the session + token of the QuEra backend. Defaults to `None`. + session_expires (Optional[int]) = Sigv4Request argument representing the + expiration timestamp for the session on QuEra backend. Defaults to `None`. + role_arn (Optional[str]) = Role of the user accessing QuEra backend. + Defaults to `None`. + role_session_name (Optional[str]) = Role session name for QuEra backend. + Defaults to `None`. + profile (Optional[str]) = User profile for QuEra backend. + Defaults to `None`. """ api_hostname: str @@ -61,6 +61,7 @@ class QuEraBackend(SubmissionBackend): @property def queue_api(self): + """TODO: Document""" if self._queue_api is None: try: from qcs.api_client.api import QueueApi @@ -76,12 +77,12 @@ 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 QuEra system. Defaults to `False`. + use_experimental (bool): Whether to use experimental capabilities of + the QuEra 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. """ try: return QuEraCapabilities(**self.queue_api.get_capabilities()) @@ -92,12 +93,12 @@ def submit_task(self, task_ir: QuEraTaskSpecification) -> str: """Submit the task to the QuEra backend. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) - to be executed on the QuEra backend. + task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + to be executed on the QuEra backend. Returns: - Task id as a result of executing IR(Intermediate Represetation) - on the QuEra backend. + task_id (str): Task id as a result of executing + IR(Intermediate Represetation) on the QuEra backend. """ return self.queue_api.submit_task( task_ir.json(by_alias=True, exclude_none=True, exclude_unset=True) @@ -108,10 +109,11 @@ def task_results(self, task_id: str) -> QuEraTaskResults: by using the task id. Args: - task_id (str): task id after executing program on the QuEra backend. + task_id (str): task id after executing program on the QuEra backend. Returns: - Task result of the task by using the task id. + task_result (QuEraTaskResults): + Final result of the task by using the task id. """ return QuEraTaskResults(**self.queue_api.poll_task_results(task_id)) @@ -119,7 +121,7 @@ def cancel_task(self, task_id: str): """Cancels the task submitted to the QuEra backend. Args: - task_id (str): task id after executing program on the QuEra backend. + task_id (str): task id after executing program on the QuEra backend. """ self.queue_api.cancel_task_in_queue(task_id) @@ -128,10 +130,10 @@ def task_status(self, task_id: str) -> QuEraTaskStatusCode: by using the task id. Args: - task_id (str): task id after executing program on the QuEra backend. + task_id (str): task id after executing program on the QuEra backend. Returns: - Task status of the task by using the task id. + task_status (QuEraTaskStatusCode): status of the task by using the task id. """ return_body = self.queue_api.get_task_status_in_queue(task_id) return QuEraTaskStatusCode(return_body) @@ -140,11 +142,11 @@ def validate_task(self, task_ir: QuEraTaskSpecification): """Validates the task submitted to the QuEra backend. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) - to be executed on the QuEra backend. + task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + to be executed on the QuEra backend. Raises: - ValidationError: For tasks that fail validation. + ValidationError: For tasks that fail validation. """ try: self.queue_api.validate_task( @@ -159,12 +161,12 @@ def update_credential( """Update the credentials Args: - access_key (Optional[str]): Sigv4Request argument representing the access - key required to access QuEra backend. Defaults to `None`. - secret_key (Optional[str]): Sigv4Request argument representing the secret - key required to access QuEra backend. Defaults to `None`. - session_token (Optional[str]): Sigv4Request argument representing the session - token of the QuEra backend. Defaults to `None`. + access_key (Optional[str]): Sigv4Request argument representing the access + key required to access QuEra backend. Defaults to `None` + secret_key (Optional[str]): Sigv4Request argument representing the secret + key required to access QuEra backend. Defaults to `None` + session_token (Optional[str]): Sigv4Request argument representing the + session token of the QuEra backend. Defaults to `None` """ if secret_key is not None: self.secret_key = secret_key From 11d2386e5323330634abc83042116b7a12e59f82 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Mon, 3 Jun 2024 18:05:55 -0700 Subject: [PATCH 4/9] typo fix --- src/bloqade/submission/quera.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index f97b3ed04..5eefd8481 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -142,7 +142,7 @@ def validate_task(self, task_ir: QuEraTaskSpecification): """Validates the task submitted to the QuEra backend. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) + task_ir (QuEraTaskSpecification): task IR(Intermediate Representation) to be executed on the QuEra backend. Raises: From 379a2a3ef34162fe55e7a79da8fb625852b3a4d8 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Wed, 5 Jun 2024 12:42:21 -0700 Subject: [PATCH 5/9] Addressing PR feedback --- src/bloqade/submission/quera.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index 5eefd8481..443934049 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -93,12 +93,12 @@ def submit_task(self, task_ir: QuEraTaskSpecification) -> str: """Submit the task to the QuEra backend. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Represetation) - to be executed on the QuEra backend. + task_ir (QuEraTaskSpecification): task IR to be + executed on the QuEra backend. Returns: task_id (str): Task id as a result of executing - IR(Intermediate Represetation) on the QuEra backend. + IR on the QuEra backend. """ return self.queue_api.submit_task( task_ir.json(by_alias=True, exclude_none=True, exclude_unset=True) @@ -142,8 +142,8 @@ def validate_task(self, task_ir: QuEraTaskSpecification): """Validates the task submitted to the QuEra backend. Args: - task_ir (QuEraTaskSpecification): task IR(Intermediate Representation) - to be executed on the QuEra backend. + task_ir (QuEraTaskSpecification): task IR to be + executed on the QuEra backend. Raises: ValidationError: For tasks that fail validation. From 6a699198baa53558ea2b5c47094e71e721f4b154 Mon Sep 17 00:00:00 2001 From: Manvi-Agrawal <40084144+Manvi-Agrawal@users.noreply.github.com> Date: Mon, 10 Jun 2024 10:32:35 -0700 Subject: [PATCH 6/9] Update src/bloqade/submission/quera.py --- src/bloqade/submission/quera.py | 1 - 1 file changed, 1 deletion(-) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index 443934049..bc6562136 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -61,7 +61,6 @@ class QuEraBackend(SubmissionBackend): @property def queue_api(self): - """TODO: Document""" if self._queue_api is None: try: from qcs.api_client.api import QueueApi From 1fbc946810342b8549a24dcf9f6ccb5293e475c2 Mon Sep 17 00:00:00 2001 From: Manvi-Agrawal <40084144+Manvi-Agrawal@users.noreply.github.com> Date: Tue, 11 Jun 2024 00:49:17 -0700 Subject: [PATCH 7/9] Update src/bloqade/submission/quera.py Co-authored-by: Phillip Weinberg --- src/bloqade/submission/quera.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index bc6562136..f4dccc006 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -104,7 +104,7 @@ def submit_task(self, task_ir: QuEraTaskSpecification) -> str: ) def task_results(self, task_id: str) -> QuEraTaskResults: - """Get the status of the task submitted to the QuEra backend + """Get the status of a task previously submitted to the QuEra backend by using the task id. Args: From b4a6694d844759652c46751f8c847f6f153bbf0e Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Tue, 11 Jun 2024 00:55:39 -0700 Subject: [PATCH 8/9] PR feedback --- src/bloqade/submission/quera.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index f4dccc006..d8206d102 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -89,7 +89,7 @@ def get_capabilities(self, use_experimental: bool = False) -> QuEraCapabilities: return super().get_capabilities(use_experimental) def submit_task(self, task_ir: QuEraTaskSpecification) -> str: - """Submit the task to the QuEra backend. + """Submit a task to the QuEra backend. Args: task_ir (QuEraTaskSpecification): task IR to be @@ -112,12 +112,12 @@ def task_results(self, task_id: str) -> QuEraTaskResults: Returns: task_result (QuEraTaskResults): - Final result of the task by using the task id. + Final result of a task previously submitted by using the task id. """ return QuEraTaskResults(**self.queue_api.poll_task_results(task_id)) def cancel_task(self, task_id: str): - """Cancels the task submitted to the QuEra backend. + """Cancels a task previously submitted to the QuEra backend. Args: task_id (str): task id after executing program on the QuEra backend. @@ -125,14 +125,15 @@ def cancel_task(self, task_id: str): self.queue_api.cancel_task_in_queue(task_id) def task_status(self, task_id: str) -> QuEraTaskStatusCode: - """Get the status of the task submitted to the QuEra backend + """Get the status of a task previously submitted to the QuEra backend by using the task id. Args: task_id (str): task id after executing program on the QuEra backend. Returns: - task_status (QuEraTaskStatusCode): status of the task by using the task id. + task_status (QuEraTaskStatusCode): + status of a task previously by using the task id. """ return_body = self.queue_api.get_task_status_in_queue(task_id) return QuEraTaskStatusCode(return_body) From e8b6a28ccf5fd71e17c8914cabbdc77c8985e917 Mon Sep 17 00:00:00 2001 From: Manvi Agrawal Date: Tue, 11 Jun 2024 01:05:26 -0700 Subject: [PATCH 9/9] Add note about blocking call --- src/bloqade/submission/quera.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index d8206d102..58dce0dc9 100644 --- a/src/bloqade/submission/quera.py +++ b/src/bloqade/submission/quera.py @@ -113,6 +113,10 @@ def task_results(self, task_id: str) -> QuEraTaskResults: Returns: task_result (QuEraTaskResults): Final result of a task previously submitted by using the task id. + + Note: + This is a blocking call, meaning the function will not + return till the task has stopped. """ return QuEraTaskResults(**self.queue_api.poll_task_results(task_id))