This is a python based Clifford circuit simulation package that not only offers fast simulation but also supports analytical-level manipulation of Pauli operators and stabilizer states. And we are working on quantum circuit (strong/weak) simulations that include a few T-gates. To get started, in the examples folder (or older version PyClifford Jupyter Book), we have made several Jupyter notebooks to illustrate the basics of PyClifford. It is very intuitive to use and get started!
Also, there are several application show cases below that are helpful.
You can install PyClifford locally by following these simple steps:
It’s recommended to use a virtual environment to avoid dependency conflicts.
Using conda (recommended)
conda create --name pyclifford python=3.11
conda activate pycliffordUsing venv (if not using conda)
python3 -m venv pyclifford-env
source pyclifford-env/bin/activateMake sure you have the following packages installed:
pip install numpy matplotlib numbaYou may also need to install a compatible version of setuptools:
pip install setuptools==68.2.2git clone https://github.com/hongyehu/PyClifford.git
cd PyClifford
pip install .Open a Python shell and try:
import pyclifford as pc
print(pc.__version__)Suppose the version is >=v0.1.1 ; then, it is the updated version. See the release notes later for the changes. And now try:
import pyclifford as pc
print(pc.pauli("X"))You should see output corresponding to the Pauli X operator! Congratulations! 🎉
We're excited to introduce our latest feature!: ✨
- A new
examplesfolder containing step-by-step examples.
Here's how to create a 4-qubit GHZ state using PyClifford:
import pyclifford as pc
# Create a 4-qubit quantum circuit
N = 4
circ = pc.Circuit()
# Apply gates: H on qubit 0, then a chain of CNOTs
circ.append(pc.H(0))
circ.append(pc.CNOT(0, 1))
circ.append(pc.CNOT(1, 2))
circ.append(pc.CNOT(2, 3))
# Initialize the |0000⟩ state
state = pc.zero_state(N)
# Apply the circuit
state = circ.forward(state)
# Print the final state
print("State after circuit:", state)Or one can simply do
import pyclifford as pc
# Create a 4-qubit quantum circuit
N = 4
circ = pc.Circuit(pc.H(0),pc.CNOT(0, 1),pc.CNOT(1, 2),pc.CNOT(2, 3))
# Initialize the |0000⟩ state
state = pc.zero_state(N)
# Apply the circuit
state = circ.forward(state)
# Print the final state
print("State after circuit:", state)Now, let's do a mid-circuit measurement!
import pyclifford as pc
# Create a 4-qubit quantum circuit
N = 4
circ = pc.Circuit()
# Apply gates: H on qubit 0, then a chain of CNOTs
circ.append(pc.H(0))
circ.append(pc.CNOT(0, 1))
circ.append(pc.Measurement(1)) # measure qubit-1 in z-basis
circ.append(pc.H(1))
circ.append(pc.CNOT(1, 2))
circ.append(pc.CNOT(2, 3))
# Initialize the |0000⟩ state
state = pc.zero_state(N)
# Apply the circuit
state = circ.forward(state)
# Print the final state
print("State after circuit:", state)
# Print mid-circuit measurement result
print("mid-circuit measurement:", circ.measure_result)- Prof. Zhen Bi (Pappalardo Fellow 17'@MIT, Assistant Professor@PennState):
"PyClifford is an exceptional tool that offers researchers in quantum condensed matter a wide range of capabilities, including an intuitive programming language for simulating and analyzing Clifford circuits, quantum measurement, and evaluation of entanglement quantities, all of which are crucial in advancing our understanding of the quantum world. Its continuous updates and enhancements by a well-coordinated team of experts make it a reliable and powerful resource that can keep pace with the latest research developments and drive new discoveries in the field."
(We are still working on making detailed examples in those Jupyter notebooks)
- Solving a strong disordered Hamiltonian by Spectrum Bifurcation Renormalization Group (Condensed Matter Physics) Link
- Measurement induced phase transition (Condensed Matter Physics/Quantum Error Correction) Link
- Classical shadow tomography with shallow layers (Quantum Computation & Information) Link
- Clifford ansatz for quantum chemistry (Quantum Computation & Quantum Chemistry) Link
The structure of PyClifford is illustrated below. Pauli strings, stabilizer states, and Clifford maps are represented by binary or integer strings. All the low-level calculation is in the utils.py with JIT compliation. Then paulialg.py handles all the Pauli algebra and manipulation of Pauli string lists. On top of that, we have built stabilizer.py to handle stabilizer states and Clifford maps. Finally, circuit.py gives user an easy access to all the functions.
In addition, we are interested in developing PyCliffordExt as an extension to PyClifford, where we would like to include few-T gate into the package. If you are interested in its physics or contributing to the code, please feel free to contact us!
- Numba
- Numpy
- Matplotlib
- Qiskit 0.39.4
- Pyscf 2.0.1
📦 Major Update: v0.1.1 (May 2025)
🚀 Major Update Summary
- Unified circuit architecture to support both unitary and measurement operations, and more flexible circuit class to compose any type of operation.
- Unified measurement and post-selection framework using
log2scale for stability. - Removed
QuTiPdependency in favor of pure NumPy implementations. - Added caching for measurements and random unitaries to support classical shadows. 🗂 File-by-File Updates
### `__init__.py`
- Refactored imports and renamed core classes:
Circuit,Layer,Measurement. - Removed obsolete classes:
CliffordCircuit,MeasurementLayer. - Added new gate primitives:
SWAP,CZ,CX,measurement_layer.
### `utils.py`
- Introduced
stabilizer_postselect, unified treatment of projection and post-selection withlog2prob. - Removed deprecated methods:
stabilizer_projection_trace,stabilizer_postselection, anddecompose. - Explained the encoder-decoder logic for Pauli decomposition using
.transform_by(state.to_map().inverse()).
### `paulialg.py`
- Removed
qutipdependency and replaced withto_numpymethods. - Vectorized
PauliList.to_numpyfor efficiency. - Constructors now accept
**kwargsto support inheritance.
### `stabilizer.py`
- Fixed
.copy()issue by improving constructor signature handlingr. - Removed
.set_r(), now setrvia constructor or direct assignment. - Standardized error handling with Python exceptions.
- Unified implementation of
.expect()and.get_prob()usingstabilizer_postselect. - Introduced fugacity for reweighting Pauli observable expectations.
### `circuit.py`
- Major refactor of
CircuitandLayerclasses to support measurements and flexible composition. - Replaced
.take()with.append(). forwardandbackwardnow return(state, log2prob)tuple uniformly.- Introduced
Measurementclass with cached outcomes, enabling classical shadows via forward/backward structure. - Removed
.Nand constructor no longer requires qubit count. - Added
.reset()methods to clear cached values. - Random unitary caching in
CliffordGateto support deterministic inverses in backward pass.
- Generalized stabilizer states
- Noisy circuit simulation of classical shadows
- One-line calculation of Pauli weight used for classical post-processing. (Tensor network-based algorithm)
We are currently preparing a documentation paper for PyClifford, expected in July 2025. In the meantime, if you use this package in your research, please consider citing the related works that contributed to its development:
-
Topological and symmetry-enriched random quantum critical points
Carlos M. Duque, Hong-Ye Hu, Yi-Zhuang You, Vedika Khemani, Ruben Verresen, Romain Vasseur
Phys. Rev. B 103, L100207 (2021)
DOI: 10.1103/PhysRevB.103.L100207 -
Classical shadow tomography with locally scrambled quantum dynamics
Hong-Ye Hu, Soonwon Choi, Yi-Zhuang You
Phys. Rev. Research 5, 023027 (2023)
DOI: 10.1103/PhysRevResearch.5.023027 -
Demonstration of robust and efficient quantum property learning with shallow shadows
Hong-Ye Hu, Andi Gu, Swarnadeep Majumder, Hang Ren, Yipei Zhang, Derek S. Wang, Yi-Zhuang You, Zlatko Minev, Susanne F. Yelin, Alireza Seif
Nature Communications 16, 2943 (2025)
DOI: 10.1038/s41467-025-57349-w
We are planning to move TorchClifford to a separate package and keep PyClifford lightweight, as users' suggestions. For users of TorchClifford, please keep an eye for the update.