tensorcircuit-nightly 1.0.2.dev20250108__py3-none-any.whl → 1.4.0.dev20251103__py3-none-any.whl

tensorcircuit/stabilizercircuit.py

@@ -0,0 +1,479 @@
+"""
+Stabilizer circuit simulator using Stim backend
+"""
+
+from typing import Any, Dict, List, Optional, Sequence
+import numpy as np
+import stim
+
+from .abstractcircuit import AbstractCircuit
+
+Tensor = Any
+
+
+class StabilizerCircuit(AbstractCircuit):
+    """
+    Quantum circuit simulator for stabilizer circuits using Stim backend.
+    Supports Clifford operations and measurements.
+    """
+
+    # Add gate sets as class attributes
+    clifford_gates = ["h", "x", "y", "z", "cnot", "cz", "swap", "s", "sd"]
+    gate_map = {
+        "h": "H",
+        "x": "X",
+        "y": "Y",
+        "z": "Z",
+        "cnot": "CNOT",
+        "cz": "CZ",
+        "swap": "SWAP",
+        "s": "S",
+        "sd": "S_DAG",
+    }
+
+    def __init__(
+        self, nqubits: int, inputs: Tensor = None, tableau_inputs: Tensor = None
+    ) -> None:
+        """
+        ``StabilizerCircuit`` class based on stim package
+
+        :param nqubits: Number of qubits
+        :type nqubits: int
+        :param inputs: initial state by stabilizers, defaults to None
+        :type inputs: Tensor, optional
+        :param tableau_inputs: initial state by **inverse** tableau, defaults to None
+        :type tableau_inputs: Tensor, optional
+        """
+        self._nqubits = nqubits
+        self._stim_circuit = stim.Circuit()
+        self._qir: List[Dict[str, Any]] = []
+        self.is_dm = False
+        self.inputs = None
+        self._extra_qir: List[Dict[str, Any]] = []
+        self.current_sim = stim.TableauSimulator()
+        if inputs:
+            self.current_sim.set_state_from_stabilizers(inputs)
+        if tableau_inputs:
+            self.current_sim.set_inverse_tableau(tableau_inputs)
+
+    def apply_general_gate(
+        self,
+        gate: Any,
+        *index: int,
+        name: Optional[str] = None,
+        **kws: Any,
+    ) -> None:
+        """
+        Apply a Clifford gate to the circuit.
+
+        :param gate: Gate to apply (must be Clifford)
+        :type gate: Any
+        :param index: Qubit indices to apply the gate to
+        :type index: int
+        :param name: Name of the gate operation, defaults to None
+        :type name: Optional[str], optional
+        :raises ValueError: If non-Clifford gate is applied
+        """
+        if name is None:
+            name = ""
+
+        # Record gate in QIR
+        gate_dict = {
+            "gate": gate,
+            "index": index,
+            "name": name,
+            "split": None,
+            "mpo": False,
+        }
+        ir_dict = kws["ir_dict"]
+        if ir_dict is not None:
+            ir_dict.update(gate_dict)
+        else:
+            ir_dict = gate_dict
+        self._qir.append(ir_dict)
+
+        # Map TensorCircuit gates to Stim gates
+
+        if name.lower() in self.gate_map:
+            # self._stim_circuit.append(gate_map[name.lower()], list(index))
+            gn = self.gate_map[name.lower()]
+            instruction = f"{gn} {' '.join(map(str, index))}"
+            self._stim_circuit.append_from_stim_program_text(instruction)
+            # append is much slower
+            # self.current_sim.do(stim.Circuit(instruction))
+            getattr(self.current_sim, gn.lower())(*index)
+        else:
+            raise ValueError(f"Gate {name} is not supported in stabilizer simulation")
+
+    apply = apply_general_gate
+
+    def state(self) -> Tensor:
+        """
+        Return the wavefunction of the circuit.
+        Note that the state can have smaller qubit count if no gate is applied on later qubits
+        """
+        tab = self.current_tableau()
+        return tab.to_state_vector(endian="big")
+
+    def random_gate(self, *index: int, recorded: bool = False) -> None:
+        """
+        Apply a random Clifford gate to the circuit.
+        This operation will not record in qir
+
+        :param index: Qubit indices to apply the gate to
+        :type index: int
+        :param recorded: Whether the gate is recorded in ``stim.Circuit``, defaults to False
+        :type recorded: bool, optional
+        """
+        m = len(index)
+        t = stim.Tableau.random(m)
+        self.current_sim.do_tableau(t, index)
+        if recorded:
+            self._stim_circuit += t.to_circuit()
+
+    def tableau_gate(self, *index: int, tableau: Any, recorded: bool = False) -> None:
+        """
+        Apply a gate indicated by tableau to the circuit.
+        This operation will not record in qir
+
+        :param index: Qubit indices to apply the gate to
+        :type index: int
+        :param tableau: stim.Tableau representation of the gate
+        :type tableau: Any
+        :param recorded: Whether the gate is recorded in ``stim.Circuit``, defaults to False
+        :type recorded: bool, optional
+        """
+        self.current_sim.do_tableau(tableau, index)
+        if recorded:
+            self._stim_circuit += tableau.to_circuit()
+
+    def measure(self, *index: int, with_prob: bool = False) -> Tensor:
+        """
+        Measure qubits in the Z basis.
+
+        :param index: Indices of the qubits to measure.
+        :type index: int
+        :param with_prob: If True, returns the theoretical probability of the measurement outcome.
+            defaults to False
+        :type with_prob: bool, optional
+        :return: A tensor containing the measurement results.
+            If `with_prob` is True, a tuple containing the results and the probability is returned.
+        :rtype: Tensor
+        """
+        # Convert negative indices
+
+        index = tuple([i for i in index if i >= 0])
+
+        # Add measurement instructions
+        s1 = self.current_simulator().copy()
+        # Sample once from the circuit using sampler
+
+        if with_prob:
+            num_random_measurements = 0
+            for i in index:
+                if s1.peek_z(i) == 0:
+                    num_random_measurements += 1
+            probability = (0.5) ** num_random_measurements
+
+        m = s1.measure_many(*index)
+        if with_prob:
+            return m, probability
+        return m
+
+    def cond_measurement(self, index: int) -> Tensor:
+        """
+        Measure a single qubit in the Z basis and collapse the state.
+
+        :param index: The index of the qubit to measure.
+        :type index: int
+        :return: The measurement result (0 or 1).
+        :rtype: Tensor
+        """
+        # Convert negative indices
+
+        # Add measurement instructions
+        self._stim_circuit.append_from_stim_program_text("M " + str(index))
+        # self.current_sim = None
+        m = self.current_simulator().measure(index)
+        # Sample once from the circuit using sampler
+
+        return m
+
+    cond_measure = cond_measurement
+
+    def cond_measure_many(self, *index: int) -> Tensor:
+        """
+        Measure multiple qubits in the Z basis and collapse the state.
+
+        :param index: The indices of the qubits to measure.
+        :type index: int
+        :return: A tensor containing the measurement results.
+        :rtype: Tensor
+        """
+        # Convert negative indices
+
+        # Add measurement instructions
+        self._stim_circuit.append_from_stim_program_text(
+            "M " + " ".join(map(str, index))
+        )
+        # self.current_sim = None
+        m = self.current_simulator().measure_many(*index)
+        # Sample once from the circuit using sampler
+
+        return m
+
+    def sample(
+        self,
+        batch: Optional[int] = None,
+        **kws: Any,
+    ) -> Tensor:
+        """
+        Sample measurements from the circuit.
+
+        :param batch: Number of samples to take, defaults to None (single sample)
+        :type batch: Optional[int], optional
+        :return: Measurement results
+        :rtype: Tensor
+        """
+        if batch is None:
+            batch = 1
+        c = self.current_circuit().copy()
+        for i in range(self._nqubits):
+            c.append("M", [i])
+        sampler = c.compile_sampler()
+        samples = sampler.sample(batch)
+        return np.array(samples)
+
+    def expectation_ps(  # type: ignore
+        self,
+        x: Optional[Sequence[int]] = None,
+        y: Optional[Sequence[int]] = None,
+        z: Optional[Sequence[int]] = None,
+        **kws: Any,
+    ) -> Any:
+        """
+        Compute exact expectation value of Pauli string using stim's direct calculation.
+
+        :param x: Indices for Pauli X measurements
+        :type x: Optional[Sequence[int]], optional
+        :param y: Indices for Pauli Y measurements
+        :type y: Optional[Sequence[int]], optional
+        :param z: Indices for Pauli Z measurements
+        :type z: Optional[Sequence[int]], optional
+        :return: Expectation value
+        :rtype: float
+        """
+        # Build Pauli string representation
+        pauli_str = ["I"] * self._nqubits
+
+        if x:
+            for i in x:
+                pauli_str[i] = "X"
+        if y:
+            for i in y:
+                pauli_str[i] = "Y"
+        if z:
+            for i in z:
+                pauli_str[i] = "Z"
+
+        pauli_string = "".join(pauli_str)
+        # Calculate expectation using stim's direct method
+        expectation = self.current_simulator().peek_observable_expectation(
+            stim.PauliString(pauli_string)
+        )
+        return expectation
+
+    expps = expectation_ps
+
+    def sample_expectation_ps(
+        self,
+        x: Optional[Sequence[int]] = None,
+        y: Optional[Sequence[int]] = None,
+        z: Optional[Sequence[int]] = None,
+        shots: Optional[int] = None,
+        **kws: Any,
+    ) -> float:
+        """
+        Compute expectation value of Pauli string measurements.
+
+        :param x: Indices for Pauli X measurements, defaults to None
+        :type x: Optional[Sequence[int]], optional
+        :param y: Indices for Pauli Y measurements, defaults to None
+        :type y: Optional[Sequence[int]], optional
+        :param z: Indices for Pauli Z measurements, defaults to None
+        :type z: Optional[Sequence[int]], optional
+        :param shots: Number of measurement shots, defaults to None
+        :type shots: Optional[int], optional
+        :return: Expectation value
+        :rtype: float
+        """
+        if shots is None:
+            shots = 1000  # Default number of shots
+
+        circuit = self._stim_circuit.copy()
+
+        # Add basis rotations for measurements
+        if x:
+            for i in x:
+                circuit.append("H", [i])
+        if y:
+            for i in y:
+                circuit.append("S_DAG", [i])
+                circuit.append("H", [i])
+
+        # Add measurements
+        measured_qubits: List[int] = []
+        if x:
+            measured_qubits.extend(x)
+        if y:
+            measured_qubits.extend(y)
+        if z:
+            measured_qubits.extend(z)
+
+        for i in measured_qubits:
+            circuit.append("M", [i])
+
+        # Sample and compute expectation using sampler
+        sampler = circuit.compile_sampler()
+        samples = sampler.sample(shots)
+        results = np.array(samples)
+
+        # Convert from {0,1} to {1,-1}
+        results = 1 - 2 * results
+
+        # Average over shots
+        expectation = np.mean(np.prod(results, axis=1))
+
+        return float(expectation)
+
+    sexpps = sample_expectation_ps
+
+    def mid_measurement(self, index: int, keep: int = 0) -> Tensor:
+        """
+        Perform a mid-measurement operation on a qubit on z direction.
+        The post-selection cannot be recorded in ``stim.Circuit``
+
+        :param index: Index of the qubit to measure
+        :type index: int
+        :param keep: State of qubits to keep after measurement, defaults to 0 (up)
+        :type keep: int, optional
+        :return: Result of the mid-measurement operation
+        :rtype: Tensor
+        """
+        if keep not in [0, 1]:
+            raise ValueError("keep must be 0 or 1")
+
+        self.current_sim.postselect_z(index, desired_value=keep)
+
+    mid_measure = mid_measurement
+    post_select = mid_measurement
+    post_selection = mid_measurement
+
+    def depolarizing(self, *index: int, p: float) -> None:
+        """
+        Apply depolarizing noise to a qubit.
+
+        :param index: Index of the qubit to apply noise to
+        :type index: int
+        :param p: Noise parameter (probability of depolarizing)
+        :type p: float
+        """
+        self._stim_circuit.append_from_stim_program_text(
+            f"DEPOLARIZE1({p}) {' '.join(map(str, index))}"
+        )
+        self.current_sim.depolarize1(*index, p=p)
+
+    def current_simulator(self) -> stim.TableauSimulator:
+        """
+        Return the current simulator of the circuit.
+        """
+        return self.current_sim
+
+    def current_circuit(self) -> stim.Circuit:
+        """
+        Return the current stim circuit representation of the circuit.
+        """
+        return self._stim_circuit
+
+    def current_tableau(self) -> stim.Tableau:
+        """
+        Return the current tableau of the circuit.
+        """
+        return self.current_simulator().current_inverse_tableau() ** -1
+
+    def current_inverse_tableau(self) -> stim.Tableau:
+        """
+        Return the current inverse tableau of the circuit.
+        """
+        return self.current_simulator().current_inverse_tableau()
+
+    def entanglement_entropy(self, cut: Sequence[int]) -> float:
+        """
+        Calculate the entanglement entropy for a subset of qubits using stabilizer formalism.
+
+        :param cut: Indices of qubits to calculate entanglement entropy for
+        :type cut: Sequence[int]
+        :return: Entanglement entropy
+        :rtype: float
+        """
+        # Get stabilizer tableau
+        tableau = self.current_tableau()
+        N = len(tableau)
+
+        # Pre-allocate binary matrix with proper dtype
+        # binary_matrix = np.zeros((N, 2 * N), dtype=np.int8)
+
+        # Vectorized conversion of stabilizers to binary matrix
+        # z_outputs = np.array([tableau.z_output(k) for k in range(N)])
+        # x_part = z_outputs == 1  # X
+        # z_part = z_outputs == 3  # Z
+        # y_part = z_outputs == 2  # Y
+
+        # binary_matrix[:, :N] = x_part | y_part
+        # binary_matrix[:, N:] = z_part | y_part
+
+        _, _, z2x, z2z, _, _ = tableau.to_numpy()
+        binary_matrix = np.concatenate([z2x, z2z], axis=1)
+        # Get reduced matrix for the cut using boolean indexing
+        cut_set = set(cut)
+        cut_indices = np.array(
+            [i for i in range(N) if i in cut_set]
+            + [i + N for i in range(N) if i in cut_set]
+        )
+        reduced_matrix = binary_matrix[:, cut_indices]
+
+        # Efficient rank calculation using Gaussian elimination
+        matrix = reduced_matrix.copy()
+        n_rows, n_cols = matrix.shape
+        rank = 0
+        row = 0
+
+        for col in range(n_cols):
+            # Vectorized pivot finding
+            pivot_rows = np.nonzero(matrix[row:, col])[0]
+            if len(pivot_rows) > 0:
+                pivot_row = pivot_rows[0] + row
+
+                # Swap rows if necessary
+                if pivot_row != row:
+                    matrix[row], matrix[pivot_row] = (
+                        matrix[pivot_row].copy(),
+                        matrix[row].copy(),
+                    )
+
+                # Vectorized elimination
+                eliminate_mask = matrix[row + 1 :, col] == 1
+                matrix[row + 1 :][eliminate_mask] ^= matrix[row]
+
+                rank += 1
+                row += 1
+
+                if row == n_rows:
+                    break
+
+        # Calculate entropy
+        return float((rank - len(cut)) * np.log(2))
+
+
+# Call _meta_apply at module level to register the gates
+StabilizerCircuit._meta_apply()

tensorcircuit/templates/__init__.py

@@ -5,5 +5,7 @@ from . import dataset
 from . import graphs
 from . import measurements
 from . import conversions
+from . import lattice
+from . import hamiltonians
 
 costfunctions = measurements

tensorcircuit/templates/blocks.py

@@ -91,7 +91,7 @@ def QAOA_block(
                 e2,
                 unitary=G._zz_matrix,
                 theta=paramzz * g[e1][e2].get("weight", 1.0),
-                **kws
+                **kws,
             )
     else:
         i = 0
@@ -157,7 +157,7 @@ def qft(
     *index: int,
     do_swaps: bool = True,
     inverse: bool = False,
-    insert_barriers: bool = False
+    insert_barriers: bool = False,
 ) -> Circuit:
     """
     This function applies quantum fourier transformation (QFT) to the selected circuit lines

tensorcircuit/templates/hamiltonians.py

@@ -0,0 +1,174 @@
+from typing import Any, List, Tuple, Union
+import numpy as np
+from ..cons import dtypestr, backend
+from ..quantum import PauliStringSum2COO
+from .lattice import AbstractLattice
+
+
+def _create_empty_sparse_matrix(shape: Tuple[int, int]) -> Any:
+    """
+    Helper function to create a backend-agnostic empty sparse matrix.
+    """
+    indices = backend.convert_to_tensor(backend.zeros((0, 2), dtype="int32"))
+    values = backend.convert_to_tensor(backend.zeros((0,), dtype=dtypestr))  # type: ignore
+    return backend.coo_sparse_matrix(indices=indices, values=values, shape=shape)  # type: ignore
+
+
+def heisenberg_hamiltonian(
+    lattice: AbstractLattice,
+    j_coupling: Union[float, List[float], Tuple[float, ...]] = 1.0,
+    interaction_scope: str = "neighbors",
+) -> Any:
+    r"""
+    Generates the sparse matrix of the Heisenberg Hamiltonian for a given lattice.
+
+    The Heisenberg Hamiltonian is defined as:
+    :math:`H = J\sum_{i,j} (X_i X_j + Y_i Y_j + Z_i Z_j)`
+    where the sum is over a specified set of interacting pairs {i,j}.
+
+    :param lattice: An instance of a class derived from AbstractLattice,
+        which provides the geometric information of the system.
+    :type lattice: AbstractLattice
+    :param j_coupling: The coupling constants. Can be a single float for an
+        isotropic model (Jx=Jy=Jz) or a list/tuple of 3 floats for an
+        anisotropic model (Jx, Jy, Jz). Defaults to 1.0.
+    :type j_coupling: Union[float, List[float], Tuple[float, ...]], optional
+    :param interaction_scope: Defines the range of interactions.
+        - "neighbors": Includes only nearest-neighbor pairs (default).
+        - "all": Includes all unique pairs of sites.
+    :type interaction_scope: str, optional
+    :return: The Hamiltonian as a backend-agnostic sparse matrix.
+    :rtype: Any
+    """
+    num_sites = lattice.num_sites
+    if interaction_scope == "neighbors":
+        neighbor_pairs = lattice.get_neighbor_pairs(k=1, unique=True)
+    elif interaction_scope == "all":
+        neighbor_pairs = lattice.get_all_pairs()
+    else:
+        raise ValueError(
+            f"Invalid interaction_scope: '{interaction_scope}'. "
+            "Must be 'neighbors' or 'all'."
+        )
+
+    if isinstance(j_coupling, (float, int)):
+        js = [float(j_coupling)] * 3
+    else:
+        if len(j_coupling) != 3:
+            raise ValueError("j_coupling must be a float or a list/tuple of 3 floats.")
+        js = [float(j) for j in j_coupling]
+
+    if not neighbor_pairs:
+        return _create_empty_sparse_matrix(shape=(2**num_sites, 2**num_sites))
+    if num_sites == 0:
+        raise ValueError("Cannot generate a Hamiltonian for a lattice with zero sites.")
+
+    pauli_map = {"X": 1, "Y": 2, "Z": 3}
+
+    ls: List[List[int]] = []
+    weights: List[float] = []
+
+    pauli_terms = ["X", "Y", "Z"]
+    for i, j in neighbor_pairs:
+        for idx, pauli_char in enumerate(pauli_terms):
+            if abs(js[idx]) > 1e-9:
+                string = [0] * num_sites
+                string[i] = pauli_map[pauli_char]
+                string[j] = pauli_map[pauli_char]
+                ls.append(string)
+                weights.append(js[idx])
+
+    hamiltonian_matrix = PauliStringSum2COO(ls, weight=weights, numpy=False)
+
+    return hamiltonian_matrix
+
+
+def rydberg_hamiltonian(
+    lattice: AbstractLattice, omega: float, delta: float, c6: float
+) -> Any:
+    r"""
+    Generates the sparse matrix of the Rydberg atom array Hamiltonian.
+
+    The Hamiltonian is defined as:
+    .. math::
+
+    H = \sum_i \frac{\Omega}{2} X_i
+        - \sum_i \frac{\delta}{2} \bigl(1 - Z_i \bigr)
+        + \sum_{i<j} \frac{V_{ij}}{4} \bigl(1 - Z_i \bigr)\bigl(1 - Z_j \bigr)
+
+      = \sum_i \frac{\Omega}{2} X_i
+        + \sum_i \frac{\delta}{2} Z_i
+        + \sum_{i<j} \frac{V_{ij}}{4}\,\bigl(Z_i Z_j - Z_i - Z_j \bigr)
+
+    where :math:`V_{ij} = C6 / |r_i - r_j|^6`.
+
+    Note: Constant energy offset terms (proportional to the identity operator)
+    are ignored in this implementation.
+
+    :param lattice: An instance of a class derived from AbstractLattice,
+        which provides site coordinates and the distance matrix.
+    :type lattice: AbstractLattice
+    :param omega: The Rabi frequency (Ω) of the driving laser field.
+    :type omega: float
+    :param delta: The laser detuning (δ).
+    :type delta: float
+    :param c6: The Van der Waals interaction coefficient (C6).
+    :type c6: float
+    :return: The Hamiltonian as a backend-agnostic sparse matrix.
+    :rtype: Any
+    """
+    num_sites = lattice.num_sites
+    if num_sites == 0:
+        raise ValueError("Cannot generate a Hamiltonian for a lattice with zero sites.")
+
+    pauli_map = {"X": 1, "Y": 2, "Z": 3}
+    ls: List[List[int]] = []
+    weights: List[float] = []
+
+    for i in range(num_sites):
+        x_string = [0] * num_sites
+        x_string[i] = pauli_map["X"]
+        ls.append(x_string)
+        weights.append(omega / 2.0)
+
+    z_coefficients = np.zeros(num_sites)
+
+    for i in range(num_sites):
+        z_coefficients[i] += delta / 2.0
+
+    dist_matrix = lattice.distance_matrix
+
+    for i in range(num_sites):
+        for j in range(i + 1, num_sites):
+            distance = dist_matrix[i, j]
+
+            if distance < 1e-9:
+                continue
+
+            interaction_strength = c6 / (distance**6)
+            coefficient = interaction_strength / 4.0
+
+            zz_string = [0] * num_sites
+            zz_string[i] = pauli_map["Z"]
+            zz_string[j] = pauli_map["Z"]
+            ls.append(zz_string)
+            weights.append(coefficient)
+
+            # The interaction term V_ij * n_i * n_j, when expanded using
+            # n_i = (1-Z_i)/2, becomes (V_ij/4)*(I - Z_i - Z_j + Z_i*Z_j).
+            # This contributes a positive term (+V_ij/4) to the ZZ interaction,
+            # but negative terms (-V_ij/4) to the single-site Z_i and Z_j operators.
+
+            z_coefficients[i] -= coefficient
+            z_coefficients[j] -= coefficient
+
+    for i in range(num_sites):
+        if abs(z_coefficients[i]) > 1e-9:
+            z_string = [0] * num_sites
+            z_string[i] = pauli_map["Z"]
+            ls.append(z_string)
+            weights.append(z_coefficients[i])  # type: ignore
+
+    hamiltonian_matrix = PauliStringSum2COO(ls, weight=weights, numpy=False)
+
+    return hamiltonian_matrix