# BQSKit-FT: Fault-Tolerant Quantum Compilation
A BQSKit extension package for compiling quantum circuits to fault-tolerant gate sets.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/BSD-3-Clause)
## Overview
BQSKit-FT extends the Berkeley Quantum Synthesis Toolkit ([BQSKit](https://github.com/BQSKit/bqskit)) with specialized compilation workflows and machine models for fault-tolerant quantum computing. This package provides tools for compiling arbitrary quantum circuits into fault-tolerant gate sets such as Clifford+T and Clifford+RZ.
## Key Features
### Machine Models
- **CliffordTModel**: Fault-tolerant machine model with Clifford+T gate set
- **CliffordRZModel**: Fault-tolerant machine model with Clifford+RZ gate set
- **FaultTolerantModel**: Base class for custom fault-tolerant machine models
### Synthesis Passes
- **GridSynthPass**: High-precision RZ gate synthesis using the gridsynth algorithm
- **RoundToDiscreteZPass**: Rounds RZ gates to discrete Clifford+T equivalents
- **IsolateRZGatePass**: Isolates RZ gates for individual processing
### Compilation Workflows
- Pre-built workflows for circuit, unitary, state preparation, and state mapping compilation
- Support for multiple optimization levels (1-4)
- Configurable synthesis precision and error thresholds
- Optional RZ gate decomposition into Clifford+T
## Installation
### Dependencies
```bash
pip install bqskit numpy scipy pygridsynth
```
### Install BQSKit-FT
```bash
git clone https://github.com/BQSKit/bqskit-ft.git
cd bqskit-ft
pip install -e .
```
## Quick Start
### Basic Clifford+T Compilation
```python
from bqskit import Circuit, compile
from bqskit.ft import CliffordTModel
from bqskit.ir.gates import RZGate, CNOTGate
# Create a circuit with arbitrary rotations
circuit = Circuit(2)
circuit.append_gate(CNOTGate(), [0, 1])
circuit.append_gate(RZGate(), [0], [0.12345]) # Arbitrary angle
circuit.append_gate(RZGate(), [1], [0.67890])
# Define fault-tolerant machine model
model = CliffordTModel(2)
# Compile to Clifford+T gate set
ft_circuit = compile(circuit, model)
# Verify output uses only fault-tolerant gates
print(f"Gate set: {ft_circuit.gate_set}")
```
### High-Precision RZ Synthesis
```python
from bqskit.ft.ftpasses import GridSynthPass
from bqskit.compiler import Compiler
# Single RZ gate with arbitrary angle
circuit = Circuit(1)
circuit.append_gate(RZGate(), [0], [0.1234567890123456])
# High-precision synthesis (20 decimal places)
gridsynth = GridSynthPass(precision=20)
with Compiler() as compiler:
result = compiler.compile(circuit, [gridsynth])
print(f"Synthesized with {result.num_operations} gates")
```
### Custom Workflows
```python
from bqskit.ft.ftpasses import IsolateRZGatePass, GridSynthPass
from bqskit.passes import ForEachBlockPass, UnfoldPass
# Build custom workflow for mixed circuits
workflow = [
IsolateRZGatePass(), # Isolate RZ gates
ForEachBlockPass([GridSynthPass(15)]), # Synthesize each RZ gate
UnfoldPass(), # Flatten the circuit
]
with Compiler() as compiler:
result = compiler.compile(circuit, workflow)
```
## Machine Models
### CliffordTModel
Represents a fault-tolerant quantum computer with the Clifford+T gate set:
- **Clifford gates**: H, X, Y, Z, S, S†, √X, CNOT, CZ, SWAP
- **Non-Clifford gates**: T, T†, RZ
```python
from bqskit.ft import CliffordTModel
# 4-qubit fault-tolerant machine
model = CliffordTModel(
num_qudits=4,
clifford_gates=None, # Use default Clifford gates
non_clifford_gates=None, # Use default T gates + RZ
)
```
### CliffordRZModel
Alternative model that keeps RZ gates (no T gate decomposition):
- **Clifford gates**: H, X, Y, Z, S, S†, √X, CNOT, CZ, SWAP
- **Non-Clifford gates**: T, T†, RZ (RZ gates preserved)
```python
from bqskit.ft import CliffordRZModel
model = CliffordRZModel(num_qudits=3)
```
## Synthesis Passes
### GridSynthPass
Implements the gridsynth algorithm for optimal Clifford+T synthesis of RZ gates:
```python
from bqskit.ft.ftpasses import GridSynthPass
# Precision: 10^-15 approximation error
gridsynth = GridSynthPass(precision=15)
```
**Features:**
- Arbitrary precision synthesis using mpmath
- Provably optimal T-count for single-qubit unitaries
- Configurable precision (affects T-gate count vs. accuracy trade-off)
### RoundToDiscreteZPass
Rounds RZ gates to the nearest π/4 multiple (Clifford+T equivalent):
```python
from bqskit.ft.ftpasses import RoundToDiscreteZPass
rounder = RoundToDiscreteZPass(synthesis_epsilon=1e-8)
```
**Use cases:**
- Fast approximation for near-Clifford+T angles
- Pre-processing step before gridsynth
- Error-tolerant applications
## Compilation Options
### Optimization Levels
- **Level 1**: Fast compilation, basic optimization
- **Level 2**: Balanced speed/quality
- **Level 3**: Aggressive optimization
- **Level 4**: Maximum optimization (slowest)
### Synthesis Parameters
- `synthesis_epsilon`: Maximum unitary distance error (default: 1e-8)
- `max_synthesis_size`: Maximum block size for synthesis (default: 3)
- `decompose_rz`: Whether to decompose RZ gates to Clifford+T (default: True)
```python
from bqskit import compile
from bqskit.ft import CliffordTModel
model = CliffordTModel(2)
# High-precision, aggressive optimization
result = compile(
circuit,
model,
optimization_level=4,
synthesis_epsilon=1e-12,
max_synthesis_size=4
)
```
## Advanced Usage
### Custom Gate Sets
```python
from bqskit.ft import FaultTolerantModel
from bqskit.ir.gates import HGate, CNOTGate, TGate
# Custom fault-tolerant model
custom_clifford = [HGate(), CNOTGate()] # Minimal Clifford set
custom_non_clifford = [TGate()] # T gates only
model = FaultTolerantModel(
num_qudits=2,
clifford_gates=custom_clifford,
non_clifford_gates=custom_non_clifford
)
```
## References
- [BQSKit Documentation](https://bqskit.readthedocs.io/)
- [Gridsynth Algorithm](https://arxiv.org/abs/1403.2975)
## Citation
If you use `bqskit-ft` in your research, please cite:
```bibtex
@software{bqskit_ft,
title = {{BQSKit-FT}: Fault-Tolerant Quantum Compilation},
author = {Weiden, Mathias},
year = {2024},
url = {https://github.com/BQSKit/bqskit-ft}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "bqskit-ft",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "quantum computing, compilation, fault-tolerant, clifford+t",
"author": null,
"author_email": "Mathias Weiden <mtweiden@berkeley.edu>",
"download_url": "https://files.pythonhosted.org/packages/fe/b4/5f50f20bf10f875e47234884da325ef9f0557bbf1a402ac1be3f12121e92/bqskit_ft-0.2.0.tar.gz",
"platform": null,
"description": "# BQSKit-FT: Fault-Tolerant Quantum Compilation\n\nA BQSKit extension package for compiling quantum circuits to fault-tolerant gate sets.\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/BSD-3-Clause)\n\n## Overview\n\nBQSKit-FT extends the Berkeley Quantum Synthesis Toolkit ([BQSKit](https://github.com/BQSKit/bqskit)) with specialized compilation workflows and machine models for fault-tolerant quantum computing. This package provides tools for compiling arbitrary quantum circuits into fault-tolerant gate sets such as Clifford+T and Clifford+RZ.\n\n## Key Features\n\n### Machine Models\n- **CliffordTModel**: Fault-tolerant machine model with Clifford+T gate set\n- **CliffordRZModel**: Fault-tolerant machine model with Clifford+RZ gate set\n- **FaultTolerantModel**: Base class for custom fault-tolerant machine models\n\n### Synthesis Passes\n- **GridSynthPass**: High-precision RZ gate synthesis using the gridsynth algorithm\n- **RoundToDiscreteZPass**: Rounds RZ gates to discrete Clifford+T equivalents\n- **IsolateRZGatePass**: Isolates RZ gates for individual processing\n\n### Compilation Workflows\n- Pre-built workflows for circuit, unitary, state preparation, and state mapping compilation\n- Support for multiple optimization levels (1-4)\n- Configurable synthesis precision and error thresholds\n- Optional RZ gate decomposition into Clifford+T\n\n## Installation\n\n### Dependencies\n```bash\npip install bqskit numpy scipy pygridsynth\n```\n\n### Install BQSKit-FT\n```bash\ngit clone https://github.com/BQSKit/bqskit-ft.git\ncd bqskit-ft\npip install -e .\n```\n\n## Quick Start\n\n### Basic Clifford+T Compilation\n\n```python\nfrom bqskit import Circuit, compile\nfrom bqskit.ft import CliffordTModel\nfrom bqskit.ir.gates import RZGate, CNOTGate\n\n# Create a circuit with arbitrary rotations\ncircuit = Circuit(2)\ncircuit.append_gate(CNOTGate(), [0, 1])\ncircuit.append_gate(RZGate(), [0], [0.12345]) # Arbitrary angle\ncircuit.append_gate(RZGate(), [1], [0.67890])\n\n# Define fault-tolerant machine model\nmodel = CliffordTModel(2)\n\n# Compile to Clifford+T gate set\nft_circuit = compile(circuit, model)\n\n# Verify output uses only fault-tolerant gates\nprint(f\"Gate set: {ft_circuit.gate_set}\")\n```\n\n### High-Precision RZ Synthesis\n\n```python\nfrom bqskit.ft.ftpasses import GridSynthPass\nfrom bqskit.compiler import Compiler\n\n# Single RZ gate with arbitrary angle\ncircuit = Circuit(1)\ncircuit.append_gate(RZGate(), [0], [0.1234567890123456])\n\n# High-precision synthesis (20 decimal places)\ngridsynth = GridSynthPass(precision=20)\n\nwith Compiler() as compiler:\n result = compiler.compile(circuit, [gridsynth])\n\nprint(f\"Synthesized with {result.num_operations} gates\")\n```\n\n### Custom Workflows\n\n```python\nfrom bqskit.ft.ftpasses import IsolateRZGatePass, GridSynthPass\nfrom bqskit.passes import ForEachBlockPass, UnfoldPass\n\n# Build custom workflow for mixed circuits\nworkflow = [\n IsolateRZGatePass(), # Isolate RZ gates\n ForEachBlockPass([GridSynthPass(15)]), # Synthesize each RZ gate\n UnfoldPass(), # Flatten the circuit\n]\n\nwith Compiler() as compiler:\n result = compiler.compile(circuit, workflow)\n```\n\n## Machine Models\n\n### CliffordTModel\nRepresents a fault-tolerant quantum computer with the Clifford+T gate set:\n- **Clifford gates**: H, X, Y, Z, S, S\u2020, \u221aX, CNOT, CZ, SWAP\n- **Non-Clifford gates**: T, T\u2020, RZ\n\n```python\nfrom bqskit.ft import CliffordTModel\n\n# 4-qubit fault-tolerant machine\nmodel = CliffordTModel(\n num_qudits=4,\n clifford_gates=None, # Use default Clifford gates\n non_clifford_gates=None, # Use default T gates + RZ\n)\n```\n\n### CliffordRZModel\nAlternative model that keeps RZ gates (no T gate decomposition):\n- **Clifford gates**: H, X, Y, Z, S, S\u2020, \u221aX, CNOT, CZ, SWAP\n- **Non-Clifford gates**: T, T\u2020, RZ (RZ gates preserved)\n\n```python\nfrom bqskit.ft import CliffordRZModel\n\nmodel = CliffordRZModel(num_qudits=3)\n```\n\n## Synthesis Passes\n\n### GridSynthPass\nImplements the gridsynth algorithm for optimal Clifford+T synthesis of RZ gates:\n\n```python\nfrom bqskit.ft.ftpasses import GridSynthPass\n\n# Precision: 10^-15 approximation error\ngridsynth = GridSynthPass(precision=15)\n```\n\n**Features:**\n- Arbitrary precision synthesis using mpmath\n- Provably optimal T-count for single-qubit unitaries\n- Configurable precision (affects T-gate count vs. accuracy trade-off)\n\n### RoundToDiscreteZPass\nRounds RZ gates to the nearest \u03c0/4 multiple (Clifford+T equivalent):\n\n```python\nfrom bqskit.ft.ftpasses import RoundToDiscreteZPass\n\nrounder = RoundToDiscreteZPass(synthesis_epsilon=1e-8)\n```\n\n**Use cases:**\n- Fast approximation for near-Clifford+T angles\n- Pre-processing step before gridsynth\n- Error-tolerant applications\n\n## Compilation Options\n\n### Optimization Levels\n- **Level 1**: Fast compilation, basic optimization\n- **Level 2**: Balanced speed/quality\n- **Level 3**: Aggressive optimization\n- **Level 4**: Maximum optimization (slowest)\n\n### Synthesis Parameters\n- `synthesis_epsilon`: Maximum unitary distance error (default: 1e-8)\n- `max_synthesis_size`: Maximum block size for synthesis (default: 3)\n- `decompose_rz`: Whether to decompose RZ gates to Clifford+T (default: True)\n\n```python\nfrom bqskit import compile\nfrom bqskit.ft import CliffordTModel\n\nmodel = CliffordTModel(2)\n\n# High-precision, aggressive optimization\nresult = compile(\n circuit,\n model,\n optimization_level=4,\n synthesis_epsilon=1e-12,\n max_synthesis_size=4\n)\n```\n\n## Advanced Usage\n\n### Custom Gate Sets\n```python\nfrom bqskit.ft import FaultTolerantModel\nfrom bqskit.ir.gates import HGate, CNOTGate, TGate\n\n# Custom fault-tolerant model\ncustom_clifford = [HGate(), CNOTGate()] # Minimal Clifford set\ncustom_non_clifford = [TGate()] # T gates only\n\nmodel = FaultTolerantModel(\n num_qudits=2,\n clifford_gates=custom_clifford,\n non_clifford_gates=custom_non_clifford\n)\n```\n\n## References\n\n- [BQSKit Documentation](https://bqskit.readthedocs.io/)\n- [Gridsynth Algorithm](https://arxiv.org/abs/1403.2975)\n\n## Citation\n\nIf you use `bqskit-ft` in your research, please cite:\n\n```bibtex\n@software{bqskit_ft,\n title = {{BQSKit-FT}: Fault-Tolerant Quantum Compilation},\n author = {Weiden, Mathias},\n year = {2024},\n url = {https://github.com/BQSKit/bqskit-ft}\n}\n```\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "BQSKit extension for compiling to Fault-Tolerant gate sets.",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/BQSKit/bqskit-ft/blob/main/README.md",
"Homepage": "https://github.com/BQSKit/bqskit-ft",
"Issues": "https://github.com/BQSKit/bqskit-ft/issues",
"Repository": "https://github.com/BQSKit/bqskit-ft"
},
"split_keywords": [
"quantum computing",
" compilation",
" fault-tolerant",
" clifford+t"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f0e8dc49f37da2b5b05ff30147efcad255b9d9b81198b21419aea7dfc82804c",
"md5": "d10bfebe39ca312d5086ae7c414d1089",
"sha256": "02356d9dca0998d31e78c2e70bed49f4eac2045a8721ae47b9c0eef3ac9304eb"
},
"downloads": -1,
"filename": "bqskit_ft-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d10bfebe39ca312d5086ae7c414d1089",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19850,
"upload_time": "2025-08-30T22:38:06",
"upload_time_iso_8601": "2025-08-30T22:38:06.785072Z",
"url": "https://files.pythonhosted.org/packages/4f/0e/8dc49f37da2b5b05ff30147efcad255b9d9b81198b21419aea7dfc82804c/bqskit_ft-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "feb45f50f20bf10f875e47234884da325ef9f0557bbf1a402ac1be3f12121e92",
"md5": "3f17dfd3bfcb6f06ec6b17d375fd67ca",
"sha256": "e6d482e422c3dc73bffc49d7a70fdf98c70518273f1c693686703c1672eac14c"
},
"downloads": -1,
"filename": "bqskit_ft-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "3f17dfd3bfcb6f06ec6b17d375fd67ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14947,
"upload_time": "2025-08-30T22:38:08",
"upload_time_iso_8601": "2025-08-30T22:38:08.768762Z",
"url": "https://files.pythonhosted.org/packages/fe/b4/5f50f20bf10f875e47234884da325ef9f0557bbf1a402ac1be3f12121e92/bqskit_ft-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 22:38:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BQSKit",
"github_project": "bqskit-ft",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bqskit-ft"
}
JSON
