memq_dqc¶
memq_dqc
¶
Public package interface for memq_dqc.
This module exposes the core workflow objects and configuration types
needed for distributed quantum compilation. The recommended entry point is
Compiler (compile -> verify) together with Scheduler; Compiler
wraps the lower-level Partitioner, which stays available for callers who
want direct control over partitioning. Supporting helpers remain importable
from their own subpackages (e.g. memq_dqc.network, memq_dqc.verify).
Compiler
¶
Compiler(
circuit: ProgramInput,
topology: NetworkInput,
algo: str
| type[BasePartitioner]
| BasePartitioner = "interaction",
*,
algo_kwargs: dict[str, Any] | None = None,
)
Compile a circuit for a distributed quantum network.
This is the recommended entry point for end users. Construct it with a circuit and a network topology, then call compile; the distributed circuit and its derived artifacts are then available as properties. Under the hood it drives a Partitioner, which can also be used directly for finer control over partitioning.
Initialize the compiler.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
ProgramInput
|
The input circuit, as a parsed OpenQASM 3 program, a path
to a |
required |
topology
|
NetworkInput
|
The network topology, as a |
required |
algo
|
str | type[BasePartitioner] | BasePartitioner
|
Partitioning 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/compiler.py
partitioner
property
¶
partitioner: Partitioner
Return the underlying partitioner driving this compiler.
distributed_circuit
property
¶
distributed_circuit: DistributedCircuit
Return the distributed circuit, extracting it on first access.
Raises:
| Type | Description |
|---|---|
ValueError
|
If the circuit has not been compiled yet. |
RuntimeError
|
If extraction does not populate the circuit. |
distributed_program
property
¶
Return the distributed OpenQASM program.
distributed_qasm
property
¶
Return the distributed circuit as OpenQASM 3 source text.
compile
¶
compile(
*,
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
Compile the circuit for the configured network.
Runs partitioning and reconstructs the distributed circuit. After this call, distributed_circuit, distributed_qasm, and the other result properties are available.
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, partitioning runs and extraction is deferred until the distributed circuit is first accessed. |
None
|
group_gates
|
bool
|
Whether to 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'
|
Source code in src/memq_dqc/compiler.py
save_distributed_circuit
¶
Write the distributed circuit to an OpenQASM 3 file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Destination file path. |
required |
Returns:
| Type | Description |
|---|---|
Path
|
The path the circuit was written to. |
Source code in src/memq_dqc/compiler.py
annotated_dag
¶
Return the compiled program as an annotated distributed DAG.
Opt-in export; compiling never builds this automatically. A fresh
annotated networkx.DiGraph is constructed on each call. See
memq_dqc.circuit.dag.build_annotated_dag for the node and edge
attributes.
Returns:
| Type | Description |
|---|---|
DiGraph
|
An annotated |
Source code in src/memq_dqc/compiler.py
to_dag_json
¶
Serialize the annotated distributed DAG to a JSON document.
Opt-in export; compiling never serializes automatically. See memq_dqc.circuit.dag.annotated_dag_to_json for the document layout.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path | 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/compiler.py
get_verification_artifacts
¶
get_verification_artifacts() -> VerificationArtifacts
Return original and distributed circuit verification inputs.
The returned OpenQASM programs can be passed directly to memq_dqc.verify.verify_distributed_circuit. The DAGs are independent NetworkX graph objects suitable for structural checks.
Returns:
| Type | Description |
|---|---|
VerificationArtifacts
|
Original and distributed OpenQASM programs, source strings, and |
VerificationArtifacts
|
DAGs. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the circuit has not been compiled yet. |
Source code in src/memq_dqc/compiler.py
verify
¶
verify(
*,
shots: int = 50000000,
fidelity_threshold: float = 0.9,
verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> bool
Verify the distributed circuit against the original circuit.
See memq_dqc.partition.Partitioner.verify for details.
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. |
Source code in src/memq_dqc/compiler.py
to_scheduling_instance
¶
to_scheduling_instance(
*,
hardware_profile: SchedulerHardwareProfile
| None = None,
) -> SchedulingInstance
Build a scheduling instance from the existing distributed result.
Opt-in export for external RL schedulers. Uses the already-compiled distributed circuit (extracting it on first access if compilation has occurred) and does not rerun partitioning. Compile the circuit first.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
hardware_profile
|
SchedulerHardwareProfile | None
|
Scheduler hardware profile whose timings set the
deterministic operation durations. |
None
|
Returns:
| Type | Description |
|---|---|
SchedulingInstance
|
A validated SchedulingInstance. |
Source code in src/memq_dqc/compiler.py
recompile_with_placement
¶
recompile_with_placement(
schedule: PartitionSchedule,
windows: PartitionWindows | None = None,
*,
hardware_profile: SchedulerHardwareProfile
| None = None,
) -> SchedulingInstance
Re-derive the distributed circuit and scheduling instance.
Injects a caller-supplied placement and rebuilds the scheduling
instance from it, reusing the parsed program, monolithic DAG, and
(unless overridden) the windows from the prior compile; only the
placement -> distributed derivation re-runs. Partitioning is not
re-run, so the compiler must already have produced windows (call
compile first) or windows must be supplied explicitly.
The existing distributed flags held on the partitioner
(ebit_assignment, group_gates, max_group_size) are
preserved. The injected placement is folded into the resulting
instance's source_fingerprint so distinct placements never collide.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
schedule
|
PartitionSchedule
|
Per-window placement mapping each QPU to the set of logical qubit indices assigned to it. |
required |
windows
|
PartitionWindows | None
|
Optional replacement operation windows. When omitted, the windows from the prior compile are reused. |
None
|
hardware_profile
|
SchedulerHardwareProfile | None
|
Scheduler hardware profile whose timings set the
deterministic operation durations. |
None
|
Returns:
| Type | Description |
|---|---|
SchedulingInstance
|
A validated SchedulingInstance |
SchedulingInstance
|
derived from the injected placement. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the placement is missing windows, its schedule and windows differ in length, a window is not a partition of the circuit's logical qubits, per-QPU counts differ across windows, or a QPU id or qubit index is out of range for the network. |
Source code in src/memq_dqc/compiler.py
VerificationArtifacts
dataclass
¶
VerificationArtifacts(
original_program: Program,
original_qasm: str,
original_dag: DiGraph,
distributed_program: Program,
distributed_qasm: str,
distributed_dag: DiGraph,
)
Represent both circuits needed for equivalence verification.
Attributes:
| Name | Type | Description |
|---|---|---|
original_program |
Program
|
Parsed original OpenQASM program. |
original_qasm |
str
|
Original circuit serialized as OpenQASM source. |
original_dag |
DiGraph
|
Original circuit dependency graph. |
distributed_program |
Program
|
Parsed distributed OpenQASM program. |
distributed_qasm |
str
|
Distributed circuit serialized as OpenQASM source. |
distributed_dag |
DiGraph
|
Annotated distributed circuit dependency graph. |
SchedulingCompileRequest
dataclass
¶
SchedulingCompileRequest(
request_id: str,
circuit: ProgramInput,
topology: NetworkInput,
options: SchedulingCompileOptions | None = None,
)
One batch compilation request.
Attributes:
| Name | Type | Description |
|---|---|---|
request_id |
str
|
Caller-chosen identifier echoed back in the result. |
circuit |
ProgramInput
|
The input circuit (parsed program, path, or inline source).
Use a file path when compiling with |
topology |
NetworkInput
|
The network topology ( |
options |
SchedulingCompileOptions | None
|
Compilation options; |
SchedulingCompileResult
dataclass
¶
SchedulingCompileResult(
request_id: str,
instance: SchedulingInstance | None,
cache_hit: bool,
elapsed_seconds: float,
error: str | None,
)
The outcome of one batch compilation request.
Attributes:
| Name | Type | Description |
|---|---|---|
request_id |
str
|
Identifier of the originating request. |
instance |
SchedulingInstance | None
|
The compiled instance, or |
cache_hit |
bool
|
Whether the instance was loaded from the cache. |
elapsed_seconds |
float
|
Wall-clock time spent on this request. |
error |
str | None
|
A |
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. |
Source code in src/memq_dqc/partition/partitioner.py
Scheduler
¶
Scheduler(
source: Compiler | Partitioner | DistributedCircuit,
*,
algo: str | type[_Algorithm] | _Algorithm = "fifo",
profile: SchedulerHardwareProfile | None = None,
modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
multiplex_entangle: bool = True,
algo_kwargs: dict[str, Any] | None = None,
)
Orchestrate a scheduling algorithm implementation.
Initialize the scheduler and select the algorithm.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
Compiler | Partitioner | DistributedCircuit
|
What to schedule. A |
required |
algo
|
str | type[_Algorithm] | _Algorithm
|
Algorithm name, class, or preconfigured instance. |
'fifo'
|
profile
|
SchedulerHardwareProfile | None
|
Optional convenience object selecting both modality and
entanglement profile. When provided, |
None
|
modality
|
SchedulerModality
|
Hardware timing profile used for local 1Q/2Q gate
durations. Defaults to |
DEFAULT_SCHEDULER_MODALITY
|
entanglement_profile
|
SchedulerEntanglementProfile
|
Entanglement-generation profile used for
entanglement timing. Defaults to |
DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
|
multiplex_entangle
|
bool
|
Whether entanglement generation may overlap across independent communication resources. |
True
|
algo_kwargs
|
dict[str, Any] | None
|
Keyword arguments forwarded to the algorithm. |
None
|
Source code in src/memq_dqc/scheduler/schedule.py
distributed_circuit
property
¶
distributed_circuit: DistributedCircuit
Return the distributed circuit used by the scheduler.
schedule
property
¶
schedule: OperationSchedule | None
Return the latest operation schedule, if available.
run
¶
Run the configured scheduling algorithm.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verbosity
|
Literal['quiet', 'info', 'debug']
|
Logging verbosity for this workflow call. |
'quiet'
|
Source code in src/memq_dqc/scheduler/schedule.py
plot_gantt
¶
plot_gantt(
*,
ax: Axes | None = None,
title: str | None = None,
display: Literal["pretty", "legacy"] = "pretty",
explicit_ops: bool = False,
show: bool = False,
save_path: str | PathLike[str] | None = None,
dpi: int = 150,
) -> Axes
Render this scheduler's result as a Gantt chart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ax
|
Axes | None
|
Existing axes to draw into. A new figure and axes are created when omitted. |
None
|
title
|
str | None
|
Optional chart title (ignored in |
None
|
display
|
Literal['pretty', 'legacy']
|
Which rendering to produce. |
'pretty'
|
explicit_ops
|
bool
|
Whether to render one row per scheduled event instead of one row per physical qubit. |
False
|
show
|
bool
|
Whether to call |
False
|
save_path
|
str | PathLike[str] | None
|
Optional file path. When given, the rendered figure is saved there. |
None
|
dpi
|
int
|
Resolution used when saving to |
150
|
Returns:
| Type | Description |
|---|---|
Axes
|
The Matplotlib axes containing the rendered schedule. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the scheduler has not produced a schedule yet. |
Source code in src/memq_dqc/scheduler/schedule.py
to_json
¶
Serialize this scheduler's result to a JSON document.
Opt-in export; scheduling never serializes automatically. See memq_dqc.scheduler.serialize.schedule_to_json for the document layout.
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. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the scheduler has not produced a schedule yet. |
Source code in src/memq_dqc/scheduler/schedule.py
SchedulerHardwareProfile
dataclass
¶
SchedulerHardwareProfile(
modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
one_qubit_gate_time: float | None = None,
two_qubit_gate_time: float | None = None,
measurement_time: float | None = None,
entanglement_rate: float | None = None,
epr_lifetime: float | None = None,
)
User-facing hardware selection for scheduler timing.
The two selector fields pick a named profile from settings.toml. The
remaining fields are optional per-instance overrides of the individual
hardware parameters that profile resolves to: None keeps the profile's
value, and any other value replaces it. Derived timings (cat-entangling,
cat-disentangling, state teleport, entanglement duration, DES success
probability) always recompute from the effective values, so they cannot
contradict the parameters they are built from.
Example
A Sr+ trapped-ion device with a faster two-qubit gate and a longer EPR lifetime than the packaged profile assumes:
Attributes:
| Name | Type | Description |
|---|---|---|
modality |
SchedulerModality
|
Modality profile used for local gate times. |
entanglement_profile |
SchedulerEntanglementProfile
|
Entanglement-generation profile used for entanglement timing. |
one_qubit_gate_time |
float | None
|
Optional override for the local single-qubit gate duration. |
two_qubit_gate_time |
float | None
|
Optional override for the local two-qubit gate duration. |
measurement_time |
float | None
|
Optional override for the measurement duration. |
entanglement_rate |
float | None
|
Optional override for the entanglement-generation rate. |
epr_lifetime |
float | None
|
Optional override for the maximum EPR-pair lifetime. |
overrides
property
¶
Return the supplied overrides, keyed by field name.
ba_trapped_ion
classmethod
¶
ba_trapped_ion(
*,
entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
one_qubit_gate_time: float | None = None,
two_qubit_gate_time: float | None = None,
measurement_time: float | None = None,
entanglement_rate: float | None = None,
epr_lifetime: float | None = None,
) -> SchedulerHardwareProfile
Return the Ba+ trapped-ion hardware selection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entanglement_profile
|
SchedulerEntanglementProfile
|
Entanglement-generation profile to pair with the modality. |
DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
|
one_qubit_gate_time
|
float | None
|
Optional single-qubit gate duration override. |
None
|
two_qubit_gate_time
|
float | None
|
Optional two-qubit gate duration override. |
None
|
measurement_time
|
float | None
|
Optional measurement duration override. |
None
|
entanglement_rate
|
float | None
|
Optional entanglement-generation rate override. |
None
|
epr_lifetime
|
float | None
|
Optional EPR-pair lifetime override. |
None
|
Returns:
| Type | Description |
|---|---|
SchedulerHardwareProfile
|
The hardware profile. |
Source code in src/memq_dqc/scheduler/schedule.py
sr_trapped_ion
classmethod
¶
sr_trapped_ion(
*,
entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
one_qubit_gate_time: float | None = None,
two_qubit_gate_time: float | None = None,
measurement_time: float | None = None,
entanglement_rate: float | None = None,
epr_lifetime: float | None = None,
) -> SchedulerHardwareProfile
Return the Sr+ trapped-ion hardware selection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entanglement_profile
|
SchedulerEntanglementProfile
|
Entanglement-generation profile to pair with the modality. |
DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
|
one_qubit_gate_time
|
float | None
|
Optional single-qubit gate duration override. |
None
|
two_qubit_gate_time
|
float | None
|
Optional two-qubit gate duration override. |
None
|
measurement_time
|
float | None
|
Optional measurement duration override. |
None
|
entanglement_rate
|
float | None
|
Optional entanglement-generation rate override. |
None
|
epr_lifetime
|
float | None
|
Optional EPR-pair lifetime override. |
None
|
Returns:
| Type | Description |
|---|---|
SchedulerHardwareProfile
|
The hardware profile. |
Source code in src/memq_dqc/scheduler/schedule.py
forte_trapped_ion
classmethod
¶
forte_trapped_ion(
*,
entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
one_qubit_gate_time: float | None = None,
two_qubit_gate_time: float | None = None,
measurement_time: float | None = None,
entanglement_rate: float | None = None,
epr_lifetime: float | None = None,
) -> SchedulerHardwareProfile
Return the IonQ Forte Enterprise 1 trapped-ion hardware selection.
Timings come from the vendor-published calibration record; unlike the other packaged modalities, this profile also supplies its own measurement time rather than falling back to the package default.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entanglement_profile
|
SchedulerEntanglementProfile
|
Entanglement-generation profile to pair with the modality. |
DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
|
one_qubit_gate_time
|
float | None
|
Optional single-qubit gate duration override. |
None
|
two_qubit_gate_time
|
float | None
|
Optional two-qubit gate duration override. |
None
|
measurement_time
|
float | None
|
Optional measurement duration override. |
None
|
entanglement_rate
|
float | None
|
Optional entanglement-generation rate override. |
None
|
epr_lifetime
|
float | None
|
Optional EPR-pair lifetime override. |
None
|
Returns:
| Type | Description |
|---|---|
SchedulerHardwareProfile
|
The hardware profile. |
Source code in src/memq_dqc/scheduler/schedule.py
neutral_atom
classmethod
¶
neutral_atom(
*,
entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
one_qubit_gate_time: float | None = None,
two_qubit_gate_time: float | None = None,
measurement_time: float | None = None,
entanglement_rate: float | None = None,
epr_lifetime: float | None = None,
) -> SchedulerHardwareProfile
Return the neutral-atom hardware selection.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entanglement_profile
|
SchedulerEntanglementProfile
|
Entanglement-generation profile to pair with the modality. |
DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
|
one_qubit_gate_time
|
float | None
|
Optional single-qubit gate duration override. |
None
|
two_qubit_gate_time
|
float | None
|
Optional two-qubit gate duration override. |
None
|
measurement_time
|
float | None
|
Optional measurement duration override. |
None
|
entanglement_rate
|
float | None
|
Optional entanglement-generation rate override. |
None
|
epr_lifetime
|
float | None
|
Optional EPR-pair lifetime override. |
None
|
Returns:
| Type | Description |
|---|---|
SchedulerHardwareProfile
|
The hardware profile. |
Source code in src/memq_dqc/scheduler/schedule.py
SchedulingCompileOptions
dataclass
¶
SchedulingCompileOptions(
partitioner: str = "interaction",
partitioner_kwargs: Mapping[str, Any] | None = None,
partition_seed: int | None = None,
ebit_assignment: bool = True,
group_gates: bool = False,
max_group_size: int | None = None,
hardware_profile: Any | None = None,
)
Options controlling how a scheduling instance is compiled.
For the initial RL corpus the MVP requires ebit_assignment=True and
group_gates=False; the remaining fields are kept general for later
experiments.
Attributes:
| Name | Type | Description |
|---|---|---|
partitioner |
str
|
Registry name of the partitioning algorithm. |
partitioner_kwargs |
Mapping[str, Any] | None
|
Extra keyword arguments forwarded to the
partitioning algorithm, or |
partition_seed |
int | None
|
Optional seed for partitioners with random components. |
ebit_assignment |
bool
|
Whether the compiler assigns concrete e-bit pairs
( |
group_gates |
bool
|
Whether compatible remote gates share a cat-entanglement region. |
max_group_size |
int | None
|
Optional maximum number of two-qubit gates per group. |
hardware_profile |
Any | None
|
Scheduler hardware profile whose timings set the
deterministic operation durations. |
SchedulingInstance
dataclass
¶
SchedulingInstance(
schema_version: int,
instance_id: str,
compiler_version: str,
source_fingerprint: str,
time_unit: str,
operations: tuple[SchedulingOperation, ...],
dependencies: tuple[SchedulingDependency, ...],
resources: tuple[SchedulingResource, ...],
epr_demands: tuple[EPRDemand, ...],
nominal_makespan: float,
metadata: Mapping[str, JSONValue] = dict(),
)
A self-contained scheduling artifact for an external RL scheduler.
Attributes:
| Name | Type | Description |
|---|---|---|
schema_version |
int
|
Scheduling-instance schema version. |
instance_id |
str
|
Deterministic identifier derived from
|
compiler_version |
str
|
memq_dqc version that produced the instance. |
source_fingerprint |
str
|
Hash of the normalized inputs, options, hardware profile, and schema version. |
time_unit |
str
|
Unit for all durations and nominal times. |
operations |
tuple[SchedulingOperation, ...]
|
Distributed operations, ordered by |
dependencies |
tuple[SchedulingDependency, ...]
|
Precedence edges, ordered by |
resources |
tuple[SchedulingResource, ...]
|
Physical resources, ordered by |
epr_demands |
tuple[EPRDemand, ...]
|
Entanglement demands, ordered by |
nominal_makespan |
float
|
Maximum nominal operation end time. |
metadata |
Mapping[str, JSONValue]
|
Reproducibility metadata (partitioner, seed, profile, ...). |
DESSimulationSettings
dataclass
¶
Timing assumptions for DES scheduler simulation.
Attributes:
| Name | Type | Description |
|---|---|---|
entanglement_time_step |
float
|
Duration of one entanglement-attempt cycle. |
EntanglementGenerationProfile
dataclass
¶
EntanglementGenerationProfile(
path: tuple[str, ...],
entanglement_rate: float,
epr_lifetime: float,
)
Entanglement-generation assumptions for one link profile.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
tuple[str, ...]
|
Selector path used to identify the profile. |
entanglement_rate |
float
|
Nominal entanglement generation rate. |
epr_lifetime |
float
|
Maximum lifetime of a generated EPR pair. |
GlobalSettings
dataclass
¶
Optional global settings shared across workflows.
Attributes:
| Name | Type | Description |
|---|---|---|
time_unit |
str | None
|
Optional human-readable time unit label such as |
ModalityProfile
dataclass
¶
ModalityProfile(
path: tuple[str, ...],
one_qubit_gate_time: float,
two_qubit_gate_time: float,
measurement_time: float | None = None,
)
Timing assumptions for one hardware modality profile.
Attributes:
| Name | Type | Description |
|---|---|---|
path |
tuple[str, ...]
|
Selector path used to identify the profile. |
one_qubit_gate_time |
float
|
Duration of a single-qubit gate. |
two_qubit_gate_time |
float
|
Duration of a two-qubit gate. |
measurement_time |
float | None
|
Duration of a measurement (readout). |
Settings
dataclass
¶
Settings(
global_settings: GlobalSettings,
des_simulation: DESSimulationSettings,
modality_profiles: dict[
tuple[str, ...], ModalityProfile
],
entanglement_profiles: dict[
tuple[str, ...], EntanglementGenerationProfile
],
verification: VerificationSettings,
)
Validated settings loaded from TOML.
Attributes:
| Name | Type | Description |
|---|---|---|
global_settings |
GlobalSettings
|
Optional global configuration values. |
des_simulation |
DESSimulationSettings
|
DES scheduler simulation timing settings. |
modality_profiles |
dict[tuple[str, ...], ModalityProfile]
|
Modality timing profiles indexed by selector path. |
entanglement_profiles |
dict[tuple[str, ...], EntanglementGenerationProfile]
|
Entanglement profiles indexed by selector path. |
verification |
VerificationSettings
|
Verification defaults. |
modality_profile
¶
modality_profile(*path: str) -> ModalityProfile
Return one modality profile selected by path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*path
|
str
|
Selector components such as |
()
|
Returns:
| Type | Description |
|---|---|
ModalityProfile
|
The matching modality profile. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the selector is empty or no matching profile exists. |
Source code in src/memq_dqc/settings.py
entanglement_profile
¶
entanglement_profile(
*path: str,
) -> EntanglementGenerationProfile
Return one entanglement-generation profile selected by path.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*path
|
str
|
Selector components such as |
()
|
Returns:
| Type | Description |
|---|---|
EntanglementGenerationProfile
|
The matching entanglement-generation profile. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the selector is empty or no matching profile exists. |
Source code in src/memq_dqc/settings.py
VerificationSettings
dataclass
¶
Verification defaults loaded from TOML.
Attributes:
| Name | Type | Description |
|---|---|---|
shots |
int
|
Number of simulator shots to use by default. |
fidelity_threshold |
float
|
Minimum required fidelity threshold. |
compile_scheduling_instance
¶
compile_scheduling_instance(
circuit: ProgramInput,
topology: NetworkInput,
*,
options: SchedulingCompileOptions | None = None,
verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> SchedulingInstance
Compile a circuit into a self-contained scheduling instance.
High-level entry point for external RL schedulers: partitions, extracts the distributed circuit, and assembles a versioned, JSON-persistable SchedulingInstance (distributed DAG, zero-EPR-wait nominal schedule, physical resources and links, and EPR demands).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
ProgramInput
|
The input circuit, as a parsed OpenQASM 3 program, a path to a
|
required |
topology
|
NetworkInput
|
The network topology, as a |
required |
options
|
SchedulingCompileOptions | None
|
Compilation options. |
None
|
verbosity
|
Literal['quiet', 'info', 'debug']
|
Logging verbosity for this workflow call. |
'quiet'
|
Returns:
| Type | Description |
|---|---|
SchedulingInstance
|
A validated SchedulingInstance. |
Source code in src/memq_dqc/compiler.py
compute_scheduling_source_fingerprint
¶
compute_scheduling_source_fingerprint(
circuit: ProgramInput,
topology: NetworkInput,
options: SchedulingCompileOptions | None = None,
) -> str
Return the source fingerprint for a compile request without compiling.
Parses and normalizes the inputs and hashes them together with the compilation options, hardware profile, and source-normalization schema version. This is the same value compile_scheduling_instance records, enabling a cache lookup before the (much more expensive) compilation runs.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
ProgramInput
|
The input circuit (parsed program, path, or inline source). |
required |
topology
|
NetworkInput
|
The network topology ( |
required |
options
|
SchedulingCompileOptions | None
|
Compilation options; |
None
|
Returns:
| Type | Description |
|---|---|
str
|
A hex SHA-256 digest of the normalized inputs and options. |
Source code in src/memq_dqc/compiler.py
get_verification_artifacts
¶
get_verification_artifacts(
circuit: ProgramInput,
topology: NetworkInput,
*,
options: SchedulingCompileOptions | None = None,
verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> VerificationArtifacts
Compile and return everything needed for circuit equivalence checks.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
ProgramInput
|
The input circuit, as a parsed OpenQASM 3 program, a path to a
|
required |
topology
|
NetworkInput
|
The network topology, as a |
required |
options
|
SchedulingCompileOptions | None
|
Compilation options. |
None
|
verbosity
|
Literal['quiet', 'info', 'debug']
|
Logging verbosity for the compilation workflow. |
'quiet'
|
Returns:
| Type | Description |
|---|---|
VerificationArtifacts
|
Original and distributed OpenQASM programs, source strings, and DAGs. |
Source code in src/memq_dqc/compiler.py
recompile_scheduling_instance
¶
recompile_scheduling_instance(
circuit: ProgramInput,
topology: NetworkInput,
*,
schedule: PartitionSchedule,
windows: PartitionWindows | None = None,
options: SchedulingCompileOptions | None = None,
verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> SchedulingInstance
Compile a circuit and re-derive its instance from an injected placement.
Convenience wrapper mirroring compile_scheduling_instance: it builds
a Compiler, runs a full compile to establish the reusable program,
monolithic DAG, windows, and distributed flags, then re-derives the
scheduling instance from schedule (and windows when provided) via
Compiler.recompile_with_placement.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
ProgramInput
|
The input circuit, as a parsed OpenQASM 3 program, a path to a
|
required |
topology
|
NetworkInput
|
The network topology, as a |
required |
schedule
|
PartitionSchedule
|
Per-window placement mapping each QPU to the set of logical qubit indices assigned to it. |
required |
windows
|
PartitionWindows | None
|
Optional replacement operation windows. When omitted, the windows produced by the initial compile are reused. |
None
|
options
|
SchedulingCompileOptions | None
|
Compilation options. |
None
|
verbosity
|
Literal['quiet', 'info', 'debug']
|
Logging verbosity for this workflow call. |
'quiet'
|
Returns:
| Type | Description |
|---|---|
SchedulingInstance
|
A validated SchedulingInstance |
SchedulingInstance
|
derived from the injected placement. |
Source code in src/memq_dqc/compiler.py
compile_scheduling_batch
¶
compile_scheduling_batch(
requests: Sequence[SchedulingCompileRequest],
*,
workers: int = 1,
cache_dir: str | PathLike[str] | None = None,
fail_fast: bool = False,
) -> tuple[SchedulingCompileResult, ...]
Compile a batch of scheduling-instance requests.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
requests
|
Sequence[SchedulingCompileRequest]
|
Requests to compile. The returned results preserve this order. |
required |
workers
|
int
|
Number of worker processes. |
1
|
cache_dir
|
str | PathLike[str] | None
|
Optional directory for the fingerprint cache. When set,
each artifact is cached by |
None
|
fail_fast
|
bool
|
When |
False
|
Returns:
| Type | Description |
|---|---|
tuple[SchedulingCompileResult, ...]
|
One SchedulingCompileResult per request, in input order. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
RuntimeError
|
If |
Source code in src/memq_dqc/compiler_batch.py
scheduling_instance_from_json
¶
scheduling_instance_from_json(
source: str | PathLike[str] | Mapping[str, Any],
) -> SchedulingInstance
Load and validate a scheduling instance from JSON.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
str | PathLike[str] | Mapping[str, Any]
|
A parsed mapping, a JSON document string, or a path to a JSON
file (as |
required |
Returns:
| Type | Description |
|---|---|
SchedulingInstance
|
The reconstructed, validated SchedulingInstance. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the document type or schema version is unsupported, a number is non-finite, or the reconstructed instance is invalid. |
Source code in src/memq_dqc/scheduler/instance_serialize.py
scheduling_instance_to_json
¶
scheduling_instance_to_json(
instance: SchedulingInstance,
path: str | PathLike[str] | None = None,
*,
indent: int | None = 2,
) -> str
Serialize a scheduling instance to a JSON document.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instance
|
SchedulingInstance
|
The scheduling instance to serialize. |
required |
path
|
str | PathLike[str] | None
|
Optional destination file. When given, the document is written there as UTF-8 text in addition to being returned. |
None
|
indent
|
int | None
|
Indentation forwarded to |
2
|
Returns:
| Type | Description |
|---|---|
str
|
The JSON document as a string. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the instance contains a non-finite number. |
Source code in src/memq_dqc/scheduler/instance_serialize.py
validate_scheduling_instance
¶
validate_scheduling_instance(
instance: SchedulingInstance,
) -> None
Validate the structural and nominal-schedule invariants of an instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
instance
|
SchedulingInstance
|
The scheduling instance to validate. |
required |
Raises:
| Type | Description |
|---|---|
ValueError
|
If any invariant is violated. The message names the offending id(s) and the invariant. |
Source code in src/memq_dqc/scheduler/instance.py
default_settings_path
¶
load_settings_file
¶
load_settings_file(path: str | Path) -> Settings
Load and validate settings from a TOML file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Filesystem path to the TOML file. |
required |
Returns:
| Type | Description |
|---|---|
Settings
|
The validated settings object. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the TOML file is malformed or misses required fields. |