Pasqal Cloud Connection

WorkloadNotDoneError

Bases: Exception

Is raised if a workload is not yet finished running on remote.

WorkloadSpec(circuit, backend, result_types, parameter_values=None, observable=None) dataclass

Specification of a workload to be executed on Pasqal Cloud.

This data class defines a single workload specification that is to be executed on Pasqal's cloud platform.

PARAMETER	DESCRIPTION
circuit	The quantum circuit to be executed. TYPE: QuantumCircuit
backend	The backend to execute the workload on. Not all backends are available on the cloud platform. Currently the supported backend is BackendName.PYQTORCH. TYPE: BackendName | str
result_types	The types of result to compute for this workload. The circuit will be run for all result types specified here one by one. TYPE: list[ResultType]
parameter_values	If the quantum circuit has feature parameters, values for those need to be provided. In the case there are only variational parameters, this field is optional. In the case there are no parameters, this field needs to be None. The parameter values can be either a tensor of dimension 0 or 1, which can differ per parameter. For parameters that are an array, i.e. dimension 1, all array lengths should be equal. TYPE: dict[str, Tensor] | None DEFAULT: None
observable	Observable that is used when result_types contains ResultType.EXPECTATION. The observable field is mandatory in this case. If not, the value of this field will be ignored. Only a single observable can be passed for cloud submission; providing a list of observables is not supported. TYPE: AbstractBlock | None DEFAULT: None

WorkloadStoppedError

Bases: Exception

Is raised when a workload has stopped running on remote for some reason.

check_status(connection, workload_id)

Checks if the workload is successfully finished on remote connection.

PARAMETER	DESCRIPTION
connection	A pasqal_cloud.SDK instance which is used to connect to the cloud. TYPE: SDK
workload_id	the id str that is associated with the workload. TYPE: str

RAISES	DESCRIPTION
WorkloadNotDoneError	Is raised when the workload status is "PENDING", "RUNNING" or "PAUSED".
WorkloadStoppedError	Is raise when the workload status is "CANCELED", "TIMED_OUT" or "ERROR".
ValueError	Is raised when the workload status has an unsupported value.

RETURNS	DESCRIPTION
Workload	The workload result if its status is "DONE" as a pasqal_cloud.Workload object.

Source code in qadence/pasqal_cloud_connection.py

def check_status(connection: SDK, workload_id: str) -> WorkloadResult:
    """Checks if the workload is successfully finished on remote connection.

    Args:
        connection: A `pasqal_cloud.SDK` instance which is used to connect to the cloud.
        workload_id: the id `str` that is associated with the workload.

    Raises:
        WorkloadNotDoneError: Is raised when the workload status is "PENDING", "RUNNING" or
            "PAUSED".
        WorkloadStoppedError: Is raise when the workload status is "CANCELED", "TIMED_OUT" or
            "ERROR".
        ValueError: Is raised when the workload status has an unsupported value.

    Returns:
        The workload result if its status is "DONE" as a `pasqal_cloud.Workload` object.
    """
    # TODO Make the function return a "nice" result object
    result = connection.get_workload(workload_id)
    if result.status == "DONE":
        return result
    if result.status in ("PENDING", "RUNNING", "PAUSED"):
        raise WorkloadNotDoneError(
            f"Workload with id {workload_id} is not yet finished, the status is {result.status}"
        )
    if result.status in ("CANCELED", "TIMED_OUT", "ERROR"):
        message = f"Workload with id {workload_id} couldn't finish, the status is {result.status}."
        if result.status == "ERROR":
            message += f"The following error(s) occurred {result.errors}"
        raise WorkloadStoppedError(message)
    raise ValueError(
        f"Undefined workload status ({result.status}) was returned for workload ({result.id})"
    )

get_result(connection, workload_id, timeout=60.0, refresh_time=1.0)

Repeatedly checks if a workload has finished and returns the result.

PARAMETER	DESCRIPTION
connection	A pasqal_cloud.SDK instance which is used to connect to the cloud. TYPE: SDK
workload_id	the id str that is associated with the workload. TYPE: str
timeout	Time in seconds after which the function times out. Defaults to 60.0. TYPE: float DEFAULT: 60.0
refresh_time	Time in seconds after which the remote is requested to update the status again, when the workload is not finished yet. Defaults to 1.0. TYPE: float DEFAULT: 1.0

RAISES	DESCRIPTION
TimeoutError	description

RETURNS	DESCRIPTION
Workload	The workload result if its status is "DONE" as a pasqal_cloud.Workload object.

Source code in qadence/pasqal_cloud_connection.py

def get_result(
    connection: SDK, workload_id: str, timeout: float = 60.0, refresh_time: float = 1.0
) -> WorkloadResult:
    """Repeatedly checks if a workload has finished and returns the result.

    Args:
        connection: A `pasqal_cloud.SDK` instance which is used to connect to the cloud.
        workload_id: the id `str` that is associated with the workload.
        timeout: Time in seconds after which the function times out. Defaults to 60.0.
        refresh_time: Time in seconds after which the remote is requested to update the status
            again, when the workload is not finished yet. Defaults to 1.0.

    Raises:
        TimeoutError: _description_

    Returns:
        The workload result if its status is "DONE" as a `pasqal_cloud.Workload` object.
    """
    max_refresh_count = int(timeout // refresh_time)
    for _ in range(max_refresh_count):
        try:
            result = check_status(connection, workload_id)
        except WorkloadNotDoneError:
            time.sleep(refresh_time)
            continue
        return result
    raise TimeoutError("Request timed out because it wasn't finished in the specified time. ")

get_spec_from_model(model, result_types, parameter_values=None, observable=None)

Creates a WorkloadSpec from a quantum model.

This function creates a WorkloadSpec from a QuantumModel and the other arguments provided. The circuit, that is extracted from the model, is the original circuit that was used to initialize the model, not the backend converted circuit in model.circuit. The backend set in the model will be used in the workload specification.

It is important to note that in case there is an observable defined in the model, it is ignored in the workload specification. To provide an observable to the workload specification, it is only possible to set it in the observable argument of this function.

PARAMETER	DESCRIPTION
model	The quantum model that defines the circuit and backend for the workload spec. TYPE: QuantumModel
result_types	A list of result types that is requested in this workload. TYPE: list[ResultType]
parameter_values	The parameter values that should be used during execution of the workload. TYPE: dict[str, Tensor] | None DEFAULT: None
observable	Observable that is used when result_types contains ResultType.EXPECTATION. The observable field is mandatory in this case. If not, the value of this field will be ignored. Only a single observable can be passed for cloud submission; providing a list of observables is not supported. TYPE: AbstractBlock | None DEFAULT: None

RETURNS	DESCRIPTION
WorkloadSpec	A WorkloadSpec instance based on the quantum model passed to this function.

Source code in qadence/pasqal_cloud_connection.py

def get_spec_from_model(
    model: QuantumModel,
    result_types: list[ResultType],
    parameter_values: dict[str, Tensor] | None = None,
    observable: AbstractBlock | None = None,
) -> WorkloadSpec:
    """Creates a `WorkloadSpec` from a quantum model.

    This function creates a `WorkloadSpec` from a `QuantumModel` and the other arguments provided.
    The circuit, that is extracted from the model, is the original circuit that was used to
    initialize the model, not the backend converted circuit in `model.circuit`. The backend set in
    the model will be used in the workload specification.

    It is important to note that in case there is an observable defined in the model, it is ignored
    in the workload specification. To provide an observable to the workload specification, it is
    only possible to set it in the observable argument of this function.

    Args:
        model: The quantum model that defines the circuit and backend for the workload spec.
        result_types: A list of result types that is requested in this workload.
        parameter_values: The parameter values that should be used during execution of the
            workload.
        observable: Observable that is used when `result_types` contains `ResultType.EXPECTATION`.
            The observable field is mandatory in this case. If not, the value of this field will
            be ignored. Only a single observable can be passed for cloud submission; providing a
            list of observables is not supported.

    Returns:
        A `WorkloadSpec` instance based on the quantum model passed to this function.
    """
    circuit = model._circuit.original
    backend = model._backend_name
    return WorkloadSpec(circuit, backend, result_types, parameter_values, observable)

submit_workload(connection, workload)

Uploads a workload to Pasqal's Cloud and returns the created workload ID.

PARAMETER	DESCRIPTION
connection	A pasqal_cloud.SDK instance which is used to connect to the cloud. TYPE: SDK
workload	A WorkloadSpec object, defining the specification of the workload that needs to be uploaded. TYPE: WorkloadSpec

RETURNS	DESCRIPTION
str	A workload id as a str.

Source code in qadence/pasqal_cloud_connection.py

def submit_workload(connection: SDK, workload: WorkloadSpec) -> str:
    """Uploads a workload to Pasqal's Cloud and returns the created workload ID.

    Args:
        connection: A `pasqal_cloud.SDK` instance which is used to connect to the cloud.
        workload: A `WorkloadSpec` object, defining the specification of the workload that needs to
            be uploaded.

    Returns:
        A workload id as a `str`.
    """
    workload_json = _workload_spec_to_json(workload)
    remote_workload = connection.create_workload(
        workload_json.workload_type, workload_json.backend_type, workload_json.config
    )
    workload_id: str = remote_workload.id
    return workload_id