Merge branch 'master' into beta

Author: refraction-ray

.pylintrc

@@ -13,7 +13,7 @@ disable=all
 enable=c-extension-no-member,
        bad-indentation,
        bare-except,
-       broad-except,
+       ; broad-except,
        dangerous-default-value,
        function-redefined,
        len-as-condition,

CHANGELOG.md

@@ -8,6 +8,12 @@
 
 - Add `circuit.to_openqasm_file` function for compatibility of qiskit>1
 
+- Add `tc.cite()` to get citation information
+
+### Fixed
+
+- Fix customized jax eigh operator by noting the return is a namedtuple
+
 ## 1.0.2
 
 ### Added

docs/source/advance.rst

@@ -19,7 +19,7 @@ The larger bond dimension we set, the better approximation ratio (of course the
 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.
+Stacked-gate is a simple syntactic sugar rendering circuit construction easily when multiple gate of the same type are applied on different qubits, namely, the index for gate call can accept list of ints instead of one integer.
 
 .. code-block:: python
 
@@ -98,12 +98,14 @@ 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.
+
+We support two modes of analog simulation, where :py:meth:`tensorcircuit.experimental.evol_global` evolve the state via a Hamiltonian define on the whole system, and :py:meth:`tensorcircuit.experimental.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.
+    ``evol_global`` uses sparse Hamiltonian while ``evol_local`` uses dense Hamiltonian.
 
 
 .. code-block:: python
@@ -155,9 +157,9 @@ We wrap the tf-backend `SavedModel` as very easy-to-use function :py:meth:`tenso
 
 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>`_.
 
-**Updates**: jax now also support jitted function save/load via ``export`` module, see `jax documentation <https://jax.readthedocs.io/en/latest/export/export.html>_`.
+**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
+We wrap the jax function export capability in ``experimental`` module and can be used as follows
 
 .. code-block:: python
 

docs/source/index.rst

@@ -7,10 +7,11 @@ TensorCircuit Next Generation
 
 **Welcome and congratulations! You have found TensorCircuit: the Next Generation.** 👏 
 
+
 Introduction
 ---------------
 
-TensorCircuit-NG is an open-source high-performance quantum computing software framework in Python.
+TensorCircuit-NG is an open-source high-performance quantum software framework in Python.
 
 * It is built for humans. 👽
 
@@ -22,16 +23,21 @@ TensorCircuit-NG is an open-source high-performance quantum computing software f
 
 * It is implemented with industry-standard machine learning frameworks: TensorFlow, JAX, and PyTorch. 🤖
 
+* It is flexible and powerful to build and simulate tensor networks, neural networks and quantum circuits together. 🧠
+
 * It is compatible with machine learning engineering paradigms: automatic differentiation, just-in-time compilation, vectorized parallelism and GPU acceleration. 🛠
 
-With the help of TensorCircuit-NG, now get ready to efficiently and elegantly solve interesting and challenging quantum computing problems: from academic research prototype to industry application deployment.
+With the help of TensorCircuit-NG, now get ready to efficiently and elegantly solve interesting and challenging quantum computing and quantum many-body problems: from academic research prototype to industry application deployment.
 
+.. important::
+   Please cite the `whitepaper <https://quantum-journal.org/papers/q-2023-02-02-912/>`_ when using TensorCircuit or TensorCircuit-NG in your research. The bibtex information is provided by ``tc.cite()``.
 
 
 
-Relevant Links
+Useful Links
 --------------------
 
+
 TensorCircuit is created and now maintained as TensorCircuit-NG by `Shi-Xin Zhang <https://github.com/refraction-ray>`_.
 
 The current core authors of TensorCircuit-NG are `Shi-Xin Zhang <https://github.com/refraction-ray>`_ and `Yu-Qin Chen <https://github.com/yutuer21>`_.
@@ -153,19 +159,19 @@ TensorCircuit-NG is unifying infrastructures and interfaces for quantum computin
       :columns: 12 6 3 3
       :shadow: md
 
-      ideal/noisy/approximate simulation
+      ideal/noisy/approximate/analog simulation
 
    .. grid-item-card:: Unified Representations
       :columns: 12 6 3 3
       :shadow: md
 
       from/to_IR/qiskit/openqasm/json
 
-   .. grid-item-card:: Unified Pipelines
+   .. grid-item-card:: Unified Objects
       :columns: 12 6 3 3
       :shadow: md
 
-      stateless functional programming/stateful ML models
+      neural-net/tensor-net/quantum-circuit
 
 
 

docs/source/quickstart.rst

@@ -15,7 +15,7 @@ Either pip from conda or other python env managers is fine.
 Since there are many optional packages for various features, 
 the users may need to install more pip packages when required. 
 
-- For Linux with Nvidia GPU,
+For Nvidia GPU,
 please refer to the GPU aware installation guide of corresponding machine learning frameworks: 
 `TensorFlow <https://www.tensorflow.org/install/gpu>`_, 
 `Jax <https://github.com/google/jax#pip-installation-gpu-cuda>`_, 
@@ -27,7 +27,6 @@ Docker is also recommended (especially Linux + Nvidia GPU setup):
 
 For more details on docker setup, please refer to `docker readme <https://github.com/tensorcircuit/tensorcircuit-ng/tree/master/docker>`_.
 
-- 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>`_.
 
 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.
@@ -239,6 +238,7 @@ To learn more about the jit mechanism, one can refer to documentation or blogs o
 
 Inputs, parameters, measurements, circuit structures, and Monte Carlo noise can all be evaluated in parallel.
 To learn more about vmap mechanism, one can refer to documentation or blogs on ``tf.vectorized_map`` or ``jax.vmap``.
+One can also refer to `tutorial <https://tensorcircuit-ng.readthedocs.io/en/latest/whitepaper/6-3-vmap.html>`_ for more details on the vmap usage in TensorCircuit-NG.
 
 
 Backend Agnosticism

tensorcircuit/__init__.py

@@ -6,7 +6,7 @@
 
 gpu_memory_share()
 
-from .about import about
+from .about import about, cite
 from .cons import (
     backend,
     set_backend,

tensorcircuit/about.py

@@ -23,20 +23,26 @@ def about() -> None:
         print(f"Scipy version: {scipy.__version__}")
     except ModuleNotFoundError:
         print(f"Scipy is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Scipy: {e}")
 
     try:
         import pandas
 
         print(f"Pandas version: {pandas.__version__}")
     except ModuleNotFoundError:
         print(f"Pandas is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Pandas: {e}")
 
     try:
         import tensornetwork as tn
 
         print(f"TensorNetwork version: {tn.__version__}")
     except ModuleNotFoundError:
         print(f"TensorNetwork is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for TensorNetwork: {e}")
 
     try:
         import cotengra
@@ -47,6 +53,8 @@ def about() -> None:
             print(f"Cotengra: installed")
     except ModuleNotFoundError:
         print(f"Cotengra is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Cotengra: {e}")
 
     try:
         import tensorflow as tf
@@ -56,6 +64,8 @@ def about() -> None:
         print(f"TensorFlow CUDA infos: {dict(tf.sysconfig.get_build_info())}")
     except ModuleNotFoundError:
         print(f"TensorFlow is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for TensorFlow: {e}")
 
     try:
         import jax
@@ -68,13 +78,17 @@ def about() -> None:
             print(f"Jax installation doesn't support GPU")
     except ModuleNotFoundError:
         print(f"Jax is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Jax: {e}")
 
     try:
         import jaxlib
 
         print(f"JaxLib version: {jaxlib.__version__}")
     except ModuleNotFoundError:
         print(f"JaxLib is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Jaxlib: {e}")
 
     try:
         import torch
@@ -88,32 +102,64 @@ def about() -> None:
             print(f"Pytorch cuda version: {torch.version.cuda}")
     except ModuleNotFoundError:
         print(f"PyTorch is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Torch: {e}")
 
     try:
         import cupy
 
         print(f"Cupy version: {cupy.__version__}")
     except ModuleNotFoundError:
         print(f"Cupy is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Cupy: {e}")
 
     try:
         import qiskit
 
         print(f"Qiskit version: {qiskit.__version__}")
     except ModuleNotFoundError:
         print(f"Qiskit is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Qiskit: {e}")
 
     try:
         import cirq
 
         print(f"Cirq version: {cirq.__version__}")
     except ModuleNotFoundError:
         print(f"Cirq is not installed")
+    except Exception as e:
+        print(f"Misconfiguration for Cirq: {e}")
 
     from tensorcircuit import __version__
 
     print(f"TensorCircuit version {__version__}")
 
 
+def cite(format: str = "bib") -> str:
+    """
+    Returns the citation information for tensorcircuit.
+    Please cite our work if you use the package in your research.
+
+    :param format: format for bib, defaults to "bib"
+    :type format: str, optional
+    :return: the citation information
+    :rtype: str
+    """
+    if format == "bib":
+        return """@article{Zhang_TensorCircuit_2023,
+        author = {Zhang, Shi-Xin and Allcock, Jonathan and Wan, Zhou-Quan and Liu, Shuo and Sun, Jiace and Yu, Hao and Yang, Xing-Han and Qiu, Jiezhong and Ye, Zhaofeng and Chen, Yu-Qin and Lee, Chee-Kong and Zheng, Yi-Cong and Jian, Shao-Kai and Yao, Hong and Hsieh, Chang-Yu and Zhang, Shengyu},
+        doi = {10.22331/q-2023-02-02-912},
+        journal = {Quantum},
+        month = feb,
+        title = {{TensorCircuit: a Quantum Software Framework for the NISQ Era}},
+        volume = {7},
+        year = {2023}}"""
+    elif format == "aps":
+        return """S.-X. Zhang, J. Allcock, Z.-Q. Wan, S. Liu, J. Sun, H. Yu, X.-H. Yang, J. Qiu, Z. Ye, Y.-Q. Chen, C.-K. Lee, Y.-C. Zheng, S.-K. Jian, H. Yao, C.-Y. Hsieh, and S. Zhang, TensorCircuit: a Quantum Software Framework for the NISQ Era, Quantum 7, 912 (2023)."""  # pylint: disable=line-too-long
+    raise ValueError(f"Unsupported format: {format}")
+
+
 if __name__ == "__main__":
     about()

tensorcircuit/backends/jax_ops.py

@@ -151,7 +151,8 @@ def _QrGradSquareAndDeepMatrices(q: Array, r: Array, dq: Array, dr: Array) -> Ar
 
 @jax.custom_vjp
 def adaware_eigh(A: Array) -> Array:
-    return jnp.linalg.eigh(A)
+    e, v = jnp.linalg.eigh(A)
+    return e, v
 
 
 def jaxeigh_fwd(A: Array) -> Array:

tensorcircuit/experimental.py

@@ -534,7 +534,7 @@ def jax_jitted_function_save(filename: str, f: Callable[..., Any], *args: Any) -
     :param args: example function arguments for ``f``
     """
 
-    from jax import export
+    from jax import export  # type: ignore
 
     f_export = export.export(f)(*args)  # type: ignore
     barray = f_export.serialize()
@@ -555,14 +555,14 @@ def jax_jitted_function_load(filename: str) -> Callable[..., Any]:
     :return: the loaded function
     :rtype: _type_
     """
-    from jax import export
+    from jax import export  # type: ignore
 
     with open(filename, "rb") as f:
         barray = f.read()
 
     f_load = export.deserialize(barray)  # type: ignore
 
-    return f_load.call
+    return f_load.call  # type: ignore
 
 
 jax_func_load = jax_jitted_function_load

tests/test_miscs.py

@@ -36,6 +36,11 @@ def test_about():
     print(tc.about())
 
 
+def test_cite():
+    print(tc.cite())
+    print(tc.cite("aps"))
+
+
 def test_ps2coo(tfb):
     for l, a in check_pairs:
         r1 = PauliString2COO(tf.constant(l, dtype=tf.int64))