memq_dqc.network¶
network
¶
Network graph data structures, loaders, generators, and config helpers.
CanonicalNetworkConfigBuilder
dataclass
¶
CanonicalNetworkConfigBuilder(
version: str = "1.0",
units: JsonObject = (
lambda: deepcopy(DEFAULT_CANONICAL_NETWORK_UNITS)
)(),
metadata: JsonObject = dict(),
initial_state: JsonObject = dict(),
simulation: JsonObject = dict(),
mapping_hints: JsonObject = dict(),
)
Builder for canonical quantum network JSON configurations.
add_object
¶
add_object(
section: str, obj: dict[str, Any]
) -> CanonicalNetworkConfigBuilder
Add an object to one of the canonical list sections.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
section
|
str
|
Canonical top-level list section name. |
required |
obj
|
dict[str, Any]
|
Object to add to the section. |
required |
Returns:
| Type | Description |
|---|---|
CanonicalNetworkConfigBuilder
|
The builder instance for chaining. |
Raises:
| Type | Description |
|---|---|
CanonicalNetworkConfigError
|
If the section name is unsupported. |
Source code in src/memq_dqc/network/canonical_config.py
add_node
¶
add_node(
*,
id: str,
type: str,
label: str | None = None,
role: str | None = None,
position: dict[str, Any] | None = None,
ports: list[dict[str, Any]] | None = None,
memory_ids: list[str] | None = None,
processor_ids: list[str] | None = None,
parameters: dict[str, Any] | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a node definition.
Source code in src/memq_dqc/network/canonical_config.py
add_channel
¶
add_channel(
*,
id: str,
type: str,
channel_type: str,
source: str,
target: str,
bidirectional: bool | None = None,
parameters: dict[str, Any] | None = None,
noise_model_id: str | None = None,
delay_model: dict[str, Any] | None = None,
loss_model: dict[str, Any] | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a channel definition.
Source code in src/memq_dqc/network/canonical_config.py
add_link
¶
add_link(
*,
id: str,
type: str,
channel_ids: list[str] | None = None,
node_ids: list[str] | None = None,
parameters: dict[str, Any] | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a logical link definition.
Source code in src/memq_dqc/network/canonical_config.py
add_memory
¶
add_memory(
*,
id: str,
type: str,
node_id: str,
parameters: dict[str, Any] | None = None,
noise_model_id: str | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a quantum memory definition.
Source code in src/memq_dqc/network/canonical_config.py
add_processor
¶
add_processor(
*,
id: str,
type: str,
node_id: str,
parameters: dict[str, Any] | None = None,
noise_model_id: str | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a processor definition.
Source code in src/memq_dqc/network/canonical_config.py
add_noise_model
¶
add_noise_model(
*,
id: str,
type: str,
parameters: dict[str, Any] | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a reusable noise model definition.
Source code in src/memq_dqc/network/canonical_config.py
add_protocol
¶
add_protocol(
*,
id: str,
type: str,
participants: list[str] | None = None,
trigger: JsonValue | None = None,
requirements: JsonValue | None = None,
parameters: dict[str, Any] | None = None,
success_conditions: JsonValue | None = None,
failure_policy: JsonValue | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a protocol definition.
Source code in src/memq_dqc/network/canonical_config.py
add_constraint
¶
add_constraint(
*,
id: str,
type: str,
parameters: dict[str, Any] | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add a constraint definition.
Source code in src/memq_dqc/network/canonical_config.py
add_observable
¶
add_observable(
*,
id: str,
type: str,
parameters: dict[str, Any] | None = None,
custom: JsonValue | None = None,
) -> CanonicalNetworkConfigBuilder
Add an observable definition.
Source code in src/memq_dqc/network/canonical_config.py
set_initial_state
¶
set_initial_state(
initial_state: dict[str, Any],
) -> CanonicalNetworkConfigBuilder
Set initial network state assumptions.
Source code in src/memq_dqc/network/canonical_config.py
set_simulation
¶
set_simulation(
simulation: dict[str, Any],
) -> CanonicalNetworkConfigBuilder
Set simulation settings.
Source code in src/memq_dqc/network/canonical_config.py
set_mapping_hints
¶
set_mapping_hints(
mapping_hints: dict[str, Any],
) -> CanonicalNetworkConfigBuilder
Set mapping hints for downstream translators.
Source code in src/memq_dqc/network/canonical_config.py
to_definition
¶
Return the builder state as a plain definition dictionary.
Source code in src/memq_dqc/network/canonical_config.py
build
¶
dumps
¶
Serialize the current configuration to deterministic JSON.
write
¶
Write the current configuration to disk.
Source code in src/memq_dqc/network/canonical_config.py
CanonicalNetworkConfigError
¶
Bases: ValueError
Raised when a canonical network configuration is invalid.
NetworkGraph
¶
Represents a quantum network constructed from a JSON specification.
This class parses a network description JSON file and builds a
networkx.Graph instance whose nodes represent qubits and whose
edges represent local and remote connections between those qubits.
The resulting graph and associated metadata can be accessed via
the graph and qubit_type_map properties and are used to
derive summary information such as qubit counts per QPU.
Initialize a NetworkGraph from a JSON specification file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network_json_filename
|
str
|
The filename of the network specification JSON file. |
required |
Source code in src/memq_dqc/network/network_graph.py
qubit_type_map
property
¶
qubit_type_map: dict[PhysicalQubit, str]
Return the mapping of qubit IDs to their types.
num_comp_qubits
property
¶
Return the number of computation qubits in the network.
num_comm_qubits
property
¶
Return the number of communication qubits in the network.
local_swap_dict
property
¶
local_swap_dict: dict[
PhysicalQubit, tuple[float, list[PhysicalQubit]]
]
Return map from comp qubits to swaps toward nearest comm qubit.
is_homogeneous
property
¶
Return True if all QPUs have identical comp and comm qubit counts.
Returns:
| Type | Description |
|---|---|
bool
|
True when computation and communication qubit counts match across |
bool
|
all QPUs. |
computation_qubits
¶
computation_qubits() -> list[PhysicalQubit]
Return all computation qubit nodes in deterministic order.
Source code in src/memq_dqc/network/network_graph.py
communication_qubits
¶
communication_qubits() -> list[PhysicalQubit]
Return all communication qubit nodes in deterministic order.
Source code in src/memq_dqc/network/network_graph.py
comp_qubits_per_qpu
¶
Return the number of computation qubits for each QPU.
Returns:
| Type | Description |
|---|---|
list[int]
|
Counts of computation qubits per QPU, ordered by processor ID. |
Source code in src/memq_dqc/network/network_graph.py
comm_qubits_per_qpu
¶
Return the number of communication qubits for each QPU.
Returns:
| Type | Description |
|---|---|
list[int]
|
Counts of communication qubits per QPU, ordered by processor ID. |
Source code in src/memq_dqc/network/network_graph.py
qpu_ids
¶
Return the QPU IDs ordered to match the per-QPU count helpers.
The ordering is identical to comp_qubits_per_qpu and
comm_qubits_per_qpu (sorted numerically by processor ID), so a
positional index into any of those lists refers to the QPU ID at the
same position here. Unlike deriving IDs from the qubit set, this
includes every declared processor even one with no qubits, keeping
the index-to-QPU mapping stable.
Returns:
| Type | Description |
|---|---|
list[int]
|
QPU IDs ordered by processor ID. |
Source code in src/memq_dqc/network/network_graph.py
get_comm_pair_options
¶
get_comm_pair_options(
qubit_a: PhysicalQubit, qubit_b: PhysicalQubit
) -> list[
tuple[
int,
tuple[PhysicalQubit, PhysicalQubit],
tuple[list[PhysicalQubit], list[PhysicalQubit]],
]
]
Return reachable communication-pair options sorted by cost.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qubit_a
|
PhysicalQubit
|
The first computation qubit. |
required |
qubit_b
|
PhysicalQubit
|
The second computation qubit. |
required |
Returns:
| Type | Description |
|---|---|
list[tuple[int, tuple[PhysicalQubit, PhysicalQubit], tuple[list[PhysicalQubit], list[PhysicalQubit]]]]
|
Ranked communication-pair options sorted by increasing cost and |
list[tuple[int, tuple[PhysicalQubit, PhysicalQubit], tuple[list[PhysicalQubit], list[PhysicalQubit]]]]
|
deterministic label tie-breakers. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no valid communication pairs exist or no pair is reachable via local paths. |
Source code in src/memq_dqc/network/network_graph.py
get_qpu_route
¶
Return a directional QPU route for a routed remote gate.
The route moves the source operand through rswap hops until it is
on a QPU adjacent to the target operand. Internal hops must support
rswap (2 e-bit pairs), while the final hop to the target side
must support a remote gate (1 e-bit pair).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source_qpu_id
|
int
|
QPU ID of the operand selected to move. |
required |
target_qpu_id
|
int
|
QPU ID of the operand kept in place. |
required |
Returns:
| Type | Description |
|---|---|
list[int]
|
Ordered QPU IDs from source to target. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no directional route is available. |
Source code in src/memq_dqc/network/network_graph.py
remote_gate_ebit_cost
¶
Return minimum raw e-bit pairs for a remote gate between two QPUs.
The gate itself costs one e-bit pair. Reaching an adjacent QPU first
costs a remote swap per intermediary, and a remote swap is two pairs,
so a route through k intermediaries costs 1 + 2k.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qpu_a
|
int
|
First QPU ID. |
required |
qpu_b
|
int
|
Second QPU ID. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Minimum required e-bit pairs. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no routed remote-gate path is available. |
Source code in src/memq_dqc/network/network_graph.py
remote_swap_ebit_cost
¶
Return routed swap cost between two QPUs.
Every remote swap costs two e-bit pairs, and a route of h hops
lowers to h adjacent remote swaps, so the cost is 2h. A swap
onto a directly linked QPU is one hop and costs 2; a swap onto a QPU
one further along the chain is two hops and costs 4.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qpu_a
|
int
|
First QPU ID. |
required |
qpu_b
|
int
|
Second QPU ID. |
required |
Returns:
| Type | Description |
|---|---|
int
|
Routed swap cost in e-bit pairs. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If no swap-capable QPU route is available. |
Source code in src/memq_dqc/network/network_graph.py
supports_remote_swap
¶
Return whether two QPUs can perform a direct remote swap.
A remote swap teleports both states, so it needs two disjoint communication pairs on a direct link between the two QPUs. A False result rules out a single remote swap only; the two QPUs may still be swappable as a routed chain of adjacent remote swaps, which remote_swap_ebit_cost prices and rejects when unroutable.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qpu_a
|
int
|
First QPU ID. |
required |
qpu_b
|
int
|
Second QPU ID. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True when a direct remote swap is possible. |
Source code in src/memq_dqc/network/network_graph.py
display
¶
Display the network graph using Matplotlib.
Source code in src/memq_dqc/network/network_graph.py
PhysicalQubit
dataclass
¶
Structured identifier for a qubit in a network graph.
build_canonical_network_config
¶
Normalize and validate a canonical network configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
definition
|
dict[str, Any]
|
In-memory network definition to normalize into the canonical JSON structure. |
required |
Returns:
| Type | Description |
|---|---|
JsonObject
|
A validated configuration dictionary with deterministic section |
JsonObject
|
ordering and defaulted top-level sections. |
Raises:
| Type | Description |
|---|---|
CanonicalNetworkConfigError
|
If the definition has invalid structure, unsupported JSON values, or broken cross-references. |
Source code in src/memq_dqc/network/canonical_config.py
dumps_canonical_network_config
¶
Return deterministic JSON for a canonical network configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
definition
|
dict[str, Any]
|
In-memory network definition or already normalized config. |
required |
indent
|
int
|
Number of spaces used for indentation. |
2
|
Returns:
| Type | Description |
|---|---|
str
|
Deterministic JSON with sorted keys. |
Source code in src/memq_dqc/network/canonical_config.py
validate_canonical_network_config
¶
Validate a canonical network configuration in-place.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
dict[str, Any]
|
Canonical network configuration to validate. |
required |
Raises:
| Type | Description |
|---|---|
CanonicalNetworkConfigError
|
If the configuration is invalid. |
Source code in src/memq_dqc/network/canonical_config.py
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 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 | |
write_canonical_network_config
¶
write_canonical_network_config(
definition: dict[str, Any],
output_path: str | Path,
*,
indent: int = 2,
) -> Path
Write a canonical network configuration to disk.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
definition
|
dict[str, Any]
|
In-memory network definition to serialize. |
required |
output_path
|
str | Path
|
Destination file path. |
required |
indent
|
int
|
Number of spaces used for indentation. |
2
|
Returns:
| Type | Description |
|---|---|
Path
|
The resolved path written to disk. |
Source code in src/memq_dqc/network/canonical_config.py
generate_network
¶
generate_network(
num_qpus: int,
computation_qubits_per_qpu: int,
arrangement: QpuArrangement
| Sequence[tuple[int, int]] = "chain",
*,
intra_qpu: IntraQpuConnectivity = "nearest_neighbor",
links_per_pair: int = 2,
coherence_time: float = 100.0,
) -> dict[str, Any]
Generate a network topology with identically sized QPUs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
num_qpus
|
int
|
Number of QPUs, with ids |
required |
computation_qubits_per_qpu
|
int
|
Computation (data) qubits on every QPU. |
required |
arrangement
|
QpuArrangement | Sequence[tuple[int, int]]
|
How the QPUs are linked. |
'chain'
|
intra_qpu
|
IntraQpuConnectivity
|
Coupling between qubits inside each QPU, either
|
'nearest_neighbor'
|
links_per_pair
|
int
|
Remote links between each pair of linked QPUs. Use at least 2 so qubits can be teleported across a link, which routing between QPUs that are not directly linked requires. |
2
|
coherence_time
|
float
|
Coherence time recorded on every qubit, in microseconds. No current algorithm reads it. |
100.0
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The network as a JSON-serializable dictionary, in the format |
dict[str, Any]
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If a count is below 1, the arrangement is unknown or needs more QPUs, or the QPU links reference unknown QPUs, contain a self-link, or leave a QPU unreachable. |
Source code in src/memq_dqc/network/generation.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 169 170 171 172 173 174 175 176 177 178 | |
validate_network
¶
Check that a network topology is structurally sound.
Checks that:
- every QPU in
processorsis keyed by its numericid; - every qubit has a valid
typeand belongs to exactly one QPU, the one itsprocessorIdnames; - local connections join qubits on the same QPU;
- remote connections join communication qubits on different QPUs;
- every connection references a known qubit and is listed on both ends.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
network
|
Mapping[str, Any]
|
The parsed network JSON. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the network is malformed. The message lists every problem found. |