qcs 0.26.1

# 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.
    """