# quantumlib/cirq architecture

> Architecture diagram of the GitHub repository quantumlib/cirq, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quantumlib/cirq
- Repository: https://github.com/quantumlib/cirq

## Overview

Cirq is a Python toolkit for defining, transforming, simulating, and running quantum circuits. The central workflow is to express gates and qubits in a circuit, optionally compile or route it for a device, then simulate it locally or submit it through a provider client and obtain measurement results. The repository also includes noise models, experiments, serialization, and provider-specific integrations. The README documents the main user workflow and capabilities; several provider and subsystem links below are limited to the sampled source and SOURCE INDEX evidence.

Main entry points: [`cirq-core/cirq/circuits/circuit.py`](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/circuits/circuit.py) (Circuit Builder), [`cirq-google/cirq_google/engine/engine.py`](https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine.py) (Google Engine), [`cirq-google/cirq_google/engine/engine_client.py`](https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine_client.py) (Engine Client), [`cirq-core/cirq/contrib/routing/router.py`](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/contrib/routing/router.py) (Circuit Routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Circuit Core"]
  node_gates["Gates And Qubits"]
  node_circuit["Circuit Builder<br/>[circuit.py]"]
  node_qubitmanager["Ancilla Manager"]
  node_serialization["JSON Serialization"]
  node_contribjson["Contrib JSON<br/>[json.py]"]
end

subgraph group_compile["Compile And Model"]
  node_transformers["Circuit Transformers"]
  node_routing["Circuit Routing<br/>[router.py]"]
  node_devices["Device Models"]
  node_noise["Noise Models<br/>[noise_model.py]"]
end

subgraph group_execution["Simulation And Experiments"]
  node_simulators["Circuit Simulators"]
  node_experiments["Experiments"]
end

subgraph group_google["Google Quantum Engine"]
  node_googleengine["Google Engine<br/>[engine.py]"]
  node_googleclient["Engine Client<br/>[engine_client.py]"]
  node_googlejob["Engine Jobs<br/>[engine_job.py]"]
  node_googleapi["Engine API Types<br/>[engine.py]"]
  node_googleprotocol["Google Program Format<br/>[program.py]"]
end

subgraph group_providers["Other Providers"]
  node_aqt["AQT Sampler<br/>[aqt_sampler.py]"]
  node_ionq["IonQ Service<br/>[service.py]"]
  node_pasqal["Pasqal Device<br/>[pasqal_device.py]"]
end

node_user(("Quantum Developer"))
node_cloud{{"Google Quantum Engine"}}

node_user -->|"builds"| node_circuit
node_circuit -->|"uses"| node_gates
node_user -->|"runs locally"| node_simulators
node_circuit -->|"simulates"| node_simulators
node_user -->|"compiles"| node_transformers
node_circuit -.->|"routes"| node_routing
node_routing -.->|"targets"| node_devices
node_circuit -.->|"models noise"| node_noise
node_user -.->|"analyzes"| node_experiments
node_circuit -.->|"serializes"| node_serialization
node_contribjson -->|"registers resolvers"| node_serialization
node_qubitmanager -->|"allocates qubits"| node_gates
node_user -->|"submits circuit"| node_googleengine
node_googleengine -->|"calls"| node_googleclient
node_googleengine -->|"creates jobs"| node_googlejob
node_googlejob -->|"requests results"| node_googleclient
node_googleclient -->|"uses requests"| node_googleapi
node_googleclient -.->|"sends requests"| node_cloud
node_googleengine -->|"uses format"| node_googleprotocol
node_user -.->|"submits runs"| node_aqt
node_user -.->|"submits runs"| node_ionq
node_user -.->|"targets hardware"| node_pasqal

click node_gates "https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/ops"
click node_circuit "https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/circuits/circuit.py"
click node_qubitmanager "https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/ops/greedy_qubit_manager.py"
click node_serialization "https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/protocols/json_serialization.py"
click node_contribjson "https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/contrib/json.py"
click node_transformers "https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/transformers"
click node_routing "https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/contrib/routing/router.py"
click node_devices "https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/devices"
click node_noise "https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/devices/noise_model.py"
click node_simulators "https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/sim"
click node_experiments "https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/experiments"
click node_googleengine "https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine.py"
click node_googleclient "https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine_client.py"
click node_googlejob "https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine_job.py"
click node_googleapi "https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/cloud/quantum_v1alpha1/types/engine.py"
click node_googleprotocol "https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/api/v2/program.py"
click node_aqt "https://github.com/quantumlib/cirq/blob/main/cirq-aqt/cirq_aqt/aqt_sampler.py"
click node_ionq "https://github.com/quantumlib/cirq/blob/main/cirq-ionq/cirq_ionq/service.py"
click node_pasqal "https://github.com/quantumlib/cirq/blob/main/cirq-pasqal/cirq_pasqal/pasqal_device.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gates,node_circuit,node_qubitmanager,node_serialization,node_contribjson toneBlue
class node_transformers,node_routing,node_devices,node_noise toneAmber
class node_simulators,node_experiments toneMint
class node_googleengine,node_googleclient,node_googlejob,node_googleapi,node_googleprotocol toneRose
class node_aqt,node_ionq,node_pasqal,node_user,node_cloud toneIndigo
```

## Components

### Circuit Core

- [Gates And Qubits](https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/ops): `cirq-core/cirq/ops`
- [Circuit Builder](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/circuits/circuit.py): `cirq-core/cirq/circuits/circuit.py`
- [Ancilla Manager](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/ops/greedy_qubit_manager.py): `cirq-core/cirq/ops/greedy_qubit_manager.py`
- [JSON Serialization](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/protocols/json_serialization.py): `cirq-core/cirq/protocols/json_serialization.py`
- [Contrib JSON](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/contrib/json.py): `cirq-core/cirq/contrib/json.py`

### Compile And Model

- [Circuit Transformers](https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/transformers): `cirq-core/cirq/transformers`
- [Circuit Routing](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/contrib/routing/router.py): `cirq-core/cirq/contrib/routing/router.py`
- [Device Models](https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/devices): `cirq-core/cirq/devices`
- [Noise Models](https://github.com/quantumlib/cirq/blob/main/cirq-core/cirq/devices/noise_model.py): `cirq-core/cirq/devices/noise_model.py`

### Simulation And Experiments

- [Circuit Simulators](https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/sim): `cirq-core/cirq/sim`
- [Experiments](https://github.com/quantumlib/cirq/tree/main/cirq-core/cirq/experiments): `cirq-core/cirq/experiments`

### Google Quantum Engine

- [Google Engine](https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine.py): `cirq-google/cirq_google/engine/engine.py`
- [Engine Client](https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine_client.py): `cirq-google/cirq_google/engine/engine_client.py`
- [Engine Jobs](https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/engine/engine_job.py): `cirq-google/cirq_google/engine/engine_job.py`
- [Engine API Types](https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/cloud/quantum_v1alpha1/types/engine.py): `cirq-google/cirq_google/cloud/quantum_v1alpha1/types/engine.py`
- [Google Program Format](https://github.com/quantumlib/cirq/blob/main/cirq-google/cirq_google/api/v2/program.py): `cirq-google/cirq_google/api/v2/program.py`

### Other Providers

- [AQT Sampler](https://github.com/quantumlib/cirq/blob/main/cirq-aqt/cirq_aqt/aqt_sampler.py): `cirq-aqt/cirq_aqt/aqt_sampler.py`
- [IonQ Service](https://github.com/quantumlib/cirq/blob/main/cirq-ionq/cirq_ionq/service.py): `cirq-ionq/cirq_ionq/service.py`
- [Pasqal Device](https://github.com/quantumlib/cirq/blob/main/cirq-pasqal/cirq_pasqal/pasqal_device.py): `cirq-pasqal/cirq_pasqal/pasqal_device.py`

### Other components

- **Quantum Developer**
- **Google Quantum Engine**

## Connections

- Quantum Developer → Circuit Builder: builds
- Circuit Builder → Gates And Qubits: uses
- Quantum Developer → Circuit Simulators: runs locally
- Circuit Builder → Circuit Simulators: simulates
- Quantum Developer → Circuit Transformers: compiles
- Circuit Builder → Circuit Routing: routes
- Circuit Routing → Device Models: targets
- Circuit Builder → Noise Models: models noise
- Quantum Developer → Experiments: analyzes
- Circuit Builder → JSON Serialization: serializes
- Contrib JSON → JSON Serialization: registers resolvers (evidence: `cirq-core/cirq/contrib/json.py`)
- Ancilla Manager → Gates And Qubits: allocates qubits (evidence: `cirq-core/cirq/ops/greedy_qubit_manager.py`)
- Quantum Developer → Google Engine: submits circuit
- Google Engine → Engine Client: calls (evidence: `cirq-google/cirq_google/engine/engine.py`)
- Google Engine → Engine Jobs: creates jobs (evidence: `cirq-google/cirq_google/engine/engine.py`)
- Engine Jobs → Engine Client: requests results (evidence: `cirq-google/cirq_google/engine/engine_job.py`)
- Engine Client → Engine API Types: uses requests
- Engine Client → Google Quantum Engine: sends requests
- Google Engine → Google Program Format: uses format (evidence: `cirq-google/cirq_google/engine/engine.py`)
- Quantum Developer → AQT Sampler: submits runs
- Quantum Developer → IonQ Service: submits runs
- Quantum Developer → Pasqal Device: targets hardware
