Skip to content

qulacs

Run a program on the Qulacs statevector simulator.

Qubit 0 is the least significant bit of a gate matrix and of each sample. Hadamard uses the Qulacs kernel. Every Unitary is a dense matrix.

QulacsCircuitBackend

Bases: _UnsupportedCircuitMetrics

Evolve one program with the Qulacs statevector simulator.

z_expectations and x_expectations are exact, so shots and seed are accepted and ignored there. run_counts samples the computational-basis distribution, and the same seed repeats those counts. The backend stores no shots attribute, so Trotterization reads the exact expectations.

Reset, a measurement followed by a gate, and state preparation after the register has left |0...0> are rejected. depth, width, gate_count, t_count, and toffoli_count are not available.

Statevectors agree with the NumPy backend to an absolute tolerance of 1e-8. One local Hamiltonian makes the Trotter product exact: that ⟨Z⟩ curve matches cos(2t) to 1e-8. A seeded Hadamard of 4000 shots stays within 0.05 of the NumPy frequencies.

Attributes:

  • name –

    "qulacs". Stored on simulation result metadata.

Source code in shadowsim/backends/qulacs.py
class QulacsCircuitBackend(_UnsupportedCircuitMetrics):
    """Evolve one program with the Qulacs statevector simulator.

    ``z_expectations`` and ``x_expectations`` are exact, so ``shots`` and
    ``seed`` are accepted and ignored there. ``run_counts`` samples the
    computational-basis distribution, and the same ``seed`` repeats those
    counts. The backend stores no ``shots`` attribute, so Trotterization reads
    the exact expectations.

    ``Reset``, a measurement followed by a gate, and state preparation after
    the register has left ``|0...0>`` are rejected. ``depth``, ``width``,
    ``gate_count``, ``t_count``, and ``toffoli_count`` are not available.

    Statevectors agree with the NumPy backend to an absolute tolerance of
    ``1e-8``. One local Hamiltonian makes the Trotter product exact: that
    ``⟨Z⟩`` curve matches ``cos(2t)`` to ``1e-8``. A seeded Hadamard of 4000
    shots stays within ``0.05`` of the NumPy frequencies.

    Attributes:
        name: ``"qulacs"``. Stored on simulation result metadata.
    """

    def __init__(self) -> None:
        """Record the Qulacs backend name."""
        self.name = "qulacs"

    def run_counts(self, program: Program, *, shots: int, seed: int | None) -> dict[str, int]:
        """Sample ``program`` in the computational basis.

        Args:
            program: Program to execute.
            shots: Number of shots.
            seed: Seed for Qulacs sampling. ``None`` draws without a fixed seed.

        Returns:
            Mapping from bitstring to shot count. The rightmost character is qubit 0.

        Raises:
            ValueError: ``shots`` is not a positive integer, or the statevector
                probabilities do not sum to 1.
            TypeError: ``seed`` is not an ``int`` or ``None``.
            NotImplementedError: ``program`` resets a qubit, measures a qubit
                and then applies a gate, or prepares a state after leaving
                ``|0...0>``.
            ImportError: The ``qulacs`` extra is not installed.
        """
        _require_shots(shots)
        _require_seed(seed)
        state = _state(program)
        _check_normalized(state)
        if seed is None:
            outcomes = state.sampling(shots)
        else:
            outcomes = state.sampling(shots, seed)
        counts: dict[str, int] = {}
        width = program.num_qubits
        for outcome in outcomes:
            key = format(int(outcome), f"0{width}b")
            counts[key] = counts.get(key, 0) + 1
        return counts

    def z_expectations(
        self,
        program: Program,
        qubits: Sequence[int],
        *,
        shots: int,
        seed: int | None,
    ) -> list[float]:
        """Return exact ``⟨Z⟩`` for each qubit in ``qubits``.

        Args:
            program: Program to execute, before the computational-basis measurement.
            qubits: 0-based indexes in ``program``. The result follows this order.
            shots: Unused. The value is not estimated from shots.
            seed: Unused.

        Returns:
            One expectation per entry of ``qubits``.

        Raises:
            ValueError: An index is outside ``program``.
            NotImplementedError: ``program`` resets a qubit, measures a qubit and
                then applies a gate, or prepares a state after leaving ``|0...0>``.
            ImportError: The ``qulacs`` extra is not installed.
        """
        del shots, seed
        return _expectations(program, qubits, "Z")

    def x_expectations(
        self,
        program: Program,
        qubits: Sequence[int],
        *,
        shots: int,
        seed: int | None,
    ) -> list[float]:
        """Return exact ``⟨X⟩`` for each qubit in ``qubits``.

        Args:
            program: Program to execute, before the X-basis measurement.
            qubits: 0-based indexes in ``program``. The result follows this order.
            shots: Unused. The value is not estimated from shots.
            seed: Unused.

        Returns:
            One expectation per entry of ``qubits``.

        Raises:
            ValueError: An index is outside ``program``.
            NotImplementedError: ``program`` resets a qubit, measures a qubit and
                then applies a gate, or prepares a state after leaving ``|0...0>``.
            ImportError: The ``qulacs`` extra is not installed.
        """
        del shots, seed
        return _expectations(program, qubits, "X")

__init__

__init__() -> None

Record the Qulacs backend name.

Source code in shadowsim/backends/qulacs.py
def __init__(self) -> None:
    """Record the Qulacs backend name."""
    self.name = "qulacs"

run_counts

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

Sample program in the computational basis.

Parameters:

  • program (Program) –

    Program to execute.

  • shots (int) –

    Number of shots.

  • seed (int | None) –

    Seed for Qulacs sampling. None draws without a fixed seed.

Returns:

  • dict[str, int] –

    Mapping from bitstring to shot count. The rightmost character is qubit 0.

Raises:

  • ValueError –

    shots is not a positive integer, or the statevector probabilities do not sum to 1.

  • TypeError –

    seed is not an int or None.

  • NotImplementedError –

    program resets a qubit, measures a qubit and then applies a gate, or prepares a state after leaving |0...0>.

  • ImportError –

    The qulacs extra is not installed.

Source code in shadowsim/backends/qulacs.py
def run_counts(self, program: Program, *, shots: int, seed: int | None) -> dict[str, int]:
    """Sample ``program`` in the computational basis.

    Args:
        program: Program to execute.
        shots: Number of shots.
        seed: Seed for Qulacs sampling. ``None`` draws without a fixed seed.

    Returns:
        Mapping from bitstring to shot count. The rightmost character is qubit 0.

    Raises:
        ValueError: ``shots`` is not a positive integer, or the statevector
            probabilities do not sum to 1.
        TypeError: ``seed`` is not an ``int`` or ``None``.
        NotImplementedError: ``program`` resets a qubit, measures a qubit
            and then applies a gate, or prepares a state after leaving
            ``|0...0>``.
        ImportError: The ``qulacs`` extra is not installed.
    """
    _require_shots(shots)
    _require_seed(seed)
    state = _state(program)
    _check_normalized(state)
    if seed is None:
        outcomes = state.sampling(shots)
    else:
        outcomes = state.sampling(shots, seed)
    counts: dict[str, int] = {}
    width = program.num_qubits
    for outcome in outcomes:
        key = format(int(outcome), f"0{width}b")
        counts[key] = counts.get(key, 0) + 1
    return counts

z_expectations

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

Return exact ⟨Z⟩ for each qubit in qubits.

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) –

    Unused. The value is not estimated from shots.

  • seed (int | None) –

    Unused.

Returns:

  • list[float] –

    One expectation per entry of qubits.

Raises:

  • ValueError –

    An index is outside program.

  • NotImplementedError –

    program resets a qubit, measures a qubit and then applies a gate, or prepares a state after leaving |0...0>.

  • ImportError –

    The qulacs extra is not installed.

Source code in shadowsim/backends/qulacs.py
def z_expectations(
    self,
    program: Program,
    qubits: Sequence[int],
    *,
    shots: int,
    seed: int | None,
) -> list[float]:
    """Return exact ``⟨Z⟩`` for each qubit in ``qubits``.

    Args:
        program: Program to execute, before the computational-basis measurement.
        qubits: 0-based indexes in ``program``. The result follows this order.
        shots: Unused. The value is not estimated from shots.
        seed: Unused.

    Returns:
        One expectation per entry of ``qubits``.

    Raises:
        ValueError: An index is outside ``program``.
        NotImplementedError: ``program`` resets a qubit, measures a qubit and
            then applies a gate, or prepares a state after leaving ``|0...0>``.
        ImportError: The ``qulacs`` extra is not installed.
    """
    del shots, seed
    return _expectations(program, qubits, "Z")

x_expectations

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

Return exact ⟨X⟩ for each qubit in qubits.

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) –

    Unused. The value is not estimated from shots.

  • seed (int | None) –

    Unused.

Returns:

  • list[float] –

    One expectation per entry of qubits.

Raises:

  • ValueError –

    An index is outside program.

  • NotImplementedError –

    program resets a qubit, measures a qubit and then applies a gate, or prepares a state after leaving |0...0>.

  • ImportError –

    The qulacs extra is not installed.

Source code in shadowsim/backends/qulacs.py
def x_expectations(
    self,
    program: Program,
    qubits: Sequence[int],
    *,
    shots: int,
    seed: int | None,
) -> list[float]:
    """Return exact ``⟨X⟩`` for each qubit in ``qubits``.

    Args:
        program: Program to execute, before the X-basis measurement.
        qubits: 0-based indexes in ``program``. The result follows this order.
        shots: Unused. The value is not estimated from shots.
        seed: Unused.

    Returns:
        One expectation per entry of ``qubits``.

    Raises:
        ValueError: An index is outside ``program``.
        NotImplementedError: ``program`` resets a qubit, measures a qubit and
            then applies a gate, or prepares a state after leaving ``|0...0>``.
        ImportError: The ``qulacs`` extra is not installed.
    """
    del shots, seed
    return _expectations(program, qubits, "X")