Skip to content

hybrid_wml_simulator

Hybrid wave-matrix Lindbladization simulator.

HybridWMLSimulator

Bases: ProductFormulaSimulator

Simulate open-system dynamics with hybrid wave-matrix Lindbladization.

Each of the num_steps samples one term. The weight of a Hamiltonian eigenvalue λ is |λ|, and the weight of a Lindblad L is ||L||_F^2. Their sum is c. A sampled eigenvalue prepares its eigenvector on a program register and applies exp(-i sgn(λ) SWAP Δ) on that register and the term's qubits, with Δ = c t / num_steps, then resets the program register. A sampled Lindblad applies exp(-i J_L sqrt(τ)) on one ancilla and the Lindblad's qubits, with τ = c t / (num_steps ||L||_F^2), then resets the ancilla. One seeded sequence is frozen into the circuit and reused for every shot.

Counts come from circuit_backend. Omitting it uses Aer. The shot count is that backend's shots attribute. Before the measurement, each system qubit is rotated into its letter of basis (default all Z). The ancilla and the program register are not measured. Bit i of a counts key is system qubit i. Read those counts with :meth:measure. With workers greater than 1, that backend is pickled into each worker process.

Each time point starts from initial_state. The term sequence and the shot sampler are a pure function of seed and the time index, so workers=1 and a larger pool return the same counts. workers=1 (the default) runs the points serially, in tlist order. progress(index, total) may run in completion order when workers is greater than 1. A job from start() counts each finished time point in completed_steps.

Source code in shadowsim/simulators/hybrid_wml_simulator.py
class HybridWMLSimulator(ProductFormulaSimulator):
    """Simulate open-system dynamics with hybrid wave-matrix Lindbladization.

    Each of the ``num_steps`` samples one term. The weight of a Hamiltonian
    eigenvalue ``λ`` is ``|λ|``, and the weight of a Lindblad ``L`` is
    ``||L||_F^2``. Their sum is ``c``. A sampled eigenvalue prepares its
    eigenvector on a program register and applies ``exp(-i sgn(λ) SWAP Δ)`` on
    that register and the term's qubits, with ``Δ = c t / num_steps``, then
    resets the program register. A sampled Lindblad applies
    ``exp(-i J_L sqrt(τ))`` on one ancilla and the Lindblad's qubits, with
    ``τ = c t / (num_steps ||L||_F^2)``, then resets the ancilla. One seeded
    sequence is frozen into the circuit and reused for every shot.

    Counts come from ``circuit_backend``. Omitting it uses Aer.
    The shot count is that backend's ``shots`` attribute. Before the measurement,
    each system qubit is rotated into its letter of ``basis`` (default all ``Z``).
    The ancilla and the program register are not measured. Bit ``i`` of a counts
    key is system qubit ``i``. Read those counts with :meth:`measure`.
    With ``workers`` greater than 1, that backend is pickled into each worker process.

    Each time point starts from ``initial_state``. The term sequence and the shot
    sampler are a pure function of ``seed`` and the time index, so ``workers=1``
    and a larger pool return the same counts. ``workers=1`` (the default) runs
    the points serially, in ``tlist`` order. ``progress(index, total)`` may run
    in completion order when ``workers`` is greater than 1. A job from ``start()``
    counts each finished time point in ``completed_steps``.
    """

    title: str = "Hybrid WML"
    requires_sampling_backend: bool = True
    sampling_backend_error: str = "Hybrid WML samples a circuit and needs a backend with a shot budget"

    def __init__(
        self,
        hamiltonians: list[LocalHamiltonian],
        lindblads: list[LocalOperator],
        initial_state: State,
        *,
        num_qubits: int,
        total_time: float,
        time_steps: int,
        num_steps: int,
        verbose: bool = False,
        seed: int | None = None,
        progress: ProgressCallback | None = None,
        workers: int = 1,
        circuit_backend: CircuitBackend | None = None,
        basis: str | None = None,
    ) -> None:
        """Initialize a hybrid WML simulator for the given model.

        Raises:
            TypeError: An operator has the wrong type, or ``seed`` or ``workers``
                has the wrong type.
            ValueError: ``workers`` or ``num_steps`` is not positive, ``total_time``
                is negative, ``basis`` is malformed, the backend has no shot budget,
                an operator does not act on the register, or every sampling weight
                is zero.
        """
        super().__init__(
            hamiltonians,
            lindblads,
            initial_state,
            num_qubits=num_qubits,
            total_time=total_time,
            time_steps=time_steps,
            id="hybrid_wml_simulator",
        )
        if self.total_time < 0.0:
            raise ValueError("total_time must be non-negative")
        self._configure_run(
            num_steps=_positive_int("num_steps", num_steps),
            verbose=verbose,
            seed=seed,
            progress=progress,
            workers=workers,
            circuit_backend=circuit_backend,
            basis=basis,
        )
        _prepare(self.hamiltonians, self.lindblads, self.num_qubits)

    def _time_point_call(self, t: float, index: int) -> TimeCall:
        """Return the hybrid WML counts call for time ``t`` at ``index``."""
        hamiltonians = cast(list[LocalHamiltonian], self.hamiltonians)
        lindblads = cast(list[LocalOperator], self.lindblads)
        return (
            _hybrid_wml,
            (
                hamiltonians,
                lindblads,
                self.initial_state,
                self.num_qubits,
                t,
                self.num_steps,
            ),
            {
                "verbose": self.verbose,
                "shots": backend_shots(self.circuit_backend),
                "seed": self.seed,
                "time_index": index,
                "circuit_backend": self.circuit_backend,
                "basis": self.basis,
            },
        )

    def _extra_metadata(self) -> dict[str, Any]:
        """Return the Lindblad count stored on the result."""
        return {"lindblad_count": len(self.lindblads)}

    def metrics_circuit(self) -> Program:
        """Return the program executed at the final time, including measurement."""
        return _hybrid_wml_circuit(
            cast(list[LocalHamiltonian], self.hamiltonians),
            cast(list[LocalOperator], self.lindblads),
            self.initial_state,
            self.num_qubits,
            float(self.tlist[-1]),
            self.num_steps,
            verbose=False,
            seed=self.seed,
            time_index=len(self.tlist) - 1,
            basis=self.basis,
        )

__init__

__init__(
    hamiltonians: list[LocalHamiltonian],
    lindblads: list[LocalOperator],
    initial_state: State,
    *,
    num_qubits: int,
    total_time: float,
    time_steps: int,
    num_steps: int,
    verbose: bool = False,
    seed: int | None = None,
    progress: ProgressCallback | None = None,
    workers: int = 1,
    circuit_backend: CircuitBackend | None = None,
    basis: str | None = None,
) -> None

Initialize a hybrid WML simulator for the given model.

Raises:

  • TypeError –

    An operator has the wrong type, or seed or workers has the wrong type.

  • ValueError –

    workers or num_steps is not positive, total_time is negative, basis is malformed, the backend has no shot budget, an operator does not act on the register, or every sampling weight is zero.

Source code in shadowsim/simulators/hybrid_wml_simulator.py
def __init__(
    self,
    hamiltonians: list[LocalHamiltonian],
    lindblads: list[LocalOperator],
    initial_state: State,
    *,
    num_qubits: int,
    total_time: float,
    time_steps: int,
    num_steps: int,
    verbose: bool = False,
    seed: int | None = None,
    progress: ProgressCallback | None = None,
    workers: int = 1,
    circuit_backend: CircuitBackend | None = None,
    basis: str | None = None,
) -> None:
    """Initialize a hybrid WML simulator for the given model.

    Raises:
        TypeError: An operator has the wrong type, or ``seed`` or ``workers``
            has the wrong type.
        ValueError: ``workers`` or ``num_steps`` is not positive, ``total_time``
            is negative, ``basis`` is malformed, the backend has no shot budget,
            an operator does not act on the register, or every sampling weight
            is zero.
    """
    super().__init__(
        hamiltonians,
        lindblads,
        initial_state,
        num_qubits=num_qubits,
        total_time=total_time,
        time_steps=time_steps,
        id="hybrid_wml_simulator",
    )
    if self.total_time < 0.0:
        raise ValueError("total_time must be non-negative")
    self._configure_run(
        num_steps=_positive_int("num_steps", num_steps),
        verbose=verbose,
        seed=seed,
        progress=progress,
        workers=workers,
        circuit_backend=circuit_backend,
        basis=basis,
    )
    _prepare(self.hamiltonians, self.lindblads, self.num_qubits)

metrics_circuit

metrics_circuit() -> Program

Return the program executed at the final time, including measurement.

Source code in shadowsim/simulators/hybrid_wml_simulator.py
def metrics_circuit(self) -> Program:
    """Return the program executed at the final time, including measurement."""
    return _hybrid_wml_circuit(
        cast(list[LocalHamiltonian], self.hamiltonians),
        cast(list[LocalOperator], self.lindblads),
        self.initial_state,
        self.num_qubits,
        float(self.tlist[-1]),
        self.num_steps,
        verbose=False,
        seed=self.seed,
        time_index=len(self.tlist) - 1,
        basis=self.basis,
    )