qcs_sdk.qpu.api 

 1# This file is automatically generated by pyo3_stub_gen
 2# ruff: noqa: F401
 3
 4from qcs_sdk._qcs_sdk.qpu.api import APIExecutionOptions, APIExecutionOptionsBuilder, BuildOptionsError, ConnectionStrategy, ExecutionOptions, ExecutionOptionsBuilder, ExecutionResult, ExecutionResults, QpuApiDuration, QpuApiError, SubmissionError, cancel_job, cancel_job_async, cancel_jobs, cancel_jobs_async, retrieve_results, retrieve_results_async, submit, submit_async, submit_with_parameter_batch, submit_with_parameter_batch_async
 5__all__ = [
 6    "APIExecutionOptions",
 7    "APIExecutionOptionsBuilder",
 8    "BuildOptionsError",
 9    "ConnectionStrategy",
10    "ExecutionOptions",
11    "ExecutionOptionsBuilder",
12    "ExecutionResult",
13    "ExecutionResults",
14    "QpuApiDuration",
15    "QpuApiError",
16    "SubmissionError",
17    "cancel_job",
18    "cancel_job_async",
19    "cancel_jobs",
20    "cancel_jobs_async",
21    "retrieve_results",
22    "retrieve_results_async",
23    "submit",
24    "submit_async",
25    "submit_with_parameter_batch",
26    "submit_with_parameter_batch_async",
27]
class APIExecutionOptions:

Options available when executing a job on a QPU, particular to the execution service's API.

This is a conventent alias for [InnerApiExecutionOptions] which provides a builder.

Use [Default] to get a reasonable set of defaults, or start with [ApiExecutionOptionsBuilder] to build a custom set of options.

def builder():

Get an [ExecutionOptionsBuilder] that can be used to build a custom [ExecutionOptions].

def default():
bypass_settings_protection

Get the configured bypass_settings_protection value.

timeout

Get the configured timeout value.

Note, this is the timeout while running a job; the job will be evicted from the hardware once this time has elapsed.

If unset, the job's estimated duration will be used; if the job does not have an estimated duration, the default timeout is selected by the service.

The service may also enforce a maximum value for this field.

class APIExecutionOptionsBuilder:

Builder for ApiExecutionOptions.

def default():
def build(self, /):
timeout
bypass_settings_protection
class BuildOptionsError(qcs_sdk.qpu.api.QpuApiError):

Errors building execution options.

class ConnectionStrategy:

The connection strategy to use when submitting and retrieving jobs from a QPU.

def default():
def get_endpoint_id(self, /):
class ConnectionStrategy.Gateway(qcs_sdk.qpu.api.ConnectionStrategy):

Connect through the publicly accessible gateway.

class ConnectionStrategy.DirectAccess(qcs_sdk.qpu.api.ConnectionStrategy):

Connect directly to the default endpoint, bypassing the gateway. Should only be used when you have direct network access and an active reservation.

class ConnectionStrategy.EndpointId(qcs_sdk.qpu.api.ConnectionStrategy):

Connect directly to a specific endpoint using its ID.

class ConnectionStrategy.EndpointAddress(qcs_sdk.qpu.api.ConnectionStrategy):

Connect directly to a specific endpoint by its gRPC address, bypassing the gateway.

Should only be used when you have direct network access.

class ExecutionOptions:

Options available when executing a job on a QPU.

Use [Default] to get a reasonable set of defaults, or start with [ExecutionOptionsBuilder] to build a custom set of options.

def default():
def builder():
timeout_seconds
api_options
connection_strategy

The [ConnectionStrategy] to use to establish a connection to the QPU.

class ExecutionOptionsBuilder:

Builder for ExecutionOptions.

def default():
def build(self, /):
connection_strategy
api_options
timeout_seconds
class ExecutionResult:

Execution readout data from a particular memory location.

def from_register(register):

Build an ExecutionResult from a Register.

data

The result data for all shots by the particular memory location.

dtype

The type of the result data (as a numpy dtype).

shape

The shape of the result data.

class ExecutionResults:

Execution readout data for all memory locations.

memory

The final state of memory for parameters that were read from and written to during the execution of the program.

buffers

The readout results of execution, mapping a published filter node to its data.

See TranslationResult.ro_sources which provides the mapping from the filter node name to the name of the memory declaration in the source program.

execution_duration_microseconds

The time spent executing the program.

class QpuApiDuration:

The duration of an API call.

seconds
nanos
class QpuApiError(qcs_sdk._qcs_sdk.QcsSdkError):

Errors that can occur while attempting to establish a connection to the QPU.

class SubmissionError(qcs_sdk.qpu.api.QpuApiError):

Errors that may occur when submitting a program for execution.

def cancel_job( job_id, quantum_processor_id=None, client=None, execution_options=None):

Cancel a job that has yet to begin executing.

This action is not atomic, and will attempt to cancel a job even if it cannot be cancelled. A job can be cancelled only if it has not yet started executing.

Success response indicates only that the request was received. Cancellation is not guaranteed, as it is based on job state at the time of cancellation, and is completed on a best effort basis.

Parameters
  • job_id: The job ID to cancel.
  • quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use.
  • execution_options: The ExecutionOptions to use.
def cancel_job_async( job_id, quantum_processor_id=None, client=None, execution_options=None):

Cancel a job that has yet to begin executing.

This action is not atomic, and will attempt to cancel a job even if it cannot be cancelled. A job can be cancelled only if it has not yet started executing.

Success response indicates only that the request was received. Cancellation is not guaranteed, as it is based on job state at the time of cancellation, and is completed on a best effort basis.

Parameters
  • job_id: The job ID to cancel.
  • quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use.
  • execution_options: The ExecutionOptions to use.
def cancel_jobs( job_ids, quantum_processor_id=None, client=None, execution_options=None):

Cancel all given jobs that have yet to begin executing.

This action is not atomic, and will attempt to cancel every job even when some jobs cannot be cancelled. A job can be cancelled only if it has not yet started executing.

Success response indicates only that the request was received. Cancellation is not guaranteed, as it is based on job state at the time of cancellation, and is completed on a best effort basis.

Parameters
  • job_ids: The job IDs to cancel.
  • quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use.
  • execution_options: The ExecutionOptions to use.
def cancel_jobs_async( job_ids, quantum_processor_id=None, client=None, execution_options=None):

Cancel all given jobs that have yet to begin executing.

This action is not atomic, and will attempt to cancel every job even when some jobs cannot be cancelled. A job can be cancelled only if it has not yet started executing.

Success response indicates only that the request was received. Cancellation is not guaranteed, as it is based on job state at the time of cancellation, and is completed on a best effort basis.

Parameters
  • job_ids: The job IDs to cancel.
  • quantum_processor_id: The quantum processor to execute the job on. This parameter is required unless using the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use.
  • execution_options: The ExecutionOptions to use.
def retrieve_results( job_id, quantum_processor_id=None, client=None, execution_options=None):

Fetches execution results for the given QCS Job ID.

Parameters
  • job_id: The ID of the job to retrieve results for.
  • quantum_processor_id: The ID of the quantum processor the job ran on. This field is required, unless being used with the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use. Creates one using environment configuration if unset - see https: //docs.rigetti.com/qcs/references/qcs-client-configuration
  • execution_options: The ExecutionOptions to use.

:returns: Results from execution.

Raises
  • LoadClientError: If there is an issue loading the QCS Client configuration.
  • QpuApiError: If there was a problem retrieving the results.
def retrieve_results_async( job_id, quantum_processor_id=None, client=None, execution_options=None):

Fetches execution results for the given QCS Job ID.

Parameters
  • job_id: The ID of the job to retrieve results for.
  • quantum_processor_id: The ID of the quantum processor the job ran on. This field is required, unless being used with the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use. Creates one using environment configuration if unset - see https: //docs.rigetti.com/qcs/references/qcs-client-configuration
  • execution_options: The ExecutionOptions to use.

:returns: Results from execution.

Raises
  • LoadClientError: If there is an issue loading the QCS Client configuration.
  • QpuApiError: If there was a problem retrieving the results.
def submit( program, patch_values, quantum_processor_id=None, client=None, execution_options=None):

Submits an executable program to be run on the specified QPU.

Parameters
  • program: An executable program (see qcs_sdk.qpu.translation.translate).
  • patch_values: A mapping of symbols to their desired values (see build_patch_values).
  • quantum_processor_id: The ID of the quantum processor to run the executable on. This field is required, unless being used with the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use. Creates one using environment configuration if unset. See https://docs.rigetti.com/qcs/references/qcs-client-configuration for more information.
  • execution_options: The ExecutionOptions to use. If the connection strategy option used is ConnectionStrategy.endpoint_id("endpoint_id") or ConnectionStrategy.endpoint_address("http://some_endpoint_address"), then direct access to "endpoint_id" overrides the quantum_processor_id parameter.

:returns: The ID of the submitted job which can be used to fetch results.

Raises
  • LoadClientError: If there is an issue loading the QCS Client configuration.
  • SubmissionError: If there was a problem submitting the program for execution.
def submit_async( program, patch_values, quantum_processor_id=None, client=None, execution_options=None):

Submits an executable program to be run on the specified QPU.

Parameters
  • program: An executable program (see qcs_sdk.qpu.translation.translate).
  • patch_values: A mapping of symbols to their desired values (see build_patch_values).
  • quantum_processor_id: The ID of the quantum processor to run the executable on. This field is required, unless being used with the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use. Creates one using environment configuration if unset. See https://docs.rigetti.com/qcs/references/qcs-client-configuration for more information.
  • execution_options: The ExecutionOptions to use. If the connection strategy option used is ConnectionStrategy.endpoint_id("endpoint_id") or ConnectionStrategy.endpoint_address("http://some_endpoint_address"), then direct access to "endpoint_id" overrides the quantum_processor_id parameter.

:returns: The ID of the submitted job which can be used to fetch results.

Raises
  • LoadClientError: If there is an issue loading the QCS Client configuration.
  • SubmissionError: If there was a problem submitting the program for execution.
def submit_with_parameter_batch( program, patch_values, quantum_processor_id=None, client=None, execution_options=None):

Execute a compiled program on a QPU with multiple sets of patch_values.

This action is atomic in that all jobs will be queued, or none of them will. On success, this function will return a list of strings where the length and order correspond to the patch_values given. However, note that execution in the order of given patch values is not guaranteed. If there is a failure to queue any of the jobs, then none will be queued.

Parameters
  • program: An executable program (see translate).
  • patch_values: An iterable containing one or more mapping of symbols to their desired values.
  • quantum_processor_id: The ID of the quantum processor to run the executable on. This field is required, unless being used with the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use. Creates one using environment configuration if unset - see https: //docs.rigetti.com/qcs/references/qcs-client-configuration
  • execution_options: The ExecutionOptions to use.

:returns: The IDs of the submitted jobs which can be used to fetch results.

Raises
  • LoadClientError: If there is an issue loading the QCS Client configuration.
  • SubmissionError: If there was a problem submitting any of the jobs for execution, or if no patch_values are given.
def submit_with_parameter_batch_async( program, patch_values, quantum_processor_id=None, client=None, execution_options=None):

Execute a compiled program on a QPU with multiple sets of patch_values.

This action is atomic in that all jobs will be queued, or none of them will. On success, this function will return a list of strings where the length and order correspond to the patch_values given. However, note that execution in the order of given patch values is not guaranteed. If there is a failure to queue any of the jobs, then none will be queued.

Parameters
  • program: An executable program (see translate).
  • patch_values: An iterable containing one or more mapping of symbols to their desired values.
  • quantum_processor_id: The ID of the quantum processor to run the executable on. This field is required, unless being used with the ConnectionStrategy.endpoint_id() or ConnectionStrategy.endpoint_address() execution option.
  • client: The Qcs client to use. Creates one using environment configuration if unset - see https: //docs.rigetti.com/qcs/references/qcs-client-configuration
  • execution_options: The ExecutionOptions to use.

:returns: The IDs of the submitted jobs which can be used to fetch results.

Raises
  • LoadClientError: If there is an issue loading the QCS Client configuration.
  • SubmissionError: If there was a problem submitting any of the jobs for execution, or if no patch_values are given.