tensorcircuit-nightly 1.3.0.dev20250728__tar.gz → 1.3.0.dev20250730__tar.gz

{tensorcircuit_nightly-1.3.0.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+### Added
+
+- Add new module `tc.timeevol` for different types of time evolution solvers.
+
+### Fixed
+
+- Fixed `one_hot` in numpy backend.
+
+- Fixed `scan` in tensorflow backend and numpy backend.
+
+### Changed
+
+- The order of arguments of `tc.timeevol.ed_evol` are changed for consistent interface with other evolution methods.
+
 ## v1.3.0
 
 ### Added

{tensorcircuit_nightly-1.3.0.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorcircuit-nightly
-Version: 1.3.0.dev20250728
+Version: 1.3.0.dev20250730
 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 → tensorcircuit_nightly-1.3.0.dev20250730}/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.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/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.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/docs/source/advance.rst

@@ -149,6 +149,297 @@ We support two modes of analog simulation, where :py:meth:`tensorcircuit.experim
     v, gs = hybrid_evol(b)
 
 
+Time Evolution
+------------------
+
+TensorCircuit-NG provides several methods for simulating quantum time evolution, including exact diagonalization, Krylov subspace methods, and ODE-based approaches. 
+These methods are essential for studying quantum dynamics, particularly in many-body systems, and all support automatic differentiation (AD) and JIT compilation for enhanced performance.
+
+**Exact Diagonalization:**
+
+For small systems where full diagonalization is feasible, the :py:meth:`tensorcircuit.timeevol.ed_evol` method provides exact time evolution by directly computing matrix exponentials
+(alias :py:meth:`tensorcircuit.timeevol.hamiltonian_evol`):
+
+.. code-block:: python
+
+    import tensorcircuit as tc
+    
+    n = 4
+    g = tc.templates.graphs.Line1D(n, pbc=False)
+    h = tc.quantum.heisenberg_hamiltonian(g, hzz=1.0, hxx=1.0, hyy=1.0, sparse=False)
+    
+    # Initial Neel state: |↑↓↑↓⟩
+    c = tc.Circuit(n)
+    c.x([1, 3])  # Apply X gates to qubits 1 and 3
+    psi0 = c.state()
+    
+    # Imaginary time evolution times
+    times = tc.backend.convert_to_tensor([0.0, 0.5, 1.0, 2.0])
+    
+    # Evolve and get states
+    states = tc.timeevol.ed_evol(h, psi0, times)
+    print(states)
+    
+
+    def evolve_and_measure(params):
+        # Parametrized Hamiltonian
+        h_param = tc.quantum.heisenberg_hamiltonian(
+            g, hzz=params[0], hxx=params[1], hyy=params[2], sparse=False
+        )
+        states = tc.timeevol.ed_evol(h_param, psi0, times)
+        # Measure observable on final state
+        circuit = tc.Circuit(n, inputs=states[-1])
+        return tc.backend.real(circuit.expectation_ps(z=[0]))
+
+    evolve_and_measure(tc.backend.ones([3]))
+
+This method is particularly efficient for time-independent Hamiltonians as it uses eigendecomposition to compute the evolution. 
+It provides exact results but is limited to small systems (typically <16 qubits) due to the exponential growth of the Hilbert space.
+
+.. note::
+
+    For real time evolution, the time should be chosen as ``times = 1.j * tc.backend.convert_to_tensor([0.0, 0.5, 1.0, 2.0])``
+
+
+**Krylov Subspace Methods:**
+
+For larger systems where exact diagonalization becomes intractable, the Krylov subspace method provides an efficient approximation. 
+The :py:meth:`tensorcircuit.timeevol.krylov_evol` function implements this approach:
+
+.. code-block:: python
+
+    import tensorcircuit as tc
+    
+    # Create a Heisenberg Hamiltonian for a 1D chain
+    n = 10
+    g = tc.templates.graphs.Line1D(n, pbc=False)
+    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(range(n//2, n))
+    psi0 = c.state()
+    
+    # Real time evolution points
+    times = tc.backend.convert_to_tensor([0.0, 0.5, 1.0, 2.0])
+    
+    # Perform Krylov evolution with a 30-dimensional subspace
+    states = tc.timeevol.krylov_evol(h, psi0, times, subspace_dimension=30)
+    
+    # Krylov method also supports AD and JIT
+
+    def krylov_evolution(params):
+        # Parametrized initial state
+        c = tc.Circuit(n)
+        for i in range(n):
+            c.rx(i, theta=params[i])
+        psi0_param = c.state()
+        states = tc.timeevol.krylov_evol(h, psi0_param, [1.0], subspace_dimension=20)
+        # Measure total magnetization
+        circuit = tc.Circuit(n, inputs=states[0])
+        mz = sum(circuit.expectation_ps(z=[i]) for i in range(n))
+        return tc.backend.real(mz)
+
+The Krylov method constructs a small subspace that captures the essential dynamics, making it possible to simulate larger systems efficiently. 
+It supports both standard and scan-based jit-friendly implementations:
+
+.. code-block:: python
+
+    # Standard implementation (default)
+    states = tc.timeevol.krylov_evol(h, psi0, times, subspace_dimension=20, scan_impl=False)
+    
+    # Scan-based implementation for better JIT performance
+    states = tc.timeevol.krylov_evol(h, psi0, times, subspace_dimension=20, scan_impl=True)
+
+**ODE-Based Evolution:**
+
+For time-dependent Hamiltonians or when fine control over the evolution process is needed, TensorCircuit provides ODE-based evolution methods. 
+These methods solve the time-dependent Schrödinger equation directly by integrating the equation :math:`i\frac{d}{dt}|\psi(t)\rangle = H(t)|\psi(t)\rangle`.
+
+TensorCircuit provides two ODE-based evolution methods depending on whether the Hamiltonian acts on the entire system or just a local subsystem:
+
+1. **Global Evolution** (:py:meth:`tensorcircuit.timeevol.ode_evol_global`): For time-dependent Hamiltonians acting on the entire system. The Hamiltonian should be provided in sparse matrix format for efficiency.
+
+.. code-block:: python
+
+    import tensorcircuit as tc
+    from jax import jit, value_and_grad
+    
+    # Set JAX backend for ODE support
+    K = tc.set_backend("jax")
+    
+     # H(t) = -∑ᵢ Jᵢ(t) ZᵢZᵢ₊₁ - ∑ᵢ hᵢ(t) Xᵢ
+
+    # Time-dependent coefficients
+    def time_dep_J(t):
+        return 1.0 + 0.5 * tc.backend.sin(2.0 * t)
+
+    def time_dep_h(t):
+        return 0.5 * tc.backend.cos(1.5 * t)
+
+    zz_ham = tc.quantum.PauliStringSum2COO(
+        [[3, 3, 0, 0], [0, 3, 3, 0], [0, 0, 3, 3]], [1, 1, 1]
+    )
+    x_ham = tc.quantum.PauliStringSum2COO(
+        [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]], [1, 1, 1, 1]
+    )
+
+    # Hamiltonian construction function
+    def hamiltonian_func(t):
+        # Create time-dependent ZZ terms
+        zz_coeff = time_dep_J(t)
+
+        # Create time-dependent X terms
+        x_coeff = time_dep_h(t)
+
+        return zz_coeff * zz_ham + x_coeff * x_ham
+
+    # Initial state: |↑↓↑↓⟩
+    c = tc.Circuit(4)
+    c.x([1, 3])
+    psi0 = c.state()
+
+    # Time points for evolution
+    times = tc.backend.arange(0, 5, 0.5)
+
+    # Perform global ODE evolution
+    states = tc.timeevol.ode_evol_global(hamiltonian_func, psi0, times)
+    assert tc.backend.shape_tuple(states) == (10, 16)
+
+    zz_ham = tc.quantum.PauliStringSum2COO([[3, 3, 0, 0], [0, 3, 3, 0]], [1, 1])
+    x_ham = tc.quantum.PauliStringSum2COO([[1, 0, 0, 0], [0, 1, 0, 0]], [1, 1])
+
+    # Example with parameterized Hamiltonian and optimization
+    def parametrized_hamiltonian(t, params):
+        # params = [J0, J1, h0, h1] - parameters to optimize
+        J_t = params[0] + params[1] * tc.backend.sin(2.0 * t)
+        h_t = params[2] + params[3] * tc.backend.cos(1.5 * t)
+
+        return J_t * zz_ham + h_t * x_ham
+
+    # Observable function: measure ZZ correlation
+    def zz_correlation(state):
+        n = int(np.log2(state.shape[0]))
+        circuit = tc.Circuit(n, inputs=state)
+        return circuit.expectation_ps(z=[0, 1])
+
+    @tc.backend.jit
+    @tc.backend.value_and_grad
+    def objective_function(params):
+        states = tc.timeevol.ode_evol_global(
+            parametrized_hamiltonian,
+            psi0,
+            tc.backend.convert_to_tensor([0, 1.0]),
+            None,
+            params,
+        )
+        # Measure ZZ correlation at final time
+        final_state = states[-1]
+        return tc.backend.real(zz_correlation(final_state))
+
+    print(objective_function(tc.backend.ones([4])))
+    
+
+
+2. **Local Evolution** (:py:meth:`tensorcircuit.timeevol.ode_evol_local`): For time-dependent Hamiltonians acting on a subsystem of qubits. The Hamiltonian should be provided in dense matrix format.
+
+.. code-block:: python
+
+    import tensorcircuit as tc
+    import jax.numpy as jnp
+    from jax import jit
+    
+    # Set JAX backend for ODE support
+    tc.set_backend("jax")
+    K = tc.backend
+    
+    # Time-dependent local Hamiltonian on qubits 1 and 2
+    # H(t) = Ω(t) * (cos(φ(t)) * X + sin(φ(t)) * Y)
+    def local_hamiltonian(t, Omega, phi):
+        # Rabi oscillation Hamiltonian
+        angle = phi * t
+        coeff = Omega * jnp.cos(2.0 * t)  # Amplitude modulation
+        
+        # Single-qubit Rabi Hamiltonian (2x2 matrix)
+        hx = coeff * jnp.cos(angle) * tc.gates.x().tensor
+        hy = coeff * jnp.sin(angle) * tc.gates.y().tensor
+        return hx + hy
+    
+    # Initial state: GHZ state |0000⟩ + |1111⟩
+    c = tc.Circuit(4)
+    c.h(0)
+    for i in range(3):
+        c.cnot(i, i+1)
+    psi0 = c.state()
+    
+    times = tc.backend.arange(0.0, 3.0, 0.1)
+    
+    # Evolve with local Hamiltonian acting on qubit 1
+    states = tc.timeevol.ode_evol_local(
+        local_hamiltonian,
+        psi0,
+        times,
+        [1],  # Apply to qubit 1
+        None,
+        1.0, 
+        2.0 # Omega=1.0, phi=2.0
+    )
+    
+
+Both ODE-based methods support automatic differentiation and JIT compilation when using the JAX backend, making them suitable for optimization tasks in quantum control and variational quantum algorithms. 
+The methods integrate the time-dependent Schrödinger equation using JAX's ODE solvers, providing flexible and efficient simulation of quantum dynamics with time-dependent Hamiltonians.
+
+.. note::
+
+    1. ODE-based methods currently only support the JAX backend due to the dependency on JAX's ODE solvers.
+    2. Global evolution requires sparse Hamiltonian matrices for efficiency with large systems.
+    3. Local evolution requires dense Hamiltonian matrices and is suitable for subsystems with few qubits.
+    4. Both methods support callback functions to compute observables during evolution without storing all state vectors.
+
+**Comparison of Time Evolution Methods:**
+
++--------------------------+----------------+------------------+------------------+------------------+
+| Method                   | System Size    | Accuracy         | AD Support       | JIT Support      |
++==========================+================+==================+==================+==================+
+| ED Evolution             | < 16 qubits    | Exact            | ✅               | ✅               |
++--------------------------+----------------+------------------+------------------+------------------+
+| Krylov Evolution         | 16-30+ qubits  | Approximate      | ✅               | ✅ (JAX only)    |
++--------------------------+----------------+------------------+------------------+------------------+
+| ODE Local Evolution      | Any size       | Solver-dependent | ✅ (JAX only)    | ✅ (JAX only)    |
++--------------------------+----------------+------------------+------------------+------------------+
+| ODE Global Evolution     | ~ 20 qubits    | Solver-dependent | ✅ (JAX only)    | ✅ (JAX only)    |
++--------------------------+----------------+------------------+------------------+------------------+
+
+**Method Selection Guidelines:**
+
+1. **Exact diagonalization Evolution**: Best for small systems where exact results are required. Most efficient for time-independent Hamiltonians. Support imaginary time evolution.
+
+2. **Krylov Evolution**: Ideal for large systems with time-independent Hamiltonians. Provides a good balance between accuracy and computational efficiency. The subspace dimension controls the trade-off between accuracy and speed.
+
+3. **ODE Local Evolution**: Suitable for time-dependent Hamiltonians acting on a few qubits. Most flexible for complex control protocols or digital-analog hybrid programs.
+
+4. **ODE Global Evolution**: Best for time-dependent Hamiltonians acting on the entire system. 
+
+**Advanced Usage:**
+
+Callback functions can be used to compute observables during evolution without storing all state vectors:
+
+.. code-block:: python
+
+    def compute_total_magnetization(state):
+        # Compute total magnetization ⟨∑Zᵢ⟩
+        n = int(tc.backend.log2(tc.backend.shape_tuple(state)[0]))
+        circuit = tc.Circuit(n, inputs=state)
+        total_mz = sum(circuit.expectation_ps(z=[i]) for i in range(n))
+        return tc.backend.real(total_mz)
+    
+    # Evolve with callback
+    magnetizations = tc.timeevol.krylov_evol(
+        h, psi0, times, subspace_dimension=20, callback=compute_total_magnetization
+    )
+
+All time evolution methods in TensorCircuit support automatic differentiation and JIT compilation, making them suitable for variational optimization and other machine learning applications in quantum physics.
+
 
 Jitted Function Save/Load
 -----------------------------

{tensorcircuit_nightly-1.3.0.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/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.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/tensorcircuit/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.3.0.dev20250728"
+__version__ = "1.3.0.dev20250730"
 __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.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/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``.
@@ -1386,9 +1389,21 @@ class ExtendedBackend:
         :rtype: Tensor
         """
         carry = init
-        for x in xs:
-            carry = f(carry, x)
+        # Check if `xs` is a PyTree (tuple or list) of arrays.
+        if isinstance(xs, (tuple, list)):
+            for x_slice_tuple in zip(*xs):
+                # x_slice_tuple will be (k_elems[i], j_elems[i]) at each step.
+                carry = f(carry, x_slice_tuple)
+        else:
+            # If xs is a single array, iterate normally.
+            for x in xs:
+                carry = f(carry, x)
+
         return carry
+        # carry = init
+        # for x in xs:
+        #     carry = f(carry, x)
+        # return carry
 
     def stop_gradient(self: Any, a: Tensor) -> Tensor:
         """

{tensorcircuit_nightly-1.3.0.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/tensorcircuit/backends/numpy_backend.py

@@ -200,6 +200,7 @@ class NumpyBackend(numpy_backend.NumPyBackend, ExtendedBackend):  # type: ignore
         return softmax(a, axis=axis)
 
     def onehot(self, a: Tensor, num: int) -> Tensor:
+        a = np.asarray(a)
         res = np.eye(num)[a.reshape([-1])]
         return res.reshape(list(a.shape) + [num])
         # https://stackoverflow.com/questions/38592324/one-hot-encoding-using-numpy

{tensorcircuit_nightly-1.3.0.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/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)
@@ -712,7 +719,10 @@ class TensorFlowBackend(tensorflow_backend.TensorFlowBackend, ExtendedBackend):
     def scan(
         self, f: Callable[[Tensor, Tensor], Tensor], xs: Tensor, init: Tensor
     ) -> Tensor:
-        return tf.scan(f, xs, init)[-1]
+        stacked_results = tf.scan(f, xs, init)
+        final_state = tf.nest.map_structure(lambda x: x[-1], stacked_results)
+        return final_state
+        # return tf.scan(f, xs, init)[-1]
 
     def device(self, a: Tensor) -> str:
         dev = a.device

{tensorcircuit_nightly-1.3.0.dev20250728 → tensorcircuit_nightly-1.3.0.dev20250730}/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