# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401

import builtins
import collections.abc
import numpy
import numpy.typing
import quil.instructions
import typing

class BasicBlock:
    @property
    def instructions(self) -> builtins.list[Instruction]:
        r"""
        A list of the instructions in the block, in order of definition.
        
        This does not include the label or terminator instructions.
        """
    @property
    def label(self) -> typing.Optional[Target]:
        r"""
        The label of the block, if any.
        This is used to target this block in control flow.
        """
    @property
    def terminator(self) -> typing.Optional[Instruction]:
        r"""
        The control flow terminator instruction of the block, if any.
        
        If this is ``None``, the implicit behavior is to "continue" to the subsequent block.
        """
    def __new__(cls, instance:BasicBlock) -> BasicBlock: ...
    def __repr__(self) -> builtins.str: ...
    def as_schedule_seconds(self, program:Program) -> ScheduleSeconds: ...
    def gate_depth(self, gate_minimum_qubit_count:builtins.int) -> builtins.int:
        r"""
        Return the length of the longest path
        from an initial instruction (one with no prerequisite instructions)
        to a final instruction (one with no dependent instructions),
        where the length of a path is the number of gate instructions in the path.
        
        :param gate_minimum_qubit_count:
            The minimum number of qubits in a gate
            for it to be counted in the depth.
        """

class BasicBlockScheduleError(builtins.ProgramError):
    ...

class CalibrationExpansion:
    r"""
    Details about the expansion of a calibration.
    """
    @property
    def calibration_used(self) -> CalibrationSource:
        r"""
        The calibration used to expand the instruction.
        """
    @property
    def expansions(self) -> CalibrationExpansionSourceMap:
        r"""
        The source map describing the nested expansions made.
        """
    @property
    def range(self) -> range:
        r"""
        The range of instructions in the expanded list
        which were generated by this expansion.
        """
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __repr__(self) -> builtins.str: ...

class CalibrationExpansionSourceMap:
    def __repr__(self) -> builtins.str: ...
    def entries(self) -> builtins.list[CalibrationExpansionSourceMapEntry]: ...
    def list_sources_for_calibration_used(self, calibration_used:CalibrationSource) -> builtins.list[builtins.int]:
        r"""
        Given a particular calibration (`DEFCAL` or `DEFCAL MEASURE`), =
        return the locations in the source which were expanded using that calibration.
        
        This is `O(n)` where `n` is the number of first-level calibration expansions performed.
        """
    def list_sources_for_target_index(self, target_index:builtins.int) -> builtins.list[builtins.int]:
        r"""
        Return all source ranges in the source map
        which were used to generate the target index.
        
        This is `O(n)` where `n` is the number of entries in the map.
        """
    def list_targets_for_source_index(self, source_index:builtins.int) -> builtins.list[CalibrationExpansion]:
        r"""
        Return all target ranges which were used to generate the source range.
        
        This is `O(n)` where `n` is the number of entries in the map.
        """

class CalibrationExpansionSourceMapEntry:
    r"""
    A description of the expansion of one instruction into other instructions.
    
    If present, the instruction located at `source_location` was expanded using calibrations
    into the instructions located at `target_location`.
    
    Note that both `source_location` and `target_location` are relative to the scope of expansion.
    
    In the case of a nested expansion, both describe the location relative only to that
    level of expansion and *not* the original program.
    
    Consider the following example:
    
    ```python
    DEFCAL A:
        NOP
        B
        HALT
    
    
    DEFCAL B:
        NOP
        WAIT
    
    NOP
    NOP
    NOP
    A
    ```
    
    In this program, `A` will expand into `NOP`, `B`, and `HALT`.
    Then, `B` will expand into `NOP` and `WAIT`.
    Each level of this expansion
    will have its own ``CalibrationExpansionSourceMap`` describing the expansion.
    In the map of `B` to `NOP` and `WAIT`, the `source_location` will be `1`
    because `B` is the second instruction in `DEFCAL A`,
    even though `A` is the 4th instruction (index = 3) in the original program.
    """
    def __repr__(self) -> builtins.str: ...
    def source_location(self) -> builtins.int:
        r"""
        The instruction index within the source program's body instructions.
        """
    def target_location(self) -> CalibrationExpansion:
        r"""
        The location of the expanded instruction within the target
        program's body instructions.
        """

class CalibrationSet:
    r"""
    A collection of Quil calibrations (`DEFCAL` instructions) with utility methods.
    
    This exposes the semantics similar to [`CalibrationSet`] to Python users,
    so see the documentation there for more information.
    """
    @property
    def calibrations(self) -> builtins.list[CalibrationDefinition]:
        r"""
        Return a list of all [`CalibrationDefinition`]s in the set.
        """
    @property
    def measure_calibrations(self) -> builtins.list[MeasureCalibrationDefinition]:
        r"""
        Return a list of all [`MeasureCalibrationDefinition`]s in the set.
        """
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __len__(self) -> builtins.int:
        r"""
        Return the count of contained calibrations.
        """
    def __new__(cls, calibrations:typing.Sequence[CalibrationDefinition], measure_calibrations:typing.Sequence[MeasureCalibrationDefinition]) -> CalibrationSet: ...
    def __repr__(self) -> builtins.str: ...
    def expand(self, instruction:Instruction, previous_calibrations:typing.Sequence[Instruction]) -> typing.Optional[builtins.list[Instruction]]:
        r"""
        Given an instruction, return the instructions to which it is expanded if there is a match.
        Recursively calibrate instructions, returning an error if a calibration directly or indirectly
        expands into itself.
        
        Return only the expanded instructions; for more information about the expansion process,
        see [`Self::expand_with_detail`].
        """
    def extend(self, other:CalibrationSet) -> None:
        r"""
        Append another [`CalibrationSet`] onto this one.
        
        Calibrations with conflicting [`CalibrationSignature`]s are overwritten by the ones in the
        given set.
        """
    def get_match_for_gate(self, gate:Gate) -> typing.Optional[CalibrationDefinition]:
        r"""
        Return the final calibration which matches the gate per the QuilT specification:
        
        A calibration matches a gate if:
        1. It has the same name
        2. It has the same modifiers
        3. It has the same qubit count (any mix of fixed & variable)
        4. It has the same parameter count (both specified and unspecified)
        5. All fixed qubits in the calibration definition match those in the gate
        6. All specified parameters in the calibration definition match those in the gate
        """
    def get_match_for_measurement(self, measurement:Measurement) -> typing.Optional[MeasureCalibrationDefinition]:
        r"""
        Returns the last-specified ``MeasureCalibrationDefinition`` that matches the target
        qubit (if any), or otherwise the last-specified one that specified no qubit.
        
        If multiple calibrations match the measurement, the precedence is as follows:
        
          1. Match fixed qubit.
          2. Match variable qubit.
          3. Match no qubit.
        
        In the case of multiple calibrations with equal precedence, the last one wins.
        """
    def insert_calibration(self, calibration:CalibrationDefinition) -> typing.Optional[CalibrationDefinition]:
        r"""
        Insert a [`CalibrationDefinition`] into the set.
        
        If a calibration with the same [signature][crate::instruction::CalibrationSignature] already
        exists in the set, it will be replaced and the old calibration will be returned.
        """
    def insert_measurement_calibration(self, calibration:MeasureCalibrationDefinition) -> typing.Optional[MeasureCalibrationDefinition]:
        r"""
        Insert a [`MeasureCalibrationDefinition`] into the set.
        
        If a calibration with the same [signature][crate::instruction::CalibrationSignature] already
        exists in the set, it will be replaced and the old calibration will be returned.
        """
    def is_empty(self) -> builtins.bool:
        r"""
        Return true if this contains no data.
        """
    def to_instructions(self) -> builtins.list[Instruction]:
        r"""
        Return the Quil instructions which describe the contained calibrations.
        """

class CalibrationSource:
    r"""
    The source of a calibration, either a [`CalibrationIdentifier`] or a
    [`MeasureCalibrationIdentifier`].
    """
    def __getnewargs__(self) -> tuple[CalibrationIdentifier | MeasureCalibrationIdentifier]: ...
    def __repr__(self) -> builtins.str: ...
    class Calibration(CalibrationSource):
        r"""
        Describes a `DEFCAL` instruction
        """
        __match_args__ = ("_0",)
        @property
        def _0(self) -> CalibrationIdentifier: ...
        def __getitem__(self, key:builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0:CalibrationIdentifier) -> CalibrationSource.Calibration: ...
    
    class MeasureCalibration(CalibrationSource):
        r"""
        Describes a `DEFCAL MEASURE` instruction
        """
        __match_args__ = ("_0",)
        @property
        def _0(self) -> MeasureCalibrationIdentifier: ...
        def __getitem__(self, key:builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0:MeasureCalibrationIdentifier) -> CalibrationSource.MeasureCalibration: ...
    

class ComputedScheduleError(builtins.ProgramError):
    r"""
    Error raised if the computed schedule is invalid.
    """
    ...

class ControlFlowGraph:
    def __new__(cls, instance:ControlFlowGraph) -> ControlFlowGraph: ...
    def __repr__(self) -> builtins.str: ...
    def basic_blocks(self) -> builtins.list[BasicBlock]:
        r"""
        Return a list of all the basic blocks in the control flow graph, in order of definition.
        """
    def has_dynamic_control_flow(self) -> builtins.bool:
        r"""
        Return ``True`` if the program has dynamic control flow, i.e. contains a conditional branch instruction.
        
        ``False`` does not imply that there is only one basic block in the program.
        Multiple basic blocks may have non-conditional control flow among them,
        in which the execution order is deterministic and does not depend on program state.
        This may be a sequence of basic blocks with fixed `JUMP`s or without explicit terminators.
        """

class FrameSet:
    r"""
    A collection of Quil frames (`DEFFRAME` instructions) with utility methods.
    """
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __len__(self) -> builtins.int:
        r"""
        Return the number of frames described within.
        """
    def __new__(cls) -> FrameSet: ...
    def __repr__(self) -> builtins.str: ...
    def get(self, identifier:FrameIdentifier) -> typing.Optional[builtins.dict[builtins.str, AttributeValue]]:
        r"""
        Retrieve the attributes of a frame by its identifier.
        """
    def get_all_frames(self) -> builtins.dict[FrameIdentifier, builtins.dict[builtins.str, AttributeValue]]: ...
    def get_keys(self) -> builtins.list[FrameIdentifier]:
        r"""
        Return a list of all ``FrameIdentifier``s described by this ``FrameSet``.
        """
    def insert(self, identifier:FrameIdentifier, attributes:typing.Mapping[builtins.str, AttributeValue]) -> None:
        r"""
        Insert a new frame by ID, overwriting any existing one.
        """
    def intersection(self, identifiers:builtins.set[FrameIdentifier]) -> FrameSet:
        r"""
        Return a new [`FrameSet`] which describes only the given [`FrameIdentifier`]s.
        """
    def is_empty(self) -> builtins.bool:
        r"""
        Return true if this describes no frames.
        """
    def merge(self, other:FrameSet) -> None:
        r"""
        Merge another [FrameSet] with this one, overwriting any existing keys
        """
    def to_instructions(self) -> builtins.list[Instruction]:
        r"""
        Return the Quil instructions which describe the contained frames.
        """

class MaybeCalibrationExpansion:
    r"""
    The result of an attempt to expand an instruction within a [`Program`]
    """
    def __getnewargs__(self) -> tuple[CalibrationExpansion, InstructionIndex]: ...
    def __repr__(self) -> builtins.str: ...
    class Expanded(MaybeCalibrationExpansion):
        r"""
        The instruction was expanded into others
        """
        __match_args__ = ("_0",)
        @property
        def _0(self) -> CalibrationExpansion: ...
        def __getitem__(self, key:builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0:CalibrationExpansion) -> MaybeCalibrationExpansion.Expanded: ...
    
    class Unexpanded(MaybeCalibrationExpansion):
        r"""
        The instruction was not expanded, but was simply copied over into the target program at the given instruction index
        """
        __match_args__ = ("_0",)
        @property
        def _0(self) -> builtins.int: ...
        def __getitem__(self, key:builtins.int) -> typing.Any: ...
        def __len__(self) -> builtins.int: ...
        def __new__(cls, _0:builtins.int) -> MaybeCalibrationExpansion.Unexpanded: ...
    

class MemoryRegion:
    @property
    def sharing(self) -> typing.Optional[Sharing]: ...
    @property
    def size(self) -> Vector: ...
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __getnewargs__(self) -> tuple[Vector, typing.Optional[Sharing]]: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, size:Vector, sharing:typing.Optional[Sharing]) -> MemoryRegion: ...
    def __repr__(self) -> builtins.str: ...

class Program:
    r"""
    A Quil Program instance describes a quantum program with metadata used in execution.
    
    This contains not only instructions which are executed in turn on the quantum processor, but
    also the "headers" used to describe and manipulate those instructions, such as calibrations
    and frame definitions.
    """
    @property
    def body_instructions(self) -> builtins.list[Instruction]: ...
    @property
    def calibrations(self) -> CalibrationSet: ...
    @property
    def declarations(self) -> builtins.dict[builtins.str, Declaration]: ...
    @property
    def frames(self) -> FrameSet: ...
    @property
    def gate_definitions(self) -> builtins.dict[builtins.str, GateDefinition]: ...
    @property
    def instructions(self) -> builtins.list[Instruction]: ...
    @property
    def memory_regions(self) -> builtins.dict[builtins.str, MemoryRegion]: ...
    @property
    def pragma_extern_map(self) -> builtins.set[typing.Optional[builtins.str], Pragma]: ...
    @property
    def used_qubits(self) -> builtins.set[Qubit]: ...
    @property
    def waveforms(self) -> builtins.dict[builtins.str, Waveform]: ...
    @calibrations.setter
    def calibrations(self, value: CalibrationSet) -> None: ...
    @frames.setter
    def frames(self, value: FrameSet) -> None: ...
    @gate_definitions.setter
    def gate_definitions(self, value: builtins.dict[builtins.str, GateDefinition]) -> None: ...
    @instructions.setter
    def instructions(self, value: builtins.list[Instruction]) -> None: ...
    @memory_regions.setter
    def memory_regions(self, value: builtins.dict[builtins.str, MemoryRegion]) -> None: ...
    @waveforms.setter
    def waveforms(self, value: builtins.dict[builtins.str, Waveform]) -> None: ...
    def __add__(self, rhs:Program) -> Program: ...
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __getstate__(self) -> bytes:
        r"""
        This will raise an error if the program contains any unresolved
        placeholders. This is because they can't be converted to valid quil,
        nor can they be serialized and deserialized in a consistent way.
        """
    def __iadd__(self, rhs:Program) -> None: ...
    def __new__(cls) -> Program: ...
    def __repr__(self) -> builtins.str: ...
    def __setstate__(self, state:bytes) -> None: ...
    def add_instruction(self, instruction:Instruction) -> None:
        r"""
        Add an instruction to the end of the program.
        
        Note, parsing extern signatures is deferred here to maintain infallibility
        of [`Program::add_instruction`]. This means that invalid `PRAGMA EXTERN`
        instructions are still added to the [`Program::extern_pragma_map`];
        duplicate `PRAGMA EXTERN` names are overwritten.
        """
    def add_instructions(self, instructions:typing.Sequence[Instruction]) -> None:
        r"""
        Add a list of instructions to the end of the program.
        """
    def clone_without_body_instructions(self) -> Program:
        r"""
        Return a deep copy of the `Program`, but without the body instructions.
        """
    def control_flow_graph(self) -> ControlFlowGraph:
        r"""
        Return the [control flow graph][] of the program.
        
        [control flow graph]: https://en.wikipedia.org/wiki/Control-flow_graph
        """
    def copy(self) -> Program:
        r"""
        Return a deep copy of the `Program`.
        """
    def dagger(self) -> Program:
        r"""
        Creates a new conjugate transpose of the [`Program`] by reversing the order of gate
        instructions and applying the DAGGER modifier to each.
        
        # Errors
        
        Errors if any of the instructions in the program are not [`Instruction::Gate`]
        """
    def expand_calibrations(self) -> Program:
        r"""
        Expand any instructions in the program which have a matching calibration,
        leaving the others unchanged.
        Return the expanded copy of the program.
        
        Returns an error if any instruction expands into itself.
        
        See [`Program::expand_calibrations_with_source_map`] for a version that returns a source mapping.
        """
    def expand_calibrations_with_source_map(self) -> ProgramCalibrationExpansion:
        r"""
        Expand any instructions in the program which have a matching calibration,
        leaving the others unchanged.
        Return the expanded copy of the program
        and a source mapping describing the expansions made.
        """
    def filter_instructions(self, predicate:collections.abc.Callable[[Instruction], bool]) -> Program:
        r"""
        Return a new ``Program`` containing only the instructions
        for which `predicate` returns true.
        """
    def into_simplified(self) -> Program:
        r"""
        Simplify this program into a new [`Program`] which contains only instructions
        and definitions which are executed; effectively, perform dead code removal.
        
        Removes:
        - All calibrations, following calibration expansion
        - Frame definitions which are not used by any instruction such as `PULSE` or `CAPTURE`
        - Waveform definitions which are not used by any instruction
        - `PRAGMA EXTERN` instructions which are not used by any `CALL` instruction (see
          [`Program::extern_pragma_map`]).
        
        When a valid program is simplified, it remains valid.
        
        # Note
        
        If you need custom instruction handling during simplification,
        use [`InstructionHandler::simplify_program`] instead.
        """
    @staticmethod
    def parse(input:builtins.str) -> Program:
        r"""
        Parse a ``Program`` from a string.
        
        Raises a ``ProgramError`` if the string isn't a valid Quil expression.
        """
    def resolve_placeholders(self) -> None:
        r"""
        Resolve [`LabelPlaceholder`]s and [`QubitPlaceholder`]s within the program using default resolvers.
        
        See [`resolve_placeholders_with_custom_resolvers`](Self::resolve_placeholders_with_custom_resolvers),
        [`default_target_resolver`](Self::default_target_resolver),
        and [`default_qubit_resolver`](Self::default_qubit_resolver) for more information.
        """
    def resolve_placeholders_with_custom_resolvers(self, *, target_resolver:typing.Optional[collections.abc.Callable[[TargetPlaceholder], str | None]]=None, qubit_resolver:typing.Optional[collections.abc.Callable[[QubitPlaceholder], int | None]]=None) -> None:
        r"""
        Resolve ``TargetPlaceholder``s and ``QubitPlaceholder``s within the program.
        
        The resolved values will remain unique to that placeholder
        within the scope of the program.
        If you provide ``target_resolver`` and/or ``qubit_resolver``,
        those will be used to resolve those values respectively.
        If your resolver returns `None` for a particular placeholder,
        it will not be replaced but will be left as a placeholder.
        If you do not provide a resolver for a placeholder,
        a default resolver will be used which will generate
        a unique value for that placeholder within the scope of the program
        using an auto-incrementing value (for qubit) or suffix (for target)
        while ensuring that unique value is not already in use within the program.
        """
    def to_instructions(self) -> builtins.list[Instruction]:
        r"""
        Return a copy of all of the instructions which constitute this [`Program`].
        """
    def to_quil(self) -> builtins.str: ...
    def to_quil_or_debug(self) -> builtins.str: ...
    def to_unitary(self, n_qubits:builtins.int) -> numpy.typing.NDArray[numpy.complex128]:
        r"""
        Return the unitary of a program.
        
        # Errors
        
        Returns an error if the program contains instructions other than `Gate`s.
        """
    def wrap_in_loop(self, loop_count_reference:MemoryReference, start_target:Target, end_target:Target, iterations:builtins.int) -> Program:
        r"""
        Return a copy of the [`Program`] wrapped in a loop that repeats `iterations` times.
        
        The loop is constructed by wrapping the body of the program in classical Quil instructions.
        The given `loop_count_reference` must refer to an INTEGER memory region. The value at the
        reference given will be set to `iterations` and decremented in the loop. The loop will
        terminate when the reference reaches 0. For this reason your program should not itself
        modify the value at the reference unless you intend to modify the remaining number of
        iterations (i.e. to break the loop).
        
        The given `start_target` and `end_target` will be used as the entry and exit points for the
        loop, respectively. You should provide unique [`Target`]s that won't be used elsewhere in
        the program.
        
        If `iterations` is 0, then a copy of the program is returned without any changes.
        """

class ProgramCalibrationExpansion:
    @property
    def program(self) -> Program:
        r"""
        The program containing the instructions.
        """
    @property
    def source_map(self) -> ProgramCalibrationExpansionSourceMap:
        r"""
        The source mapping describing the expansions made.
        """
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __repr__(self) -> builtins.str: ...

class ProgramCalibrationExpansionSourceMap:
    def __repr__(self) -> builtins.str: ...
    def entries(self) -> builtins.list[ProgramCalibrationExpansionSourceMapEntry]: ...
    def list_sources_for_calibration_used(self, calibration_used:CalibrationSource) -> builtins.list[builtins.int]:
        r"""
        Given a particular calibration (`DEFCAL` or `DEFCAL MEASURE`), =
        return the locations in the source which were expanded using that calibration.
        
        This is `O(n)` where `n` is the number of first-level calibration expansions performed.
        """
    def list_sources_for_target_index(self, target_index:builtins.int) -> builtins.list[builtins.int]:
        r"""
        Return all source ranges in the source map
        which were used to generate the target index.
        
        This is `O(n)` where `n` is the number of entries in the map.
        """
    def list_targets_for_source_index(self, source_index:builtins.int) -> builtins.list[MaybeCalibrationExpansion]:
        r"""
        Return all target ranges which were used to generate the source range.
        
        This is `O(n)` where `n` is the number of entries in the map.
        """

class ProgramCalibrationExpansionSourceMapEntry:
    def __repr__(self) -> builtins.str: ...
    def source_location(self) -> builtins.int:
        r"""
        The instruction index within the source program's body instructions.
        """
    def target_location(self) -> MaybeCalibrationExpansion:
        r"""
        The location of the expanded instruction within the target
        program's body instructions.
        """

class ProgramError(builtins.QuilError):
    r"""
    Errors encountered related to a Program.
    """
    ...

class QubitGraphError(builtins.ProgramError):
    ...

class ScheduleSeconds:
    r"""
    A Schedule is a ``DependencyGraph`` flattened into a linear sequence of instructions,
    each of which is assigned a start time and duration.
    """
    @property
    def duration(self) -> builtins.float:
        r"""
        The schedule duration, in seconds.
        
        This is the maximum end time among all scheduled items.
        """
    @property
    def items(self) -> builtins.list[ScheduleSecondsItem]:
        r"""
        Scheduled items, in an unspecified order.
        """
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __repr__(self) -> builtins.str: ...

class ScheduleSecondsItem:
    r"""
    A single item within a schedule, representing a single instruction within a basic block.
    """
    @property
    def instruction_index(self) -> builtins.int:
        r"""
        The time span during which the instruction is scheduled.
        """
    @property
    def time_span(self) -> TimeSpanSeconds:
        r"""
        The index of the instruction within the basic block.
        """
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __repr__(self) -> builtins.str: ...

class TimeSpanSeconds:
    r"""
    A time span, in seconds.
    """
    @property
    def duration(self) -> builtins.float:
        r"""
        The duration of the time span, in seconds.
        """
    @property
    def end(self) -> builtins.float:
        r"""
        The end time of the time span, in seconds.
        
        This is the sum of the start time and duration.
        """
    @property
    def start(self) -> builtins.float:
        r"""
        The inclusive start time of the time span,
        in seconds relative to the start of the scheduling context (such as the basic block).
        """
    def __eq__(self, other:builtins.object) -> builtins.bool: ...
    def __repr__(self) -> builtins.str: ...

