memq_dqc.partition¶
partition
¶
Partitioning algorithms for interaction and network graphs.
PartitionSchedule
module-attribute
¶
PartitionSchedule: TypeAlias = list[dict[QPU, set[int]]]
Per-window placement mapping each QPU to its assigned logical qubits.
PartitionWindows
module-attribute
¶
PartitionWindows: TypeAlias = list[list[Op]]
Per-window operation groupings produced alongside a placement.
BenchmarkRandomPartitioner
¶
BenchmarkRandomPartitioner(
network: NetworkGraph,
program: Program,
*,
window_length: int | None = None,
seed: int | None = None,
)
Bases: BasePartitioner
Partition qubits into static, randomly initialized assignments.
Initialize the benchmark random partitioner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
NetworkGraph
|
Network graph describing available resources. |
required |
program
|
Program
|
Parsed OpenQASM 3 program. |
required |
window_length
|
int | None
|
Number of two-qubit gates per window. |
None
|
seed
|
int | None
|
Optional RNG seed for reproducible random initialization. |
None
|
Source code in src/memq_dqc/partition/benchmark_random/benchmark_random.py
run
¶
Run the benchmark random partitioning algorithm.
Updates
cost, schedule, and windows with the latest partitioning results.
Source code in src/memq_dqc/partition/benchmark_random/benchmark_random.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 | |
BenchmarkStaticPartitioner
¶
BenchmarkStaticPartitioner(
network: NetworkGraph,
program: Program,
*,
window_length: int | None = None,
seed: int | None = None,
)
Bases: BasePartitioner
Partition qubits into static, capacity-bounded QPU assignments.
Initialize the benchmark static partitioner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
NetworkGraph
|
Network graph describing available resources. |
required |
program
|
Program
|
Parsed OpenQASM 3 program. |
required |
window_length
|
int | None
|
Number of two-qubit gates per window. |
None
|
seed
|
int | None
|
Optional seed, recorded but unused by this deterministic algorithm. |
None
|
Source code in src/memq_dqc/partition/benchmark_static/benchmark_static.py
run
¶
Run the benchmark static partitioning algorithm.
Updates
cost, schedule, and windows with the latest partitioning results.
Source code in src/memq_dqc/partition/benchmark_static/benchmark_static.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 | |
HypergraphPartitioner
¶
HypergraphPartitioner(
network: NetworkGraph,
program: Program,
*,
config_path: str | PathLike[str] | None = None,
epsilon: float = 0.03,
max_group_size: int | None = None,
window_length: int | None = None,
respect_qpu_capacities: bool = True,
seed: int | None = None,
)
Bases: BasePartitioner
Partition qubits once using a grouped-gate hypergraph.
Initialize the hypergraph partitioner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
NetworkGraph
|
Network graph describing available resources. |
required |
program
|
Program
|
Parsed OpenQASM 3 program. |
required |
config_path
|
str | PathLike[str] | None
|
Optional KahyPar INI configuration path. When omitted, the packaged hypergraph configuration is used. |
None
|
epsilon
|
float
|
Allowed KahyPar partition imbalance. |
0.03
|
max_group_size
|
int | None
|
Optional maximum two-qubit gates per group. |
None
|
window_length
|
int | None
|
Optional window length used only to adapt the static assignment to the existing schedule interface. |
None
|
respect_qpu_capacities
|
bool
|
When True, the real per-QPU computation
capacities are passed to KahyPar as custom target block
weights so it respects non-uniform, fully-packed networks.
Set False to reproduce the prior behavior where KahyPar
balances uniformly using only |
True
|
seed
|
int | None
|
Optional KahyPar random seed. When omitted, the seed from the INI configuration is used. |
None
|
Source code in src/memq_dqc/partition/hypergraph/hypergraph.py
run
¶
Run grouped-gate hypergraph partitioning.
Updates
cost, schedule, and windows with the latest partitioning results.
Source code in src/memq_dqc/partition/hypergraph/hypergraph.py
InteractionPartitioner
¶
InteractionPartitioner(
network: NetworkGraph,
program: Program,
*,
window_length: int | None = None,
seed: int | None = None,
)
Bases: BasePartitioner
Partition qubits using the Interaction (TODO: cite) algorithm.
Initialize the Interaction partitioner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
NetworkGraph
|
Network graph describing available resources. |
required |
program
|
Program
|
Parsed OpenQASM 3 program. |
required |
window_length
|
int | None
|
Number of two-qubit gates per window. |
None
|
seed
|
int | None
|
Optional seed for the randomized initial partitioning. When omitted the historical default seed is used, preserving prior behavior. |
None
|
Source code in src/memq_dqc/partition/interaction/interaction.py
run
¶
Run the Interaction partitioning algorithm.
Updates
cost, schedule, and windows with the latest partitioning results.
Source code in src/memq_dqc/partition/interaction/interaction.py
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 | |
InteractionStaticPartitioner
¶
InteractionStaticPartitioner(
network: NetworkGraph,
program: Program,
*,
window_length: int | None = None,
)
Bases: BasePartitioner
Partition qubits once using the whole-circuit interaction graph.
Initialize the static interaction partitioner.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
NetworkGraph
|
Network graph describing available resources. |
required |
program
|
Program
|
Parsed OpenQASM 3 program. |
required |
window_length
|
int | None
|
Number of two-qubit gates per reporting window. |
None
|
Source code in src/memq_dqc/partition/interaction_static/interaction_static.py
run
¶
Run static whole-circuit interaction partitioning.
Updates
cost, schedule, and windows with the latest partitioning results.
Source code in src/memq_dqc/partition/interaction_static/interaction_static.py
62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 | |
BasePartitioner
¶
BasePartitioner(
network: NetworkGraph,
program: Program,
*,
seed: int | None = None,
)
Bases: ABC
Base class for partitioning algorithm implementations.
Initialize the partitioner with circuit and network inputs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
NetworkGraph
|
Network graph describing available resources. |
required |
program
|
Program
|
Parsed OpenQASM 3 program. |
required |
seed
|
int | None
|
Optional seed for algorithms with random components. Deterministic algorithms record it but may ignore it. |
None
|
Source code in src/memq_dqc/partition/partitioner.py
cost
property
writable
¶
Return the latest entanglement cost, if available.
When a schedule and windowing are available, cost is derived from the total routed e-bit usage implied by remote gates and inter-window qubit movement.
run
abstractmethod
¶
Run the partitioning algorithm.
Updates
cost, schedule, and windows with the latest partitioning results.
Partitioner
¶
Partitioner(
network: NetworkInput | ProgramInput,
program: ProgramInput | NetworkInput,
*,
algo: str
| type[_Algorithm]
| _Algorithm = "interaction",
algo_kwargs: dict[str, Any] | None = None,
)
Orchestrate a partitioning algorithm implementation.
Initialize the partitioner and select the algorithm.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
NetworkInput | ProgramInput
|
Network graph or parsed OpenQASM 3 program, or a path to either input type. When both positional inputs are file paths or in-memory objects, the constructor infers which one is the network and which one is the program. |
required |
program
|
ProgramInput | NetworkInput
|
Parsed OpenQASM 3 program or network graph, or a path to either input type. When both positional inputs are file paths or in-memory objects, the constructor infers which one is the network and which one is the program. |
required |
algo
|
str | type[_Algorithm] | _Algorithm
|
Algorithm name, class, or preconfigured instance. |
'interaction'
|
algo_kwargs
|
dict[str, Any] | None
|
Keyword arguments forwarded to the algorithm. |
None
|
Source code in src/memq_dqc/partition/partitioner.py
cost
property
¶
Return the exact entanglement cost, if available.
The true e-bit usage is only known once the distributed circuit has been extracted, because that is where routing, link selection, and state-teleportation swaps are actually resolved. This property therefore extracts the distributed circuit on first access rather than reporting the cheaper partition-time approximation, so the reported cost does not depend on whether the caller happened to touch the distributed circuit first.
If the distributed circuit cannot be extracted at all -- for example on a network whose computation qubits cannot reach any communication qubit -- there is no measured cost to report, so the partition-time approximation is returned and a warning is logged.
schedule
property
¶
schedule: PartitionSchedule | None
Return the latest partition schedule, if available.
windows
property
¶
windows: PartitionWindows | None
Return the latest operation windows, if available.
distributed_circuit
property
¶
distributed_circuit: DistributedCircuit
Return the distributed circuit, extracting it on first access.
Raises:
| Type | Description |
|---|---|
ValueError
|
If partitioning has not been run yet. |
RuntimeError
|
If extraction does not populate the circuit. |
distributed_program
property
¶
Return the distributed OpenQASM program for this partitioner.
distributed_qasm
property
¶
Return the distributed circuit as OpenQASM 3 source text.
Extracts the distributed circuit on first access if needed.
run
¶
run(
*,
ebit_assignment: bool | None = None,
group_gates: bool = True,
max_group_size: int | None = None,
group_size_profile: SchedulerHardwareProfile
| None = None,
verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> None
Run the configured partitioning algorithm.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ebit_assignment
|
bool | None
|
Whether to also extract the distributed circuit during this call, and if so whether the compiler assigns concrete e-bit pairs into the scheduler DAG. When omitted, this method only runs partitioning and lazy extraction defaults to explicit e-bit assignment. |
None
|
group_gates
|
bool
|
Whether distributed extraction should keep compatible remote gate groups inside a shared cat-entanglement region. |
True
|
max_group_size
|
int | None
|
Optional maximum number of two-qubit gates per emitted gate group. |
None
|
group_size_profile
|
SchedulerHardwareProfile | None
|
Scheduler hardware profile whose timing bounds each gate group's duration to the EPR lifetime. When omitted the EPR-lifetime cap is disabled. |
None
|
verbosity
|
Literal['quiet', 'info', 'debug']
|
Logging verbosity for this workflow call. |
'quiet'
|
Updates
cost, schedule, and windows with the latest partitioning results.
Source code in src/memq_dqc/partition/partitioner.py
save_distributed_circuit
¶
Write the distributed circuit to an OpenQASM 3 file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | PathLike[str]
|
Destination file path. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The path the circuit was written to. |
Source code in src/memq_dqc/partition/partitioner.py
annotated_dag
¶
Build an annotated distributed-DAG graph for the circuit.
Opt-in export; compilation never builds this automatically. A fresh graph is constructed on each call. Extracts the distributed circuit on first access if needed.
Returns:
| Type | Description |
|---|---|
DiGraph
|
An annotated |
Source code in src/memq_dqc/partition/partitioner.py
to_dag_json
¶
Serialize the annotated distributed DAG to a JSON document.
Opt-in export; compilation never serializes automatically. See memq_dqc.circuit.dag.annotated_dag_to_json for the document layout. Extracts the distributed circuit on first access if needed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | PathLike[str] | None
|
Optional destination file. When given, the JSON document is written there in addition to being returned. |
None
|
indent
|
int | None
|
Indentation forwarded to the underlying serializer. Pass
|
2
|
Returns:
| Type | Description |
|---|---|
str
|
The JSON document as a string. |
Source code in src/memq_dqc/partition/partitioner.py
verify
¶
verify(
*,
shots: int = 50000000,
fidelity_threshold: float = 0.9,
verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> bool
Verify that the distributed circuit matches the original circuit.
Treats the distributed circuit as a single monolithic circuit in which remote operations act perfectly, then compares its measurement distribution against the original (pre-partition) circuit via Hellinger fidelity. The original circuit is taken from this partitioner, so it does not need to be supplied again. Extracts the distributed circuit on first access if needed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shots
|
int
|
Number of shots to execute each circuit for. |
50000000
|
fidelity_threshold
|
float
|
Minimum Hellinger fidelity required for the distributed circuit to be considered correct. |
0.9
|
verbosity
|
Literal['quiet', 'info', 'debug']
|
Logging verbosity for this workflow call. |
'quiet'
|
Returns:
| Type | Description |
|---|---|
bool
|
True if the distributed circuit reproduces the original circuit's |
bool
|
output distribution within the fidelity threshold, False otherwise. |