qcs_sdk

The qcs_sdk package provides a Python interface to the Rigetti Quantum Cloud Services (QCS) platform.

For more information about QCS, see the QCS documentation.

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

1# type: ignore
2# See the following documentation for why this file is necessary:
3# https://pyo3.rs/v0.18.0/python_typing_hints#__init__py-content
4
5from .qcs_sdk import *
6
7
8__doc__ = qcs_sdk.__doc__
9__all__ = getattr(qcs_sdk, "__all__", []) + ["diagnostics"]
class ExecutionData:

Contains the ResultData and the duration of the execution.

duration: Optional[datetime.timedelta]

Get the duration field from Python. Annotated with @property.

result_data: ResultData

Get the result_data field from Python. Annotated with @property.

class ResultData:

Represents the two possible types of data returned from either the QVM or a real QPU. Each variant contains the original data returned from its respective executor.

Usage

Your usage of ResultData will depend on the types of programs you are running and where. The ResultData.to_register_map() method will attempt to build RegisterMap out of the data, where each register name is mapped to a 2-dimensional rectangular RegisterMatrix where each row represents the final values in each register index for a particular shot. This is often the desired form of the data and it is probably what you want. This transformation isn't always possible, in which case to_register_map() will return an error.

To understand why this transformation can fail, we need to understand a bit about how readout data is returned from the QVM and from a real QPU:

The QVM treats each DECLARE statement as initialzing some amount of memory. This memory works as one might expect it to. It is zero-initalized, and subsequent writes to the same region overwrite the previous value. The QVM returns memory at the end of every shot. This means we get the last value in every memory reference for each shot, which is exactly the representation we want for a RegisterMatrix. For this reason, to_register_map() should always succeed for ResultData::Qvm.

The QPU on the other hand doesn't use the same memory model as the QVM. Each memory reference (ie. "ro[0]") is more like a stream than a value in memory. Every MEASURE to a memory reference emits a new value to said stream. This means that the number of values per memory reference can vary per shot. For this reason, it's not always clear what the final value in each shot was for a particular reference. When this is the case, to_register_map() will return an error as it's impossible to build a correct RegisterMatrix from the data without knowing the intent of the program that was run. Instead, it's recommended to build the RegisterMatrix you need from the inner QPUResultData data using the knowledge of your program to choose the correct readout values for each shot.

For more information on QPU readout data, refer to the QCS Documentation.

Variants:

  • qvm: Data returned from the QVM, stored as QVMResultData
  • qpu: Data returned from the QPU, stored as QPUResultData

Methods (each per variant):

  • is_*: if the underlying values are that type.
  • as_*: if the underlying values are that type, then those values, otherwise None.
  • to_*: the underlying values as that type, raises ValueError if they are not.
  • from_*: wrap underlying values as this enum type.
ResultData(inner: Union[QPUResultData, QVMResultData])

Create a new ResultData from either QVM or QPU result data.

def from_qpu(inner: QPUResultData) -> ResultData:

The Python wrapper for [ResultData::Qpu], creating a [PyResultData] and taking a Python argument.

def from_qvm(inner: QVMResultData) -> ResultData:

The Python wrapper for [ResultData::Qvm], creating a [PyResultData] and taking a Python argument.

def inner(self) -> Union[QVMResultData, QPUResultData]:

Returns the inner result data

def is_qpu(self) -> bool:

Tests if this [PyResultData] wraps a [ResultData::qpu] value

def as_qpu(self) -> Optional[QPUResultData]:

Returns x if this [PyResultData] wraps a ResultData::qpu(x); otherwise returns (Python) None. On the Rust side, this corresponds to either Some(x) or [None].

def to_qpu(self) -> QPUResultData:

Returns x if this [PyResultData] wraps a ResultData::qpu(x); otherwise raises a ValueError. On the Rust side, this corresponds to either Ok(x) or Err(...).

def is_qvm(self) -> bool:

Tests if this [PyResultData] wraps a [ResultData::qvm] value

def as_qvm(self) -> Optional[QVMResultData]:

Returns x if this [PyResultData] wraps a ResultData::qvm(x); otherwise returns (Python) None. On the Rust side, this corresponds to either Some(x) or [None].

def to_qvm(self) -> QVMResultData:

Returns x if this [PyResultData] wraps a ResultData::qvm(x); otherwise raises a ValueError. On the Rust side, this corresponds to either Ok(x) or Err(...).

def to_register_map(self) -> RegisterMap:

Convert ResultData from its inner representation as QVMResultData or QPUResultData into a RegisterMap. The RegisterMatrix for each register will be constructed such that each row contains all the final values in the register for a single shot.

Errors

Raises a RegisterMatrixConversionError if the inner execution data for any of the registers would result in a jagged matrix. QPUResultData data is captured per measure, meaning a value is returned for every measure to a memory reference, not just once per shot. This is often the case in programs that use mid-circuit measurement or dynamic control flow, where measurements to the same memory reference might occur multiple times in a shot, or be skipped conditionally. In these cases, building a rectangular RegisterMatrix would necessitate making assumptions about the data that could skew the data in undesirable ways. Instead, it's recommended to manually build a matrix from QPUResultData that accurately selects the last value per-shot based on the program that was run.

def to_raw_readout_data(self) -> Union[RawQPUReadoutData, RawQVMReadoutData]:

Get the raw data returned from the QVM or QPU. See RawQPUReadoutData and RawQVMReadoutData for more information.

class RegisterMap:

A map of register names (ie. "ro") to a RegisterMatrix containing the values of the register.

def get_register_matrix(self, register_name: str) -> Optional[RegisterMatrix]:

Get the RegisterMatrix for the given register. Returns None if the register doesn't exist.

def keys(self) -> Iterable[str]:
def values(self) -> Iterable[RegisterMatrix]:
def items(self) -> Iterable[Tuple[str, RegisterMatrix]]:
def get( self, key: str, default: Optional[RegisterMatrix] = None) -> Optional[RegisterMatrix]:
class RegisterMatrix:

Values in a 2-dimensional ndarray representing the final shot value in each memory reference across all shots. Each variant corresponds to the possible data types a register can contain.

Variants:

  • integer: Corresponds to the Quil BIT, OCTET, or INTEGER types.
  • real: Corresponds to the Quil REAL type.
  • complex: Registers containing complex numbers.

Methods (each per variant):

  • is_*: if the underlying values are that type.
  • as_*: if the underlying values are that type, then those values, otherwise None.
  • to_*: the underlying values as that type, raises ValueError if they are not.
  • from_*: wrap underlying values as this enum type.
def to_ndarray( self) -> Union[numpy.ndarray[Any, numpy.dtype[numpy.complex128]], numpy.ndarray[Any, numpy.dtype[numpy.int64]], numpy.ndarray[Any, numpy.dtype[numpy.float64]]]:

Get the RegisterMatrix as numpy ndarray.

def from_integer( inner: numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]) -> RegisterMatrix:
def to_integer(self) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.int64]]:
def as_integer(self) -> Optional[numpy.ndarray[Any, numpy.dtype[numpy.int64]]]:
def is_integer(self) -> bool:
def from_real( inner: numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]) -> RegisterMatrix:
def to_real(self) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.float64]]:
def as_real(self) -> Optional[numpy.ndarray[Any, numpy.dtype[numpy.float64]]]:
def is_real(self) -> bool:
def from_complex( inner: numpy.ndarray[typing.Any, numpy.dtype[numpy.complex128]]) -> RegisterMatrix:
def to_complex(self) -> numpy.ndarray[typing.Any, numpy.dtype[numpy.complex128]]:
def as_complex(self) -> Optional[numpy.ndarray[Any, numpy.dtype[numpy.complex128]]]:
def is_complex(self) -> bool:
class Executable:

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

def execute_on_qvm(self, client: QVMClient) -> ExecutionData:

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

Raises
async def execute_on_qvm_async(self, client: QVMClient) -> ExecutionData:

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

Raises
def execute_on_qpu( self, quantum_processor_id: str, endpoint_id: Optional[str] = None, translation_options: Optional[TranslationOptions] = None, execution_options: Optional[qcs_sdk.qpu.api.ExecutionOptions] = None) -> ExecutionData:

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
async def execute_on_qpu_async( self, quantum_processor_id: str, endpoint_id: Optional[str] = None, translation_options: Optional[TranslationOptions] = None, execution_options: Optional[qcs_sdk.qpu.api.ExecutionOptions] = None) -> ExecutionData:

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
def submit_to_qpu( self, quantum_processor_id: str, endpoint_id: Optional[str] = None, translation_options: Optional[TranslationOptions] = None, execution_options: Optional[qcs_sdk.qpu.api.ExecutionOptions] = None) -> JobHandle:

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
async def submit_to_qpu_async( self, quantum_processor_id: str, endpoint_id: Optional[str] = None, translation_options: Optional[TranslationOptions] = None, execution_options: Optional[qcs_sdk.qpu.api.ExecutionOptions] = None) -> JobHandle:

Compile the program and execute it on a QPU, without 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
def retrieve_results(self, job_handle: JobHandle) -> ExecutionData:

Wait for the results of a job to complete.

Raises
async def retrieve_results_async(self, job_handle: JobHandle) -> ExecutionData:

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

Raises
class ExeParameter:

Program execution parameters.

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

index: int
value: float
name: str
class JobHandle:

The result of submitting a job to a QPU.

Used to retrieve the results of a job.

readout_map: Dict[str, str]

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

job_id: str

Unique ID associated with a single job execution.

class Service:
Quilc = Service.Quilc
QVM = Service.QVM
QCS = Service.QCS
QPU = Service.QPU
class RegisterData:

Values present in a register that are one of a set of variants.

Variants:

  • i8: Corresponds to the Quil BIT or OCTET types.
  • i16: Corresponds to the Quil INTEGER type.
  • f64: Corresponds to the Quil REAL type.
  • complex32: Results containing complex numbers.

Methods (each per variant):

  • is_*: if the underlying values are that type.
  • as_*: if the underlying values are that type, then those values, otherwise None.
  • to_*: the underlying values as that type, raises ValueError if they are not.
  • from_*: wrap underlying values as this enum type.
def from_i8(inner: Sequence[Sequence[int]]) -> RegisterData:

The Python wrapper for [RegisterData::I8], creating a [PyRegisterData] and taking a Python argument.

def from_f64(inner: Sequence[Sequence[float]]) -> RegisterData:

The Python wrapper for [RegisterData::F64], creating a [PyRegisterData] and taking a Python argument.

def from_i16(inner: Sequence[Sequence[int]]) -> RegisterData:

The Python wrapper for [RegisterData::I16], creating a [PyRegisterData] and taking a Python argument.

def from_complex32(inner: Sequence[Sequence[complex]]) -> RegisterData:

The Python wrapper for [RegisterData::Complex32], creating a [PyRegisterData] and taking a Python argument.

def inner(self) -> Union[List[List[int]], List[List[float]], List[List[complex]]]:

Returns the inner value.

def is_i8(self) -> bool:

Tests if this [PyRegisterData] wraps a [RegisterData::i8] value

def as_i8(self) -> Optional[List[List[int]]]:

Returns x if this [PyRegisterData] wraps a RegisterData::i8(x); otherwise returns (Python) None. On the Rust side, this corresponds to either Some(x) or [None].

def to_i8(self) -> List[List[int]]:

Returns x if this [PyRegisterData] wraps a RegisterData::i8(x); otherwise raises a ValueError. On the Rust side, this corresponds to either Ok(x) or Err(...).

def is_f64(self) -> bool:

Tests if this [PyRegisterData] wraps a [RegisterData::f64] value

def as_f64(self) -> Optional[List[List[float]]]:

Returns x if this [PyRegisterData] wraps a RegisterData::f64(x); otherwise returns (Python) None. On the Rust side, this corresponds to either Some(x) or [None].

def to_f64(self) -> List[List[float]]:

Returns x if this [PyRegisterData] wraps a RegisterData::f64(x); otherwise raises a ValueError. On the Rust side, this corresponds to either Ok(x) or Err(...).

def is_i16(self) -> bool:

Tests if this [PyRegisterData] wraps a [RegisterData::i16] value

def as_i16(self) -> Optional[List[List[int]]]:

Returns x if this [PyRegisterData] wraps a RegisterData::i16(x); otherwise returns (Python) None. On the Rust side, this corresponds to either Some(x) or [None].

def to_i16(self) -> List[List[int]]:

Returns x if this [PyRegisterData] wraps a RegisterData::i16(x); otherwise raises a ValueError. On the Rust side, this corresponds to either Ok(x) or Err(...).

def is_complex32(self) -> bool:

Tests if this [PyRegisterData] wraps a [RegisterData::complex32] value

def as_complex32(self) -> Optional[List[List[complex]]]:

Returns x if this [PyRegisterData] wraps a RegisterData::complex32(x); otherwise returns (Python) None. On the Rust side, this corresponds to either Some(x) or [None].

def to_complex32(self) -> List[List[complex]]:

Returns x if this [PyRegisterData] wraps a RegisterData::complex32(x); otherwise raises a ValueError. On the Rust side, this corresponds to either Ok(x) or Err(...).

def as_ndarray( self) -> Union[numpy.ndarray[Any, numpy.dtype[numpy.int64]], numpy.ndarray[Any, numpy.dtype[numpy.float64]], numpy.ndarray[Any, numpy.dtype[numpy.complex128]]]:

Returns the values as an ndarray.

class QCSClient:
def load(profile_name=None):
qvm_url
api_url
oauth_session
grpc_api_url
quilc_url
class ExecutionError(builtins.RuntimeError):

Error encountered when executing a program.

class RegisterMatrixConversionError(builtins.ValueError):

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

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.

def _gather_diagnostics():
__version__: str = $CARGO_MAKE_PROJECT_VERSION