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

qcs_sdk/compiler/quilc.pyi

@@ -0,0 +1,316 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+import collections.abc
+import typing
+from qcs_sdk import QcsSdkError
+from qcs_sdk.qpu.isa import InstructionSetArchitecture
+from quil.program import Program
+
+@typing.final
+class CompilationResult:
+    r"""
+    The result of compiling a Quil program to native quil with `quilc`
+    """
+    @property
+    def native_quil_metadata(self) -> typing.Optional[NativeQuilMetadata]:
+        r"""
+        Metadata about the compiled program
+        """
+    @property
+    def program(self) -> Program:
+        r"""
+        The compiled program
+        """
+
+@typing.final
+class CompilerOpts:
+    r"""
+    A set of options that determine the behavior of compiling programs with quilc
+    """
+    def __new__(cls, timeout: typing.Optional[builtins.float] = 30.0, protoquil: typing.Optional[builtins.bool] = None) -> CompilerOpts:
+        r"""
+        Create a new instance of `CompilerOpts`.
+        """
+    @staticmethod
+    def default() -> CompilerOpts:
+        r"""
+        Create a new instance of `CompilerOpts` with default values.
+        """
+
+@typing.final
+class ConjugateByCliffordRequest:
+    r"""
+    Request to conjugate a Pauli Term by a Clifford element.
+    """
+    @property
+    def clifford(self) -> builtins.str:
+        r"""
+        Clifford element.
+        """
+    @property
+    def pauli(self) -> PauliTerm:
+        r"""
+        Pauli Term to conjugate.
+        """
+    def __new__(cls, pauli: PauliTerm, clifford: builtins.str) -> ConjugateByCliffordRequest: ...
+
+@typing.final
+class ConjugatePauliByCliffordRequest:
+    r"""
+    The "outer" request shape for a `conjugate_pauli_by_clifford` request.
+    """
+    @property
+    def args(self) -> builtins.list[ConjugateByCliffordRequest]: ...
+
+@typing.final
+class ConjugatePauliByCliffordResponse:
+    r"""
+    Conjugate Pauli by Clifford response.
+    """
+    @property
+    def pauli(self) -> builtins.str:
+        r"""
+        Description of the encoded Pauli.
+        """
+    @property
+    def phase(self) -> builtins.int:
+        r"""
+        Encoded global phase factor on the emitted Pauli.
+        """
+
+@typing.final
+class GenerateRandomizedBenchmarkingSequenceResponse:
+    r"""
+    Randomly generated benchmarking sequence response.
+    """
+    @property
+    def sequence(self) -> builtins.list[builtins.list[builtins.int]]:
+        r"""
+        List of Cliffords, each expressed as a list of generator indices.
+        """
+
+@typing.final
+class NativeQuilMetadata:
+    r"""
+    Metadata about a program compiled to native quil.
+    """
+    def __eq__(self, other: builtins.object) -> builtins.bool: ...
+    def __getnewargs__(self) -> tuple[typing.Optional[builtins.list[builtins.int]], typing.Optional[builtins.int], typing.Optional[builtins.int], typing.Optional[builtins.int], typing.Optional[builtins.float], typing.Optional[builtins.float], typing.Optional[builtins.int], typing.Optional[builtins.float]]: ...
+    def __new__(cls, final_rewiring: typing.Optional[typing.Sequence[builtins.int]], gate_depth: typing.Optional[builtins.int], gate_volume: typing.Optional[builtins.int], multiqubit_gate_depth: typing.Optional[builtins.int], program_duration: typing.Optional[builtins.float], program_fidelity: typing.Optional[builtins.float], topological_swaps: typing.Optional[builtins.int], qpu_runtime_estimation: typing.Optional[builtins.float]) -> NativeQuilMetadata:
+        r"""
+        Construct a new `NativeQuilMetadata` from arguments.
+        """
+    def __repr__(self) -> builtins.str:
+        r"""
+        Implements `__repr__` for Python in terms of the Rust
+        [`Debug`](std::fmt::Debug) implementation.
+        """
+
+@typing.final
+class PauliTerm:
+    r"""
+    Pauli Term
+    """
+    @property
+    def indices(self) -> builtins.list[builtins.int]:
+        r"""
+        Qubit indices onto which the factors of the Pauli term are applied.
+        """
+    @property
+    def symbols(self) -> builtins.list[builtins.str]:
+        r"""
+        Ordered factors of the Pauli term.
+        """
+    def __new__(cls, indices: typing.Sequence[builtins.int], symbols: typing.Sequence[builtins.str]) -> PauliTerm: ...
+
+@typing.final
+class QuilcClient:
+    r"""
+    Client used to communicate with Quilc.
+    """
+    def __new__(cls) -> QuilcClient: ...
+    @staticmethod
+    def new_libquil() -> QuilcClient: ...
+    @staticmethod
+    def new_rpcq(endpoint: builtins.str) -> QuilcClient:
+        r"""
+        Construct a `QuilcClient` that uses RPCQ to communicate with Quilc.
+        """
+
+class QuilcError(QcsSdkError):
+    r"""
+    Errors encountered compiling a Quil program.
+    """
+    ...
+
+@typing.final
+class RandomizedBenchmarkingRequest:
+    r"""
+    Request to generate a randomized benchmarking sequence.
+    """
+    @property
+    def depth(self) -> builtins.int:
+        r"""
+        Depth of the benchmarking sequence.
+        """
+    @property
+    def gateset(self) -> builtins.list[builtins.str]:
+        r"""
+        List of Quil programs, each describing a Clifford.
+        """
+    @property
+    def interleaver(self) -> typing.Optional[builtins.str]:
+        r"""
+        Fixed Clifford, specified as a Quil string, to interleave through an RB sequence.
+        """
+    @property
+    def qubits(self) -> builtins.int:
+        r"""
+        Number of qubits involved in the benchmarking sequence.
+        """
+    @property
+    def seed(self) -> typing.Optional[builtins.int]:
+        r"""
+        PRNG seed. Set this to guarantee repeatable results.
+        """
+    def __new__(cls, depth: builtins.int, qubits: builtins.int, gateset: typing.Sequence[builtins.str], seed: typing.Optional[builtins.int], interleaver: typing.Optional[builtins.str]) -> RandomizedBenchmarkingRequest: ...
+
+@typing.final
+class TargetDevice:
+    r"""
+    Description of a device to compile for.
+    """
+    @staticmethod
+    def from_isa(isa: InstructionSetArchitecture) -> TargetDevice:
+        r"""
+        Create a [`TargetDevice`] based on an [`InstructionSetArchitecture`].
+        
+        # Errors
+        
+        Returns a [`QuilcError`] if the [`InstructionSetArchitecture`]
+        cannot be converted into a format that Quilc understands.
+        """
+    @staticmethod
+    def from_json(value: builtins.str) -> TargetDevice:
+        r"""
+        Create a [`TargetDevice`] from a JSON string.
+        
+        # Errors
+        
+        Returns a [`QuilcError`] if the JSON is malformed.
+        """
+
+def compile_program(quil: builtins.str, target: TargetDevice, client: QuilcClient, options: typing.Optional[CompilerOpts] = None) -> CompilationResult:
+    r"""
+    Compile a quil program for a target device.
+    
+    :param quil: The Quil program to compile.
+    :param target: Architectural description of device to compile for.
+    :param client: Client used to send compilation requests to Quilc.
+    :param options: Optional compiler options. If ``None``, default values are used.
+    
+    :raises QuilcError: If compilation fails.
+    """
+
+def compile_program_async(quil: builtins.str, target: TargetDevice, client: QuilcClient, options: typing.Optional[CompilerOpts] = None) -> collections.abc.Awaitable[CompilationResult]:
+    r"""
+    Compile a quil program for a target device.
+    
+    :param quil: The Quil program to compile.
+    :param target: Architectural description of device to compile for.
+    :param client: Client used to send compilation requests to Quilc.
+    :param options: Optional compiler options. If ``None``, default values are used.
+    
+    :raises QuilcError: If compilation fails.
+    """
+
+def conjugate_pauli_by_clifford(request: ConjugateByCliffordRequest, client: QuilcClient) -> ConjugatePauliByCliffordResponse:
+    r"""
+    Given a circuit that consists only of elements of the Clifford group, return its action on a PauliTerm.
+    In particular, for Clifford C, and Pauli P, this returns the PauliTerm representing CPC^{\dagger}.
+    
+    :param request: Pauli Term conjugation request.
+    :param client: Client used to send compilation requests to Quilc.
+    
+    :raises QuilcError: If there is a failure connecting to Quilc or if the request is malformed.
+    """
+
+def conjugate_pauli_by_clifford_async(request: ConjugateByCliffordRequest, client: QuilcClient) -> collections.abc.Awaitable[ConjugatePauliByCliffordResponse]:
+    r"""
+    Given a circuit that consists only of elements of the Clifford group, return its action on a PauliTerm.
+    In particular, for Clifford C, and Pauli P, this returns the PauliTerm representing CPC^{\dagger}.
+    
+    :param request: Pauli Term conjugation request.
+    :param client: Client used to send compilation requests to Quilc.
+    
+    :raises QuilcError: If there is a failure connecting to Quilc or if the request is malformed.
+    """
+
+def generate_randomized_benchmarking_sequence(request: RandomizedBenchmarkingRequest, client: QuilcClient) -> GenerateRandomizedBenchmarkingSequenceResponse:
+    r"""
+    Construct a randomized benchmarking experiment on the given qubits, decomposing into
+    gateset. If interleaver is not provided, the returned sequence will have the form
+    
+    ```ignore
+        C_1 C_2 ... C_(depth-1) C_inv ,
+    ```
+    
+    where each C is a Clifford element drawn from gateset, C_{< depth} are randomly selected,
+    and C_inv is selected so that the entire sequence composes to the identity. If an
+    interleaver G (which must be a Clifford, and which will be decomposed into the native
+    gateset) is provided, then the sequence instead takes the form
+    
+    ```ignore
+        C_1 G C_2 G ... C_(depth-1) G C_inv .
+    ```
+    
+    :param request: Randomized benchmarking request.
+    :param client: Client used to send compilation requests to Quilc.
+    
+    :raises QuilcError: If there is a failure connecting to Quilc or if the request is malformed.
+    """
+
+def generate_randomized_benchmarking_sequence_async(request: RandomizedBenchmarkingRequest, client: QuilcClient) -> collections.abc.Awaitable[GenerateRandomizedBenchmarkingSequenceResponse]:
+    r"""
+    Construct a randomized benchmarking experiment on the given qubits, decomposing into
+    gateset. If interleaver is not provided, the returned sequence will have the form
+    
+    ```ignore
+        C_1 C_2 ... C_(depth-1) C_inv ,
+    ```
+    
+    where each C is a Clifford element drawn from gateset, C_{< depth} are randomly selected,
+    and C_inv is selected so that the entire sequence composes to the identity. If an
+    interleaver G (which must be a Clifford, and which will be decomposed into the native
+    gateset) is provided, then the sequence instead takes the form
+    
+    ```ignore
+        C_1 G C_2 G ... C_(depth-1) G C_inv .
+    ```
+    
+    :param request: Randomized benchmarking request.
+    :param client: Client used to send compilation requests to Quilc.
+    
+    :raises QuilcError: If there is a failure connecting to Quilc or if the request is malformed.
+    """
+
+def get_version_info(client: QuilcClient) -> builtins.str:
+    r"""
+    Fetch the version information from the running Quilc service.
+    
+    :param client: Client used to send compilation requests to Quilc.
+    
+    :raises QuilcError: If there is a failure connecting to Quilc.
+    """
+
+def get_version_info_async(client: QuilcClient) -> collections.abc.Awaitable[builtins.str]:
+    r"""
+    Fetch the version information from the running Quilc service.
+    
+    :param client: Client used to send compilation requests to Quilc.
+    
+    :raises QuilcError: If there is a failure connecting to Quilc.
+    """
+

qcs_sdk/diagnostics.pyi

@@ -0,0 +1,36 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+import collections.abc
+
+def get_report() -> builtins.str:
+    r"""
+    Return a string describing the package and its environment for use in bug reporting and diagnosis.
+    
+    This is a synchronous wrapper around `get_report_async`.
+    Use that version in async environments.
+    
+    Note: this format is not stable and its content may change between versions.
+    """
+
+def get_report_async() -> collections.abc.Awaitable[builtins.str]:
+    r"""
+    Return a string describing the package and its environment for use in bug reporting and diagnosis.
+    
+    Note: this format is not stable and its content may change between versions.
+    
+    # Python Usage
+    
+    ```python
+    import asyncio
+    from qcs_sdk import diagnostics
+    
+    async def main():
+        return await diagnostics.get_report_async()
+    
+    report = asyncio.run(main())
+    print(report)
+    ```
+    """
+

qcs_sdk/qpu/__init__.pyi

@@ -0,0 +1,216 @@
+# This file is automatically generated by pyo3_stub_gen
+# ruff: noqa: E501, F401
+
+import builtins
+import collections.abc
+import typing
+from qcs_sdk import QcsSdkError, RegisterMap
+from qcs_sdk.client import QCSClient
+from . import api
+from . import experimental
+from . import isa
+from . import translation
+
+class ListQuantumProcessorsError(QcsSdkError):
+    r"""
+    API Errors encountered when trying to list available quantum processors.
+    """
+    ...
+
+class MemoryValues:
+    r"""
+    A row of data containing the contents of a memory region at the end of a job.
+    
+    There is a variant for each possible type the memory region could be.
+    """
+    def __getnewargs__(self) -> tuple[builtins.list[builtins.int] | builtins.list[builtins.float]]: ...
+    def __new__(cls, values: typing.Sequence[builtins.int] | typing.Sequence[builtins.float]) -> MemoryValues: ...
+    def inner(self) -> builtins.list[builtins.int] | builtins.list[builtins.float]: ...
+    @typing.final
+    class Binary(MemoryValues):
+        r"""
+        Values that correspond to a memory region declared with the BIT or OCTET data type.
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.list[builtins.int]: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: typing.Sequence[builtins.int]) -> MemoryValues.Binary: ...
+    
+    @typing.final
+    class Integer(MemoryValues):
+        r"""
+        Values that correspond to a memory region declared with the INTEGER data type.
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.list[builtins.int]: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: typing.Sequence[builtins.int]) -> MemoryValues.Integer: ...
+    
+    @typing.final
+    class Real(MemoryValues):
+        r"""
+        Values that correspond to a memory region declared with the REAL data type.
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.list[builtins.float]: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: typing.Sequence[builtins.float]) -> MemoryValues.Real: ...
+    
+
+@typing.final
+class QPUResultData:
+    r"""
+    Encapsulates data returned from the QPU after executing a job.
+    
+    `QpuResultData` contains "mappings", which map declared memory regions
+    in a program (ie. "ro[0]") to that region's readout key in `QpuResultData.readout_values`.
+    `readout_values` maps those readout keys to the values emitted for that region
+    across all shots.
+    
+    Read more about QPU readout data in the
+    [QCS Documentation](https://docs.rigetti.com/qcs/guides/qpus-vs-qvms#qpu-readout-data)
+    """
+    @property
+    def mappings(self) -> builtins.dict[builtins.str, builtins.str]:
+        r"""
+        Mappings of a memory region (ie. "ro[0]") to its key name in `readout_values` (ie. "q0").
+        """
+    @property
+    def memory_values(self) -> builtins.dict[builtins.str, MemoryValues]:
+        r"""
+        The final contents of each memory region, keyed on region name.
+        """
+    @property
+    def readout_values(self) -> builtins.dict[builtins.str, ReadoutValues]:
+        r"""
+        Mapping of a readout values identifier (ie. "q0") to a set of `ReadoutValues`.
+        """
+    def __getnewargs__(self) -> tuple[builtins.dict[builtins.str, builtins.str], builtins.dict[builtins.str, ReadoutValues], builtins.dict[builtins.str, MemoryValues]]: ...
+    def __new__(cls, mappings: typing.Mapping[builtins.str, builtins.str], readout_values: typing.Mapping[builtins.str, ReadoutValues], memory_values: typing.Mapping[builtins.str, MemoryValues]) -> QPUResultData:
+        r"""
+        Construct a new `QPUResultData` from mappings and values.
+        """
+    def __repr__(self) -> builtins.str:
+        r"""
+        Implements `__repr__` for Python in terms of the Rust
+        [`Debug`](std::fmt::Debug) implementation.
+        """
+    def to_raw_readout_data(self) -> RawQPUReadoutData:
+        r"""
+        Get the raw readout data as a flattened structure.
+        """
+    def to_register_map(self) -> RegisterMap:
+        r"""
+        Convert 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
+        
+        Returns a [`RegisterMatrixConversionError`] if the 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.
+        """
+
+@typing.final
+class RawQPUReadoutData:
+    r"""
+    A wrapper type for data returned by the QPU in a more flat structure than
+    [`QpuResultData`] offers. This makes it more convenient to work with
+    the data if you don't care what type of number the readout values for
+    each register contains.
+    """
+    @property
+    def mappings(self) -> builtins.dict[builtins.str, builtins.str]: ...
+    @property
+    def memory_values(self) -> builtins.dict[builtins.str, list]: ...
+    @property
+    def readout_values(self) -> builtins.dict[builtins.str, list]: ...
+    def __repr__(self) -> builtins.str:
+        r"""
+        Implements `__repr__` for Python in terms of the Rust
+        [`Debug`](std::fmt::Debug) implementation.
+        """
+
+class ReadoutValues:
+    r"""
+    A row of readout values from the QPU.
+    
+    Each row contains all the values emitted to a memory reference across all shots.
+    There is a variant for each possible type the list of readout values could be.
+    """
+    def __getnewargs__(self) -> tuple[builtins.list[builtins.int] | builtins.list[builtins.float] | builtins.list[builtins.complex]]: ...
+    def __new__(cls, values: typing.Sequence[builtins.int] | typing.Sequence[builtins.float] | typing.Sequence[builtins.complex]) -> ReadoutValues: ...
+    def inner(self) -> builtins.list[builtins.int] | builtins.list[builtins.float] | builtins.list[builtins.complex]: ...
+    @typing.final
+    class Complex(ReadoutValues):
+        r"""
+        Complex readout values
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.list[builtins.complex]: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: typing.Sequence[builtins.complex]) -> ReadoutValues.Complex: ...
+    
+    @typing.final
+    class Integer(ReadoutValues):
+        r"""
+        Integer readout values
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.list[builtins.int]: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: typing.Sequence[builtins.int]) -> ReadoutValues.Integer: ...
+    
+    @typing.final
+    class Real(ReadoutValues):
+        r"""
+        Real numbered readout values
+        """
+        __match_args__ = ("_0",)
+        @property
+        def _0(self) -> builtins.list[builtins.float]: ...
+        def __getitem__(self, key: builtins.int) -> typing.Any: ...
+        def __len__(self) -> builtins.int: ...
+        def __new__(cls, _0: typing.Sequence[builtins.float]) -> ReadoutValues.Real: ...
+    
+
+def list_quantum_processors(client: typing.Optional[QCSClient] = None, timeout: typing.Optional[builtins.float] = None) -> builtins.list[builtins.str]:
+    r"""
+    Returns all available Quantum Processor (QPU) IDs.
+    
+    :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 timeout: Maximum duration to wait for API calls to complete, in seconds.
+    
+    :raises ListQuantumProcessorsError: If the request to list available QPU IDs failed.
+    """
+
+def list_quantum_processors_async(client: typing.Optional[QCSClient] = None, timeout: typing.Optional[builtins.float] = None) -> collections.abc.Awaitable[builtins.list[builtins.str]]:
+    r"""
+    Returns all available Quantum Processor (QPU) IDs.
+    
+    :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 timeout: Maximum duration to wait for API calls to complete, in seconds.
+    
+    :raises ListQuantumProcessorsError: If the request to list available QPU IDs failed.
+    """
+