diff --git a/src/bloqade/submission/quera.py b/src/bloqade/submission/quera.py index f437c66a1..58dce0dc9 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,85 @@ 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: + capabilities (QuEraCapabilities): 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 a task to the QuEra backend. + + Args: + task_ir (QuEraTaskSpecification): task IR to be + executed on the QuEra backend. + + Returns: + task_id (str): Task id as a result of executing + IR 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: + """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_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)) def cancel_task(self, task_id: str): + """Cancels a task previously 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 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 a task previously 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 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 +162,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: