Skip to content

aer

Run shot circuits on Qiskit Aer.

AerCircuitBackend

Run a program on Qiskit Aer and return shot counts.

The program is translated to a Qiskit circuit and transpiled for AerSimulator. A set seed is passed as seed_simulator. basis_gates is passed the same way when it is set. z_expectations and x_expectations estimate Pauli expectations from those counts. depth, width, gate_count, t_count, and toffoli_count read that transpiled circuit. A unitary stays one instruction, so t and ccx counts stay zero unless transpilation emits those names.

Attributes:

  • name –

    "aer". Stored on simulation result metadata.

  • shots –

    Shot budget passed to each run_counts call by a simulator.

  • basis_gates –

    Gate names passed to AerSimulator, or None for Aer's own basis.

  • BASIS_GATE_NAMES –

    Gate names basis_gates may contain.

Source code in shadowsim/backends/aer.py
class AerCircuitBackend:
    """Run a program on Qiskit Aer and return shot counts.

    The program is translated to a Qiskit circuit and transpiled for
    ``AerSimulator``. A set ``seed`` is passed as ``seed_simulator``.
    ``basis_gates`` is passed the same way when it is set. ``z_expectations``
    and ``x_expectations`` estimate Pauli expectations from those counts.
    ``depth``, ``width``, ``gate_count``, ``t_count``, and ``toffoli_count``
    read that transpiled circuit. A unitary stays one instruction, so ``t``
    and ``ccx`` counts stay zero unless transpilation emits those names.

    Attributes:
        name: ``"aer"``. Stored on simulation result metadata.
        shots: Shot budget passed to each ``run_counts`` call by a simulator.
        basis_gates: Gate names passed to ``AerSimulator``, or ``None`` for
            Aer's own basis.
        BASIS_GATE_NAMES: Gate names ``basis_gates`` may contain.
    """

    BASIS_GATE_NAMES = _BASIS_GATE_NAMES

    def __init__(self, shots: int = 10000, basis_gates: Sequence[str] | None = None) -> None:
        """Store the shot budget and optional compilation basis.

        Args:
            shots: Number of shots for each circuit. Must be a positive integer.
            basis_gates: Gate names ``transpile`` may use. ``None`` keeps Aer's
                own basis. Names are stripped, lowercased, and de-duplicated.
                Each name must be in ``BASIS_GATE_NAMES``.

        Raises:
            ValueError: ``shots`` is not a positive integer, ``basis_gates`` is
                not a sequence of gate names, the sequence is empty, or a name
                is not a gate Aer can compile into.
        """
        self.name = "aer"
        self.shots = _require_shots(shots)
        self.basis_gates = _basis_gates(basis_gates)

    def run_counts(self, program: Program, *, shots: int, seed: int | None) -> dict[str, int]:
        """Translate ``program`` to Qiskit, transpile that for Aer, and return counts.

        Args:
            program: Program to execute.
            shots: Number of shots.
            seed: Passed as ``seed_simulator`` when set. Omitted when ``None``.

        Returns:
            Mapping from bitstring to shot count.

        Raises:
            ValueError: ``program`` cannot be compiled into ``basis_gates``.
        """
        return self._run_counts(to_qiskit(program), shots=shots, seed=seed)

    def z_expectations(
        self,
        program: Program,
        qubits: Sequence[int],
        *,
        shots: int,
        seed: int | None,
    ) -> list[float]:
        """Estimate ``⟨Z⟩`` on ``qubits`` from computational-basis shots.

        Args:
            program: Program to execute, before the computational-basis measurement.
            qubits: 0-based indexes in ``program``. The result follows this order.
            shots: Number of shots.
            seed: Passed as ``seed_simulator`` when set. Omitted when ``None``.

        Returns:
            One estimate per entry of ``qubits``, each ``(n0 - n1) / shots``.

        Raises:
            ValueError: An index is outside ``program``, or ``program`` cannot be
                compiled into ``basis_gates``.
        """
        return _expectations(self, program, qubits, shots=shots, seed=seed, basis="z")

    def x_expectations(
        self,
        program: Program,
        qubits: Sequence[int],
        *,
        shots: int,
        seed: int | None,
    ) -> list[float]:
        """Estimate ``⟨X⟩`` on ``qubits`` by applying Hadamard and then measuring.

        Args:
            program: Program to execute, before the X-basis measurement.
            qubits: 0-based indexes in ``program``. The result follows this order.
            shots: Number of shots.
            seed: Passed as ``seed_simulator`` when set. Omitted when ``None``.

        Returns:
            One estimate per entry of ``qubits``, each ``(n0 - n1) / shots``.

        Raises:
            ValueError: An index is outside ``program``, or ``program`` cannot be
                compiled into ``basis_gates``.
        """
        return _expectations(self, program, qubits, shots=shots, seed=seed, basis="x")

    def depth(self, program: Program) -> int:
        """Return the depth of ``program`` after transpilation for Aer.

        Args:
            program: Program to measure. It is translated and transpiled for this basis.

        Returns:
            Length of the critical path on the transpiled circuit.

        Raises:
            ValueError: ``program`` cannot be compiled into ``basis_gates``.
        """
        return int(self._compiled(program).depth())

    def width(self, program: Program) -> int:
        """Return the qubit count of ``program`` after transpilation for Aer.

        Args:
            program: Program to measure. It is translated and transpiled for this basis.

        Returns:
            Number of qubits on the transpiled circuit. Classical bits are not included.

        Raises:
            ValueError: ``program`` cannot be compiled into ``basis_gates``.
        """
        return int(self._compiled(program).num_qubits)

    def gate_count(self, program: Program) -> int:
        """Return the instruction count of ``program`` after transpilation for Aer.

        Args:
            program: Program to measure. It is translated and transpiled for this basis.

        Returns:
            Total number of instructions on the transpiled circuit, including
            measurements when ``program`` contains them.

        Raises:
            ValueError: ``program`` cannot be compiled into ``basis_gates``.
        """
        return int(self._compiled(program).size())

    def t_count(self, program: Program) -> int:
        """Return the number of ``t`` gates after transpilation for Aer.

        ``tdg`` is not included. A multi-qubit unitary stays one instruction, so
        a program built only from unitaries reports zero.

        Args:
            program: Program to measure. It is translated and transpiled for this basis.

        Returns:
            Count of instructions named ``t``.

        Raises:
            ValueError: ``program`` cannot be compiled into ``basis_gates``.
        """
        return int(self._compiled(program).count_ops().get("t", 0))

    def toffoli_count(self, program: Program) -> int:
        """Return the number of ``ccx`` and ``ccz`` gates after transpilation for Aer.

        A multi-qubit unitary stays one instruction, so a program built only
        from unitaries reports zero.

        Args:
            program: Program to measure. It is translated and transpiled for this basis.

        Returns:
            Sum of ``ccx`` and ``ccz`` instructions.

        Raises:
            ValueError: ``program`` cannot be compiled into ``basis_gates``.
        """
        counts = self._compiled(program).count_ops()
        return int(counts.get("ccx", 0)) + int(counts.get("ccz", 0))

    def _simulator(self, seed: int | None) -> AerSimulator:
        """Return an Aer simulator for this basis and, when set, ``seed``."""
        options: dict[str, object] = {}
        if seed is not None:
            options["seed_simulator"] = seed
        if self.basis_gates is not None:
            options["basis_gates"] = list(self.basis_gates)
        return AerSimulator(**options)

    def _run_counts(self, circuit: QuantumCircuit, *, shots: int, seed: int | None) -> dict[str, int]:
        """Transpile ``circuit`` for Aer and return counts."""
        backend = self._simulator(seed)
        compiled = _transpile(circuit, backend, self.basis_gates)
        job = backend.run(compiled, shots=shots)
        return job.result().get_counts()

    def _compiled(self, program: Program) -> QuantumCircuit:
        """Translate ``program`` and transpile it for this backend's basis."""
        return _transpile(to_qiskit(program), self._simulator(None), self.basis_gates)

__init__

__init__(
    shots: int = 10000,
    basis_gates: Sequence[str] | None = None,
) -> None

Store the shot budget and optional compilation basis.

Parameters:

  • shots (int, default: 10000 ) –

    Number of shots for each circuit. Must be a positive integer.

  • basis_gates (Sequence[str] | None, default: None ) –

    Gate names transpile may use. None keeps Aer's own basis. Names are stripped, lowercased, and de-duplicated. Each name must be in BASIS_GATE_NAMES.

Raises:

  • ValueError –

    shots is not a positive integer, basis_gates is not a sequence of gate names, the sequence is empty, or a name is not a gate Aer can compile into.

Source code in shadowsim/backends/aer.py
def __init__(self, shots: int = 10000, basis_gates: Sequence[str] | None = None) -> None:
    """Store the shot budget and optional compilation basis.

    Args:
        shots: Number of shots for each circuit. Must be a positive integer.
        basis_gates: Gate names ``transpile`` may use. ``None`` keeps Aer's
            own basis. Names are stripped, lowercased, and de-duplicated.
            Each name must be in ``BASIS_GATE_NAMES``.

    Raises:
        ValueError: ``shots`` is not a positive integer, ``basis_gates`` is
            not a sequence of gate names, the sequence is empty, or a name
            is not a gate Aer can compile into.
    """
    self.name = "aer"
    self.shots = _require_shots(shots)
    self.basis_gates = _basis_gates(basis_gates)

run_counts

run_counts(
    program: Program, *, shots: int, seed: int | None
) -> dict[str, int]

Translate program to Qiskit, transpile that for Aer, and return counts.

Parameters:

  • program (Program) –

    Program to execute.

  • shots (int) –

    Number of shots.

  • seed (int | None) –

    Passed as seed_simulator when set. Omitted when None.

Returns:

  • dict[str, int] –

    Mapping from bitstring to shot count.

Raises:

  • ValueError –

    program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def run_counts(self, program: Program, *, shots: int, seed: int | None) -> dict[str, int]:
    """Translate ``program`` to Qiskit, transpile that for Aer, and return counts.

    Args:
        program: Program to execute.
        shots: Number of shots.
        seed: Passed as ``seed_simulator`` when set. Omitted when ``None``.

    Returns:
        Mapping from bitstring to shot count.

    Raises:
        ValueError: ``program`` cannot be compiled into ``basis_gates``.
    """
    return self._run_counts(to_qiskit(program), shots=shots, seed=seed)

z_expectations

z_expectations(
    program: Program,
    qubits: Sequence[int],
    *,
    shots: int,
    seed: int | None,
) -> list[float]

Estimate ⟨Z⟩ on qubits from computational-basis shots.

Parameters:

  • program (Program) –

    Program to execute, before the computational-basis measurement.

  • qubits (Sequence[int]) –

    0-based indexes in program. The result follows this order.

  • shots (int) –

    Number of shots.

  • seed (int | None) –

    Passed as seed_simulator when set. Omitted when None.

Returns:

  • list[float] –

    One estimate per entry of qubits, each (n0 - n1) / shots.

Raises:

  • ValueError –

    An index is outside program, or program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def z_expectations(
    self,
    program: Program,
    qubits: Sequence[int],
    *,
    shots: int,
    seed: int | None,
) -> list[float]:
    """Estimate ``⟨Z⟩`` on ``qubits`` from computational-basis shots.

    Args:
        program: Program to execute, before the computational-basis measurement.
        qubits: 0-based indexes in ``program``. The result follows this order.
        shots: Number of shots.
        seed: Passed as ``seed_simulator`` when set. Omitted when ``None``.

    Returns:
        One estimate per entry of ``qubits``, each ``(n0 - n1) / shots``.

    Raises:
        ValueError: An index is outside ``program``, or ``program`` cannot be
            compiled into ``basis_gates``.
    """
    return _expectations(self, program, qubits, shots=shots, seed=seed, basis="z")

x_expectations

x_expectations(
    program: Program,
    qubits: Sequence[int],
    *,
    shots: int,
    seed: int | None,
) -> list[float]

Estimate ⟨X⟩ on qubits by applying Hadamard and then measuring.

Parameters:

  • program (Program) –

    Program to execute, before the X-basis measurement.

  • qubits (Sequence[int]) –

    0-based indexes in program. The result follows this order.

  • shots (int) –

    Number of shots.

  • seed (int | None) –

    Passed as seed_simulator when set. Omitted when None.

Returns:

  • list[float] –

    One estimate per entry of qubits, each (n0 - n1) / shots.

Raises:

  • ValueError –

    An index is outside program, or program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def x_expectations(
    self,
    program: Program,
    qubits: Sequence[int],
    *,
    shots: int,
    seed: int | None,
) -> list[float]:
    """Estimate ``⟨X⟩`` on ``qubits`` by applying Hadamard and then measuring.

    Args:
        program: Program to execute, before the X-basis measurement.
        qubits: 0-based indexes in ``program``. The result follows this order.
        shots: Number of shots.
        seed: Passed as ``seed_simulator`` when set. Omitted when ``None``.

    Returns:
        One estimate per entry of ``qubits``, each ``(n0 - n1) / shots``.

    Raises:
        ValueError: An index is outside ``program``, or ``program`` cannot be
            compiled into ``basis_gates``.
    """
    return _expectations(self, program, qubits, shots=shots, seed=seed, basis="x")

depth

depth(program: Program) -> int

Return the depth of program after transpilation for Aer.

Parameters:

  • program (Program) –

    Program to measure. It is translated and transpiled for this basis.

Returns:

  • int –

    Length of the critical path on the transpiled circuit.

Raises:

  • ValueError –

    program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def depth(self, program: Program) -> int:
    """Return the depth of ``program`` after transpilation for Aer.

    Args:
        program: Program to measure. It is translated and transpiled for this basis.

    Returns:
        Length of the critical path on the transpiled circuit.

    Raises:
        ValueError: ``program`` cannot be compiled into ``basis_gates``.
    """
    return int(self._compiled(program).depth())

width

width(program: Program) -> int

Return the qubit count of program after transpilation for Aer.

Parameters:

  • program (Program) –

    Program to measure. It is translated and transpiled for this basis.

Returns:

  • int –

    Number of qubits on the transpiled circuit. Classical bits are not included.

Raises:

  • ValueError –

    program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def width(self, program: Program) -> int:
    """Return the qubit count of ``program`` after transpilation for Aer.

    Args:
        program: Program to measure. It is translated and transpiled for this basis.

    Returns:
        Number of qubits on the transpiled circuit. Classical bits are not included.

    Raises:
        ValueError: ``program`` cannot be compiled into ``basis_gates``.
    """
    return int(self._compiled(program).num_qubits)

gate_count

gate_count(program: Program) -> int

Return the instruction count of program after transpilation for Aer.

Parameters:

  • program (Program) –

    Program to measure. It is translated and transpiled for this basis.

Returns:

  • int –

    Total number of instructions on the transpiled circuit, including

  • int –

    measurements when program contains them.

Raises:

  • ValueError –

    program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def gate_count(self, program: Program) -> int:
    """Return the instruction count of ``program`` after transpilation for Aer.

    Args:
        program: Program to measure. It is translated and transpiled for this basis.

    Returns:
        Total number of instructions on the transpiled circuit, including
        measurements when ``program`` contains them.

    Raises:
        ValueError: ``program`` cannot be compiled into ``basis_gates``.
    """
    return int(self._compiled(program).size())

t_count

t_count(program: Program) -> int

Return the number of t gates after transpilation for Aer.

tdg is not included. A multi-qubit unitary stays one instruction, so a program built only from unitaries reports zero.

Parameters:

  • program (Program) –

    Program to measure. It is translated and transpiled for this basis.

Returns:

  • int –

    Count of instructions named t.

Raises:

  • ValueError –

    program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def t_count(self, program: Program) -> int:
    """Return the number of ``t`` gates after transpilation for Aer.

    ``tdg`` is not included. A multi-qubit unitary stays one instruction, so
    a program built only from unitaries reports zero.

    Args:
        program: Program to measure. It is translated and transpiled for this basis.

    Returns:
        Count of instructions named ``t``.

    Raises:
        ValueError: ``program`` cannot be compiled into ``basis_gates``.
    """
    return int(self._compiled(program).count_ops().get("t", 0))

toffoli_count

toffoli_count(program: Program) -> int

Return the number of ccx and ccz gates after transpilation for Aer.

A multi-qubit unitary stays one instruction, so a program built only from unitaries reports zero.

Parameters:

  • program (Program) –

    Program to measure. It is translated and transpiled for this basis.

Returns:

  • int –

    Sum of ccx and ccz instructions.

Raises:

  • ValueError –

    program cannot be compiled into basis_gates.

Source code in shadowsim/backends/aer.py
def toffoli_count(self, program: Program) -> int:
    """Return the number of ``ccx`` and ``ccz`` gates after transpilation for Aer.

    A multi-qubit unitary stays one instruction, so a program built only
    from unitaries reports zero.

    Args:
        program: Program to measure. It is translated and transpiled for this basis.

    Returns:
        Sum of ``ccx`` and ``ccz`` instructions.

    Raises:
        ValueError: ``program`` cannot be compiled into ``basis_gates``.
    """
    counts = self._compiled(program).count_ops()
    return int(counts.get("ccx", 0)) + int(counts.get("ccz", 0))