QuPort Documentation

QuPort is a Python and Qiskit toolkit for modeling, mapping, routing, splitting, scheduling, and benchmarking quantum circuits on modular multi-QPU machines. The project models each QPU as a block of compute and communication qubits, exposes multiple interconnect abstractions, and provides both global-routing and explicit distributed-compilation workflows.

Documentation map

Page	What it answers	Primary audience
Getting started	How do I install QuPort and run the first mapping/compile?	New users
Concepts	What are the machine, partitioning, routing, and scheduling models?	Researchers and users interpreting results
Entanglement model	How many EPR pairs does a partition cost, and how are cross-QPU gates aggregated?	Researchers comparing communication cost
Configuration	What does every config/latency field mean, and how do fields interact?	Experiment authors
CLI reference	What commands are available and what files do they produce?	CLI users and automation authors
API reference	What Python objects/functions are public and what do they return?	Library users
Examples	What are complete snippets for common workflows?	Notebook/script authors
Development	How should contributors test, format, type-check, and update docs?	Contributors

Recommended reading order

1. Start with Getting started if you want to run QuPort quickly.

2. Read Concepts before interpreting benchmark or scheduling numbers.

3. Read Entanglement model before comparing EPR-pair or e-bit figures.

4. Use Configuration while designing architecture sweeps.

5. Use API reference while writing experiments against the Python API.

6. Use CLI reference when scripting command-line workflows.

7. Use Development before contributing changes.

Workflow decision guide

Goal	Recommended entry point	Why
Compare mapped-circuit depth/SWAPs across partitioning strategies	map_and_transpile or quport map	Produces one globally routed Qiskit circuit and standard circuit metrics
Produce per-QPU local programs and explicit remote operations	compile_distributed or quport compile-dist	Keeps cross-QPU gates as remote events instead of hiding them inside global routing
Run repeated random-circuit comparisons	benchmark_random_circuits or quport bench	Writes row-oriented benchmark metrics suitable for CSV analysis
Sweep topology/port settings	sweep_topologies or quport sweep	Aggregates repeated benchmark rows by architecture setting
Count EPR pairs and inspect the communication plan	quport ebits or compile_distributed(...).aggregation	Reports e-bit demand after cat-entanglement aggregation, not just cut gates
See what letting qubits move mid-circuit would save	quport migrate or optimize_temporal_partition	Prices time-varying placement against static placement in the same e-bit model
Judge how good a partition actually is	quport optimal or partition_gap	Solves the same instance exactly, so a heuristic’s result has a scale to be read against
Check that a schedule manifest adds up	audit_topology_schedule_plan / audit_entanglement_schedule	The topology audit re-derives every figure in a plan independently; the entanglement audit, which has no event log to replay, checks the resource bounds its totals must satisfy
Inspect communication bottlenecks	estimate_topology_schedule_plan	Returns layer/round traces with absolute timing, port usage, link utilization, and a validated JSON-ready to_dict() manifest

Documentation accuracy policy

The API reference mirrors the exported objects in quport.__all__ and the CLI reference mirrors the Typer commands in quport.cli. If a public symbol, command, configuration field, output artifact, validation rule, or conceptual model changes, update the corresponding page in this directory in the same pull request.

When docs and implementation disagree, treat the implementation and tests as the source of truth, then fix the documentation immediately. For behavior that is subtle or research-model dependent, document both what QuPort currently does and what it does not claim to model.