# fiqci/qcut architecture

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

- Interactive diagram: https://gitdiagram.com/fiqci/qcut
- Repository: https://github.com/fiqci/qcut

## Overview

QCut is a Qiskit-based quantum circuit knitting package: users mark gate or resetless-wire cuts, or ask the automatic finder to choose cuts, then generate and run subcircuit experiments and reconstruct results. The graph preserves the separate planning, preparation, decomposition, execution, and result stages, including documented observables, probability reconstruction, and backend support. Source excerpts are partial, so uncertain internal call links are omitted; documented capabilities without sampled implementation are linked only where their runtime role is clear.

Main entry points: [`QCut/execution/circuit_knitting.py`](https://github.com/fiqci/qcut/blob/main/QCut/execution/circuit_knitting.py) (Experiment orchestration), [`QCut/cutting/circuit_preparation.py`](https://github.com/fiqci/qcut/blob/main/QCut/cutting/circuit_preparation.py) (Prepare and split), [`QCut/cutcircuit.py`](https://github.com/fiqci/qcut/blob/main/QCut/cutcircuit.py) (CutExperiment), [`QCut/QCutFind/cut_finding.py`](https://github.com/fiqci/qcut/blob/main/QCut/QCutFind/cut_finding.py) (Automatic cut finder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Cut planning"]
  node_finder["Automatic cut finder<br/>[cut_finding.py]"]
  node_refinement["Cut refinement<br/>[refine.py]"]
  node_options["Cut options<br/>[options.py]"]
end

subgraph group_preparation["Circuit preparation"]
  node_preparation["Prepare and split"]
  node_consolidation["Gate consolidation<br/>[consolidate.py]"]
  node_cutcircuit["CutCircuit<br/>[cutcircuit.py]"]
  node_locations["Cut locations<br/>[cutlocation.py]"]
end

subgraph group_decomposition["QPD experiments"]
  node_experiments["CutExperiment<br/>[cutcircuit.py]"]
  node_bundle["Joint cut bundles<br/>[bundle.py]"]
  node_qpd["QPD generation<br/>[qpd_generate.py]"]
  node_qpdops["Insert QPD operations<br/>[qpd_operations.py]"]
end

subgraph group_execution["Execution and results"]
  node_knitting["Experiment orchestration"]
  node_routing["MOVE routing<br/>[move_routing.py]"]
  node_parallel["Parallel execution<br/>[parallel.py]"]
  node_distribution["Shot distribution<br/>[distribution.py]"]
  node_observables["Observable handling<br/>[observables.py]"]
  node_postprocess["Result reconstruction<br/>[postprocess.py]"]
  node_probabilities["Probability reconstruction<br/>[probabilities.py]"]
  node_result["QCut result<br/>[qcutresult.py]"]
end

node_user(("QCut user"))
node_circuit["Marked circuit"]
node_backend{{"Quantum backend"}}

node_user -->|"marks cuts"| node_circuit
node_user -->|"requests cuts"| node_finder
node_circuit -->|"prepares split"| node_preparation
node_finder -->|"refines candidates"| node_refinement
node_finder -->|"creates cut markers"| node_preparation
node_options -->|"configures search"| node_finder
node_options -->|"configures split"| node_preparation
node_preparation -.->|"merges gate runs"| node_consolidation
node_preparation -->|"records cuts"| node_locations
node_preparation -->|"returns split"| node_cutcircuit
node_user -->|"requests experiments"| node_cutcircuit
node_cutcircuit -->|"builds experiments"| node_experiments
node_options -->|"configures expansion"| node_experiments
node_experiments -->|"plans joint cuts"| node_bundle
node_bundle -->|"selects decompositions"| node_qpd
node_qpd -->|"provides terms"| node_qpdops
node_experiments -->|"submits circuits"| node_knitting
node_qpdops -->|"prepares circuits"| node_knitting
node_user -->|"runs experiments"| node_knitting
node_knitting -.->|"routes when needed"| node_routing
node_knitting -->|"allocates shots"| node_distribution
node_knitting -->|"dispatches jobs"| node_parallel
node_parallel -->|"runs circuits"| node_backend
node_knitting -->|"runs circuits"| node_backend
node_backend -->|"returns counts"| node_knitting
node_experiments -->|"provides observables"| node_observables
node_knitting -->|"reconstructs estimates"| node_postprocess
node_knitting -.->|"reconstructs distributions"| node_probabilities
node_postprocess -->|"produces estimates"| node_result
node_probabilities -.->|"produces probabilities"| node_result
node_result -->|"returns results"| node_user

click node_finder "https://github.com/fiqci/qcut/blob/main/QCut/QCutFind/cut_finding.py"
click node_refinement "https://github.com/fiqci/qcut/blob/main/QCut/QCutFind/refine.py"
click node_options "https://github.com/fiqci/qcut/blob/main/QCut/options.py"
click node_preparation "https://github.com/fiqci/qcut/blob/main/QCut/cutting/circuit_preparation.py"
click node_consolidation "https://github.com/fiqci/qcut/blob/main/QCut/cutting/consolidate.py"
click node_cutcircuit "https://github.com/fiqci/qcut/blob/main/QCut/cutcircuit.py"
click node_locations "https://github.com/fiqci/qcut/blob/main/QCut/cutlocation.py"
click node_experiments "https://github.com/fiqci/qcut/blob/main/QCut/cutcircuit.py"
click node_bundle "https://github.com/fiqci/qcut/blob/main/QCut/qpd/bundle.py"
click node_qpd "https://github.com/fiqci/qcut/blob/main/QCut/qpd/qpd_generate.py"
click node_qpdops "https://github.com/fiqci/qcut/blob/main/QCut/qpd/qpd_operations.py"
click node_knitting "https://github.com/fiqci/qcut/blob/main/QCut/execution/circuit_knitting.py"
click node_routing "https://github.com/fiqci/qcut/blob/main/QCut/execution/move_routing.py"
click node_parallel "https://github.com/fiqci/qcut/blob/main/QCut/execution/parallel.py"
click node_distribution "https://github.com/fiqci/qcut/blob/main/QCut/execution/distribution.py"
click node_observables "https://github.com/fiqci/qcut/blob/main/QCut/execution/observables.py"
click node_postprocess "https://github.com/fiqci/qcut/blob/main/QCut/execution/postprocess.py"
click node_probabilities "https://github.com/fiqci/qcut/blob/main/QCut/execution/probabilities.py"
click node_result "https://github.com/fiqci/qcut/blob/main/QCut/execution/qcutresult.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_finder,node_refinement,node_options,node_user toneBlue
class node_preparation,node_consolidation,node_cutcircuit,node_locations toneAmber
class node_experiments,node_bundle,node_qpd,node_qpdops toneMint
class node_knitting,node_routing,node_parallel,node_distribution,node_observables,node_postprocess,node_probabilities,node_result toneRose
class node_circuit,node_backend toneIndigo
```

## Components

### Cut planning

- [Automatic cut finder](https://github.com/fiqci/qcut/blob/main/QCut/QCutFind/cut_finding.py): `QCut/QCutFind/cut_finding.py`
- [Cut refinement](https://github.com/fiqci/qcut/blob/main/QCut/QCutFind/refine.py): `QCut/QCutFind/refine.py`
- [Cut options](https://github.com/fiqci/qcut/blob/main/QCut/options.py): `QCut/options.py`

### Circuit preparation

- [Prepare and split](https://github.com/fiqci/qcut/blob/main/QCut/cutting/circuit_preparation.py): `QCut/cutting/circuit_preparation.py`
- [Gate consolidation](https://github.com/fiqci/qcut/blob/main/QCut/cutting/consolidate.py): `QCut/cutting/consolidate.py`
- [CutCircuit](https://github.com/fiqci/qcut/blob/main/QCut/cutcircuit.py): `QCut/cutcircuit.py`
- [Cut locations](https://github.com/fiqci/qcut/blob/main/QCut/cutlocation.py): `QCut/cutlocation.py`

### QPD experiments

- [CutExperiment](https://github.com/fiqci/qcut/blob/main/QCut/cutcircuit.py): `QCut/cutcircuit.py`
- [Joint cut bundles](https://github.com/fiqci/qcut/blob/main/QCut/qpd/bundle.py): `QCut/qpd/bundle.py`
- [QPD generation](https://github.com/fiqci/qcut/blob/main/QCut/qpd/qpd_generate.py): `QCut/qpd/qpd_generate.py`
- [Insert QPD operations](https://github.com/fiqci/qcut/blob/main/QCut/qpd/qpd_operations.py): `QCut/qpd/qpd_operations.py`

### Execution and results

- [Experiment orchestration](https://github.com/fiqci/qcut/blob/main/QCut/execution/circuit_knitting.py): `QCut/execution/circuit_knitting.py`
- [MOVE routing](https://github.com/fiqci/qcut/blob/main/QCut/execution/move_routing.py): `QCut/execution/move_routing.py`
- [Parallel execution](https://github.com/fiqci/qcut/blob/main/QCut/execution/parallel.py): `QCut/execution/parallel.py`
- [Shot distribution](https://github.com/fiqci/qcut/blob/main/QCut/execution/distribution.py): `QCut/execution/distribution.py`
- [Observable handling](https://github.com/fiqci/qcut/blob/main/QCut/execution/observables.py): `QCut/execution/observables.py`
- [Result reconstruction](https://github.com/fiqci/qcut/blob/main/QCut/execution/postprocess.py): `QCut/execution/postprocess.py`
- [Probability reconstruction](https://github.com/fiqci/qcut/blob/main/QCut/execution/probabilities.py): `QCut/execution/probabilities.py`
- [QCut result](https://github.com/fiqci/qcut/blob/main/QCut/execution/qcutresult.py): `QCut/execution/qcutresult.py`

### Other components

- **QCut user**
- **Marked circuit**
- **Quantum backend**

## Connections

- QCut user → Marked circuit: marks cuts
- QCut user → Automatic cut finder: requests cuts
- Marked circuit → Prepare and split: prepares split
- Automatic cut finder → Cut refinement: refines candidates
- Automatic cut finder → Prepare and split: creates cut markers
- Cut options → Automatic cut finder: configures search
- Cut options → Prepare and split: configures split
- Prepare and split → Gate consolidation: merges gate runs
- Prepare and split → Cut locations: records cuts
- Prepare and split → CutCircuit: returns split
- QCut user → CutCircuit: requests experiments
- CutCircuit → CutExperiment: builds experiments
- Cut options → CutExperiment: configures expansion
- CutExperiment → Joint cut bundles: plans joint cuts
- Joint cut bundles → QPD generation: selects decompositions
- QPD generation → Insert QPD operations: provides terms
- CutExperiment → Experiment orchestration: submits circuits
- Insert QPD operations → Experiment orchestration: prepares circuits
- QCut user → Experiment orchestration: runs experiments
- Experiment orchestration → MOVE routing: routes when needed
- Experiment orchestration → Shot distribution: allocates shots
- Experiment orchestration → Parallel execution: dispatches jobs
- Parallel execution → Quantum backend: runs circuits
- Experiment orchestration → Quantum backend: runs circuits
- Quantum backend → Experiment orchestration: returns counts
- CutExperiment → Observable handling: provides observables
- Experiment orchestration → Result reconstruction: reconstructs estimates
- Experiment orchestration → Probability reconstruction: reconstructs distributions
- Result reconstruction → QCut result: produces estimates
- Probability reconstruction → QCut result: produces probabilities
- QCut result → QCut user: returns results