tensorcircuit-nightly 1.3.0.dev20250728__py3-none-any.whl → 1.3.0.dev20250729__py3-none-any.whl

tensorcircuit/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.3.0.dev20250728"
+__version__ = "1.3.0.dev20250729"
 __author__ = "TensorCircuit Authors"
 __creator__ = "refraction-ray"
 
@@ -52,6 +52,7 @@ from . import compiler
 from . import cloud
 from . import fgs
 from .fgs import FGSSimulator
+from . import timeevol
 
 FGSCircuit = FGSSimulator
 

tensorcircuit/backends/abstract_backend.py

@@ -700,6 +700,9 @@ class ExtendedBackend:
             "Backend '{}' has not implemented `is_tensor`.".format(self.name)
         )
 
+    def matvec(self: Any, A: Tensor, x: Tensor) -> Tensor:
+        return self.tensordot(A, x, axes=[[1], [0]])
+
     def cast(self: Any, a: Tensor, dtype: str) -> Tensor:
         """
         Cast the tensor dtype of a ``a``.

tensorcircuit/backends/tensorflow_backend.py

@@ -678,7 +678,14 @@ class TensorFlowBackend(tensorflow_backend.TensorFlowBackend, ExtendedBackend):
         sp_a: Tensor,
         b: Tensor,
     ) -> Tensor:
-        return tf.sparse.sparse_dense_matmul(sp_a, b)
+        is_vec = False
+        if len(b.shape) == 1:
+            b = self.reshape(b, [-1, 1])
+            is_vec = True
+        r = tf.sparse.sparse_dense_matmul(sp_a, b)
+        if is_vec:
+            return self.reshape(r, [-1])
+        return r
 
     def _densify(self) -> Tensor:
         @partial(self.jit, jit_compile=True)

tensorcircuit/experimental.py

@@ -2,14 +2,20 @@
 Experimental features
 """
 
+# pylint: disable=unused-import
+
 from functools import partial
 import logging
 from typing import Any, Callable, Dict, Optional, Tuple, List, Sequence, Union
 
 import numpy as np
 
-from .cons import backend, dtypestr, contractor, rdtypestr, get_tn_info
+from .cons import backend, dtypestr, rdtypestr, get_tn_info
 from .gates import Gate
+from .timeevol import hamiltonian_evol, evol_global, evol_local
+
+
+# for backward compatibility
 
 Tensor = Any
 Circuit = Any
@@ -435,157 +441,6 @@ def finite_difference_differentiator(
     return tf_function  # type: ignore
 
 
-def hamiltonian_evol(
-    tlist: Tensor,
-    h: Tensor,
-    psi0: Tensor,
-    callback: Optional[Callable[..., Any]] = None,
-) -> Tensor:
-    """
-    Fast implementation of time independent Hamiltonian evolution using eigendecomposition.
-    By default, performs imaginary time evolution.
-
-    :param tlist: Time points for evolution
-    :type tlist: Tensor
-    :param h: Time-independent Hamiltonian matrix
-    :type h: Tensor
-    :param psi0: Initial state vector
-    :type psi0: Tensor
-    :param callback: Optional function to process state at each time point
-    :type callback: Optional[Callable[..., Any]], optional
-    :return: Evolution results at each time point. If callback is None, returns state vectors;
-            otherwise returns callback results
-    :rtype: Tensor
-
-    :Example:
-
-    >>> import tensorcircuit as tc
-    >>> import numpy as np
-    >>> # Define a simple 2-qubit Hamiltonian
-    >>> h = tc.array_to_tensor([
-    ...     [1.0, 0.0, 0.0, 0.0],
-    ...     [0.0, -1.0, 2.0, 0.0],
-    ...     [0.0, 2.0, -1.0, 0.0],
-    ...     [0.0, 0.0, 0.0, 1.0]
-    ... ])
-    >>> # Initial state |00⟩
-    >>> psi0 = tc.array_to_tensor([1.0, 0.0, 0.0, 0.0])
-    >>> # Evolution times
-    >>> times = tc.array_to_tensor([0.0, 0.5, 1.0])
-    >>> # Evolve and get states
-    >>> states = tc.experimental.hamiltonian_evol(times, h, psi0)
-    >>> print(states.shape)  # (3, 4)
-
-
-    Note:
-        1. The Hamiltonian must be time-independent
-        2. For time-dependent Hamiltonians, use ``evol_local`` or ``evol_global`` instead
-        3. The evolution is performed in imaginary time by default (factor -t in exponential)
-        4. The state is automatically normalized at each time point
-    """
-    es, u = backend.eigh(h)
-    utpsi0 = backend.reshape(
-        backend.transpose(u) @ backend.reshape(psi0, [-1, 1]), [-1]
-    )
-
-    @backend.jit
-    def _evol(t: Tensor) -> Tensor:
-        ebetah_utpsi0 = backend.exp(-t * es) * utpsi0
-        psi_exact = backend.conj(u) @ backend.reshape(ebetah_utpsi0, [-1, 1])
-        psi_exact = backend.reshape(psi_exact, [-1])
-        psi_exact = psi_exact / backend.norm(psi_exact)
-        if callback is None:
-            return psi_exact
-        return callback(psi_exact)
-
-    return backend.stack([_evol(t) for t in tlist])
-
-
-def evol_local(
-    c: Circuit,
-    index: Sequence[int],
-    h_fun: Callable[..., Tensor],
-    t: float,
-    *args: Any,
-    **solver_kws: Any,
-) -> Circuit:
-    """
-    ode evolution of time dependent Hamiltonian on circuit of given indices
-    [only jax backend support for now]
-
-    :param c: _description_
-    :type c: Circuit
-    :param index: qubit sites to evolve
-    :type index: Sequence[int]
-    :param h_fun: h_fun should return a dense Hamiltonian matrix
-        with input arguments time and *args
-    :type h_fun: Callable[..., Tensor]
-    :param t: evolution time
-    :type t: float
-    :return: _description_
-    :rtype: Circuit
-    """
-    from jax.experimental.ode import odeint
-
-    s = c.state()
-    n = c._nqubits
-    l = len(index)
-
-    def f(y: Tensor, t: Tensor, *args: Any) -> Tensor:
-        y = backend.reshape2(y)
-        y = Gate(y)
-        h = -1.0j * h_fun(t, *args)
-        h = backend.reshape2(h)
-        h = Gate(h)
-        edges = []
-        for i in range(n):
-            if i not in index:
-                edges.append(y[i])
-            else:
-                j = index.index(i)
-                edges.append(h[j])
-                h[j + l] ^ y[i]
-        y = contractor([y, h], output_edge_order=edges)
-        return backend.reshape(y.tensor, [-1])
-
-    ts = backend.stack([0.0, t])
-    ts = backend.cast(ts, dtype=rdtypestr)
-    s1 = odeint(f, s, ts, *args, **solver_kws)
-    return type(c)(n, inputs=s1[-1])
-
-
-def evol_global(
-    c: Circuit, h_fun: Callable[..., Tensor], t: float, *args: Any, **solver_kws: Any
-) -> Circuit:
-    """
-    ode evolution of time dependent Hamiltonian on circuit of all qubits
-    [only jax backend support for now]
-
-    :param c: _description_
-    :type c: Circuit
-    :param h_fun: h_fun should return a **SPARSE** Hamiltonian matrix
-        with input arguments time and *args
-    :type h_fun: Callable[..., Tensor]
-    :param t: _description_
-    :type t: float
-    :return: _description_
-    :rtype: Circuit
-    """
-    from jax.experimental.ode import odeint
-
-    s = c.state()
-    n = c._nqubits
-
-    def f(y: Tensor, t: Tensor, *args: Any) -> Tensor:
-        h = -1.0j * h_fun(t, *args)
-        return backend.sparse_dense_matmul(h, y)
-
-    ts = backend.stack([0.0, t])
-    ts = backend.cast(ts, dtype=rdtypestr)
-    s1 = odeint(f, s, ts, *args, **solver_kws)
-    return type(c)(n, inputs=s1[-1])
-
-
 def jax_jitted_function_save(filename: str, f: Callable[..., Any], *args: Any) -> None:
     """
     save a jitted jax function as a file

tensorcircuit/timeevol.py

@@ -0,0 +1,346 @@
+"""
+Analog time evolution engines
+"""
+
+from typing import Any, Tuple, Optional, Callable, List, Sequence
+
+from .cons import backend, dtypestr, rdtypestr, contractor
+from .gates import Gate
+
+Tensor = Any
+Circuit = Any
+
+
+def lanczos_iteration(
+    hamiltonian: Tensor, initial_vector: Tensor, subspace_dimension: int
+) -> Tuple[Tensor, Tensor]:
+    """
+    Use Lanczos algorithm to construct orthogonal basis and projected Hamiltonian
+    of Krylov subspace.
+
+    :param hamiltonian: Sparse or dense Hamiltonian matrix
+    :type hamiltonian: Tensor
+    :param initial_vector: Initial quantum state vector
+    :type initial_vector: Tensor
+    :param subspace_dimension: Dimension of Krylov subspace
+    :type subspace_dimension: int
+    :return: Tuple containing (basis matrix, projected Hamiltonian)
+    :rtype: Tuple[Tensor, Tensor]
+    """
+    # Initialize
+    vector = initial_vector
+    vector = backend.cast(vector, dtypestr)
+
+    # Use list to store basis vectors
+    basis_vectors: List[Any] = []
+
+    # Store alpha and beta coefficients for constructing tridiagonal matrix
+    alphas = []
+    betas = []
+
+    # Normalize initial vector
+    vector_norm = backend.norm(vector)
+    vector = vector / vector_norm
+
+    # Add first basis vector
+    basis_vectors.append(vector)
+
+    # Lanczos iteration (fixed number of iterations for JIT compatibility)
+    for j in range(subspace_dimension):
+        # Calculate H|v_j>
+        if backend.is_sparse(hamiltonian):
+            w = backend.sparse_dense_matmul(hamiltonian, vector)
+        else:
+            w = backend.matvec(hamiltonian, vector)
+
+        # Calculate alpha_j = <v_j|H|v_j>
+        alpha = backend.real(backend.sum(backend.conj(vector) * w))
+        alphas.append(alpha)
+
+        # w = H|v_j> - alpha_j|v_j> - beta_{j-1}|v_{j-1}>
+        # is not sufficient, require re-normalization
+        w = w - backend.cast(alpha, dtypestr) * vector
+
+        for k in range(j + 1):
+            v_k = basis_vectors[k]
+            projection = backend.sum(backend.conj(v_k) * w)
+            w = w - projection * v_k
+
+        # if j > 0:
+        #     w = w - prev_beta * basis_vectors[-2]
+
+        # Calculate beta_{j+1} = ||w||
+        beta = backend.norm(w)
+        betas.append(beta)
+
+        # Use regularization technique to avoid division by zero error,
+        # adding small epsilon value to ensure numerical stability
+        epsilon = 1e-15
+        norm_factor = 1.0 / (beta + epsilon)
+
+        # Normalize w to get |v_{j+1}> (except for the last iteration)
+        if j < subspace_dimension - 1:
+            vector = w * backend.cast(norm_factor, dtypestr)
+            basis_vectors.append(vector)
+
+    # Construct final basis matrix
+    basis_matrix = backend.stack(basis_vectors, axis=1)
+
+    # Construct tridiagonal projected Hamiltonian
+    # Use vectorized method to construct tridiagonal matrix at once
+    alphas_tensor = backend.stack(alphas)
+    # Only use first krylov_dim-1 beta values to construct off-diagonal
+    betas_tensor = backend.stack(betas[:-1]) if len(betas) > 1 else backend.stack([])
+
+    # Convert to correct data type
+    alphas_tensor = backend.cast(alphas_tensor, dtype=dtypestr)
+    if len(betas_tensor) > 0:
+        betas_tensor = backend.cast(betas_tensor, dtype=dtypestr)
+
+    # Construct diagonal and off-diagonal parts
+    diag_part = backend.diagflat(alphas_tensor)
+    if len(betas_tensor) > 0:
+        off_diag_part = backend.diagflat(betas_tensor, k=1)
+        projected_hamiltonian = (
+            diag_part + off_diag_part + backend.transpose(off_diag_part)
+        )
+    else:
+        projected_hamiltonian = diag_part
+
+    return basis_matrix, projected_hamiltonian
+
+
+def krylov_evol(
+    hamiltonian: Tensor,
+    initial_state: Tensor,
+    time_points: Tensor,
+    subspace_dimension: int,
+    callback: Optional[Callable[[Any], Any]] = None,
+) -> Any:
+    """
+    Perform quantum state time evolution using Krylov subspace method.
+
+    :param hamiltonian: Sparse or dense Hamiltonian matrix
+    :type hamiltonian: Tensor
+    :param initial_state: Initial quantum state
+    :type initial_state: Tensor
+    :param time_points: List of time points
+    :type time_points: Tensor
+    :param subspace_dimension: Krylov subspace dimension
+    :type subspace_dimension: int
+    :param callback: Optional callback function applied to quantum state at
+                  each evolution time point, return some observables
+    :type callback: Optional[Callable[[Any], Any]], optional
+    :return: List of evolved quantum states, or list of callback function results
+        (if callback provided)
+    :rtype: Any
+    """
+    # TODO(@refraction-ray): stable and efficient AD is to be investigated
+    basis_matrix, projected_hamiltonian = lanczos_iteration(
+        hamiltonian, initial_state, subspace_dimension
+    )
+    initial_state = backend.cast(initial_state, dtypestr)
+    # Project initial state to Krylov subspace: |psi_proj> = V_m^† |psi(0)>
+    projected_state = backend.matvec(
+        backend.conj(backend.transpose(basis_matrix)), initial_state
+    )
+
+    # Perform spectral decomposition of projected Hamiltonian: T_m = U D U^†
+    eigenvalues, eigenvectors = backend.eigh(projected_hamiltonian)
+    eigenvalues = backend.cast(eigenvalues, dtypestr)
+    time_points = backend.convert_to_tensor(time_points)
+    time_points = backend.cast(time_points, dtypestr)
+
+    # Transform projected state to eigenbasis: |psi_coeff> = U^† |psi_proj>
+    eigenvectors_projected_state = backend.matvec(
+        backend.conj(backend.transpose(eigenvectors)), projected_state
+    )
+
+    # Calculate exp(-i*projected_H*t) * projected_state
+    results = []
+    for t in time_points:
+        # Calculate exp(-i*eigenvalues*t)
+        exp_diagonal = backend.exp(-1j * eigenvalues * t)
+
+        # Evolve state in eigenbasis: |psi_evolved_coeff> = exp(-i*D*t) |psi_coeff>
+        evolved_projected_coeff = exp_diagonal * eigenvectors_projected_state
+
+        # Transform back to eigenbasis: |psi_evolved_proj> = U |psi_evolved_coeff>
+        evolved_projected = backend.matvec(eigenvectors, evolved_projected_coeff)
+
+        # Transform back to original basis: |psi(t)> = V_m |psi_evolved_proj>
+        evolved_state = backend.matvec(basis_matrix, evolved_projected)
+
+        # Apply callback function if provided
+        if callback is not None:
+            result = callback(evolved_state)
+        else:
+            result = evolved_state
+
+        results.append(result)
+
+    return backend.stack(results)
+
+
+def hamiltonian_evol(
+    tlist: Tensor,
+    h: Tensor,
+    psi0: Tensor,
+    callback: Optional[Callable[..., Any]] = None,
+) -> Tensor:
+    """
+    Fast implementation of time independent Hamiltonian evolution using eigendecomposition.
+    By default, performs imaginary time evolution.
+
+    :param tlist: Time points for evolution
+    :type tlist: Tensor
+    :param h: Time-independent Hamiltonian matrix
+    :type h: Tensor
+    :param psi0: Initial state vector
+    :type psi0: Tensor
+    :param callback: Optional function to process state at each time point
+    :type callback: Optional[Callable[..., Any]], optional
+    :return: Evolution results at each time point. If callback is None, returns state vectors;
+            otherwise returns callback results
+    :rtype: Tensor
+
+    :Example:
+
+    >>> import tensorcircuit as tc
+    >>> import numpy as np
+    >>> # Define a simple 2-qubit Hamiltonian
+    >>> h = tc.array_to_tensor([
+    ...     [1.0, 0.0, 0.0, 0.0],
+    ...     [0.0, -1.0, 2.0, 0.0],
+    ...     [0.0, 2.0, -1.0, 0.0],
+    ...     [0.0, 0.0, 0.0, 1.0]
+    ... ])
+    >>> # Initial state |00⟩
+    >>> psi0 = tc.array_to_tensor([1.0, 0.0, 0.0, 0.0])
+    >>> # Evolution times
+    >>> times = tc.array_to_tensor([0.0, 0.5, 1.0])
+    >>> # Evolve and get states
+    >>> states = tc.experimental.hamiltonian_evol(times, h, psi0)
+    >>> print(states.shape)  # (3, 4)
+
+
+    Note:
+        1. The Hamiltonian must be time-independent
+        2. For time-dependent Hamiltonians, use ``evol_local`` or ``evol_global`` instead
+        3. The evolution is performed in imaginary time by default (factor -t in exponential)
+        4. The state is automatically normalized at each time point
+    """
+    psi0 = backend.cast(psi0, dtypestr)
+    es, u = backend.eigh(h)
+    u = backend.cast(u, dtypestr)
+    utpsi0 = backend.reshape(
+        backend.transpose(u) @ backend.reshape(psi0, [-1, 1]), [-1]
+    )
+    es = backend.cast(es, dtypestr)
+    tlist = backend.cast(backend.convert_to_tensor(tlist), dtypestr)
+
+    @backend.jit
+    def _evol(t: Tensor) -> Tensor:
+        ebetah_utpsi0 = backend.exp(-t * es) * utpsi0
+        psi_exact = backend.conj(u) @ backend.reshape(ebetah_utpsi0, [-1, 1])
+        psi_exact = backend.reshape(psi_exact, [-1])
+        psi_exact = psi_exact / backend.norm(psi_exact)
+        if callback is None:
+            return psi_exact
+        return callback(psi_exact)
+
+    return backend.stack([_evol(t) for t in tlist])
+
+
+ed_evol = hamiltonian_evol
+
+
+def evol_local(
+    c: Circuit,
+    index: Sequence[int],
+    h_fun: Callable[..., Tensor],
+    t: float,
+    *args: Any,
+    **solver_kws: Any,
+) -> Circuit:
+    """
+    ode evolution of time dependent Hamiltonian on circuit of given indices
+    [only jax backend support for now]
+
+    :param c: _description_
+    :type c: Circuit
+    :param index: qubit sites to evolve
+    :type index: Sequence[int]
+    :param h_fun: h_fun should return a dense Hamiltonian matrix
+        with input arguments time and *args
+    :type h_fun: Callable[..., Tensor]
+    :param t: evolution time
+    :type t: float
+    :return: _description_
+    :rtype: Circuit
+    """
+    from jax.experimental.ode import odeint
+
+    s = c.state()
+    n = c._nqubits
+    l = len(index)
+
+    def f(y: Tensor, t: Tensor, *args: Any) -> Tensor:
+        y = backend.reshape2(y)
+        y = Gate(y)
+        h = -1.0j * h_fun(t, *args)
+        h = backend.reshape2(h)
+        h = Gate(h)
+        edges = []
+        for i in range(n):
+            if i not in index:
+                edges.append(y[i])
+            else:
+                j = index.index(i)
+                edges.append(h[j])
+                h[j + l] ^ y[i]
+        y = contractor([y, h], output_edge_order=edges)
+        return backend.reshape(y.tensor, [-1])
+
+    ts = backend.stack([0.0, t])
+    ts = backend.cast(ts, dtype=rdtypestr)
+    s1 = odeint(f, s, ts, *args, **solver_kws)
+    return type(c)(n, inputs=s1[-1])
+
+
+ode_evol_local = evol_local
+
+
+def evol_global(
+    c: Circuit, h_fun: Callable[..., Tensor], t: float, *args: Any, **solver_kws: Any
+) -> Circuit:
+    """
+    ode evolution of time dependent Hamiltonian on circuit of all qubits
+    [only jax backend support for now]
+
+    :param c: _description_
+    :type c: Circuit
+    :param h_fun: h_fun should return a **SPARSE** Hamiltonian matrix
+        with input arguments time and *args
+    :type h_fun: Callable[..., Tensor]
+    :param t: _description_
+    :type t: float
+    :return: _description_
+    :rtype: Circuit
+    """
+    from jax.experimental.ode import odeint
+
+    s = c.state()
+    n = c._nqubits
+
+    def f(y: Tensor, t: Tensor, *args: Any) -> Tensor:
+        h = -1.0j * h_fun(t, *args)
+        return backend.sparse_dense_matmul(h, y)
+
+    ts = backend.stack([0.0, t])
+    ts = backend.cast(ts, dtype=rdtypestr)
+    s1 = odeint(f, s, ts, *args, **solver_kws)
+    return type(c)(n, inputs=s1[-1])
+
+
+ode_evol_global = evol_global

{tensorcircuit_nightly-1.3.0.dev20250728.dist-info → tensorcircuit_nightly-1.3.0.dev20250729.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorcircuit-nightly
-Version: 1.3.0.dev20250728
+Version: 1.3.0.dev20250729
 Summary: nightly release for tensorcircuit
 Home-page: https://github.com/refraction-ray/tensorcircuit-dev
 Author: TensorCircuit Authors
@@ -70,7 +70,7 @@ TensorCircuit-NG is the actively maintained official version and a [fully compat
 
 Please begin with [Quick Start](/docs/source/quickstart.rst) in the [full documentation](https://tensorcircuit-ng.readthedocs.io/).
 
-For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to tensorcircuit-ng [deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) or [Context7 MCP](https://context7.com/tensorcircuit/tensorcircuit-ng).
+For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 80+ [example scripts](/examples) and 30+ [tutorial notebooks](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials). API docstrings and test cases in [tests](/tests) are also informative. One can also refer to AI-native docs for tensorcircuit-ng: [Devin Deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) and [Context7 MCP](https://context7.com/tensorcircuit/tensorcircuit-ng).
 
 For beginners, please refer to [quantum computing lectures with TC-NG](https://github.com/sxzgroup/qc_lecture) to learn both quantum computing basics and representative usage of TensorCircuit-NG.
 

{tensorcircuit_nightly-1.3.0.dev20250728.dist-info → tensorcircuit_nightly-1.3.0.dev20250729.dist-info}/RECORD

@@ -1,4 +1,4 @@
-tensorcircuit/__init__.py,sha256=Az3JXErbPVvXD9b5BomCaVlcVinaj5OO4bCCsiuQJyE,2032
+tensorcircuit/__init__.py,sha256=GNg45VO8J-m5ApDmmQbFvTPIzXvBpREXDg5MiVgCqqI,2055
 tensorcircuit/about.py,sha256=DazTswU2nAwOmASTaDII3L04PVtaQ7oiWPty5YMI3Wk,5267
 tensorcircuit/abstractcircuit.py,sha256=0osacPqq7B1EJki-cI1aLYoVRmjFaG9q3XevWMs7SsA,44125
 tensorcircuit/asciiart.py,sha256=neY1OWFwtoW5cHPNwkQHgRPktDniQvdlP9QKHkk52fM,8236
@@ -7,7 +7,7 @@ tensorcircuit/channels.py,sha256=CFQxWI-JmkIxexslCBdjp_RSxUbHs6eAJv4LvlXXXCY,286
 tensorcircuit/circuit.py,sha256=mE4b_9xRu3ydoB8iDffdx35V9GZLhAQD_tkjZDLnLjg,39105
 tensorcircuit/cons.py,sha256=uYKBeYKkDoJEqJTNrOZPRM31tBtkqe5aAg8GtVidJ1Y,33014
 tensorcircuit/densitymatrix.py,sha256=VqMBnWCxO5-OsOp6LOdc5RS2AzmB3U4-w40Vn_lqygo,14865
-tensorcircuit/experimental.py,sha256=RW97ncitCfO1QJLAUbKBvm2Tsc0hzKhqkC65ShA9-Q0,34456
+tensorcircuit/experimental.py,sha256=TGK4FaS6TS_ZhtjcIZgYVuAkGdRW50LN0DdXp-h4bos,29906
 tensorcircuit/fgs.py,sha256=pzaZuzPIFPpfr5Z-UsBQ_Yp0x7mbSM2sUc4dO2SUmVs,49543
 tensorcircuit/gates.py,sha256=x-wA7adVpP7o0AQLt_xYUScFKj8tU_wUOV2mR1GyrPc,29322
 tensorcircuit/keras.py,sha256=5OF4dfhEeS8sRYglpqYtQsWPeqp7uK0i7-P-6RRJ7zQ,10126
@@ -18,6 +18,7 @@ tensorcircuit/quantum.py,sha256=LNkIv5cJ2KG6puC18zTuXi-5cojW1Tnz-N-WjZ0Qu5Q,9021
 tensorcircuit/shadows.py,sha256=6XmWNubbuaxFNvZVWu-RXd0lN9Jkk-xwong_K8o8_KE,17014
 tensorcircuit/simplify.py,sha256=O11G3UYiVAc30GOfwXXmhLXwGZrQ8OVwLTMQMZp_XBc,9414
 tensorcircuit/stabilizercircuit.py,sha256=yNqcEKtYzRYrgqGil8QEyKN4OEMp9g6uOG2zuRaU8uc,15465
+tensorcircuit/timeevol.py,sha256=LWKOw4Y4CUtUO4a_72BVzYPH26PbubGYOaJlXkmA350,11439
 tensorcircuit/torchnn.py,sha256=z_QpM0QC3mydGyWpyp877j-tSFCPyzynCwqrTWaw-IA,4637
 tensorcircuit/translation.py,sha256=VnU7DnYmbk1cWjqa7N68WNLNDn3DwENrMzmbG4_CQco,28611
 tensorcircuit/utils.py,sha256=nEDR1wTh1WF_yV6UyZYlifqOPWdKk_Krr4HjhrWHnGQ,7228
@@ -39,7 +40,7 @@ tensorcircuit/applications/physics/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQe
 tensorcircuit/applications/physics/baseline.py,sha256=RWrzMGnC0PtmpYSFkvCE7r1llR88gncXuCakAAhFE-w,1775
 tensorcircuit/applications/physics/fss.py,sha256=ny3U9ZDmT459PXjA1oUGfarBOlSKSy6fs04vD9s1XH4,3633
 tensorcircuit/backends/__init__.py,sha256=WiUmbUFzM29w3hKfhuKxVUk3PpqDFiXf4za9g0ctpZA,80
-tensorcircuit/backends/abstract_backend.py,sha256=Ob8zp-AgovoY3uYFNEUA_WlJz9YtgnaJvugKUXWttAA,59018
+tensorcircuit/backends/abstract_backend.py,sha256=tzhOFZSOkZ_iraMvY7g84VbWBpYcELX1O0bhUipZ7YQ,59131
 tensorcircuit/backends/backend_factory.py,sha256=Z0aQ-RnxOnQzp-SRw8sefAH8XyBSlj2NXZwOlHinbfY,1713
 tensorcircuit/backends/cupy_backend.py,sha256=4vgO3lnQnsvWL5hukhskjJp37EAHqio6z6TVXTQcdjs,15077
 tensorcircuit/backends/jax_backend.py,sha256=dkDQ380CJHIdlt1fZvlN_g8DIowWPEcTTV_XBcs0YB0,26088
@@ -47,7 +48,7 @@ tensorcircuit/backends/jax_ops.py,sha256=o7tLlQMRnaKWcr5rVnOMqwG6KZVpR8M8ryNQ-ce
 tensorcircuit/backends/numpy_backend.py,sha256=sd1migp_E2FWjchvOeYRuyM47yexegT2_SW_ukSYSF8,14171
 tensorcircuit/backends/pytorch_backend.py,sha256=yhfZSrm99yNW-dmijk8t6zAkbVgLRd4b_aIWKrpT7bY,24230
 tensorcircuit/backends/pytorch_ops.py,sha256=lLxpK6OqfpVwifyFlgsqhpnt-oIn4R5paPMVg51WaW0,3826
-tensorcircuit/backends/tensorflow_backend.py,sha256=eTGVN6OyQgxvzj4C_CRvFIHv3v8tvZyb7Tt8B-kLbOo,36250
+tensorcircuit/backends/tensorflow_backend.py,sha256=N8iL2P76ZRp3USJSyFdZ2LWG8muXYe1kOuengv1ijXo,36444
 tensorcircuit/backends/tf_ops.py,sha256=FJwDU7LhZrt0VUIx12DJU0gZnWhMv7B7r9sAKG710As,3378
 tensorcircuit/cloud/__init__.py,sha256=n0Lx07GYF6YbdIa6AJCLJk4zlAm5CqaeHszvkxxuoI4,139
 tensorcircuit/cloud/abstraction.py,sha256=6aSxbz0MP21jBVdFbSMrvJPLQH117vGz9sSHbMFoodE,14582
@@ -85,7 +86,7 @@ tensorcircuit/templates/graphs.py,sha256=cPYrxjoem0xZ-Is9dZKAvEzWZL_FejfIRiCEOTA
 tensorcircuit/templates/hamiltonians.py,sha256=Ag8djD6lckTeU7I99gCbXiQAb2VYqzm_p7-hpXo-5u4,5554
 tensorcircuit/templates/lattice.py,sha256=F35ebANk0DSmSHLR0-Q_hUbcznyCmZjb4fKmvCMywmA,58575
 tensorcircuit/templates/measurements.py,sha256=pzc5Aa9S416Ilg4aOY77Z6ZhUlYcXnAkQNQFTuHjFFs,10943
-tensorcircuit_nightly-1.3.0.dev20250728.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+tensorcircuit_nightly-1.3.0.dev20250729.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/conftest.py,sha256=J9nHlLE3Zspz1rMyzadEuBWhaS5I4Q9sq0lnWybcdIA,1457
 tests/test_backends.py,sha256=rClxb2gyAoGeXd_ZYVSAJ0zEvJ7z_2btAeFM_Iy_wwY,33925
@@ -102,7 +103,7 @@ tests/test_hamiltonians.py,sha256=E0E5ABhUeG7XLMLRkb3AIAPi7aJgnIeMWTgqzF1Q6yc,57
 tests/test_interfaces.py,sha256=iJPmes8S8HkA9_PGjsu4Ike-vCXYyS1EMgnNKKXDNaU,16938
 tests/test_keras.py,sha256=U453jukavmx0RMeTSDEgPzrNdHNEfK1CW0CqO3XCNKo,4841
 tests/test_lattice.py,sha256=_ptDVK3EhS-X5fCQWiP8sHk3azdyGFuwqg6KMkBTkDE,65789
-tests/test_miscs.py,sha256=mm6kv5LqLkwHxWrGzLxajyOp1RaaKoHxq2OT1J3DpIM,9741
+tests/test_miscs.py,sha256=4fXKsW0kYu2JYO0iGlwWLAYlkFD1rfeVc4xG4Zjn5FQ,8935
 tests/test_mpscircuit.py,sha256=mDXX8oQeFeHr_PdZvwqyDs_tVcVAqLmCERqlTAU7590,10552
 tests/test_noisemodel.py,sha256=UYoMtCjwDaB-CCn5kLosofz-qTMiY4KGAFBjVtqqLPE,5637
 tests/test_qaoa.py,sha256=hEcC_XVmKBGt9XgUGtbTO8eQQK4mjorgTIrfqZCeQls,2616
@@ -114,9 +115,10 @@ tests/test_shadows.py,sha256=1T3kJesVJ5XfZrSncL80xdq-taGCSnTDF3eL15UlavY,5160
 tests/test_simplify.py,sha256=35tbOu1QANsPvY1buLwNhqPnMkBOsnBtHn82qaukmgI,1175
 tests/test_stabilizer.py,sha256=MivuZ5pY7GOcEPTanhtrflXostyLBToHyjfPqCU0tG0,5450
 tests/test_templates.py,sha256=Xm9otFFaaBWG9TZpgJ-nNh9MBfRipTzFWL8fBOnie2k,7192
+tests/test_timeevol.py,sha256=b5fsUzW3kfLZV909jnJpH9vCBz5fefONOUSrm2N6Nxg,7886
 tests/test_torchnn.py,sha256=CHLTfWkF7Ses5_XnGFN_uv_JddfgenFEFzaDtSH8XYU,2848
 tests/test_van.py,sha256=kAWz860ivlb5zAJuYpzuBe27qccT-Yf0jatf5uXtTo4,3163
-tensorcircuit_nightly-1.3.0.dev20250728.dist-info/METADATA,sha256=cdMd1YT-UPhCAWiy92CxfNIgQn553hT7bxRBlTME8mM,34895
-tensorcircuit_nightly-1.3.0.dev20250728.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-tensorcircuit_nightly-1.3.0.dev20250728.dist-info/top_level.txt,sha256=O_Iqeh2x02lasEYMI9iyPNNNtMzcpg5qvwMOkZQ7n4A,20
-tensorcircuit_nightly-1.3.0.dev20250728.dist-info/RECORD,,
+tensorcircuit_nightly-1.3.0.dev20250729.dist-info/METADATA,sha256=MijyspDQzOzMCKoGxFN50a89pOhICnhrpUeXdPASpQg,34922
+tensorcircuit_nightly-1.3.0.dev20250729.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tensorcircuit_nightly-1.3.0.dev20250729.dist-info/top_level.txt,sha256=O_Iqeh2x02lasEYMI9iyPNNNtMzcpg5qvwMOkZQ7n4A,20
+tensorcircuit_nightly-1.3.0.dev20250729.dist-info/RECORD,,

tests/test_miscs.py

@@ -226,36 +226,6 @@ def test_finite_difference_tf(tfb):
     np.testing.assert_allclose(g2, g4, atol=1e-5)
 
 
-def test_evol(jaxb):
-    def h_square(t, b):
-        return (tc.backend.sign(t - 1.0) + 1) / 2 * b * tc.gates.x().tensor
-
-    c = tc.Circuit(3)
-    c.x(0)
-    c.cx(0, 1)
-    c.h(2)
-    c = experimental.evol_local(
-        c, [1], h_square, 2.0, tc.backend.convert_to_tensor(0.2)
-    )
-    c.rx(1, theta=np.pi - 0.4)
-    np.testing.assert_allclose(c.expectation_ps(z=[1]), 1.0, atol=1e-5)
-
-    ixi = tc.quantum.PauliStringSum2COO([[0, 1, 0]])
-
-    def h_square_sparse(t, b):
-        return (tc.backend.sign(t - 1.0) + 1) / 2 * b * ixi
-
-    c = tc.Circuit(3)
-    c.x(0)
-    c.cx(0, 1)
-    c.h(2)
-    c = experimental.evol_global(
-        c, h_square_sparse, 2.0, tc.backend.convert_to_tensor(0.2)
-    )
-    c.rx(1, theta=np.pi - 0.4)
-    np.testing.assert_allclose(c.expectation_ps(z=[1]), 1.0, atol=1e-5)
-
-
 def test_energy_baseline():
     print(TFIM1Denergy(10))
     print(Heisenberg1Denergy(10))

tests/test_timeevol.py

@@ -0,0 +1,238 @@
+import sys
+import os
+import pytest
+import numpy as np
+from pytest_lazyfixture import lazy_fixture as lf
+
+thisfile = os.path.abspath(__file__)
+modulepath = os.path.dirname(os.path.dirname(thisfile))
+
+sys.path.insert(0, modulepath)
+import tensorcircuit as tc
+
+
+def test_ode_evol(jaxb):
+    def h_square(t, b):
+        return (tc.backend.sign(t - 1.0) + 1) / 2 * b * tc.gates.x().tensor
+
+    c = tc.Circuit(3)
+    c.x(0)
+    c.cx(0, 1)
+    c.h(2)
+    c = tc.timeevol.ode_evol_local(
+        c, [1], h_square, 2.0, tc.backend.convert_to_tensor(0.2)
+    )
+    c.rx(1, theta=np.pi - 0.4)
+    np.testing.assert_allclose(c.expectation_ps(z=[1]), 1.0, atol=1e-5)
+
+    ixi = tc.quantum.PauliStringSum2COO([[0, 1, 0]])
+
+    def h_square_sparse(t, b):
+        return (tc.backend.sign(t - 1.0) + 1) / 2 * b * ixi
+
+    c = tc.Circuit(3)
+    c.x(0)
+    c.cx(0, 1)
+    c.h(2)
+    c = tc.timeevol.ode_evol_global(
+        c, h_square_sparse, 2.0, tc.backend.convert_to_tensor(0.2)
+    )
+    c.rx(1, theta=np.pi - 0.4)
+    np.testing.assert_allclose(c.expectation_ps(z=[1]), 1.0, atol=1e-5)
+
+
+@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+def test_hamiltonian_evol_basic(backend):
+    """Test basic functionality of hamiltonian_evol with a simple 2-qubit Hamiltonian"""
+    # Define a simple 2-qubit Hamiltonian
+    h = tc.backend.convert_to_tensor(
+        [
+            [1.0, 0.0, 0.0, 0.0],
+            [0.0, -1.0, 2.0, 0.0],
+            [0.0, 2.0, -1.0, 0.0],
+            [0.0, 0.0, 0.0, 1.0],
+        ]
+    )
+
+    # Initial state |00⟩
+    psi0 = tc.backend.convert_to_tensor([1.0, 0.0, 0.0, 0.0])
+
+    # Evolution times
+    times = 1.0j * tc.backend.cast(
+        tc.backend.convert_to_tensor([0.0, 0.5, 1.0]), tc.dtypestr
+    )
+
+    # Evolve and get states
+    states = tc.timeevol.hamiltonian_evol(times, h, psi0)
+
+    # Check output shape
+    assert states.shape == (3, 4)
+
+    # At t=0, state should be the initial state (normalized)
+    np.testing.assert_allclose(states[0], psi0, atol=1e-5)
+
+    # All states should be normalized
+    for state in states:
+        norm = tc.backend.norm(state)
+        np.testing.assert_allclose(norm, 1.0, atol=1e-5)
+
+
+@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+def test_hamiltonian_evol_with_callback(backend):
+    """Test hamiltonian_evol with a callback function"""
+    # Define a simple Hamiltonian
+    h = tc.backend.convert_to_tensor([[1.0, 0.0], [0.0, -1.0]])
+
+    # Initial state
+    psi0 = tc.backend.convert_to_tensor([1.0, 1.0]) / np.sqrt(2)
+
+    # Evolution times
+    times = 1.0j * tc.backend.cast(
+        tc.backend.convert_to_tensor([0.0, 1.0, 2.0]), tc.dtypestr
+    )
+
+    # Define callback to compute expectation value of Pauli Z
+    def callback(state):
+        # Z operator
+        c = tc.Circuit(1, inputs=state)
+        # Compute <psi|Z|psi>
+        return tc.backend.real(c.expectation_ps(z=[0]))
+
+    # Evolve with callback
+    results = tc.timeevol.hamiltonian_evol(times, h, psi0, callback)
+
+    # Check output shape - should be scalar for each time point
+    assert results.shape == (3,)
+
+    # At t=0, for |+⟩ state, <Z> should be 0
+    np.testing.assert_allclose(results[0], 0.0, atol=1e-5)
+
+
+@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+def test_hamiltonian_evol_imaginary_time(backend):
+    """Test that hamiltonian_evol performs imaginary time evolution by default"""
+    # Define a Hamiltonian
+    h = tc.backend.convert_to_tensor([[2.0, 0.0], [0.0, 1.0]])
+
+    # Initial state with equal superposition
+    psi0 = tc.backend.convert_to_tensor([1.0, 1.0]) / np.sqrt(2)
+
+    # Large time to see ground state dominance
+    times = tc.backend.convert_to_tensor([0.0, 10.0])
+
+    # Evolve
+    states = tc.timeevol.hamiltonian_evol(times, h, psi0)
+
+    # Ground state is |1⟩ (eigenvalue 1.0), so after long imaginary time
+    # evolution, we should approach this state
+    expected_ground_state = tc.backend.convert_to_tensor([0.0, 1.0])
+    np.testing.assert_allclose(states[-1], expected_ground_state, atol=1e-3)
+
+
+@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+def test_krylov_evol_heisenberg_6_sites(backend):
+    """Test krylov_evol with Heisenberg Hamiltonian on 6 sites"""
+    n = 6
+    # Create a 1D chain graph
+    g = tc.templates.graphs.Line1D(n, pbc=False)
+
+    # Generate Heisenberg Hamiltonian
+    h = tc.quantum.heisenberg_hamiltonian(g, hzz=1.0, hxx=1.0, hyy=1.0, sparse=False)
+    print(h.dtype)
+    # Initial state - all spins up except last one down
+    psi0 = np.zeros((2**n,))
+    psi0[62] = 1.0
+    # State with pattern: up, up, up, up, up, down (111110 in binary = 62 in decimal)
+
+    # Normalize initial state
+    psi0 = psi0 / tc.backend.norm(psi0)
+
+    # Evolution times
+    times = tc.backend.convert_to_tensor([0.0, 0.5, 1.0])
+
+    # Perform Krylov evolution
+    states = tc.timeevol.krylov_evol(h, psi0, times, subspace_dimension=10)
+
+    # Check output shape
+    assert states.shape == (3, 2**n)
+
+    # At t=0, state should be the initial state
+    np.testing.assert_allclose(states[0], psi0, atol=1e-5)
+
+    # All states should be normalized
+    for state in states:
+        norm = tc.backend.norm(state)
+        np.testing.assert_allclose(norm, 1.0, atol=1e-5)
+
+
+@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+def test_krylov_evol_heisenberg_8_sites(backend):
+    """Test krylov_evol with Heisenberg Hamiltonian on 8 sites with callback"""
+    n = 8
+    # Create a 1D chain graph
+    g = tc.templates.graphs.Line1D(n, pbc=False)
+
+    # Generate Heisenberg Hamiltonian
+    h = tc.quantum.heisenberg_hamiltonian(g, hzz=1.0, hxx=1.0, hyy=1.0, sparse=True)
+
+    # Initial Neel state (alternating up and down spins)
+    c = tc.Circuit(n)
+    c.x([i for i in range(n // 2)])
+    psi0 = c.state()
+
+    # Evolution times
+    times = tc.backend.convert_to_tensor([0.0, 0.2, 0.4])
+
+    # Define callback to compute total magnetization
+    def total_magnetization(state):
+        # Calculate sum of <Z_i> for all sites
+        c = tc.Circuit(n, inputs=state)
+        total_z = 0.0
+        for i in range(n):
+            total_z += c.expectation_ps(z=[i])
+        return tc.backend.real(total_z)
+
+    # Perform Krylov evolution with callback
+    results = tc.timeevol.krylov_evol(
+        h, psi0, times, subspace_dimension=12, callback=total_magnetization
+    )
+
+    # Check output shape - should be scalar for each time point
+    assert results.shape == (3,)
+
+    # At t=0, for Neel state, total magnetization should be 0
+    np.testing.assert_allclose(results[0], 0.0, atol=1e-5)
+
+
+@pytest.mark.parametrize("backend", [lf("npb"), lf("tfb"), lf("jaxb")])
+def test_krylov_evol_subspace_accuracy(backend):
+    """Test accuracy of krylov_evol with different subspace dimensions"""
+    n = 6
+    # Create a 1D chain graph
+    g = tc.templates.graphs.Line1D(n, pbc=False)
+
+    # Generate Heisenberg Hamiltonian
+    h = tc.quantum.heisenberg_hamiltonian(g, hzz=1.0, hxx=1.0, hyy=1.0, sparse=True)
+
+    # Initial domain wall state
+    c = tc.Circuit(n)
+    c.x([i + n // 2 for i in range(n // 2)])
+    psi0 = c.state()
+
+    # Evolution time
+    times = tc.backend.convert_to_tensor([1.0])
+
+    # Compare different subspace dimensions
+    state_small = tc.timeevol.krylov_evol(h, psi0, times, subspace_dimension=6)
+    state_large = tc.timeevol.krylov_evol(h, psi0, times, subspace_dimension=16)
+
+    # Both should be normalized
+    norm_small = tc.backend.norm(state_small[0])
+    norm_large = tc.backend.norm(state_large[0])
+    np.testing.assert_allclose(norm_small, 1.0, atol=1e-5)
+    np.testing.assert_allclose(norm_large, 1.0, atol=1e-5)
+
+    # Larger subspace should be more accurate (but we can't easily test that without exact solution)
+    # At least verify they have the correct shape
+    assert state_small.shape == (1, 2**n)
+    assert state_large.shape == (1, 2**n)