---
license: apache-2.0
---

![hf-banner-ai-transpiler_cliffords](https://cdn-uploads.huggingface.co/production/uploads/64b7001445f3511db2f6aa5b/PF_bKvp4o06745LJftICp.png)

# Clifford Quantum Synthesis Circuit Models

## Introduction
This repository hosts models for clifford synthesis in quantum circuits trained with RL techniques. The models are specialized for different topologies and qubit counts.

Clifford circuits transform stabilizer states by gates that map Pauli operators to Pauli operators, typically composed of H, S, and CNOT gates arranged under the device’s connectivity constraints. [More info about Clifford circuits in Qiskit](https://quantum.cloud.ibm.com/docs/en/api/qiskit/qiskit.quantum_info.Clifford)

For each model, there is the environment config (`.json`) and the trained policy weights (`.safetensors`).

## Scope
- Clifford synthesis models only.
- Each model is tied to a specific qubit count and topology; use the matching pair for your target device/layout. To discover the specific topology for each model see the `gateset` property in the model's config.

## Contents
- `clifford_*.json`: model configs for a given qubit count/topology.
- Matching `.safetensors` files: trained policies for each JSON (same filename stem).

## Training

Training data is entirely synthetic and generated internally at IBM Quantum using custom reinforcement learning environments built on [Qiskit-Gym](https://github.com/AI4quantum/qiskit-gym).

**Data Collection:** Random clifford operators are generated by composing random CNOT, H and S gates sequences consistent with the target coupling map. The number of gates scales with the difficulty, which increase when the model learns to solve circuits at that difficulty. No external datasets or third-party circuit repositories are used.

**PII:** No personal or sensitive data is present or used in any phase of training, as all data is synthetic and generated algorithmically.

**Infrastructure:** We train the models using IBM's Cognitive Computing Cluster (CCC) using NVIDIA A100 40GB GPUs. The cluster provides a scalable and efficient infrastructure for training.

## Usage example

Below is a snippet to synthesize a random 10-qubit clifford. We use `qiskit-gym` ([repo](https://github.com/AI4quantum/qiskit-gym)), `twisteRL` ([repo](https://github.com/AI4quantum/twisteRL)), and `qiskit`. Install dependencies via `pip install qiskit-gym` in your virtual environment.

```python
from qiskit_gym.rl import RLSynthesis
from twisterl.utils import pull_hub_algorithm
from qiskit.quantum_info import random_clifford

repo_id = "Qiskit/ai-transpiler_cliffords"  # adjust if your repo name differs
model_stem = "clifford_9qL"                # replace with the stem of your model files

local_path = pull_hub_algorithm(
    repo_id=repo_id,
    model_path="./models",
    revision="main",
    validate=True,
)
if not local_path:
    raise ValueError("Failed to download Clifford model from hub")

num_qubits = 9
seed = 42
target_clifford = random_clifford(num_qubits, seed=seed)

rls = RLSynthesis.from_config_json(
    f"{local_path}/{model_stem}.json",
    f"{local_path}/{model_stem}.safetensors",
)

qc_clifford = rls.synth(
    target_clifford,
    num_searches=10,
    num_mcts_searches=0,
    deterministic=False,
)
print(qc_clifford)
```

## Models

Below is the list of available models with qubit counts and topologies:

| Model | Qubits | Topology |
| --- | --- | --- |
| [`clifford_3qL`](model_data/clifford_3qL.md) | 3 | L |
| [`clifford_4qL`](model_data/clifford_4qL.md) | 4 | L |
| [`clifford_4qT`](model_data/clifford_4qT.md) | 4 | T |
| [`clifford_5qL`](model_data/clifford_5qL.md) | 5 | L |
| [`clifford_5qT`](model_data/clifford_5qT.md) | 5 | T |
| [`clifford_6qL`](model_data/clifford_6qL.md) | 6 | L |
| [`clifford_6qT`](model_data/clifford_6qT.md) | 6 | T |
| [`clifford_6qY`](model_data/clifford_6qY.md) | 6 | Y |
| [`clifford_7qH`](model_data/clifford_7qH.md) | 7 | H |
| [`clifford_7qL`](model_data/clifford_7qL.md) | 7 | L |
| [`clifford_7qT`](model_data/clifford_7qT.md) | 7 | T |
| [`clifford_7qT2`](model_data/clifford_7qT2.md) | 7 | T2 |
| [`clifford_7qY`](model_data/clifford_7qY.md) | 7 | Y |
| [`clifford_8qH`](model_data/clifford_8qH.md) | 8 | H |
| [`clifford_8qL`](model_data/clifford_8qL.md) | 8 | L |
| [`clifford_8qT`](model_data/clifford_8qT.md) | 8 | T |
| [`clifford_8qT2`](model_data/clifford_8qT2.md) | 8 | T2 |
| [`clifford_8qY`](model_data/clifford_8qY.md) | 8 | Y |
| [`clifford_8qY2`](model_data/clifford_8qY2.md) | 8 | Y2 |
| [`clifford_9qH`](model_data/clifford_9qH.md) | 9 | H |
| [`clifford_9qH2`](model_data/clifford_9qH2.md) | 9 | H2 |
| [`clifford_9qH3`](model_data/clifford_9qH3.md) | 9 | H3 |
| [`clifford_9qH4`](model_data/clifford_9qH4.md) | 9 | H4 |
| [`clifford_9qL`](model_data/clifford_9qL.md) | 9 | L |
| [`clifford_9qT`](model_data/clifford_9qT.md) | 9 | T |
| [`clifford_9qT2`](model_data/clifford_9qT2.md) | 9 | T2 |
| [`clifford_9qT3`](model_data/clifford_9qT3.md) | 9 | T3 |

## Acknowledgements
The authors acknowledge the IBM Research CCC Service for providing resources that have contributed to the production or processing of the data contained within this data collection.