qcs-sdk-python 0.26.0__cp313-cp313-win_amd64.whl

qcs_sdk/qpu/api.pyi

@@ -0,0 +1,484 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+import collections.abc
+import datetime
+import typing
+from qcs_sdk import QcsSdkError
+from qcs_sdk.client import QCSClient
+from qcs_sdk.qpu import MemoryValues
+
+@typing.final
+class APIExecutionOptions:
+    r"""
+    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.
+    """
+    @property
+    def bypass_settings_protection(self) -> builtins.bool:
+        r"""
+        Get the configured `bypass_settings_protection` value.
+        """
+    @property
+    def timeout(self) -> typing.Optional[QpuApiDuration]:
+        r"""
+        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.
+        """
+    def __new__(cls, bypass_settings_protection: builtins.bool = False, timeout: typing.Optional[datetime.timedelta] = None) -> APIExecutionOptions: ...
+    def __repr__(self) -> builtins.str:
+        r"""
+        Implements `__repr__` for Python in terms of the Rust
+        [`Debug`](std::fmt::Debug) implementation.
+        """
+    @staticmethod
+    def builder() -> APIExecutionOptionsBuilder:
+        r"""
+        Get an [`ExecutionOptionsBuilder`] that can be used to build a custom [`ExecutionOptions`].
+        """
+    @staticmethod
+    def default() -> APIExecutionOptions: ...
+
+@typing.final
+class APIExecutionOptionsBuilder:
+    r"""
+    Builder for [`ApiExecutionOptions`](struct.ApiExecutionOptions.html).
+    """
+    @property
+    def bypass_settings_protection(self) -> typing.Never:
+        r"""
+        DO NOT CALL THIS METHOD.
+        
+        `mypy` requires write-only properties to have a getter,
+        but this method is not actually available at runtime.
+        """
+    @bypass_settings_protection.setter
+    def bypass_settings_protection(self, value: builtins.bool) -> None: ...
+    @property
+    def timeout(self) -> typing.Never:
+        r"""
+        DO NOT CALL THIS METHOD.
+        
+        `mypy` requires write-only properties to have a getter,
+        but this method is not actually available at runtime.
+        """
+    @timeout.setter
+    def timeout(self, value: typing.Optional[QpuApiDuration]) -> None: ...
+    def __new__(cls) -> APIExecutionOptionsBuilder: ...
+    def build(self) -> APIExecutionOptions: ...
+    @staticmethod
+    def default() -> APIExecutionOptionsBuilder: ...
+
+class BuildOptionsError(QpuApiError):
+    r"""
+    Errors building execution options.
+    """
+    ...
+
+class ConnectionStrategy:
+    r"""
+    The connection strategy to use when submitting and retrieving jobs from a QPU.
+    """
+    def __getnewargs__(self) -> tuple[str] | tuple[()]: ...
+    def __repr__(self) -> builtins.str:
+        r"""
+        Implements `__repr__` for Python in terms of the Rust
+        [`Debug`](std::fmt::Debug) implementation.
+        """
+    @staticmethod
+    def default() -> ConnectionStrategy: ...
+    def get_endpoint_id(self) -> builtins.str: ...
+    @typing.final
+    class DirectAccess(ConnectionStrategy):
+        r"""
+        Connect directly to the default endpoint, bypassing the gateway. Should only be used when you
+        have direct network access and an active reservation.
+        """
+        __match_args__ = ()
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls) -> ConnectionStrategy.DirectAccess: ...
+    
+    @typing.final
+    class EndpointAddress(ConnectionStrategy):
+        r"""
+        Connect directly to a specific endpoint by its gRPC address, bypassing the gateway.
+        
+        Should only be used when you have direct network access.
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.str: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: builtins.str) -> ConnectionStrategy.EndpointAddress: ...
+        
+    @typing.final
+    class EndpointId(ConnectionStrategy):
+        r"""
+        Connect directly to a specific endpoint using its ID.
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.str: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: builtins.str) -> ConnectionStrategy.EndpointId: ...
+    
+    @typing.final
+    class Gateway(ConnectionStrategy):
+        r"""
+        Connect through the publicly accessible gateway.
+        """
+        __match_args__ = ()
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls) -> ConnectionStrategy.Gateway: ...
+    
+
+@typing.final
+class ExecutionOptions:
+    r"""
+    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.
+    """
+    @property
+    def api_options(self) -> typing.Optional[APIExecutionOptions]: ...
+    @property
+    def connection_strategy(self) -> ConnectionStrategy:
+        r"""
+        The [`ConnectionStrategy`] to use to establish a connection to the QPU.
+        """
+    @property
+    def timeout_seconds(self) -> typing.Optional[builtins.float]: ...
+    def __eq__(self, other: builtins.object) -> builtins.bool: ...
+    def __getnewargs__(self) -> tuple[ConnectionStrategy, typing.Optional[datetime.timedelta], typing.Optional[APIExecutionOptions]]: ...
+    def __new__(cls, connection_strategy: ConnectionStrategy = ..., timeout: typing.Optional[datetime.timedelta] = ..., api_options: typing.Optional[APIExecutionOptions] = None) -> ExecutionOptions: ...
+    def __repr__(self) -> builtins.str:
+        r"""
+        Implements `__repr__` for Python in terms of the Rust
+        [`Debug`](std::fmt::Debug) implementation.
+        """
+    @staticmethod
+    def builder() -> ExecutionOptionsBuilder: ...
+    @staticmethod
+    def default() -> ExecutionOptions: ...
+
+@typing.final
+class ExecutionOptionsBuilder:
+    r"""
+    Builder for [`ExecutionOptions`](struct.ExecutionOptions.html).
+    """
+    @property
+    def api_options(self) -> typing.Never:
+        r"""
+        DO NOT CALL THIS METHOD.
+        
+        `mypy` requires write-only properties to have a getter,
+        but this method is not actually available at runtime.
+        """
+    @api_options.setter
+    def api_options(self, value: typing.Optional[APIExecutionOptions]) -> None: ...
+    @property
+    def connection_strategy(self) -> typing.Never:
+        r"""
+        DO NOT CALL THIS METHOD.
+        
+        `mypy` requires write-only properties to have a getter,
+        but this method is not actually available at runtime.
+        """
+    @connection_strategy.setter
+    def connection_strategy(self, value: ConnectionStrategy) -> None: ...
+    @property
+    def timeout_seconds(self) -> typing.Never:
+        r"""
+        DO NOT CALL THIS METHOD.
+        
+        `mypy` requires write-only properties to have a getter,
+        but this method is not actually available at runtime.
+        """
+    @timeout_seconds.setter
+    def timeout_seconds(self, value: typing.Optional[builtins.float]) -> None: ...
+    def __new__(cls) -> ExecutionOptionsBuilder: ...
+    def build(self) -> ExecutionOptions: ...
+    @staticmethod
+    def default() -> ExecutionOptionsBuilder: ...
+
+@typing.final
+class ExecutionResult:
+    r"""
+    Execution readout data from a particular memory location.
+    """
+    @property
+    def data(self) -> builtins.list[builtins.int] | builtins.list[builtins.complex]:
+        r"""
+        The result data for all shots by the particular memory location.
+        """
+    @property
+    def dtype(self) -> builtins.str:
+        r"""
+        The type of the result data (as a `numpy` `dtype`).
+        """
+    @property
+    def shape(self) -> builtins.list[builtins.int]:
+        r"""
+        The shape of the result data.
+        """
+    def __getnewargs__(self) -> tuple[builtins.list[builtins.int] | builtins.list[builtins.complex]]: ...
+    def __new__(cls, register: typing.Sequence[builtins.int] | typing.Sequence[builtins.complex]) -> ExecutionResult: ...
+    @staticmethod
+    def from_register(register: typing.Sequence[builtins.int] | typing.Sequence[builtins.complex]) -> ExecutionResult:
+        r"""
+        Build an `ExecutionResult` from a `Register`.
+        """
+
+@typing.final
+class ExecutionResults:
+    r"""
+    Execution readout data for all memory locations.
+    """
+    @property
+    def buffers(self) -> builtins.dict[builtins.str, ExecutionResult]:
+        r"""
+        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.
+        """
+    @property
+    def execution_duration_microseconds(self) -> typing.Optional[builtins.int]:
+        r"""
+        The time spent executing the program.
+        """
+    @property
+    def memory(self) -> builtins.dict[builtins.str, MemoryValues]:
+        r"""
+        The final state of memory for parameters that were read from and written to during
+        the execution of the program.
+        """
+    def __new__(cls, buffers: typing.Mapping[builtins.str, ExecutionResult], memory: typing.Mapping[builtins.str, MemoryValues], execution_duration_microseconds: typing.Optional[builtins.int] = None) -> ExecutionResults: ...
+
+@typing.final
+class QpuApiDuration:
+    r"""
+    The duration of an API call.
+    """
+    @property
+    def nanos(self) -> builtins.int: ...
+    @property
+    def seconds(self) -> builtins.int: ...
+    def __new__(cls, seconds: builtins.int, nanos: builtins.int) -> QpuApiDuration: ...
+
+class QpuApiError(QcsSdkError):
+    r"""
+    Errors that can occur while attempting to establish a connection to the QPU.
+    """
+    ...
+
+class SubmissionError(QpuApiError):
+    r"""
+    Errors that may occur when submitting a program for execution.
+    """
+    ...
+
+def cancel_job(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> None:
+    r"""
+    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.
+    
+    :param job_id: The job ID to cancel.
+    :param 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.
+    :param client: The ``Qcs`` client to use.
+    :param execution_options: The ``ExecutionOptions`` to use.
+    """
+
+def cancel_job_async(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[None]:
+    r"""
+    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.
+    
+    :param job_id: The job ID to cancel.
+    :param 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.
+    :param client: The ``Qcs`` client to use.
+    :param execution_options: The ``ExecutionOptions`` to use.
+    """
+
+def cancel_jobs(job_ids: typing.Sequence[builtins.str], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> None:
+    r"""
+    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.
+    
+    :param job_ids: The job IDs to cancel.
+    :param 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.
+    :param client: The ``Qcs`` client to use.
+    :param execution_options: The ``ExecutionOptions`` to use.
+    """
+
+def cancel_jobs_async(job_ids: typing.Sequence[builtins.str], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[None]:
+    r"""
+    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.
+    
+    :param job_ids: The job IDs to cancel.
+    :param 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.
+    :param client: The ``Qcs`` client to use.
+    :param execution_options: The ``ExecutionOptions`` to use.
+    """
+
+def retrieve_results(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> ExecutionResults:
+    r"""
+    Fetches execution results for the given QCS Job ID.
+    
+    :param job_id: The ID of the job to retrieve results for.
+    :param 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.
+    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
+    :param execution_options: The ``ExecutionOptions`` to use.
+    
+    :returns: Results from execution.
+    
+    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
+    :raises QpuApiError: If there was a problem retrieving the results.
+    """
+
+def retrieve_results_async(job_id: builtins.str, quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[ExecutionResults]:
+    r"""
+    Fetches execution results for the given QCS Job ID.
+    
+    :param job_id: The ID of the job to retrieve results for.
+    :param 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.
+    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
+    :param execution_options: The ``ExecutionOptions`` to use.
+    
+    :returns: Results from execution.
+    
+    :raises LoadClientError: If there is an issue loading the QCS Client configuration.
+    :raises QpuApiError: If there was a problem retrieving the results.
+    """
+
+def submit(program: builtins.str, patch_values: typing.Mapping[builtins.str, typing.Sequence[builtins.float]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> builtins.str:
+    r"""
+    Submits an executable `program` to be run on the specified QPU.
+    
+    :param program: An executable program (see ``qcs_sdk.qpu.translation.translate``).
+    :param patch_values: A mapping of symbols to their desired values (see ``build_patch_values``).
+    :param 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.
+    :param 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.
+    :param 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.
+    :raises SubmissionError: If there was a problem submitting the program for execution.
+    """
+
+def submit_async(program: builtins.str, patch_values: typing.Mapping[builtins.str, typing.Sequence[builtins.float]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[builtins.str]:
+    r"""
+    Submits an executable `program` to be run on the specified QPU.
+    
+    :param program: An executable program (see ``qcs_sdk.qpu.translation.translate``).
+    :param patch_values: A mapping of symbols to their desired values (see ``build_patch_values``).
+    :param 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.
+    :param 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.
+    :param 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.
+    :raises SubmissionError: If there was a problem submitting the program for execution.
+    """
+
+def submit_with_parameter_batch(program: builtins.str, patch_values: typing.Sequence[typing.Mapping[builtins.str, typing.Sequence[builtins.float]]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> builtins.list[builtins.str]:
+    r"""
+    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.
+    
+    :param program: An executable program (see ``translate``).
+    :param patch_values: An iterable containing one or more mapping of symbols to their desired values.
+    :param 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.
+    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
+    :param 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.
+    :raises 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: builtins.str, patch_values: typing.Sequence[typing.Mapping[builtins.str, typing.Sequence[builtins.float]]], quantum_processor_id: typing.Optional[builtins.str] = None, client: typing.Optional[QCSClient] = None, execution_options: typing.Optional[ExecutionOptions] = None) -> collections.abc.Awaitable[builtins.list[builtins.str]]:
+    r"""
+    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.
+    
+    :param program: An executable program (see ``translate``).
+    :param patch_values: An iterable containing one or more mapping of symbols to their desired values.
+    :param 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.
+    :param client: The ``Qcs`` client to use. Creates one using environment configuration if unset - see https://docs.rigetti.com/qcs/references/qcs-client-configuration
+    :param 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.
+    :raises SubmissionError: If there was a problem submitting any of the jobs for execution, or if no ``patch_values`` are given.
+    """
+

qcs_sdk/qpu/experimental/__init__.pyi

@@ -0,0 +1,5 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+from . import random
+

qcs_sdk/qpu/experimental/random.pyi

@@ -0,0 +1,98 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+import typing
+from qcs_sdk import QcsSdkError
+
+@typing.final
+class ChooseRandomRealSubRegions:
+    r"""
+    An [`ExternedCall`] that may be used to select one or more random
+    sub-regions from a source array of real values to a destination array.
+    """
+    NAME: builtins.str = 'choose_random_real_sub_regions'
+    r"""
+    The name of the function referenced by the `PRAGMA EXTERN` and `CALL` instructions.
+    """
+    @staticmethod
+    def build_signature() -> builtins.str:
+        r"""
+        Build the signature for the `PRAGMA EXTERN choose_random_real_sub_regions` instruction.
+        
+        The signature expressed in Quil is as follows:
+        
+        ```text
+        "(destination : mut REAL[], source : REAL[], sub_region_size : INTEGER, seed : mut INTEGER)"
+        ```
+        """
+
+@typing.final
+class PrngSeedValue:
+    r"""
+    A valid seed value that may be used to initialize the PRNG. Such
+    values are in the range `[1, MAX_SEQUENCER_VALUE]` and are losslessly
+    convertible to `f64`.
+    """
+    def __new__(cls, value: builtins.int) -> PrngSeedValue:
+        r"""
+        Attempt to create a new instance of `PrngSeedValue` from a `u64`.
+        
+        # Errors
+        
+        Returns [`Error::InvalidSeed`] if the value is not in range `[1, MAX_SEQUENCER_VALUE]`
+        or if it is not losslessly convertible to `f64`.
+        """
+    def as_f64(self) -> builtins.float: ...
+
+class RandomError(QcsSdkError):
+    r"""
+    Errors that may occur using the randomization primitives defined in this module.
+    """
+    ...
+
+def choose_random_real_sub_region_indices(seed: PrngSeedValue, start_index: builtins.int, series_length: builtins.int, sub_region_count: builtins.int) -> builtins.list[builtins.int]:
+    r"""
+    Given a seed, start index, series length, and sub-region count, this function
+    will generate and return the sequence of pseudo-randomly chosen indices on
+    the Rigetti control systems.
+    
+    For instance, if the following Quil program is run for 100 shots:
+    
+    ```quil
+    # presumed sub-region size is 3.
+    DECLARE destination REAL[6] # prng invocations per shot = (6 / sub_region_size)  = 2
+    DECLARE source REAL[12]     # implicit sub-region count = (12 / sub_region_size) = 4
+    DECLARE seed INTEGER[1]
+    DECLARE ro BIT[1]
+    
+    DELAY 0 1e-6
+    
+    PRAGMA EXTERN choose_random_real_sub_regions "(destination : mut REAL[], source : REAL[], sub_region_size : INTEGER, seed : mut INTEGER)"
+    CALL choose_random_real_sub_regions destination source 3 seed
+    ```
+    
+    with a seed of 639,523, the following will provide the random sequence of sub-region indices:
+    
+    ```rust
+    use qcs::qpu::experimental::random::{choose_random_real_sub_region_indices, PrngSeedValue};
+    
+    let seed = PrngSeedValue::try_new(639_523).unwrap();
+    let start_index = 0;
+    let prng_invocations_per_shot = 2;
+    let shot_count = 100;
+    let series_length = prng_invocations_per_shot * shot_count;
+    let sub_region_count = 4;
+    let _random_indices = choose_random_real_sub_region_indices(seed, start_index, series_length, sub_region_count);
+    ```
+    """
+
+def lfsr_v1_next(seed: PrngSeedValue) -> builtins.int:
+    r"""
+    This represents the [linear feedback shift
+    register](https://en.wikipedia.org/wiki/Linear-feedback_shift_register)
+    currently implemented on Rigetti control systems. Specifically,
+    it implements a 48-bit LFSR with taps at 0-based indices 47, 46, 20, and 19.
+    The taps have been shown to produce maximal sequence lengths for 48-bit strings.
+    """
+