Skip to content

program

Circuit program independent of any execution framework.

Prepare

Statevector written onto a set of qubits.

Attributes:

  • amplitudes (NDArray[complex128]) –

    Complex amplitudes, one per basis state of qubits.

  • qubits (tuple[int, ...]) –

    Qubits that receive the state, in the order the amplitudes use.

Source code in shadowsim/backends/program.py
class Prepare:
    """Statevector written onto a set of qubits.

    Attributes:
        amplitudes: Complex amplitudes, one per basis state of ``qubits``.
        qubits: Qubits that receive the state, in the order the amplitudes use.
    """

    amplitudes: npt.NDArray[np.complex128]
    qubits: tuple[int, ...]
    __hash__ = None  # type: ignore[assignment]

    def __init__(self, amplitudes: npt.ArrayLike, qubits: Sequence[int]) -> None:
        """Record ``amplitudes`` on ``qubits``.

        Args:
            amplitudes: One complex amplitude per basis state of ``qubits``.
            qubits: Qubits that receive the state, in the order the amplitudes use.

        Raises:
            ValueError: ``qubits`` is empty, contains a duplicate or a negative index,
                or ``amplitudes`` does not have one entry per basis state.
        """
        self.qubits = _qubit_indexes(qubits, label="Prepare")
        self.amplitudes = _complex_array(
            amplitudes,
            shape=(2 ** len(self.qubits),),
            label="Prepare amplitudes",
        )

    def __eq__(self, other: object) -> bool:
        """Return whether both prepares carry the same qubits and amplitudes."""
        if not isinstance(other, Prepare):
            return NotImplemented
        return self.qubits == other.qubits and bool(np.array_equal(self.amplitudes, other.amplitudes))

__init__

__init__(
    amplitudes: ArrayLike, qubits: Sequence[int]
) -> None

Record amplitudes on qubits.

Parameters:

  • amplitudes (ArrayLike) –

    One complex amplitude per basis state of qubits.

  • qubits (Sequence[int]) –

    Qubits that receive the state, in the order the amplitudes use.

Raises:

  • ValueError –

    qubits is empty, contains a duplicate or a negative index, or amplitudes does not have one entry per basis state.

Source code in shadowsim/backends/program.py
def __init__(self, amplitudes: npt.ArrayLike, qubits: Sequence[int]) -> None:
    """Record ``amplitudes`` on ``qubits``.

    Args:
        amplitudes: One complex amplitude per basis state of ``qubits``.
        qubits: Qubits that receive the state, in the order the amplitudes use.

    Raises:
        ValueError: ``qubits`` is empty, contains a duplicate or a negative index,
            or ``amplitudes`` does not have one entry per basis state.
    """
    self.qubits = _qubit_indexes(qubits, label="Prepare")
    self.amplitudes = _complex_array(
        amplitudes,
        shape=(2 ** len(self.qubits),),
        label="Prepare amplitudes",
    )

__eq__

__eq__(other: object) -> bool

Return whether both prepares carry the same qubits and amplitudes.

Source code in shadowsim/backends/program.py
def __eq__(self, other: object) -> bool:
    """Return whether both prepares carry the same qubits and amplitudes."""
    if not isinstance(other, Prepare):
        return NotImplemented
    return self.qubits == other.qubits and bool(np.array_equal(self.amplitudes, other.amplitudes))

Unitary

Matrix applied to a set of qubits.

The matrix is stored in the qubit order it was given. It is not transposed.

Attributes:

  • matrix (NDArray[complex128]) –

    Square complex matrix of shape (2**n, 2**n) for n qubits.

  • qubits (tuple[int, ...]) –

    Qubits the matrix acts on, in the order matrix uses.

Source code in shadowsim/backends/program.py
class Unitary:
    """Matrix applied to a set of qubits.

    The matrix is stored in the qubit order it was given. It is not transposed.

    Attributes:
        matrix: Square complex matrix of shape ``(2**n, 2**n)`` for ``n`` qubits.
        qubits: Qubits the matrix acts on, in the order ``matrix`` uses.
    """

    matrix: npt.NDArray[np.complex128]
    qubits: tuple[int, ...]
    __hash__ = None  # type: ignore[assignment]

    def __init__(self, matrix: npt.ArrayLike, qubits: Sequence[int]) -> None:
        """Record ``matrix`` on ``qubits``.

        Args:
            matrix: Square matrix whose dimension is ``2 ** len(qubits)``.
            qubits: Qubits the matrix acts on, in the order ``matrix`` uses.

        Raises:
            ValueError: ``qubits`` is empty, contains a duplicate or a negative index,
                or ``matrix`` does not have shape ``(2**n, 2**n)``.
        """
        self.qubits = _qubit_indexes(qubits, label="Unitary")
        dimension = 2 ** len(self.qubits)
        self.matrix = _complex_array(matrix, shape=(dimension, dimension), label="Unitary matrix")

    def __eq__(self, other: object) -> bool:
        """Return whether both unitaries carry the same qubits and matrix."""
        if not isinstance(other, Unitary):
            return NotImplemented
        return self.qubits == other.qubits and bool(np.array_equal(self.matrix, other.matrix))

__init__

__init__(matrix: ArrayLike, qubits: Sequence[int]) -> None

Record matrix on qubits.

Parameters:

  • matrix (ArrayLike) –

    Square matrix whose dimension is 2 ** len(qubits).

  • qubits (Sequence[int]) –

    Qubits the matrix acts on, in the order matrix uses.

Raises:

  • ValueError –

    qubits is empty, contains a duplicate or a negative index, or matrix does not have shape (2**n, 2**n).

Source code in shadowsim/backends/program.py
def __init__(self, matrix: npt.ArrayLike, qubits: Sequence[int]) -> None:
    """Record ``matrix`` on ``qubits``.

    Args:
        matrix: Square matrix whose dimension is ``2 ** len(qubits)``.
        qubits: Qubits the matrix acts on, in the order ``matrix`` uses.

    Raises:
        ValueError: ``qubits`` is empty, contains a duplicate or a negative index,
            or ``matrix`` does not have shape ``(2**n, 2**n)``.
    """
    self.qubits = _qubit_indexes(qubits, label="Unitary")
    dimension = 2 ** len(self.qubits)
    self.matrix = _complex_array(matrix, shape=(dimension, dimension), label="Unitary matrix")

__eq__

__eq__(other: object) -> bool

Return whether both unitaries carry the same qubits and matrix.

Source code in shadowsim/backends/program.py
def __eq__(self, other: object) -> bool:
    """Return whether both unitaries carry the same qubits and matrix."""
    if not isinstance(other, Unitary):
        return NotImplemented
    return self.qubits == other.qubits and bool(np.array_equal(self.matrix, other.matrix))

Hadamard

Hadamard on one qubit.

Attributes:

  • qubit (int) –

    Qubit that receives the Hadamard.

Source code in shadowsim/backends/program.py
class Hadamard:
    """Hadamard on one qubit.

    Attributes:
        qubit: Qubit that receives the Hadamard.
    """

    qubit: int
    __hash__ = None  # type: ignore[assignment]

    def __init__(self, qubit: int) -> None:
        """Record a Hadamard on ``qubit``.

        Args:
            qubit: Qubit that receives the Hadamard.

        Raises:
            ValueError: ``qubit`` is not a non-negative index.
        """
        self.qubit = _qubit_index(qubit, label="Hadamard")

    def __eq__(self, other: object) -> bool:
        """Return whether both Hadamards act on the same qubit."""
        if not isinstance(other, Hadamard):
            return NotImplemented
        return self.qubit == other.qubit

__init__

__init__(qubit: int) -> None

Record a Hadamard on qubit.

Parameters:

  • qubit (int) –

    Qubit that receives the Hadamard.

Raises:

  • ValueError –

    qubit is not a non-negative index.

Source code in shadowsim/backends/program.py
def __init__(self, qubit: int) -> None:
    """Record a Hadamard on ``qubit``.

    Args:
        qubit: Qubit that receives the Hadamard.

    Raises:
        ValueError: ``qubit`` is not a non-negative index.
    """
    self.qubit = _qubit_index(qubit, label="Hadamard")

__eq__

__eq__(other: object) -> bool

Return whether both Hadamards act on the same qubit.

Source code in shadowsim/backends/program.py
def __eq__(self, other: object) -> bool:
    """Return whether both Hadamards act on the same qubit."""
    if not isinstance(other, Hadamard):
        return NotImplemented
    return self.qubit == other.qubit

Reset

Return one qubit to the zero state.

Attributes:

  • qubit (int) –

    Qubit that is reset.

Source code in shadowsim/backends/program.py
class Reset:
    """Return one qubit to the zero state.

    Attributes:
        qubit: Qubit that is reset.
    """

    qubit: int
    __hash__ = None  # type: ignore[assignment]

    def __init__(self, qubit: int) -> None:
        """Record a reset of ``qubit``.

        Args:
            qubit: Qubit that is reset.

        Raises:
            ValueError: ``qubit`` is not a non-negative index.
        """
        self.qubit = _qubit_index(qubit, label="Reset")

    def __eq__(self, other: object) -> bool:
        """Return whether both resets act on the same qubit."""
        if not isinstance(other, Reset):
            return NotImplemented
        return self.qubit == other.qubit

__init__

__init__(qubit: int) -> None

Record a reset of qubit.

Parameters:

  • qubit (int) –

    Qubit that is reset.

Raises:

  • ValueError –

    qubit is not a non-negative index.

Source code in shadowsim/backends/program.py
def __init__(self, qubit: int) -> None:
    """Record a reset of ``qubit``.

    Args:
        qubit: Qubit that is reset.

    Raises:
        ValueError: ``qubit`` is not a non-negative index.
    """
    self.qubit = _qubit_index(qubit, label="Reset")

__eq__

__eq__(other: object) -> bool

Return whether both resets act on the same qubit.

Source code in shadowsim/backends/program.py
def __eq__(self, other: object) -> bool:
    """Return whether both resets act on the same qubit."""
    if not isinstance(other, Reset):
        return NotImplemented
    return self.qubit == other.qubit

Barrier

Barrier across one or more qubits.

Attributes:

  • qubits (tuple[int, ...]) –

    Qubits the barrier spans.

Source code in shadowsim/backends/program.py
class Barrier:
    """Barrier across one or more qubits.

    Attributes:
        qubits: Qubits the barrier spans.
    """

    qubits: tuple[int, ...]
    __hash__ = None  # type: ignore[assignment]

    def __init__(self, qubits: Sequence[int]) -> None:
        """Record a barrier across ``qubits``.

        Args:
            qubits: Qubits the barrier spans.

        Raises:
            ValueError: ``qubits`` is empty or contains a duplicate or a negative index.
        """
        self.qubits = _qubit_indexes(qubits, label="Barrier")

    def __eq__(self, other: object) -> bool:
        """Return whether both barriers span the same qubits."""
        if not isinstance(other, Barrier):
            return NotImplemented
        return self.qubits == other.qubits

__init__

__init__(qubits: Sequence[int]) -> None

Record a barrier across qubits.

Parameters:

  • qubits (Sequence[int]) –

    Qubits the barrier spans.

Raises:

  • ValueError –

    qubits is empty or contains a duplicate or a negative index.

Source code in shadowsim/backends/program.py
def __init__(self, qubits: Sequence[int]) -> None:
    """Record a barrier across ``qubits``.

    Args:
        qubits: Qubits the barrier spans.

    Raises:
        ValueError: ``qubits`` is empty or contains a duplicate or a negative index.
    """
    self.qubits = _qubit_indexes(qubits, label="Barrier")

__eq__

__eq__(other: object) -> bool

Return whether both barriers span the same qubits.

Source code in shadowsim/backends/program.py
def __eq__(self, other: object) -> bool:
    """Return whether both barriers span the same qubits."""
    if not isinstance(other, Barrier):
        return NotImplemented
    return self.qubits == other.qubits

Measure

Computational-basis measurement of one qubit into one classical bit.

Attributes:

  • qubit (int) –

    Qubit that is measured.

  • clbit (int) –

    Classical bit that receives the outcome.

Source code in shadowsim/backends/program.py
class Measure:
    """Computational-basis measurement of one qubit into one classical bit.

    Attributes:
        qubit: Qubit that is measured.
        clbit: Classical bit that receives the outcome.
    """

    qubit: int
    clbit: int
    __hash__ = None  # type: ignore[assignment]

    def __init__(self, qubit: int, clbit: int) -> None:
        """Record a measurement of ``qubit`` into ``clbit``.

        Args:
            qubit: Qubit that is measured.
            clbit: Classical bit that receives the outcome.

        Raises:
            ValueError: ``qubit`` or ``clbit`` is not a non-negative index.
        """
        self.qubit = _qubit_index(qubit, label="Measure")
        self.clbit = _count(clbit, label="Measure classical bit")

    def __eq__(self, other: object) -> bool:
        """Return whether both measurements use the same qubit and classical bit."""
        if not isinstance(other, Measure):
            return NotImplemented
        return self.qubit == other.qubit and self.clbit == other.clbit

__init__

__init__(qubit: int, clbit: int) -> None

Record a measurement of qubit into clbit.

Parameters:

  • qubit (int) –

    Qubit that is measured.

  • clbit (int) –

    Classical bit that receives the outcome.

Raises:

  • ValueError –

    qubit or clbit is not a non-negative index.

Source code in shadowsim/backends/program.py
def __init__(self, qubit: int, clbit: int) -> None:
    """Record a measurement of ``qubit`` into ``clbit``.

    Args:
        qubit: Qubit that is measured.
        clbit: Classical bit that receives the outcome.

    Raises:
        ValueError: ``qubit`` or ``clbit`` is not a non-negative index.
    """
    self.qubit = _qubit_index(qubit, label="Measure")
    self.clbit = _count(clbit, label="Measure classical bit")

__eq__

__eq__(other: object) -> bool

Return whether both measurements use the same qubit and classical bit.

Source code in shadowsim/backends/program.py
def __eq__(self, other: object) -> bool:
    """Return whether both measurements use the same qubit and classical bit."""
    if not isinstance(other, Measure):
        return NotImplemented
    return self.qubit == other.qubit and self.clbit == other.clbit

Program

Ordered circuit operations on a fixed register.

Qubit indexes are positions in that register. An ancilla added before the body occupies the lower indexes.

Attributes:

  • num_qubits (int) –

    Number of qubits in the register.

  • num_clbits (int) –

    Number of classical bits in the register.

  • operations (tuple[Operation, ...]) –

    Operations in the order they are applied.

Source code in shadowsim/backends/program.py
class Program:
    """Ordered circuit operations on a fixed register.

    Qubit indexes are positions in that register. An ancilla added before the
    body occupies the lower indexes.

    Attributes:
        num_qubits: Number of qubits in the register.
        num_clbits: Number of classical bits in the register.
        operations: Operations in the order they are applied.
    """

    num_qubits: int
    num_clbits: int
    operations: tuple[Operation, ...]
    __hash__ = None  # type: ignore[assignment]

    def __init__(self, num_qubits: int, num_clbits: int, operations: Sequence[Operation]) -> None:
        """Record ``operations`` on registers of the given sizes.

        Args:
            num_qubits: Number of qubits in the register.
            num_clbits: Number of classical bits in the register.
            operations: Operations in the order they are applied.

        Raises:
            TypeError: An entry of ``operations`` is not a program operation.
            ValueError: A register size is negative, or an operation names a qubit
                or classical bit outside the register.
        """
        self.num_qubits = _count(num_qubits, label="num_qubits")
        self.num_clbits = _count(num_clbits, label="num_clbits")
        recorded: list[Operation] = []
        for operation in operations:
            if not isinstance(operation, (Prepare, Unitary, Hadamard, Reset, Barrier, Measure)):
                raise TypeError(f"operations must be circuit operations, got {type(operation).__name__}")
            self._check_bounds(operation)
            recorded.append(operation)
        self.operations = tuple(recorded)

    def _check_bounds(self, operation: Operation) -> None:
        """Reject a qubit or classical bit outside this program."""
        for qubit in _bound_qubits(operation):
            if qubit >= self.num_qubits:
                raise ValueError(f"qubit {qubit} is outside a program of {self.num_qubits} qubits")
        if isinstance(operation, Measure) and operation.clbit >= self.num_clbits:
            raise ValueError(
                f"classical bit {operation.clbit} is outside a program of {self.num_clbits} classical bits"
            )

    def __eq__(self, other: object) -> bool:
        """Return whether both programs have the same registers and operations."""
        if not isinstance(other, Program):
            return NotImplemented
        return (
            self.num_qubits == other.num_qubits
            and self.num_clbits == other.num_clbits
            and self.operations == other.operations
        )

__init__

__init__(
    num_qubits: int,
    num_clbits: int,
    operations: Sequence[Operation],
) -> None

Record operations on registers of the given sizes.

Parameters:

  • num_qubits (int) –

    Number of qubits in the register.

  • num_clbits (int) –

    Number of classical bits in the register.

  • operations (Sequence[Operation]) –

    Operations in the order they are applied.

Raises:

  • TypeError –

    An entry of operations is not a program operation.

  • ValueError –

    A register size is negative, or an operation names a qubit or classical bit outside the register.

Source code in shadowsim/backends/program.py
def __init__(self, num_qubits: int, num_clbits: int, operations: Sequence[Operation]) -> None:
    """Record ``operations`` on registers of the given sizes.

    Args:
        num_qubits: Number of qubits in the register.
        num_clbits: Number of classical bits in the register.
        operations: Operations in the order they are applied.

    Raises:
        TypeError: An entry of ``operations`` is not a program operation.
        ValueError: A register size is negative, or an operation names a qubit
            or classical bit outside the register.
    """
    self.num_qubits = _count(num_qubits, label="num_qubits")
    self.num_clbits = _count(num_clbits, label="num_clbits")
    recorded: list[Operation] = []
    for operation in operations:
        if not isinstance(operation, (Prepare, Unitary, Hadamard, Reset, Barrier, Measure)):
            raise TypeError(f"operations must be circuit operations, got {type(operation).__name__}")
        self._check_bounds(operation)
        recorded.append(operation)
    self.operations = tuple(recorded)

__eq__

__eq__(other: object) -> bool

Return whether both programs have the same registers and operations.

Source code in shadowsim/backends/program.py
def __eq__(self, other: object) -> bool:
    """Return whether both programs have the same registers and operations."""
    if not isinstance(other, Program):
        return NotImplemented
    return (
        self.num_qubits == other.num_qubits
        and self.num_clbits == other.num_clbits
        and self.operations == other.operations
    )