tensorcircuit-nightly 1.3.0.dev20250727__tar.gz → 1.3.0.dev20250729__tar.gz

{tensorcircuit_nightly-1.3.0.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Added
+
+- Add new module `tc.timeevol` for different types of time evolution solvers.
+
 ## v1.3.0
 
 ### Added

{tensorcircuit_nightly-1.3.0.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorcircuit-nightly
-Version: 1.3.0.dev20250727
+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.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/README.md

@@ -35,7 +35,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.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/README_cn.md

@@ -21,11 +21,13 @@
 
 <p align="center"> <a href="README.md">English</a> |  简体中文 </p>
 
-TensorCircuit-NG 是下一代量子软件框架，完美支持自动微分、即时编译、硬件加速和向量并行化。
+TensorCircuit-NG 是下一代量子软件框架，完美支持自动微分、即时编译、硬件加速、向量并行化和分布式训练。
 
-TensorCircuit-NG 建立在现代机器学习框架 Jax, TensorFlow, PyTorch 之上，支持机器学习后端无关的统一界面。 其特别适用于理想情况、含噪声情况、稳定子情况及可控近似情况下，大规模量子经典混合范式和变分量子算法的高效模拟。
+TensorCircuit-NG 建立在现代机器学习框架 Jax, TensorFlow, PyTorch 之上，支持机器学习后端无关的统一界面。 其特别适用于理想情况、含噪声情况、稳定子情况、可控近似情况、连续动力学情况及费米子情况下，大规模量子经典混合范式和变分量子算法的高效模拟。其可以高效地编织和模拟量子线路、张量网络和神经网络组成的混合计算图。
 
-TensorCircuit-NG 现在支持真实量子硬件连接和实验，并提供优雅的 CPU/GPU/QPU 混合部署训练方案（v0.9+）。
+TensorCircuit-NG 现在支持真实量子硬件连接和实验，并提供优雅的 CPU/GPU/QPU 硬件混合部署训练方案。
+
+TensorCircuit-NG 是目前积极维护的唯一官方版本，是 TensorCircuit 的[完全兼容](https://github.com/orgs/tensorcircuit/discussions/19)的升级版本，它包含了更多新功能（例如稳定子线路、多卡分布式模拟等）和错误修复（例如支持最新的 numpy>2 和 qiskit>1）。
 
 ## 入门
 
@@ -33,6 +35,8 @@ TensorCircuit-NG 现在支持真实量子硬件连接和实验，并提供优雅
 
 有关软件用法，算法实现和工程范式演示的更多信息和介绍，请参阅 80+ [示例脚本](/examples) 和 30+ [案例教程](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials)。 [测试](/tests) 用例和 API docstring 也提供了丰富的使用信息。
 
+TensorCircuit-NG 也支持 AI 原生编程资源：[Devin Deepwiki](https://deepwiki.com/tensorcircuit/tensorcircuit-ng) 和 [Context7 MCP](https://context7.com/tensorcircuit/tensorcircuit-ng).
+
 初学者也可以参考[量子计算教程](https://github.com/sxzgroup/qc_lecture)学习量子计算基础和 TensorCircuit-NG 的典型用法.
 
 以下是一些最简易的演示。

{tensorcircuit_nightly-1.3.0.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/docs/source/modules.rst

@@ -26,6 +26,7 @@ tensorcircuit
     ./api/simplify.rst
     ./api/stabilizercircuit.rst
     ./api/templates.rst
+    ./api/timeevol.rst
     ./api/torchnn.rst
     ./api/translation.rst
     ./api/utils.rst

{tensorcircuit_nightly-1.3.0.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/tensorcircuit/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.3.0.dev20250727"
+__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_nightly-1.3.0.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/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_nightly-1.3.0.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/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_nightly-1.3.0.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/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_nightly-1.3.0.dev20250729/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.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/tensorcircuit_nightly.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorcircuit-nightly
-Version: 1.3.0.dev20250727
+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.dev20250727 → tensorcircuit_nightly-1.3.0.dev20250729}/tensorcircuit_nightly.egg-info/SOURCES.txt

@@ -41,6 +41,7 @@ tensorcircuit/quantum.py
 tensorcircuit/shadows.py
 tensorcircuit/simplify.py
 tensorcircuit/stabilizercircuit.py
+tensorcircuit/timeevol.py
 tensorcircuit/torchnn.py
 tensorcircuit/translation.py
 tensorcircuit/utils.py
@@ -141,5 +142,6 @@ tests/test_shadows.py
 tests/test_simplify.py
 tests/test_stabilizer.py
 tests/test_templates.py
+tests/test_timeevol.py
 tests/test_torchnn.py
 tests/test_van.py