qcs_sdk

An interface to Rigetti Quantum Cloud Services (QCS).

These APIs allow users to compile and run Quil programs on Rigetti quantum processors. Internally, it is powered by the QCS Rust SDK.

This package is still in development and breaking changes should be expected between minor versions.

View Source

 1# This file is automatically generated by pyo3_stub_gen
 2# ruff: noqa: F401
 3
 4from qcs_sdk import _tracing_subscriber
 5from qcs_sdk._qcs_sdk import ExeParameter, Executable, ExecutionData, ExecutionError, JobHandle, QcsSdkError, RegisterData, RegisterMap, RegisterMapItemsIter, RegisterMapKeysIter, RegisterMapValuesIter, RegisterMatrix, RegisterMatrixConversionError, Service, __doc__, __version__, client, compiler, diagnostics, qpu, qvm, reset_logging
 6from qcs_sdk._qcs_sdk.client import QCSClient
 7__all__ = [
 8    "ExeParameter",
 9    "Executable",
10    "ExecutionData",
11    "ExecutionError",
12    "JobHandle",
13    "QCSClient",
14    "QcsSdkError",
15    "RegisterData",
16    "RegisterMap",
17    "RegisterMapItemsIter",
18    "RegisterMapKeysIter",
19    "RegisterMapValuesIter",
20    "RegisterMatrix",
21    "RegisterMatrixConversionError",
22    "Service",
23    "__doc__",
24    "__version__",
25    "_tracing_subscriber",
26    "client",
27    "compiler",
28    "diagnostics",
29    "qpu",
30    "qvm",
31    "reset_logging",
32]

class ExeParameter:

Program execution parameters.

Note: The validity of parameters is not checked until execution.

value

name

index

class Executable:

A builder interface for executing Quil programs on QVMs and QPUs.

Example

This example executes a program on a QVM, specified by the qvm_url in the QCSClient:

from qcs_sdk import Executable
from qcs_sdk.client import QCSClient
from qcs_sdk.qvm import QVMClient

PROGRAM = r'''
DECLARE ro BIT[2]

H 0
CNOT 0 1

MEASURE 0 ro[0]
MEASURE 1 ro[1]
'''

async def run():
    client = QVMClient.new_http(QCSClient.load().qvm_url)
    result = await Executable(PROGRAM, shots=4).execute_on_qvm_async()
    let data = result.result_data
                        .to_register_map()
                        .expect("should convert to readout map")
                        .get_register_matrix("ro")
                        .expect("should have data in ro")
                        .as_integer()
                        .expect("should be integer matrix")
                        .to_owned();

    // In this case, we ran the program for 4 shots, so we know the number of rows is 4.
    assert_eq!(data.nrows(), 4);
    for shot in data.rows() {
        // Each shot will contain all the memory, in order, for the vector (or "register") we
        // requested the results of. In this case, "ro" (the default).
        assert_eq!(shot.len(), 2);
        // In the case of this particular program, we know ro[0] should equal ro[1]
        assert_eq!(shot[0], shot[1]);
    }

def main():
    import asyncio
    asyncio.run(run())

    # "ro" is the only source read from by default if you don't specify `registers`.

    # We first convert the readout data to a ``RegisterMap`` to get a mapping of registers
    # (ie. "ro") to a [`RegisterMatrix`], `M`, where M[`shot`][`index`] is the value for
    # the memory offset `index` during shot `shot`.
    # There are some programs where QPU readout data does not fit into a [`RegisterMap`], in
    # which case you should build the matrix you need from [`QpuResultData`] directly. See
    # the [`RegisterMap`] documentation for more information on when this transformation
    # might fail.

def execute_on_qvm(self, /, client):

Execute on a QVM which is accessible via the provided client.

Raises

ExecutionError: If the job fails to execute.

def execute_on_qvm_async(self, /, client):

Execute on a QVM which is accessible via the provided client (async analog of Executable.execute_on_qvm).

Raises

ExecutionError: If the job fails to execute.

def execute_on_qpu( self, /, quantum_processor_id, endpoint_id=None, translation_options=None, execution_options=None):

Compile the program and execute it on a QPU, waiting for results.

Parameters

endpoint_id: execute the compiled program against an explicitly provided endpoint. If None, the default endpoint for the given quantum_processor_id is used.

Raises

ExecutionError: If the job fails to execute.

def execute_on_qpu_async( self, /, quantum_processor_id, endpoint_id=None, translation_options=None, execution_options=None):

Compile the program and execute it on a QPU, waiting for results (async analog of Executable.execute_on_qpu).

Parameters

endpoint_id: execute the compiled program against an explicitly provided endpoint. If None, the default endpoint for the given quantum_processor_id is used.

Raises

ExecutionError: If the job fails to execute.

def submit_to_qpu( self, /, quantum_processor_id, endpoint_id=None, translation_options=None, execution_options=None):

Compile the program and execute it on a QPU, without waiting for results.

Parameters

endpoint_id: execute the compiled program against an explicitly provided endpoint. If None, the default endpoint for the given quantum_processor_id is used.

Raises

ExecutionError: If the job fails to execute.

def submit_to_qpu_async( self, /, quantum_processor_id, endpoint_id=None, translation_options=None, execution_options=None):

Compile the program and execute it on a QPU, without waiting for results (async analog of Executable.submit_to_qpu).

Parameters

endpoint_id: execute the compiled program against an explicitly provided endpoint. If None, the default endpoint for the given quantum_processor_id is used.

Raises

ExecutionError: If the job fails to execute.

def retrieve_results(self, /, job_handle):

Wait for the results of a job to complete.

Raises

ExecutionError: If the job fails to execute.

def retrieve_results_async(self, /, job_handle):

Wait for the results of a job to complete (async analog of Executable.retrieve_results).

Raises

ExecutionError: If the job fails to execute.

class ExecutionData:

The result of executing an Executable

result_data

The [ResultData] that was read from the Executable.

duration

The time it took to execute the program on the QPU, not including any network or queueing time. If paying for on-demand execution, this is the amount you will be billed for.

This will always be None for QVM execution.

class ExecutionError(qcs_sdk.QcsSdkError):

Errors which can occur when executing a program.

class JobHandle:

The result of submitting a job to a QPU.

Used to retrieve the results of a job.

job_id

Unique ID associated with a single job execution.

readout_map

The readout map from "source readout memory locations" to the "filter pipeline node" which publishes the data.

class QCSClient:

A client providing helper functionality for accessing QCS APIs

def load(profile_name=None):

Create a QCSClient configuration using an environment-based configuration.

Parameters

profile_name: The QCS setting's profile name to use. If None, the default value configured in your environment is used.

Raises

LoadClientError: If there is an issue loading the profile details from the environment.

def load_with_login(profile_name=None):

Create a QCSClient configuration using an environment-based configuration.

If credentials are not found or stale, a PKCE login redirect flow will be initialized. Note that this opens up a TCP port on your system to accept a browser HTTP redirect, so you should not use this in environments where that is not possible, such as hosted JupyterLab sessions.

Parameters

profile_name: The QCS setting's profile name to use. If None, the default value configured in your environment is used.

Raises

LoadClientError: If there is an issue loading the profile details from the environment or if the PKCE login flow fails.

See the QCS documentation for more details.

def load_with_login_async(profile_name=None):

Create a QCSClient configuration using an environment-based configuration.

Parameters

profile_name: The QCS setting's profile name to use. If None, the default value configured in your environment is used.

Raises

LoadClientError: If there is an issue loading the profile details from the environment or if the PKCE login flow fails.

See the QCS documentation for more details.

def get_oauth_session_async(self, /):

Get a copy of the OAuth session in an async context.

api_url

URL to access the QCS API.

qvm_url

URL to access the QVM.

oauth_session

Get a copy of the OAuth session.

quilc_url

URL to access the quilc compiler.

grpc_api_url

URL to access the QCS gRPC API.

class QcsSdkError(builtins.Exception):

Base exception type for errors raised by this package.

class RegisterData:

Data resulting from Executable::execute_on_qvm

This represents a single vector (or "register") of typed memory across some number of shots. The register corresponds to the usage of a DECLARE instruction in Quil, and the name of that register should be provided with Executable::read_from.

There is a variant of this enum for each type of data that a register could hold. The register is represented as a 2-dimensional array M where the value M[shot_number][memory_index] represents the value at memory_index for shot_number.

Usage

Typically, you will be interacting with this data through the [crate::ResultData] of an [crate::ExecutionData] returned after running a program. In those cases, you'll probably want to convert it to a readout map using [crate::ResultData.to_register_map()]. This will give you each register in the form of a [crate::RegisterMatrix] which is similar but backed by an [ndarray::Array2] and more convenient for working with matrices.

If you are interacting with [RegisterData] directly, then you should already know what type of data it _should_ have, so you can use the [mod@enum_as_inner] methods (e.g. [RegisterData::into_i8]) in order to convert any variant type to its inner data.

def as_ndarray(self, /):

Return the inner values as a 2D Numpy ndarray.

def inner(self, /):

class RegisterData.I8(qcs_sdk.RegisterData):

Corresponds to the Quil BIT or OCTET types.

class RegisterData.F64(qcs_sdk.RegisterData):

Corresponds to the Quil REAL type.

class RegisterData.I16(qcs_sdk.RegisterData):

Corresponds to the Quil INTEGER type.

class RegisterData.Complex32(qcs_sdk.RegisterData):

Results containing complex numbers.

class RegisterMap:

A mapping of a register name (ie. "ro") to a [RegisterMatrix] containing the values for the register.

def get_register_matrix(self, /, register_name):

Get the RegisterMatrix for the given register.

Returns None if the register doesn't exist.

def keys(self, /):

def values(self, /):

def items(self, /):

def get(self, /, key, default=None):

class RegisterMapItemsIter:

class RegisterMapKeysIter:

class RegisterMapValuesIter:

class RegisterMatrix:

A 2-dimensional matrix of register values.

Each variant corresponds to the possible data types a register can contain.

def to_ndarray(self, /):

Get the RegisterMatrix as Numpy ndarray.

class RegisterMatrix.Integer(qcs_sdk.RegisterMatrix):

Integer register.

class RegisterMatrix.Real(qcs_sdk.RegisterMatrix):

Real numbered register.

class RegisterMatrix.Complex(qcs_sdk.RegisterMatrix):

Complex numbered register.

class RegisterMatrixConversionError(qcs_sdk.QcsSdkError):

Error that may occur when building a RegisterMatrix from execution data.

class Service:

The external services that this SDK may connect to. Used to differentiate between networking issues in [Error::Connection].

QUILC = Service.QUILC

QVM = Service.QVM

QCS = Service.QCS

QPU = Service.QPU

__version__ = '0.26.3'

def reset_logging():

Reset all caches for logging configuration within this library, allowing the most recent Python-side changes to be applied.

See https://docs.rs/pyo3-log/latest/pyo3_log/ for more information.