Skip to content

splitjmatrix_simulator

Split JMatrix quantum-inspired simulator.

SplitJMatrixSimulator

Bases: ProductFormulaSimulator

Simulate open-system dynamics with the Split JMatrix method.

Each of the num_steps applies every Lindblad jump once, then trotter_depth Hamiltonian slices. order=1 (the default) applies each local term once per slice of width t / (num_steps * trotter_depth), in list order. order=2 uses one Strang step per slice: half-steps forward, a full step on the last term, then half-steps in reverse. Either order covers coherent time t.

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 result keeps one counts dict per time point, where bit i of a key is system qubit i and the ancilla bit is dropped. 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 and uses the same seed. workers=1 (the default) runs those points serially, in tlist order. workers greater than 1 runs one process-pool task per time point. Traces are still returned in tlist order, and progress(index, total) may run in completion order. A job from start() counts each finished time point in completed_steps.

Source code in shadowsim/simulators/splitjmatrix_simulator.py
class SplitJMatrixSimulator(ProductFormulaSimulator):
    """Simulate open-system dynamics with the Split JMatrix method.

    Each of the ``num_steps`` applies every Lindblad jump once, then
    ``trotter_depth`` Hamiltonian slices. ``order=1`` (the default) applies each
    local term once per slice of width ``t / (num_steps * trotter_depth)``, in
    list order. ``order=2`` uses one Strang step per slice: half-steps forward,
    a full step on the last term, then half-steps in reverse. Either order
    covers coherent time ``t``.

    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 result keeps one counts dict per time point, where bit ``i`` of a key is
    system qubit ``i`` and the ancilla bit is dropped.
    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`` and uses the same ``seed``.
    ``workers=1`` (the default) runs those points serially, in ``tlist`` order.
    ``workers`` greater than 1 runs one process-pool task per time point.
    Traces are still returned in ``tlist`` order, and ``progress(index, total)``
    may run in completion order. A job from ``start()`` counts each finished
    time point in ``completed_steps``.
    """

    title: str = "Split J"
    requires_sampling_backend: bool = True
    sampling_backend_error: str = "Split JMatrix samples an ancilla circuit and needs a backend with a shot budget"
    counts_skip: int = 1

    def __init__(
        self,
        hamiltonians: List[LocalHamiltonian],
        lindblads: List[LocalOperator],
        initial_state: State,
        *,
        num_qubits: int,
        total_time: float,
        time_steps: int,
        num_steps: int,
        trotter_depth: int = 1,
        order: Literal[1, 2] = 1,
        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 Split JMatrix simulator for the given model."""
        super().__init__(
            hamiltonians,
            lindblads,
            initial_state,
            num_qubits=num_qubits,
            total_time=total_time,
            time_steps=time_steps,
            id="split_jmatrix_simulator",
        )
        for L in self.lindblads:
            if not isinstance(L, LocalOperator):
                raise TypeError(
                    "SplitJMatrixSimulator `lindblads` must be LocalOperator (with "
                    f"`sites` on the register); got {type(L).__name__}."
                )
        self._configure_run(
            num_steps=num_steps,
            trotter_depth=trotter_depth,
            order=order,
            verbose=verbose,
            seed=seed,
            progress=progress,
            workers=workers,
            circuit_backend=circuit_backend,
            basis=basis,
        )

    def _time_point_call(self, t: float, _index: int) -> TimeCall:
        """Return the ancilla-circuit counts call for time ``t``."""
        hamiltonians = cast(list[LocalHamiltonian], self.hamiltonians)
        lindblads = cast(list[LocalOperator], self.lindblads)
        return (
            _split_jmatrix,
            (
                hamiltonians,
                lindblads,
                self.initial_state,
                self.num_qubits,
                t,
                self.num_steps,
                self.trotter_depth,
            ),
            {
                "order": self.order,
                "verbose": self.verbose,
                "shots": backend_shots(self.circuit_backend),
                # Same seed the serial loop passes for this circuit.
                "seed": self.seed,
                "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 _split_jmatrix_circuit(
            cast(list[LocalHamiltonian], self.hamiltonians),
            cast(list[LocalOperator], self.lindblads),
            self.initial_state,
            self.num_qubits,
            float(self.tlist[-1]),
            self.num_steps,
            self.trotter_depth,
            order=self.order,
            verbose=False,
            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,
    trotter_depth: int = 1,
    order: Literal[1, 2] = 1,
    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 Split JMatrix simulator for the given model.

Source code in shadowsim/simulators/splitjmatrix_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,
    trotter_depth: int = 1,
    order: Literal[1, 2] = 1,
    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 Split JMatrix simulator for the given model."""
    super().__init__(
        hamiltonians,
        lindblads,
        initial_state,
        num_qubits=num_qubits,
        total_time=total_time,
        time_steps=time_steps,
        id="split_jmatrix_simulator",
    )
    for L in self.lindblads:
        if not isinstance(L, LocalOperator):
            raise TypeError(
                "SplitJMatrixSimulator `lindblads` must be LocalOperator (with "
                f"`sites` on the register); got {type(L).__name__}."
            )
    self._configure_run(
        num_steps=num_steps,
        trotter_depth=trotter_depth,
        order=order,
        verbose=verbose,
        seed=seed,
        progress=progress,
        workers=workers,
        circuit_backend=circuit_backend,
        basis=basis,
    )

metrics_circuit

metrics_circuit() -> Program

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

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