Merge branch 'master' into beta

Author: refraction-ray

CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+### Added
+
+- Add jax jitted function load/save utilities in experimental module
+
+- Add `circuit.to_openqasm_file` function for compatibility of qiskit>1
+
+## 1.0.2
+
+### Added
+
+- Add `jittable` option in `c.sample()` method, friendly to switch off for large scale sample
+
+### Changed
+
+- Downgrading some logger warning to info
+
+### Fixed
+
+- Fix quafu provider
+
+- Raise ValueError for `FGSSimulator` when traced out sites correspond the full system
+
 ## 1.0.1
 
 ### Fixed

README.md

@@ -25,21 +25,23 @@
 
 <p align="center"> English | <a href="README_cn.md"> 简体中文 </a></p>
 
-TensorCircuit-NG is a high performance quantum software framework, supporting for automatic differentiation, just-in-time compiling, hardware acceleration, and vectorized parallelism, providing unified infrastructures and interfaces for quantum programming.
+TensorCircuit-NG is an open-source high-performance quantum software framework, supporting for automatic differentiation, just-in-time compiling, hardware acceleration, and vectorized parallelism, providing unified infrastructures and interfaces for quantum programming. It can compose quantum circuits, neural networks and tensor networks seamlessly with high simulation efficiency and flexibility.
 
-TensorCircuit-NG is built on top of modern machine learning frameworks: Jax, TensorFlow, and PyTorch. It is specifically suitable for highly efficient simulations of quantum-classical hybrid paradigm and variational quantum algorithms in ideal, noisy and approximate cases. It also supports quantum hardware access and provides CPU/GPU/QPU hybrid deployment solutions.
+TensorCircuit-NG is built on top of modern machine learning frameworks: Jax, TensorFlow, and PyTorch. It is specifically suitable for large-scale simulations of quantum-classical hybrid paradigm and variational quantum algorithms in ideal, noisy, approximate and analog cases. It also supports quantum hardware access and provides CPU/GPU/QPU hybrid deployment solutions.
 
-TensorCircuit-NG is [fully compatible](https://tensorcircuit-ng.readthedocs.io/en/latest/faq.html#what-is-the-relation-between-tensorcircuit-and-tensorcircuit-ng) with TensorCircuit with more new features and bug fixes (support numpy>2 and qiskit>1).
+TensorCircuit-NG is [fully compatible](https://tensorcircuit-ng.readthedocs.io/en/latest/faq.html#what-is-the-relation-between-tensorcircuit-and-tensorcircuit-ng) with TensorCircuit with more new features and bug fixes (support latest `numpy>2` and `qiskit>1`).
 
 ## Getting Started
 
 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 70+ [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.
 
+For beginners, please refer to [quantum computing lectures with TC-NG](https://github.com/sxzgroup/qc_lecture) to learn both quantum computing basis and representative usage of TensorCircuit-NG.
+
 The following are some minimal demos.
 
-- Circuit manipulation:
+- Circuit construction:
 
 ```python
 import tensorcircuit as tc
@@ -60,7 +62,7 @@ tc.set_dtype("complex128")
 tc.set_contractor("greedy")
 ```
 
-- Automatic differentiations with jit:
+- Automatic differentiation with jit:
 
 ```python
 def forward(theta):
@@ -348,7 +350,7 @@ Reference paper: https://arxiv.org/abs/2303.08154 (published in PRR as a Letter)
 
 ### TenCirChem
 
-[TenCirChem](https://github.com/tencent-quantum-lab/TenCirChem) is an efficient and versatile quantum computation package for molecular properties. TenCirChem is based on TensorCircuit and is optimized for chemistry applications.
+[TenCirChem](https://github.com/tencent-quantum-lab/TenCirChem) is an efficient and versatile quantum computation package for molecular properties. TenCirChem is based on TensorCircuit and is optimized for chemistry applications. The latest version TenCirChem-NG is open source and available at [TenCirChem-NG](https://github.com/tensorcircuit/TenCirChem-NG).
 
 Reference paper: https://arxiv.org/abs/2303.10825 (published in JCTC).
 
@@ -364,6 +366,12 @@ For the setup and simulation code of neural network encoded variational quantum
 
 Reference paper: https://arxiv.org/abs/2308.01068 (published in PRApplied).
 
+### Effective temperature in approximate ansatzes
+
+For the simulation implementation of quantum states based on neural networks, tensor networs and quantum circuits using TensorCircuit-NG, see the [project repo](https://github.com/sxzgroup/et).
+
+Reference paper: https://arxiv.org/abs/2411.18921.
+
 ### More works
 
 <details>
@@ -426,3 +434,11 @@ Reference paper: https://arxiv.org/abs/2308.01068 (published in PRApplied).
 </details>
 
 If you want to highlight your research work or projects here, feel free to add by opening PR.
+
+## Users
+
+Our users, developers, and partners:
+
+<p align="center">
+    <img width=90% src="docs/source/statics/user_logo.png">
+</p>

README_cn.md

@@ -33,6 +33,8 @@ TensorCircuit-NG 现在支持真实量子硬件连接和实验，并提供优雅
 
 有关软件用法，算法实现和工程范式演示的更多信息和介绍，请参阅 70+ [示例脚本](/examples) 和 30+ [案例教程](https://tensorcircuit-ng.readthedocs.io/en/latest/#tutorials)。 [测试](/tests) 用例和 API docstring 也提供了丰富的使用信息。
 
+初学者也可以参考[量子计算教程](https://github.com/sxzgroup/qc_lecture)学习量子计算基础和 TensorCircuit-NG 的典型用法.
+
 以下是一些最简易的演示。
 
 - 电路操作:
@@ -186,3 +188,17 @@ VQEX 在 MBL 相位识别上的应用见 [教程](/docs/source/tutorials/vqex_mb
 关于神经网络编码的变分量子算法的实现和工作流, 见 [教程](/docs/source/tutorials/nnvqe.ipynb)。
 
 参考论文: https://arxiv.org/abs/2308.01068。
+
+### 变分多体态的等效温度
+
+关于基于神经网络、张量网络和量子线路的变分量子态的模拟优化和分析，见 [项目](https://github.com/sxzgroup/et).
+
+参考论文: https://arxiv.org/abs/2411.18921.
+
+## 用户
+
+我们的用户，开发者和合作伙伴：
+
+<p align="center">
+    <img width=90% src="docs/source/statics/user_logo.png">
+</p>

docs/source/advance.rst

@@ -5,17 +5,65 @@ Advanced Usage
 MPS Simulator
 ----------------
 
-(Still experimental support)
-
-Very simple, we provide the same set of API for ``MPSCircuit`` as ``Circuit``, 
+Very straightforward to use, we provide the same set of API for ``MPSCircuit`` as ``Circuit``, 
 the only new line is to set the bond dimension for the new simulator.
 
 .. code-block:: python
 
     c = tc.MPSCircuit(n)
     c.set_split_rules({"max_singular_values": 50})
 
-The larger bond dimension we set, the better approximation ratio (of course the more computational cost we pay)
+The larger bond dimension we set, the better approximation ratio (of course the more computational cost we pay).
+
+
+Stacked gates
+----------------
+
+Stacked gates is a simple grammar sugar to make constructing the circuit easily when multiple gate of the same type are applied on the different qubits, namely, the index for gate function can accept list of ints instead of one integer.
+
+.. code-block:: python
+
+    >>> import tensorcircuit as tc
+    >>> c = tc.Circuit(4)
+    >>> c.h(range(3))
+    >>> c.draw()
+         ┌───┐
+    q_0: ┤ H ├
+         ├───┤
+    q_1: ┤ H ├
+         ├───┤
+    q_2: ┤ H ├
+         └───┘
+    q_3: ─────
+
+
+    >>> c = tc.Circuit(4)
+    >>> c.cnot([0, 1], [2, 3])
+    >>> c.draw()
+
+    q_0: ──■───────
+           │
+    q_1: ──┼────■──
+         ┌─┴─┐  │
+    q_2: ┤ X ├──┼──
+         └───┘┌─┴─┐
+    q_3: ─────┤ X ├
+              └───┘
+
+    >>> c = tc.Circuit(4)
+    >>> c.rx(range(4), theta=tc.backend.convert_to_tensor([0.1, 0.2, 0.3, 0.4]))
+    >>> c.draw()
+         ┌─────────┐
+    q_0: ┤ Rx(0.1) ├
+         ├─────────┤
+    q_1: ┤ Rx(0.2) ├
+         ├─────────┤
+    q_2: ┤ Rx(0.3) ├
+         ├─────────┤
+    q_3: ┤ Rx(0.4) ├
+         └─────────┘
+
+
 
 Split Two-qubit Gates
 -------------------------
@@ -45,15 +93,92 @@ The two-qubit gates applied on the circuit can be decomposed via SVD, which may
 
 Note ``max_singular_values`` must be specified to make the whole procedure static and thus jittable.
 
+Analog circuit simulation
+-----------------------------
+
+TensorCircuit-NG support digital-analog hybrid simulation (say cases in Rydberg atom arrays), where the analog part is simulated by the neural differential equation solver given the API to specify a time dependent Hamiltonian.
+The simulation is still differentiable and jittable. Only jax backend is supported for analog simulation as the neural ode engine is built on top of jax. 
+This utility is super helpful for optimizing quantum control or investigating digital-analog hybrid variational quantum schemes.
+We support two modes of analog simulation, where :py:meth:`tensorcircuit.experimentaql.evol_global` evolve the state via a Hamiltonian define on the whole system, and :py:meth:`tensorcircuit.experimentaql.evol_local` evolve the state via a Hamiltonian define on a local subsystem.
+
+.. Note::
+
+    ``evol_global`` use sparse Hamiltonian while ``evol_local`` use dense Hamiltonian.
+
+
+.. code-block:: python
+
+    # in this demo, we build a jittable and differentiable simulation function `hybrid_evol` 
+    # with both digital gates and local/global analog Hamiltonian evolutions
+
+    import optax
+    import tensorcircuit as tc
+    from tensorcircuit.experimental import evol_global, evol_local
+
+    K = tc.set_backend("jax")
+
+
+    def h_fun(t, b):
+        return b * tc.gates.x().tensor
+
+
+    hy = tc.quantum.PauliStringSum2COO([[2, 0]])
+
+
+    def h_fun2(t, b):
+        return b[2] * K.cos(b[0] * t + b[1]) * hy
+
+
+    @K.jit
+    @K.value_and_grad
+    def hybrid_evol(params):
+        c = tc.Circuit(2)
+        c.x([0, 1])
+        c = evol_local(c, [1], h_fun, 1.0, params[0])
+        c.cx(1, 0)
+        c.h(0)
+        c = evol_global(c, h_fun2, 1.0, params[1:])
+        return K.real(c.expectation_ps(z=[0, 1]))
+
+
+    b = K.implicit_randn([4])
+    v, gs = hybrid_evol(b)
+
+
 
 Jitted Function Save/Load
 -----------------------------
 
 To reuse the jitted function, we can save it on the disk via support from the TensorFlow `SavedModel <https://www.tensorflow.org/guide/saved_model>`_. That is to say, only jitted quantum function on the TensorFlow backend can be saved on the disk. 
 
+We wrap the tf-backend `SavedModel` as very easy-to-use function :py:meth:`tensorcircuit.keras.save_func` and :py:meth:`tensorcircuit.keras.load_func`.
+
 For the JAX-backend quantum function, one can first transform them into the tf-backend function via JAX experimental support: `jax2tf <https://github.com/google/jax/tree/main/jax/experimental/jax2tf>`_.
 
-We wrap the tf-backend `SavedModel` as very easy-to-use function :py:meth:`tensorcircuit.keras.save_func` and :py:meth:`tensorcircuit.keras.load_func`.
+**Updates**: jax now also support jitted function save/load via ``export`` module, see `jax documentation <https://jax.readthedocs.io/en/latest/export/export.html>_`.
+
+We wrape the jax function export capability in ``experimental`` module and can be used as follows
+
+.. code-block:: python
+
+    from tensorcircuit import experimental
+
+    K = tc.set_backend("jax")
+
+    @K.jit
+    def f(weights):
+        c = tc.Circuit(3)
+        c.rx(range(3), theta=weights)
+        return K.real(c.expectation_ps(z=[0]))
+
+    print(f(K.ones([3])))
+
+    experimental.jax_jitted_function_save("temp.bin", f, K.ones([3]))
+
+    f_load = tc.experimental.jax_jitted_function_load("temp.bin")
+    f_load(K.ones([3]))
+
+
 
 Parameterized Measurements
 -----------------------------

docs/source/quickstart.rst

@@ -29,10 +29,8 @@ For more details on docker setup, please refer to `docker readme <https://github
 
 - For Windows, due to the lack of support for Jax, we recommend to use docker or WSL, please refer to `TC via windows docker <contribs/development_windows.html>`_ or `TC via WSL <contribs/development_wsl2.html>`_.
 
-- For MacOS, please refer to `TC on Mac <contribs/development_Mac.html>`_.
-
-Overall, the installation of TensorCircuit is simple, since it is purely in Python and hence very portable. 
-As long as the users can take care of the installation of ML frameworks on the corresponding system, TensorCircuit will work as expected.
+Overall, the installation of TensorCircuit-NG is simple, since it is purely in Python and hence very portable. 
+As long as the users can take care of the installation of ML frameworks on the corresponding system, TensorCircuit-NG will work as expected.
 
 To debug the installation issue or report bugs, please check the environment information by ``tc.about()``.
 

docs/source/statics/user_logo.png

@@ -1,4 +1,4 @@
-__version__ = "1.0.1"
+__version__ = "1.0.2"
 __author__ = "TensorCircuit Authors"
 __creator__ = "refraction-ray"
 

tensorcircuit/__init__.py

@@ -792,6 +792,16 @@ def to_openqasm(self, **kws: Any) -> str:
             qasm_str = dumps(qc)  # type: ignore
         return qasm_str  # type: ignore
 
+    def to_openqasm_file(self, file: str, **kws: Any) -> None:
+        """
+        save the circuit to openqasm file
+
+        :param file: the file path to save the circuit
+        :type file: str
+        """
+        with open(file, "w") as f:
+            f.write(self.to_openqasm(**kws))
+
     @classmethod
     def from_openqasm(
         cls,

tensorcircuit/abstractcircuit.py

@@ -392,7 +392,7 @@ def jit(
         jit_compile: Optional[bool] = None,
         **kws: Any
     ) -> Callable[..., Any]:
-        logger.warning("numpy backend has no jit interface, just do nothing")
+        logger.info("numpy backend has no jit interface, just do nothing")
         return f
         # raise NotImplementedError("numpy backend doesn't support jit compiling")
 

tensorcircuit/backends/numpy_backend.py

@@ -528,6 +528,7 @@ def sample(
         format: Optional[str] = None,
         random_generator: Optional[Any] = None,
         status: Optional[Tensor] = None,
+        jittable: bool = True,
     ) -> Any:
         """
         batched sampling from state or circuit tensor network directly
@@ -541,12 +542,29 @@ def sample(
         :type readout_error: Optional[Sequence[Any]]. Tensor, List, Tuple
         :param format: sample format, defaults to None as backward compatibility
             check the doc in :py:meth:`tensorcircuit.quantum.measurement_results`
+            Six formats of measurement counts results:
+
+                "sample_int": # np.array([0, 0])
+
+                "sample_bin": # [np.array([1, 0]), np.array([1, 0])]
+
+                "count_vector": # np.array([2, 0, 0, 0])
+
+                "count_tuple": # (np.array([0]), np.array([2]))
+
+                "count_dict_bin": # {"00": 2, "01": 0, "10": 0, "11": 0}
+
+                "count_dict_int": # {0: 2, 1: 0, 2: 0, 3: 0}
+
         :type format: Optional[str]
         :param random_generator: random generator,  defaults to None
         :type random_generator: Optional[Any], optional
         :param status: external randomness given by tensor uniformly from [0, 1],
             if set, can overwrite random_generator
         :type status: Optional[Tensor]
+        :param jittable: when converting to count, whether keep the full size. if false, may be conflict
+            external jit, if true, may fail for large scale system with actual limited count results
+        :type jittable: bool, defaults true
         :return: List (if batch) of tuple (binary configuration tensor and corresponding probability)
             if the format is None, and consistent with format when given
         :rtype: Any
@@ -612,7 +630,9 @@ def perfect_sampling(key: Any) -> Any:
                 if batch is None:
                     r = r[0]  # type: ignore
                 return r
-        return sample2all(sample=ch, n=self._nqubits, format=format, jittable=True)
+        if self._nqubits > 35:
+            jittable = False
+        return sample2all(sample=ch, n=self._nqubits, format=format, jittable=jittable)
 
     def sample_expectation_ps(
         self,