tensorcircuit-nightly 1.2.0.dev20250326__py3-none-any.whl → 1.4.0.dev20251128__py3-none-any.whl

tensorcircuit/results/counts.py

@@ -6,12 +6,26 @@ from typing import Any, Dict, Optional, Sequence
 
 import numpy as np
 
+from ..quantum import _decode_basis_label
 
 Tensor = Any
 ct = Dict[str, int]
 
 
 def reverse_count(count: ct) -> ct:
+    """
+    Reverse the bit string keys in a count dictionary.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :return: A new dictionary with reversed bit string keys
+    :rtype: ct
+
+    :Example:
+
+    >>> reverse_count({"01": 10, "10": 20})
+    {'10': 10, '01': 20}
+    """
     ncount = {}
     for k, v in count.items():
         ncount[k[::-1]] = v
@@ -19,15 +33,56 @@ def reverse_count(count: ct) -> ct:
 
 
 def sort_count(count: ct) -> ct:
+    """
+    Sort the count dictionary by counts in descending order.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :return: A new dictionary sorted by count values (descending)
+    :rtype: ct
+
+    :Example:
+
+    >>> sort_count({"00": 5, "01": 15, "10": 10})
+    {'01': 15, '10': 10, '00': 5}
+    """
     return {k: v for k, v in sorted(count.items(), key=lambda item: -item[1])}
 
 
 def normalized_count(count: ct) -> Dict[str, float]:
+    """
+    Normalize the count dictionary to represent probabilities.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :return: A new dictionary with probabilities instead of counts
+    :rtype: Dict[str, float]
+
+    :Example:
+
+    >>> normalized_count({"00": 5, "01": 15})
+    {'00': 0.25, '01': 0.75}
+    """
     shots = sum([v for k, v in count.items()])
     return {k: v / shots for k, v in count.items()}
 
 
 def marginal_count(count: ct, keep_list: Sequence[int]) -> ct:
+    """
+    Compute the marginal distribution of a count dictionary over specified qubits.
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :param keep_list: List of qubit indices to keep in the marginal distribution
+    :type keep_list: Sequence[int]
+    :return: A new count dictionary with marginal distribution
+    :rtype: ct
+
+    :Example:
+
+    >>> marginal_count({"001": 10, "110": 20}, [0, 2])
+    {'01': 10, '10': 20}
+    """
     import qiskit
 
     count = reverse_count(count)
@@ -35,34 +90,87 @@ def marginal_count(count: ct, keep_list: Sequence[int]) -> ct:
     return reverse_count(ncount)
 
 
-def count2vec(count: ct, normalization: bool = True) -> Tensor:
-    nqubit = len(list(count.keys())[0])
-    probability = [0] * 2**nqubit
-    shots = sum([v for k, v in count.items()])
+def count2vec(
+    count: ct, normalization: bool = True, dim: Optional[int] = None
+) -> Tensor:
+    """
+    Convert a dictionary of counts (with string keys) to a probability/count vector.
+
+    Support:
+      - base-d string (d <= 36), characters taken from 0-9A-Z (case-insensitive)
+        For example:
+          qubit: '0101'
+          qudit: '012' or '09A' (A represents 10, which means [0, 9, 10])
+
+    :param count: A dictionary mapping bit strings to counts
+    :type count: ct
+    :param normalization: Whether to normalize the counts to probabilities, defaults to True
+    :type normalization: bool, optional
+    :param dim: Dimensionality of the vector, defaults to 2
+    :type dim: int, optional
+    :return: Probability vector as numpy array
+    :rtype: Tensor
+
+    :Example:
+
+    >>> count2vec({"00": 2, "10": 3, "11": 5})
+    array([0.2, 0. , 0.3, 0.5])
+    """
+
+    if not count:
+        return np.array([], dtype=float)
+
+    dim = 2 if dim is None else dim
+
+    n = len(next(iter(count)).upper())
+    prob = np.zeros(dim**n, dtype=float)
+    shots = float(sum(count.values())) if normalization else 1.0
+    if shots == 0:
+        return prob
+
+    powers = [dim**p for p in range(n)][::-1]
     for k, v in count.items():
-        if normalization is True:
-            v /= shots  # type: ignore
-        probability[int(k, 2)] = v
-    return np.array(probability)
+        digits = _decode_basis_label(k, n, dim)
+        idx = sum(dig * p for dig, p in zip(digits, powers))
+        prob[idx] = (v / shots) if normalization else v
+
+    return prob
+
 
+def vec2count(vec: Tensor, prune: bool = False, dim: Optional[int] = None) -> ct:
+    """
+    Map a count/probability vector of length D to a dictionary with base-d string keys (0-9A-Z).
+    Only generate string keys when d <= 36; if d is inferred to be > 36, raise a NotImplementedError.
 
-def vec2count(vec: Tensor, prune: bool = False) -> ct:
-    from ..quantum import count_vector2dict
+    :param vec: A one-dimensional vector of length D = d**n
+    :param prune: Whether to prune near-zero elements (threshold 1e-8)
+    :param dim: Dimensionality of the vector, defaults to 2
+    :return: {base-d string key: value}, key length n
+    """
+    from ..quantum import count_vector2dict, _infer_num_sites
 
+    dim = 2 if dim is None else dim
     if isinstance(vec, list):
         vec = np.array(vec)
-    n = int(np.log(vec.shape[0]) / np.log(2) + 1e-9)
-    c = count_vector2dict(vec, n, key="bin")
-    if prune is True:
-        nc = c.copy()
-        for k, v in c.items():
-            if np.abs(v) < 1e-8:
-                del nc[k]
-        return nc
+    n = _infer_num_sites(int(vec.shape[0]), dim)
+    c: ct = count_vector2dict(vec, n, key="bin", dim=dim)  # type: ignore
+    if prune:
+        c = {k: v for k, v in c.items() if np.abs(v) >= 1e-8}
+
     return c
 
 
 def kl_divergence(c1: ct, c2: ct) -> float:
+    """
+    Compute the Kullback-Leibler divergence between two count distributions.
+
+    :param c1: First count dictionary
+    :type c1: ct
+    :param c2: Second count dictionary
+    :type c2: ct
+    :return: KL divergence value
+    :rtype: float
+    """
     eps = 1e-4  # typical value for inverse of the total shots
     c1 = normalized_count(c1)  # type: ignore
     c2 = normalized_count(c2)  # type: ignore
@@ -113,6 +221,11 @@ def merge_count(*counts: ct) -> ct:
     :type counts: ct
     :return: Merged count dictionary
     :rtype: ct
+
+    :Example:
+
+    >>> merge_count({"00": 10, "01": 20}, {"00": 5, "10": 15})
+    {'00': 15, '01': 20, '10': 15}
     """
     merged: ct = {}
     for count in counts:

tensorcircuit/results/readout_mitigation.py

@@ -723,7 +723,10 @@ class ReadoutMit:
         cals = self._form_cals(qubits)
         M = M3MatVec(dict(counts), cals, distance)
         L = spla.LinearOperator(
-            (M.num_elems, M.num_elems), matvec=M.matvec, rmatvec=M.rmatvec
+            (M.num_elems, M.num_elems),
+            matvec=M.matvec,
+            rmatvec=M.rmatvec,
+            dtype=np.float64,
         )
         diags = M.get_diagonal()
 

tensorcircuit/shadows.py

@@ -334,7 +334,7 @@ def entropy_shadow(
 
 def renyi_entropy_2(snapshots: Tensor, sub: Optional[Sequence[int]] = None) -> Tensor:
     r"""To calculate the second order Renyi entropy of a subsystem from snapshot, please refer to
-    Brydges, T. et al. Science 364, 260–263 (2019). This function is not jitable.
+    Brydges, T. et al. Science 364, 260-263 (2019). This function is not jitable.
 
     :param snapshots: shape = (ns, repeat, nq)
     :type: Tensor

tensorcircuit/simplify.py

@@ -121,7 +121,9 @@ def _split_two_qubit_gate(
     if fixed_choice == 2:  # swap one
         return n3, n4, True  # swap
     s2 = n3.tensor.shape[-1]
-    if (s1 >= 4) and (s2 >= 4):
+    if (s1 >= n[0].dimension * n[2].dimension) and (
+        s2 >= n[1].dimension * n[3].dimension
+    ):
         # jax jit unspport split_node with trun_err anyway
         # tf function doesn't work either, though I believe it may work on tf side
         # CANNOT DONE(@refraction-ray): tf.function version with trun_err set

tensorcircuit/stabilizercircuit.py

@@ -96,10 +96,12 @@ class StabilizerCircuit(AbstractCircuit):
 
         if name.lower() in self.gate_map:
             # self._stim_circuit.append(gate_map[name.lower()], list(index))
-            instruction = f"{self.gate_map[name.lower()]} {' '.join(map(str, 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))
+            # 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")
 
@@ -147,14 +149,16 @@ class StabilizerCircuit(AbstractCircuit):
 
     def measure(self, *index: int, with_prob: bool = False) -> Tensor:
         """
-        Measure qubits in Z basis.
+        Measure qubits in the Z basis.
 
-        :param index: Indices of qubits to measure
+        :param index: Indices of the qubits to measure.
         :type index: int
-        :param with_prob: Return probability of measurement outcome, defaults to False
+        :param with_prob: If True, returns the theoretical probability of the measurement outcome.
+            defaults to False
         :type with_prob: bool, optional
-        :return: Measurement results and probability (if with_prob=True)
-        :rtype: Union[np.ndarray, Tuple[np.ndarray, float]]
+        :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
 
@@ -162,20 +166,28 @@ class StabilizerCircuit(AbstractCircuit):
 
         # Add measurement instructions
         s1 = self.current_simulator().copy()
-        m = s1.measure_many(*index)
         # Sample once from the circuit using sampler
 
-        # TODO(@refraction-ray): correct probability
+        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 qubits in Z basis with state collapse.
+        Measure a single qubit in the Z basis and collapse the state.
 
-        :param index: Index of qubit to measure
+        :param index: The index of the qubit to measure.
         :type index: int
-        :return: Measurement results and probability (if with_prob=True)
-        :rtype: Union[np.ndarray, Tuple[np.ndarray, float]]
+        :return: The measurement result (0 or 1).
+        :rtype: Tensor
         """
         # Convert negative indices
 
@@ -191,12 +203,12 @@ class StabilizerCircuit(AbstractCircuit):
 
     def cond_measure_many(self, *index: int) -> Tensor:
         """
-        Measure qubits in Z basis with state collapse.
+        Measure multiple qubits in the Z basis and collapse the state.
 
-        :param index: Index of qubit to measure
+        :param index: The indices of the qubits to measure.
         :type index: int
-        :return: Measurement results and probability (if with_prob=True)
-        :rtype: Union[np.ndarray, Tuple[np.ndarray, float]]
+        :return: A tensor containing the measurement results.
+        :rtype: Tensor
         """
         # Convert negative indices
 

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