tensorcircuit/tensorcircuit-ng

English | 简体中文

TensorCircuit-NG is the next-generation open-source high-performance quantum software framework and an AI-native quantum research runtime for turning research questions into executable, optimized, and validated quantum experiments.

TensorCircuit-NG is built upon tensornetwork engines, supporting for automatic differentiation, just-in-time compiling, hardware acceleration, vectorized parallelism and distributed training, 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 large-scale simulations of quantum-classical hybrid paradigm and variational quantum algorithms in ideal (Circuit), noisy (DMCircuit), Clifford (StabilizerCircuit), qudit (QuditCircuit), approximate (MPSCircuit), analog (AnalogCircuit), symmetric (U1Circuit) and fermionic (FGSCircuit) cases. It also supports quantum hardware access and provides CPU/GPU/QPU hybrid deployment solutions.

TensorCircuit-NG is the technical successor to TensorCircuit, led and maintained by the original TensorCircuit development team. This distribution has served as the primary home for the framework’s evolution, addressing critical maintenance gaps (numpy > 2.0, qiskit > 1.0) and feature enhancements. As a fully compatible drop-in replacement, TensorCircuit-NG delivers next-gen capabilities—including stabilizer/qudit/analog/symmetric circuit simulation and multi-node multi-GPU distributed simulation.

New companion project: We recently launched TenCirPauli, a Python-first, Rust-native companion that brings Pauli-native propagation and fixed-particle-number U(1) circuit execution to TensorCircuit-NG.

Getting Started

Please begin with Quick Start in the full documentation.

For more information on software usage, sota algorithm implementation and engineer paradigm demonstration, please refer to 200+ example scripts and 40+ tutorial notebooks. API docstrings and test cases in tests are also informative. One can also refer to AI-native docs for tensorcircuit-ng: Devin Deepwiki, Google Code Wiki, and Context7 MCP.

For beginners, please refer to quantum computing lectures with TC-NG to learn both quantum computing basics and representative usage of TensorCircuit-NG.

Agentic Quantum Research (Recommended)

TensorCircuit-NG is designed to give AI agents the context, rules, skills, and execution backends required for serious quantum research—not only code generation. To write TC-NG scripts and applications efficiently with AI coding agents (e.g., Claude Code, Cursor, CodeX), we strongly recommend working directly within the local tensorcircuit-ng repository rather than an empty folder.

In the ORBIT-Q benchmark, TensorCircuit-NG leads the evaluated quantum software frameworks on agent solve success and artifact runtime.

1. Rich Context: The 100+ scripts in examples/ and extensive test cases in tests/ provide essential references that significantly reduce AI hallucinations.
2. Built-in Rules: We provide a dedicated AGENTS.md file. It serves as the “handbook” (i.e. CLAUDE.md) for AI agents, defining coding standards and best practices to ensure the generated code is idiomatic.
3. Specialized Agentic Skills: The .agents/skills/ directory contains workflows to guide AI assistants on complex, multi-step tasks.

Recommended Workflow:

1. Clone the repository: git clone https://github.com/tensorcircuit/tensorcircuit-ng.git
2. Switch to a local playground branch: git checkout -b my-playground in case messing up with the original repository.
3. Open the repository folder in your AI IDE. And you are ready to start writing TC-NG-based scripts.

Now, enjoy exploring quantum research through natural language. By combining extreme performance with an autonomous, intent-driven AI workflow (via embedded .agents/skills/), TC-NG helps researchers move from a research question to implementation, exploration, optimization, validation, and a reusable scientific artifact.

Quick Demos

The following are some minimal demos.

• Circuit construction:

import tensorcircuit as tc
c = tc.Circuit(2)
c.H(0)
c.CNOT(0,1)
c.rx(1, theta=0.2)
print(c.wavefunction())
print(c.expectation_ps(z=[0, 1]))
print(c.sample(allow_state=True, batch=1024, format="count_dict_bin"))

• Runtime behavior customization:

tc.set_backend("jax")
tc.set_dtype("complex128")
tc.set_contractor("cotengra")

• Automatic differentiation with jit:

def forward(theta):
    c = tc.Circuit(2)
    c.R(0, theta=theta, alpha=0.5, phi=0.8)
    return tc.backend.real(c.expectation((tc.gates.z(), [0])))

g = tc.backend.grad(forward)
g = tc.backend.jit(g)
theta = tc.array_to_tensor(1.0)
print(g(theta))

Install

The package is written in pure Python and can be obtained via pip as:

pip install tensorcircuit-ng

We recommend you install this package with tensorflow or jax also installed as:

pip install "tensorcircuit-ng[jax]"

Other optional dependencies include [torch], [tensorflow], [qiskit] and [cloud].

Try nightly build for the newest features:

pip install tensorcircuit-nightly

Advantages

• Tensor network simulation engine based

• JIT, AD, vectorized parallelism compatible

• GPU support, QPU access support, hybrid deployment support

• HPC native, distributed simulation enabled, multiple devices/hosts support

• Efficiency

  • Time: 10 to 10^6+ times acceleration compared to TensorFlow Quantum, Pennylane, CuQuantum, TorchQuantum or Qiskit

  • Space: 1000+ qubits 1D VQE workflow (converged energy inaccuracy: < 0.5%)

• Elegance

  • Flexibility: customized contraction, multiple ML backend/interface choices, multiple dtype precisions, multiple QPU providers

  • API design: quantum for humans, less code, more power

• Batteries included

Contributing

Status

This project is created and maintained by Shi-Xin Zhang with current core authors Shi-Xin Zhang and Yu-Qin Chen (see the brief history of TensorCircuit and TensorCircuit-NG). We also thank contributions from the open source community.

Citation

If this project helps in your research, please cite the two versions of software whitepapers to acknowledge the work put into the development of TensorCircuit-NG.

• TensorCircuit: a Quantum Software Framework for the NISQ Era (published in Quantum).

• TensorCircuit-NG: A Universal, Composable, and Scalable Platform for Quantum Computing and Quantum Simulation.

These two works also serve as a good introduction to the software.

Research works citing TensorCircuit-NG can be highlighted in Research and Applications section.

Guidelines

For contribution guidelines and notes, see CONTRIBUTING.

We welcome issues, PRs, and discussions from everyone, and these are all hosted on GitHub.

License

TensorCircuit-NG is open source, released under the Apache License, Version 2.0.

Contributors

Executable Research Hub

The Executable Research Hub is the literature-to-artifact layer of TensorCircuit-NG’s agentic research stack. Each paper is packaged as a runnable, metadata-rich, and inspectable research artifact with its implementation, target figure, backend, scaling strategy, and validation context.

Browse the Hub or read the source in examples/reproduce_papers. For the broader agentic research workflow, see the Agentic Quantum Research guide.

Adding one is the most approachable way to make a first contribution: pick a paper, follow the conventions in examples/reproduce_papers, and open a pull request.

Research and Applications

TensorCircuit-NG is a powerful framework for driving research and applications in quantum computing. Below are examples of published academic works (150+ in total) and open-source projects that utilize TensorCircuit and TensorCircuit-NG.

DQAS

For the application of Differentiable Quantum Architecture Search, see applications.

Reference paper: https://arxiv.org/abs/2010.08561 (published in QST).

VQNHE

For the application of Variational Quantum-Neural Hybrid Eigensolver, see applications.

Reference paper: https://arxiv.org/abs/2106.05105 (published in PRL) and https://arxiv.org/abs/2112.10380 (published in AQT).

VQEX-MBL

For the application of VQEX on MBL phase identification, see the tutorial.

Reference paper: https://arxiv.org/abs/2111.13719 (published in PRB).

Stark-DTC

For the numerical demosntration of discrete time crystal enabled by Stark many-body localization, see the Floquet simulation demo.

Reference paper: https://arxiv.org/abs/2208.02866 (published in PRL).

RA-Training

For the numerical simulation of variational quantum algorithm training using random gate activation strategy by us, see the project repo.

Reference paper: https://arxiv.org/abs/2303.08154 (published in PRR as a Letter).

TenCirChem

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.

Reference paper: https://arxiv.org/abs/2303.10825 (published in JCTC).

TenCirPauli

For Rust-native Pauli propagation, fixed-particle-number U(1) circuit execution, Pauli algebra, structured Hamiltonians, measurement planning, symmetry reduction, restricted sectors, and a backend matrix-vector product interface for TensorCircuit-NG, see TenCirPauli. The project also provides structured operator algebra for fermionic, bosonic, qudit, Majorana, and hybrid systems, together with fermion-to-qubit mappings and chemistry interoperability.

EMQAOA-DARBO

For the numerical simulation and hardware experiments with error mitigation on QAOA, see the project repo.

Reference paper: https://arxiv.org/abs/2303.14877 (published in Communications Physics).

NN-VQA

For the setup and simulation code of neural network encoded variational quantum eigensolver, see the demo.

Reference paper: https://arxiv.org/abs/2308.01068 (published in PRApplied).

FLDC

Absence of barren plateaus in finite local-depth circuits with long-range entanglement, see the demo.

Reference paper: https://arxiv.org/abs/2311.01393 (published in PRL).

Effective temperature in ansatzes

For the simulation implementation of quantum states based on neural networks, tensor networs and quantum circuits using TensorCircuit-NG, see the project repo.

Reference paper: https://arxiv.org/abs/2411.18921 (published in PRR).

A Unified Variational Framework for Quantum Excited States

For the simulation code and data for variational optimization of simutaneous excited states, see the project repo.

Reference paper: https://arxiv.org/abs/2504.21459.

Quantum Machine Unlearning

For the simulation code for the work “superior resilience to poisoning and amenability to unlearning in quantum machine learning”, see the project repo.

Reference paper: https://arxiv.org/abs/2508.02422 (published in Nature Communications).

Low Weight Pauli Propagation Simulation

For the simulation code and data for the work on low weight Pauli propagation in the context of variational quantum algorithms, see the project repo.

Reference paper: https://arxiv.org/abs/2508.06358 (published in PRR).

Quantum Continual Learning

For the code implementation on the work of demonstrating plasticity in quantum continual learning, see the project repo.

Reference paper: https://arxiv.org/abs/2511.17228 (published in PRX Quantum).

Quantum Subliminal Learning

For the code implementation on the work of quantum subliminal learning, see the project repo.

Reference paper: https://arxiv.org/abs/2605.29557.

ORBIT-Q

The ORBIT-Q benchmark evaluates autonomous agents on scientific quantum programming across framework capability, agent configuration, correctness, and artifact efficiency. In its reported framework-axis comparison, TensorCircuit-NG leads the evaluated frameworks with the highest agent solve success rate and the lowest artifact-runtime slowdown. See the benchmark repository and accompanying paper.

Reference paper: https://arxiv.org/abs/2607.03105.

More works

If you want to highlight your research work or projects here, feel free to add by opening PR.

Users

Our users, developers, and partners:

For detailed copyright, disclaimers, and origin information, please refer to the NOTICE file.