Skip to content

memq_dqc.scheduler

scheduler

Public scheduler interface for distributed circuit execution planning.

DESLinkCriticalPathScheduler

DESLinkCriticalPathScheduler(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
    seed: int | None = None,
)

Bases: DESLinkFIFOScheduler

DES scheduler that prefers requests with larger remaining path cost.

Source code in src/memq_dqc/scheduler/des_link_scheduler.py
def __init__(
    self,
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> None:
    """Initialize one DES scheduler instance.

    Args:
        distributed_circuit: Distributed circuit DAG to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"``.
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Whether entanglement generation for multi-pair
            remote requests may overlap. The current DES link model still
            enforces one active entanglement process per link.
        seed: Optional random seed for deterministic simulations.
    """
    super().__init__(
        distributed_circuit,
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
        multiplex_entangle=multiplex_entangle,
    )
    self.t_cycle = self.timing_model.des_t_cycle
    self.p_success = self.timing_model.des_success_probability
    self.seed = seed
    self._rng = random.Random()
    self._op_by_id: dict[int, Op] = {}
    self._successors_by_op: dict[int, tuple[int, ...]] = {}
    self._remaining_predecessors: dict[int, int] = {}
    self._remaining_path_costs: dict[int, float] = {}
    self._catent_groups: dict[int, _CatentGroup] = {}
    self._group_by_op_id: dict[int, int] = {}
    self._group_durations: dict[int, float] = {}
    self._group_remaining_path_costs: dict[int, float] = {}
    self._qubit_timers: dict[str, float] = {}
    self._qubit_order: list[str] = []
    self._op_qubits: dict[int, tuple[str, ...]] = {}
    self._event_queue: list[_QueueEvent] = []
    self._link_states: dict[tuple[str, str], _LinkState] = {}
    self._reserved_link_counts: dict[tuple[str, str], int] = {}
    self._remote_requests: dict[int, _RemoteRequest] = {}
    self._remote_ops_with_catent: set[int] = set()
    self._scheduled_records: list[tuple[float, int, ScheduleEvent]] = []
    self._event_sequence = 0
    self._record_sequence = 0
    self._pending_request_sequence = 0

DESLinkFIFOScheduler

DESLinkFIFOScheduler(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
    seed: int | None = None,
)

Bases: BaseDESLinkScheduler

DES scheduler that serves contended links in FIFO order.

Source code in src/memq_dqc/scheduler/des_link_scheduler.py
def __init__(
    self,
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> None:
    """Initialize one DES scheduler instance.

    Args:
        distributed_circuit: Distributed circuit DAG to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"``.
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Whether entanglement generation for multi-pair
            remote requests may overlap. The current DES link model still
            enforces one active entanglement process per link.
        seed: Optional random seed for deterministic simulations.
    """
    super().__init__(
        distributed_circuit,
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
        multiplex_entangle=multiplex_entangle,
    )
    self.t_cycle = self.timing_model.des_t_cycle
    self.p_success = self.timing_model.des_success_probability
    self.seed = seed
    self._rng = random.Random()
    self._op_by_id: dict[int, Op] = {}
    self._successors_by_op: dict[int, tuple[int, ...]] = {}
    self._remaining_predecessors: dict[int, int] = {}
    self._remaining_path_costs: dict[int, float] = {}
    self._catent_groups: dict[int, _CatentGroup] = {}
    self._group_by_op_id: dict[int, int] = {}
    self._group_durations: dict[int, float] = {}
    self._group_remaining_path_costs: dict[int, float] = {}
    self._qubit_timers: dict[str, float] = {}
    self._qubit_order: list[str] = []
    self._op_qubits: dict[int, tuple[str, ...]] = {}
    self._event_queue: list[_QueueEvent] = []
    self._link_states: dict[tuple[str, str], _LinkState] = {}
    self._reserved_link_counts: dict[tuple[str, str], int] = {}
    self._remote_requests: dict[int, _RemoteRequest] = {}
    self._remote_ops_with_catent: set[int] = set()
    self._scheduled_records: list[tuple[float, int, ScheduleEvent]] = []
    self._event_sequence = 0
    self._record_sequence = 0
    self._pending_request_sequence = 0

DESLinkShortestDurationScheduler

DESLinkShortestDurationScheduler(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
    seed: int | None = None,
)

Bases: DESLinkFIFOScheduler

DES scheduler that prefers the shortest blocked remote request.

Source code in src/memq_dqc/scheduler/des_link_scheduler.py
def __init__(
    self,
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> None:
    """Initialize one DES scheduler instance.

    Args:
        distributed_circuit: Distributed circuit DAG to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"``.
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Whether entanglement generation for multi-pair
            remote requests may overlap. The current DES link model still
            enforces one active entanglement process per link.
        seed: Optional random seed for deterministic simulations.
    """
    super().__init__(
        distributed_circuit,
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
        multiplex_entangle=multiplex_entangle,
    )
    self.t_cycle = self.timing_model.des_t_cycle
    self.p_success = self.timing_model.des_success_probability
    self.seed = seed
    self._rng = random.Random()
    self._op_by_id: dict[int, Op] = {}
    self._successors_by_op: dict[int, tuple[int, ...]] = {}
    self._remaining_predecessors: dict[int, int] = {}
    self._remaining_path_costs: dict[int, float] = {}
    self._catent_groups: dict[int, _CatentGroup] = {}
    self._group_by_op_id: dict[int, int] = {}
    self._group_durations: dict[int, float] = {}
    self._group_remaining_path_costs: dict[int, float] = {}
    self._qubit_timers: dict[str, float] = {}
    self._qubit_order: list[str] = []
    self._op_qubits: dict[int, tuple[str, ...]] = {}
    self._event_queue: list[_QueueEvent] = []
    self._link_states: dict[tuple[str, str], _LinkState] = {}
    self._reserved_link_counts: dict[tuple[str, str], int] = {}
    self._remote_requests: dict[int, _RemoteRequest] = {}
    self._remote_ops_with_catent: set[int] = set()
    self._scheduled_records: list[tuple[float, int, ScheduleEvent]] = []
    self._event_sequence = 0
    self._record_sequence = 0
    self._pending_request_sequence = 0

FIFOScheduler

FIFOScheduler(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
)

Bases: BaseScheduler

Schedule operations by walking DAG layers in FIFO order.

Source code in src/memq_dqc/scheduler/schedule.py
def __init__(
    self,
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
) -> None:
    """Initialize the scheduler with a distributed circuit.

    Args:
        distributed_circuit: Distributed circuit DAG to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile, and carrying any custom hardware
            parameter overrides. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults; pass a
            profile rather than the scalar selectors to override individual
            hardware parameters.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"`` (Ba+ trapped ion).
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: True if we can perform entanglement generation
            for comm qubits on same chip simultaneously
    """
    hardware_profile = _resolve_scheduler_hardware_profile(
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
    )
    self.distributed_circuit = distributed_circuit
    self.hardware_profile = hardware_profile
    self.modality = hardware_profile.modality
    self.entanglement_profile = hardware_profile.entanglement_profile
    self.multiplex_entangle = multiplex_entangle
    self.timing_model = _load_scheduler_timing_model(hardware_profile)
    self.schedule: OperationSchedule | None = None

run

run() -> None

Build a FIFO schedule for the configured distributed circuit.

Source code in src/memq_dqc/scheduler/fifo.py
def run(self) -> None:
    """Build a FIFO schedule for the configured distributed circuit."""
    qubit_timers: dict[str, float] = {}
    qubit_order: list[str] = []
    scheduled_operations: list[ScheduleEvent] = []
    remote_ops_with_catent = _remote_ops_with_catent_setup(
        self.distributed_circuit
    )
    ops = self.distributed_circuit.ops
    op_by_id = {op.op_id: op for op in ops}
    group_owners = _catent_group_owners(ops)
    group_comm_qubits: dict[int, tuple[str, ...]] = {}
    remote_ops_with_catent.update(
        op.op_id for op in ops if op.is_remote and op.op_id in group_owners
    )
    # Source order is topological and keeps each cat block together while
    # per-qubit timestamps still allow independent operations to overlap.
    # This also reserves deferred communication resources through the end
    # of the entire block before another source block can acquire them.
    for op in ops:
        entanglement_events: list[EntanglementGeneration] = []
        cat_proxy_qubits: tuple[str, ...] = ()
        if _is_catent_operation(op):
            if len(op.qubits) > 2:
                qubits = tuple(
                    _physical_qubit_label(qubit) for qubit in op.qubits
                )
                entanglement_events, start_time = (
                    _schedule_entanglement_generation(
                        data_qubits=(qubits[0], qubits[1]),
                        ebit_qubits=_catent_ebit_labels(op),
                        qubit_timers=qubit_timers,
                        entanglement_time=self.timing_model.entanglement_time,
                        multiplex_entangle=self.multiplex_entangle,
                    )
                )
            else:
                qubits, entanglement_events, start_time = (
                    _select_remote_ebit_assignment(
                        distributed_circuit=self.distributed_circuit,
                        op=op,
                        qubit_timers=qubit_timers,
                        entanglement_time=self.timing_model.entanglement_time,
                        multiplex_entangle=self.multiplex_entangle,
                    )
                )
            if op.op_id in group_owners:
                group_comm_qubits[op.op_id] = qubits[2:]
        elif op.is_remote and op.op_id not in remote_ops_with_catent:
            qubits, entanglement_events, start_time = (
                _select_remote_ebit_assignment(
                    distributed_circuit=self.distributed_circuit,
                    op=op,
                    qubit_timers=qubit_timers,
                    entanglement_time=self.timing_model.entanglement_time,
                    multiplex_entangle=self.multiplex_entangle,
                )
            )
        else:
            owner = group_owners.get(op.op_id)
            if owner is not None:
                qubits, cat_proxy_qubits = _bound_cat_group_qubits(
                    op, op_by_id[owner].qubits[0], group_comm_qubits[owner]
                )
            else:
                qubits = tuple(
                    _physical_qubit_label(qubit) for qubit in op.qubits
                )
            start_time = max(
                (qubit_timers.get(qubit, 0.0) for qubit in qubits),
                default=0.0,
            )

        for qubit in qubits:
            if qubit not in qubit_timers:
                qubit_timers[qubit] = 0.0
                qubit_order.append(qubit)

        scheduled_operations.extend(entanglement_events)
        scheduled_op = ScheduledOperation(
            op_id=op.op_id,
            statement_id=op.statement_id,
            name=op.name,
            qubits=qubits,
            start_time=start_time,
            duration=_operation_duration(op, self.timing_model),
            is_remote=op.is_remote,
            cat_proxy_qubits=cat_proxy_qubits,
        )
        scheduled_operations.append(scheduled_op)
        for qubit in qubits:
            qubit_timers[qubit] = scheduled_op.end_time

    self.schedule = OperationSchedule(
        operations=tuple(scheduled_operations),
        timelines=_build_qubit_timelines(
            scheduled_operations,
            tuple(qubit_order),
        ),
        makespan=max(
            (
                scheduled_event.end_time
                for scheduled_event in scheduled_operations
            ),
            default=0.0,
        ),
    )

EPRDemand dataclass

EPRDemand(
    demand_id: str,
    consumer_op_id: int,
    num_pairs: int,
    assigned: EPRLinkAssignment | None,
    candidates: tuple[EPRLinkAssignment, ...],
    nominal_start_time: float,
    predecessor_op_ids: tuple[int, ...],
    remaining_critical_path: float,
)

A request for newly generated entanglement by one operation.

An EPR demand is a scheduling resource request, not an EPR-generation event. The external simulator creates as many generation attempts as its policy requires.

Attributes:

Name Type Description
demand_id str

Stable identifier for the demand.

consumer_op_id int

Operation that consumes the entanglement (a catent, an rswap, or an ungrouped remote gate).

num_pairs int

Number of EPR pairs the consumer requires.

assigned EPRLinkAssignment | None

The fixed link assignment, or None when assignment is deferred to the scheduler.

candidates tuple[EPRLinkAssignment, ...]

Candidate link assignments when assignment is deferred; empty when a fixed assignment is present.

nominal_start_time float

Consumer's nominal start time.

predecessor_op_ids tuple[int, ...]

Operation ids that must complete before the consumer.

remaining_critical_path float

Static remaining-critical-path duration from the consumer to a DAG sink.

EPRLinkAssignment dataclass

EPRLinkAssignment(
    link_ids: tuple[str, ...],
    comm_qubit_ids: tuple[str, ...],
)

One concrete or candidate link assignment for an EPR demand.

Attributes:

Name Type Description
link_ids tuple[str, ...]

Link resource ids, one per required EPR pair.

comm_qubit_ids tuple[str, ...]

Communication-qubit resource ids occupied by this assignment.

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 None for defaults.

partition_seed int | None

Optional seed for partitioners with random components.

ebit_assignment bool

Whether the compiler assigns concrete e-bit pairs (True) or exposes candidate assignments for deferred choice.

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. None selects the default profile. Besides naming a modality and entanglement profile, a SchedulerHardwareProfile can carry custom hardware parameters (gate, measurement, and entanglement timings) that override the selected profile's values.

SchedulingDependency dataclass

SchedulingDependency(
    source_op_id: int,
    target_op_id: int,
    resources: tuple[str, ...],
    classification: str | None = None,
)

One precedence edge in the distributed operation DAG.

Attributes:

Name Type Description
source_op_id int

Operation id the dependency originates from.

target_op_id int

Operation id that depends on the source.

resources tuple[str, ...]

Physical qubit resource ids that created the dependency.

classification str | None

Optional dependency label, e.g. "cross_qpu" or "local".

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 source_fingerprint.

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 op_id.

dependencies tuple[SchedulingDependency, ...]

Precedence edges, ordered by (source, target).

resources tuple[SchedulingResource, ...]

Physical resources, ordered by resource_id.

epr_demands tuple[EPRDemand, ...]

Entanglement demands, ordered by demand_id.

nominal_makespan float

Maximum nominal operation end time.

metadata Mapping[str, JSONValue]

Reproducibility metadata (partitioner, seed, profile, ...).

SchedulingOperation dataclass

SchedulingOperation(
    op_id: int,
    statement_id: int,
    name: str,
    op_type: str,
    is_remote: bool,
    data_qubits: tuple[str, ...],
    comm_qubits: tuple[str, ...],
    duration: float,
    group_id: int | None,
    nominal_start: float,
    nominal_end: float,
    cat_proxy_x: bool = False,
)

One distributed operation with its nominal timing.

Attributes:

Name Type Description
op_id int

Operation identifier from the distributed DAG.

statement_id int

Statement identifier from the distributed program.

name str

Gate or instruction name.

op_type str

Classification, e.g. "remote_gate", "epr_generation", "local_gate" (see the annotated-DAG classifier).

is_remote bool

Whether the operation is a remote distributed operation.

data_qubits tuple[str, ...]

Ordered physical data-qubit resource ids.

comm_qubits tuple[str, ...]

Ordered physical communication-qubit resource ids.

duration float

Deterministic operation duration in time_unit units.

group_id int | None

Cat-entanglement group id, or None when ungrouped.

nominal_start float

Start time in the zero-EPR-wait nominal schedule.

nominal_end float

End time in the zero-EPR-wait nominal schedule.

cat_proxy_x bool

Whether the selected cat group's remote proxy also receives X when the named data operation executes.

SchedulingResource dataclass

SchedulingResource(
    resource_id: str,
    resource_type: ResourceType,
    qpu_id: int | None = None,
    local_index: int | None = None,
    endpoints: tuple[str, str] | None = None,
    parameters: Mapping[str, JSONValue] = dict(),
)

One physical resource: a qubit or an inter-QPU link.

Attributes:

Name Type Description
resource_id str

Stable identifier, e.g. "q0[3]", "c0[1]", or a link id such as "link:c0[0]<->c1[0]".

resource_type ResourceType

Whether the resource is a computation qubit, a communication qubit, or an inter-QPU link.

qpu_id int | None

Owning QPU id for qubit resources; None for links.

local_index int | None

Local slot index for qubit resources; None for links.

endpoints tuple[str, str] | None

The two communication-qubit resource ids a link connects; None for qubit resources.

parameters Mapping[str, JSONValue]

Reserved mapping for external hardware annotations (coherence times, link fidelities); empty by default.

BaseScheduler

BaseScheduler(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
)

Bases: ABC

Base class for distributed scheduling algorithm implementations.

Initialize the scheduler with a distributed circuit.

Parameters:

Name Type Description Default
distributed_circuit DistributedCircuit

Distributed circuit DAG to schedule.

required
profile SchedulerHardwareProfile | None

Optional convenience object selecting both modality and entanglement profile, and carrying any custom hardware parameter overrides. When provided, modality and entanglement_profile must be left at their defaults; pass a profile rather than the scalar selectors to override individual hardware parameters.

None
modality SchedulerModality

Hardware timing profile used for local 1Q/2Q gate durations. Defaults to "trapped_ion.ba" (Ba+ trapped ion).

DEFAULT_SCHEDULER_MODALITY
entanglement_profile SchedulerEntanglementProfile

Entanglement-generation profile used for entanglement timing. Defaults to "ion.time_bin".

DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
multiplex_entangle bool

True if we can perform entanglement generation for comm qubits on same chip simultaneously

True
Source code in src/memq_dqc/scheduler/schedule.py
def __init__(
    self,
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
) -> None:
    """Initialize the scheduler with a distributed circuit.

    Args:
        distributed_circuit: Distributed circuit DAG to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile, and carrying any custom hardware
            parameter overrides. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults; pass a
            profile rather than the scalar selectors to override individual
            hardware parameters.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"`` (Ba+ trapped ion).
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: True if we can perform entanglement generation
            for comm qubits on same chip simultaneously
    """
    hardware_profile = _resolve_scheduler_hardware_profile(
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
    )
    self.distributed_circuit = distributed_circuit
    self.hardware_profile = hardware_profile
    self.modality = hardware_profile.modality
    self.entanglement_profile = hardware_profile.entanglement_profile
    self.multiplex_entangle = multiplex_entangle
    self.timing_model = _load_scheduler_timing_model(hardware_profile)
    self.schedule: OperationSchedule | None = None

run abstractmethod

run() -> None

Run the scheduling algorithm and update schedule.

Source code in src/memq_dqc/scheduler/schedule.py
@abstractmethod
def run(self) -> None:
    """Run the scheduling algorithm and update ``schedule``."""
    raise NotImplementedError

EntanglementGeneration dataclass

EntanglementGeneration(
    qubits: tuple[str, str],
    start_time: float,
    duration: float = _default_entanglement_duration(),
    was_used: bool = True,
)

Schedule entanglement generation between two available qubits.

Attributes:

Name Type Description
qubits tuple[str, str]

Communication qubits used for entanglement generation.

start_time float

Time at which generation begins.

duration float

Total time the EPR pair occupies the link.

was_used bool

Whether the generated pair was consumed before expiration.

name property

name: str

Return the schedule label for entanglement generation.

is_remote property

is_remote: bool

Return whether entanglement generation is a remote event.

end_time property

end_time: float

Return the end time of the entanglement generation.

OperationSchedule dataclass

OperationSchedule(
    operations: tuple[ScheduleEvent, ...],
    timelines: tuple[ScheduledQubitTimeline, ...],
    makespan: float,
)

Operation-level schedule with per-qubit execution timelines.

Attributes:

Name Type Description
operations tuple[ScheduleEvent, ...]

Scheduled operations in dispatch order.

timelines tuple[ScheduledQubitTimeline, ...]

Per-qubit views derived from operations.

makespan float

Total execution time across all physical qubits.

qubits property

qubits: tuple[str, ...]

Return the ordered physical qubits present in the schedule.

ScheduledOperation dataclass

ScheduledOperation(
    op_id: int,
    statement_id: int,
    name: str,
    qubits: tuple[str, ...],
    start_time: float,
    duration: float,
    is_remote: bool,
    cat_proxy_qubits: tuple[str, ...] = (),
)

One scheduled operation in physical-qubit coordinates.

Attributes:

Name Type Description
op_id int

Operation identifier from the distributed DAG.

statement_id int

Statement identifier from the distributed program.

name str

Gate or instruction name.

qubits tuple[str, ...]

Physical qubit labels touched by the operation.

start_time float

Earliest time the operation can begin.

duration float

Operation duration in abstract scheduler time units.

is_remote bool

Whether the operation is a remote distributed operation.

cat_proxy_qubits tuple[str, ...]

Communication qubits receiving an additional X alongside the named data gate. Empty for ordinary operations.

end_time property

end_time: float

Return the end time of the scheduled operation.

ScheduledQubitTimeline dataclass

ScheduledQubitTimeline(
    qubit: str, operations: tuple[ScheduleEvent, ...]
)

Ordered operations scheduled on a single physical qubit.

Attributes:

Name Type Description
qubit str

Physical qubit label.

operations tuple[ScheduleEvent, ...]

Operations that execute on this qubit in time order.

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 Compiler or Partitioner (its distributed circuit is used) or a DistributedCircuit directly.

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, modality and entanglement_profile must be left at their defaults.

None
modality SchedulerModality

Hardware timing profile used for local 1Q/2Q gate durations. Defaults to "trapped_ion.ba" (Ba+ trapped ion).

DEFAULT_SCHEDULER_MODALITY
entanglement_profile SchedulerEntanglementProfile

Entanglement-generation profile used for entanglement timing. Defaults to "ion.time_bin".

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
def __init__(
    self,
    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
    ),
    # TODO: make explicit / check
    multiplex_entangle: bool = True,
    algo_kwargs: dict[str, Any] | None = None,
) -> None:
    """Initialize the scheduler and select the algorithm.

    Args:
        source: What to schedule. A ``Compiler`` or ``Partitioner`` (its
            distributed circuit is used) or a ``DistributedCircuit``
            directly.
        algo: Algorithm name, class, or preconfigured instance.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"`` (Ba+ trapped ion).
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Whether entanglement generation may overlap
            across independent communication resources.
        algo_kwargs: Keyword arguments forwarded to the algorithm.
    """
    self._algorithm = self._resolve_algorithm(
        _resolve_distributed_circuit(source),
        algo,
        profile,
        modality,
        entanglement_profile,
        multiplex_entangle,
        algo_kwargs,
    )

distributed_circuit property

distributed_circuit: DistributedCircuit

Return the distributed circuit used by the scheduler.

multiplex_entangle property

multiplex_entangle: bool

Return the entanglement multiplexing option.

schedule property

schedule: OperationSchedule | None

Return the latest operation schedule, if available.

run

run(
    *,
    verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> None

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
def run(
    self,
    *,
    verbosity: Literal["quiet", "info", "debug"] = "quiet",
) -> None:
    """Run the configured scheduling algorithm.

    Args:
        verbosity: Logging verbosity for this workflow call.
    """
    with workflow_logging(verbosity):
        timer = StepTimer()
        logger.info(
            "Starting scheduling with %s.",
            type(self._algorithm).__name__,
        )
        self._algorithm.run()
        schedule = self._algorithm.schedule
        if schedule is None:
            logger.warning(
                "Scheduling finished without an operation schedule "
                "after %.3fs.",
                timer.elapsed_seconds(),
            )
            return

        logger.info(
            "Scheduling completed in %.3fs: operations=%d "
            "makespan=%.3f failed_entanglement_operations=%d.",
            timer.elapsed_seconds(),
            len(schedule.operations),
            schedule.makespan,
            _count_failed_entanglement_operations(schedule),
        )
        logger.debug(
            "Scheduled qubit timelines: %s",
            schedule.qubits,
        )

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 "pretty" display).

None
display Literal['pretty', 'legacy']

Which rendering to produce. "pretty" is the publication-ready variant; "legacy" is the on-screen diagnostic chart.

'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 matplotlib.pyplot.show after rendering.

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 save_path.

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
def plot_gantt(
    self,
    *,
    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.

    Args:
        ax: Existing axes to draw into. A new figure and axes are created
            when omitted.
        title: Optional chart title (ignored in ``"pretty"`` display).
        display: Which rendering to produce. ``"pretty"`` is the
            publication-ready variant; ``"legacy"`` is the on-screen
            diagnostic chart.
        explicit_ops: Whether to render one row per scheduled event instead
            of one row per physical qubit.
        show: Whether to call ``matplotlib.pyplot.show`` after rendering.
        save_path: Optional file path. When given, the rendered figure is
            saved there.
        dpi: Resolution used when saving to ``save_path``.

    Returns:
        The Matplotlib axes containing the rendered schedule.

    Raises:
        ValueError: If the scheduler has not produced a schedule yet.
    """
    if self.schedule is None:
        raise ValueError(
            "No schedule available; call run() before plot_gantt()."
        )
    from memq_dqc.scheduler.schedule_visualizer import plot_schedule_gantt

    axes = plot_schedule_gantt(
        self.schedule,
        ax=ax,
        title=title,
        show=show,
        explicit_ops=explicit_ops,
        display=display,
    )
    if save_path is not None:
        axes.figure.savefig(str(save_path), dpi=dpi, bbox_inches="tight")
    return axes

to_json

to_json(
    path: str | PathLike[str] | None = None,
    *,
    indent: int | None = 2,
) -> str

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 None for the most compact single-line output.

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
def to_json(
    self,
    path: str | PathLike[str] | None = None,
    *,
    indent: int | None = 2,
) -> str:
    """Serialize this scheduler's result to a JSON document.

    Opt-in export; scheduling never serializes automatically. See
    [memq_dqc.scheduler.serialize.schedule_to_json][memq_dqc.scheduler.serialize.schedule_to_json] for the document
    layout.

    Args:
        path: Optional destination file. When given, the JSON document is
            written there in addition to being returned.
        indent: Indentation forwarded to the underlying serializer. Pass
            ``None`` for the most compact single-line output.

    Returns:
        The JSON document as a string.

    Raises:
        ValueError: If the scheduler has not produced a schedule yet.
    """
    if self.schedule is None:
        raise ValueError(
            "No schedule available; call run() before to_json()."
        )
    from memq_dqc.scheduler.serialize import schedule_to_json

    return schedule_to_json(self.schedule, path, indent=indent)

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:

profile = SchedulerHardwareProfile.sr_trapped_ion(
    two_qubit_gate_time=120.0,
    epr_lifetime=80.0,
)

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

overrides: dict[str, float]

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
@classmethod
def ba_trapped_ion(
    cls,
    *,
    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.

    Args:
        entanglement_profile: Entanglement-generation profile to pair with
            the modality.
        one_qubit_gate_time: Optional single-qubit gate duration override.
        two_qubit_gate_time: Optional two-qubit gate duration override.
        measurement_time: Optional measurement duration override.
        entanglement_rate: Optional entanglement-generation rate override.
        epr_lifetime: Optional EPR-pair lifetime override.

    Returns:
        The hardware profile.
    """
    return cls(
        modality="trapped_ion.ba",
        entanglement_profile=entanglement_profile,
        one_qubit_gate_time=one_qubit_gate_time,
        two_qubit_gate_time=two_qubit_gate_time,
        measurement_time=measurement_time,
        entanglement_rate=entanglement_rate,
        epr_lifetime=epr_lifetime,
    )

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
@classmethod
def sr_trapped_ion(
    cls,
    *,
    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.

    Args:
        entanglement_profile: Entanglement-generation profile to pair with
            the modality.
        one_qubit_gate_time: Optional single-qubit gate duration override.
        two_qubit_gate_time: Optional two-qubit gate duration override.
        measurement_time: Optional measurement duration override.
        entanglement_rate: Optional entanglement-generation rate override.
        epr_lifetime: Optional EPR-pair lifetime override.

    Returns:
        The hardware profile.
    """
    return cls(
        modality="trapped_ion.sr",
        entanglement_profile=entanglement_profile,
        one_qubit_gate_time=one_qubit_gate_time,
        two_qubit_gate_time=two_qubit_gate_time,
        measurement_time=measurement_time,
        entanglement_rate=entanglement_rate,
        epr_lifetime=epr_lifetime,
    )

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
@classmethod
def forte_trapped_ion(
    cls,
    *,
    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.

    Args:
        entanglement_profile: Entanglement-generation profile to pair with
            the modality.
        one_qubit_gate_time: Optional single-qubit gate duration override.
        two_qubit_gate_time: Optional two-qubit gate duration override.
        measurement_time: Optional measurement duration override.
        entanglement_rate: Optional entanglement-generation rate override.
        epr_lifetime: Optional EPR-pair lifetime override.

    Returns:
        The hardware profile.
    """
    return cls(
        modality="trapped_ion.forte",
        entanglement_profile=entanglement_profile,
        one_qubit_gate_time=one_qubit_gate_time,
        two_qubit_gate_time=two_qubit_gate_time,
        measurement_time=measurement_time,
        entanglement_rate=entanglement_rate,
        epr_lifetime=epr_lifetime,
    )

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
@classmethod
def neutral_atom(
    cls,
    *,
    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.

    Args:
        entanglement_profile: Entanglement-generation profile to pair with
            the modality.
        one_qubit_gate_time: Optional single-qubit gate duration override.
        two_qubit_gate_time: Optional two-qubit gate duration override.
        measurement_time: Optional measurement duration override.
        entanglement_rate: Optional entanglement-generation rate override.
        epr_lifetime: Optional EPR-pair lifetime override.

    Returns:
        The hardware profile.
    """
    return cls(
        modality="neutral_atom",
        entanglement_profile=entanglement_profile,
        one_qubit_gate_time=one_qubit_gate_time,
        two_qubit_gate_time=two_qubit_gate_time,
        measurement_time=measurement_time,
        entanglement_rate=entanglement_rate,
        epr_lifetime=epr_lifetime,
    )
des_link_critical_path_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> OperationSchedule

Build a critical-path-first DES schedule.

Parameters:

Name Type Description Default
distributed_circuit DistributedCircuit

Distributed circuit to schedule.

required
profile SchedulerHardwareProfile | None

Optional convenience object selecting both modality and entanglement profile. When provided, modality and entanglement_profile must be left at their defaults.

None
modality SchedulerModality

Hardware timing profile used for local 1Q/2Q gate durations. Defaults to "trapped_ion.ba".

DEFAULT_SCHEDULER_MODALITY
entanglement_profile SchedulerEntanglementProfile

Entanglement-generation profile used for entanglement timing. Defaults to "ion.time_bin".

DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
multiplex_entangle bool

Whether entanglement generation for multi-pair remote requests may overlap. The current DES link model still enforces one active entanglement process per link.

True
seed int | None

Optional random seed for deterministic simulations.

None

Returns:

Type Description
OperationSchedule

An operation-level schedule with stochastic entanglement timing and

OperationSchedule

critical-path-first link arbitration.

Source code in src/memq_dqc/scheduler/des_link_critical_path.py
def des_link_critical_path_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> OperationSchedule:
    """Build a critical-path-first DES schedule.

    Args:
        distributed_circuit: Distributed circuit to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"``.
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Whether entanglement generation for multi-pair
            remote requests may overlap. The current DES link model still
            enforces one active entanglement process per link.
        seed: Optional random seed for deterministic simulations.

    Returns:
        An operation-level schedule with stochastic entanglement timing and
        critical-path-first link arbitration.
    """
    scheduler = DESLinkCriticalPathScheduler(
        distributed_circuit,
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
        multiplex_entangle=multiplex_entangle,
        seed=seed,
    )
    scheduler.run()
    if scheduler.schedule is None:
        raise RuntimeError(
            "DES critical-path scheduler did not produce a schedule."
        )
    return scheduler.schedule
des_link_fifo_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> OperationSchedule

Build a FIFO-arbitrated DES schedule for a distributed circuit DAG.

Parameters:

Name Type Description Default
distributed_circuit DistributedCircuit

Distributed circuit to schedule.

required
profile SchedulerHardwareProfile | None

Optional convenience object selecting both modality and entanglement profile. When provided, modality and entanglement_profile must be left at their defaults.

None
modality SchedulerModality

Hardware timing profile used for local 1Q/2Q gate durations. Defaults to "trapped_ion.ba".

DEFAULT_SCHEDULER_MODALITY
entanglement_profile SchedulerEntanglementProfile

Entanglement-generation profile used for entanglement timing. Defaults to "ion.time_bin".

DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
multiplex_entangle bool

Whether entanglement generation for multi-pair remote requests may overlap. The current DES link model still enforces one active entanglement process per link.

True
seed int | None

Optional random seed for deterministic simulations.

None

Returns:

Type Description
OperationSchedule

An operation-level schedule with stochastic entanglement timing and

OperationSchedule

FIFO link arbitration.

Source code in src/memq_dqc/scheduler/des_link_fifo.py
def des_link_fifo_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> OperationSchedule:
    """Build a FIFO-arbitrated DES schedule for a distributed circuit DAG.

    Args:
        distributed_circuit: Distributed circuit to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"``.
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Whether entanglement generation for multi-pair
            remote requests may overlap. The current DES link model still
            enforces one active entanglement process per link.
        seed: Optional random seed for deterministic simulations.

    Returns:
        An operation-level schedule with stochastic entanglement timing and
        FIFO link arbitration.
    """
    scheduler = DESLinkFIFOScheduler(
        distributed_circuit,
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
        multiplex_entangle=multiplex_entangle,
        seed=seed,
    )
    scheduler.run()
    if scheduler.schedule is None:
        raise RuntimeError(
            "DES link-FIFO scheduler did not produce a schedule."
        )
    return scheduler.schedule
des_link_shortest_duration_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> OperationSchedule

Build a shortest-duration-first DES schedule.

Parameters:

Name Type Description Default
distributed_circuit DistributedCircuit

Distributed circuit to schedule.

required
profile SchedulerHardwareProfile | None

Optional convenience object selecting both modality and entanglement profile. When provided, modality and entanglement_profile must be left at their defaults.

None
modality SchedulerModality

Hardware timing profile used for local 1Q/2Q gate durations. Defaults to "trapped_ion.ba".

DEFAULT_SCHEDULER_MODALITY
entanglement_profile SchedulerEntanglementProfile

Entanglement-generation profile used for entanglement timing. Defaults to "ion.time_bin".

DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
multiplex_entangle bool

Whether entanglement generation for multi-pair remote requests may overlap. The current DES link model still enforces one active entanglement process per link.

True
seed int | None

Optional random seed for deterministic simulations.

None

Returns:

Type Description
OperationSchedule

An operation-level schedule with stochastic entanglement timing and

OperationSchedule

shortest-duration link arbitration.

Source code in src/memq_dqc/scheduler/des_link_shortest_duration.py
def des_link_shortest_duration_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
    seed: int | None = None,
) -> OperationSchedule:
    """Build a shortest-duration-first DES schedule.

    Args:
        distributed_circuit: Distributed circuit to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"``.
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Whether entanglement generation for multi-pair
            remote requests may overlap. The current DES link model still
            enforces one active entanglement process per link.
        seed: Optional random seed for deterministic simulations.

    Returns:
        An operation-level schedule with stochastic entanglement timing and
        shortest-duration link arbitration.
    """
    scheduler = DESLinkShortestDurationScheduler(
        distributed_circuit,
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
        multiplex_entangle=multiplex_entangle,
        seed=seed,
    )
    scheduler.run()
    if scheduler.schedule is None:
        raise RuntimeError(
            "DES shortest-duration scheduler did not produce a schedule."
        )
    return scheduler.schedule

fifo_schedule

fifo_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE,
    multiplex_entangle: bool = True,
) -> OperationSchedule

Build a FIFO schedule for a distributed circuit DAG.

Parameters:

Name Type Description Default
distributed_circuit DistributedCircuit

Distributed circuit to schedule.

required
profile SchedulerHardwareProfile | None

Optional convenience object selecting both modality and entanglement profile. When provided, modality and entanglement_profile must be left at their defaults.

None
modality SchedulerModality

Hardware timing profile used for local 1Q/2Q gate durations. Defaults to "trapped_ion.ba" (Ba+ trapped ion).

DEFAULT_SCHEDULER_MODALITY
entanglement_profile SchedulerEntanglementProfile

Entanglement-generation profile used for entanglement timing. Defaults to "ion.time_bin".

DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
multiplex_entangle bool

Reserved for future entanglement multiplexing behavior.(# TODO)

True

Returns:

Type Description
OperationSchedule

An operation-level schedule with per-qubit timelines.

Source code in src/memq_dqc/scheduler/fifo.py
def fifo_schedule(
    distributed_circuit: DistributedCircuit,
    *,
    profile: SchedulerHardwareProfile | None = None,
    modality: SchedulerModality = DEFAULT_SCHEDULER_MODALITY,
    entanglement_profile: SchedulerEntanglementProfile = (
        DEFAULT_SCHEDULER_ENTANGLEMENT_PROFILE
    ),
    multiplex_entangle: bool = True,
) -> OperationSchedule:
    """Build a FIFO schedule for a distributed circuit DAG.

    Args:
        distributed_circuit: Distributed circuit to schedule.
        profile: Optional convenience object selecting both modality and
            entanglement profile. When provided, ``modality`` and
            ``entanglement_profile`` must be left at their defaults.
        modality: Hardware timing profile used for local 1Q/2Q gate
            durations. Defaults to ``"trapped_ion.ba"`` (Ba+ trapped ion).
        entanglement_profile: Entanglement-generation profile used for
            entanglement timing. Defaults to ``"ion.time_bin"``.
        multiplex_entangle: Reserved for future entanglement multiplexing
            behavior.(# TODO)

    Returns:
        An operation-level schedule with per-qubit timelines.
    """
    scheduler = FIFOScheduler(
        distributed_circuit=distributed_circuit,
        profile=profile,
        modality=modality,
        entanglement_profile=entanglement_profile,
        multiplex_entangle=multiplex_entangle,
    )
    scheduler.run()
    if scheduler.schedule is None:
        raise RuntimeError("FIFO scheduler did not produce a schedule.")
    return scheduler.schedule

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
def validate_scheduling_instance(instance: SchedulingInstance) -> None:
    """Validate the structural and nominal-schedule invariants of an instance.

    Args:
        instance: The scheduling instance to validate.

    Raises:
        ValueError: If any invariant is violated. The message names the
            offending id(s) and the invariant.
    """
    if instance.schema_version not in (1, SCHEDULING_INSTANCE_SCHEMA_VERSION):
        raise ValueError(
            f"Unsupported scheduling-instance schema version {instance.schema_version!r}."
        )
    op_ids = _validate_unique_ids(
        (op.op_id for op in instance.operations),
        kind="operation",
    )
    resource_ids = _validate_unique_ids(
        (resource.resource_id for resource in instance.resources),
        kind="resource",
    )
    _validate_unique_ids(
        (demand.demand_id for demand in instance.epr_demands),
        kind="EPR demand",
    )

    op_by_id = {op.op_id: op for op in instance.operations}
    _validate_dependencies(instance, op_ids)
    _validate_acyclic(instance, op_ids)
    _validate_epr_demands(instance, op_by_id, resource_ids)
    _validate_cat_proxy_metadata(instance)
    _validate_nominal_times(instance)
    _validate_nominal_ordering(instance, op_by_id)
    _validate_resource_intervals(instance)
    _validate_makespan(instance)

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 str or os.PathLike).

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
def scheduling_instance_from_json(
    source: str | PathLike[str] | Mapping[str, Any],
) -> SchedulingInstance:
    """Load and validate a scheduling instance from JSON.

    Args:
        source: A parsed mapping, a JSON document string, or a path to a JSON
            file (as ``str`` or `os.PathLike`).

    Returns:
        The reconstructed, validated [SchedulingInstance][memq_dqc.scheduler.instance.SchedulingInstance].

    Raises:
        ValueError: If the document type or schema version is unsupported, a
            number is non-finite, or the reconstructed instance is invalid.
    """
    data = _load_document(source)
    document_type = data.get("type")
    if document_type != _INSTANCE_TYPE:
        raise ValueError(
            f"Unsupported document type {document_type!r}; expected "
            f"{_INSTANCE_TYPE!r}."
        )
    schema_version = data.get("schema_version")
    if schema_version not in (1, SCHEDULING_INSTANCE_SCHEMA_VERSION):
        raise ValueError(
            f"Unsupported scheduling-instance schema version "
            f"{schema_version!r}; this build supports "
            f"1 and {SCHEDULING_INSTANCE_SCHEMA_VERSION}."
        )

    instance = _instance_from_dict(data)
    validate_scheduling_instance(instance)
    return instance

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 json.dumps. Pass None for the most compact single-line output (suited to large corpora).

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
def 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.

    Args:
        instance: The scheduling instance to serialize.
        path: Optional destination file. When given, the document is written
            there as UTF-8 text in addition to being returned.
        indent: Indentation forwarded to `json.dumps`. Pass ``None`` for
            the most compact single-line output (suited to large corpora).

    Returns:
        The JSON document as a string.

    Raises:
        ValueError: If the instance contains a non-finite number.
    """
    document = json.dumps(
        _instance_to_dict(instance),
        indent=indent,
        allow_nan=False,
    )
    if path is not None:
        Path(path).write_text(document, encoding="utf-8")
    return document

build_scheduling_instance

build_scheduling_instance(
    distributed: DistributedCircuit,
    network: NetworkGraph,
    *,
    options: SchedulingCompileOptions,
    compiler_version: str,
    source_fingerprint: str,
) -> SchedulingInstance

Assemble a validated scheduling instance for a compiled circuit.

Parameters:

Name Type Description Default
distributed DistributedCircuit

The compiled distributed circuit to describe.

required
network NetworkGraph

The network graph the circuit was compiled for.

required
options SchedulingCompileOptions

Compilation options recorded for reproducibility; its hardware_profile selects deterministic operation durations.

required
compiler_version str

memq_dqc version producing the instance.

required
source_fingerprint str

Precomputed fingerprint of the normalized inputs and options; also used to derive instance_id.

required

Returns:

Type Description
SchedulingInstance

A validated SchedulingInstance.

Source code in src/memq_dqc/scheduler/nominal.py
def build_scheduling_instance(
    distributed: DistributedCircuit,
    network: NetworkGraph,
    *,
    options: SchedulingCompileOptions,
    compiler_version: str,
    source_fingerprint: str,
) -> SchedulingInstance:
    """Assemble a validated scheduling instance for a compiled circuit.

    Args:
        distributed: The compiled distributed circuit to describe.
        network: The network graph the circuit was compiled for.
        options: Compilation options recorded for reproducibility; its
            ``hardware_profile`` selects deterministic operation durations.
        compiler_version: memq_dqc version producing the instance.
        source_fingerprint: Precomputed fingerprint of the normalized inputs
            and options; also used to derive ``instance_id``.

    Returns:
        A validated [SchedulingInstance][memq_dqc.scheduler.instance.SchedulingInstance].
    """
    profile = _resolve_scheduler_hardware_profile(
        profile=options.hardware_profile,
        modality="trapped_ion.ba",
        entanglement_profile="ion.time_bin",
    )
    timing_model = _load_scheduler_timing_model(profile)

    graph = build_annotated_dag(distributed)
    order = list(nx.lexicographical_topological_sort(graph, key=lambda n: n))
    durations = {
        op_id: _operation_duration(graph.nodes[op_id]["op"], timing_model)
        for op_id in order
    }
    starts, ends = _compute_nominal_schedule(graph, order, durations)
    remaining_path = _remaining_critical_path(graph, order, durations)

    operations = tuple(
        _build_operation(graph.nodes[op_id], durations[op_id], starts, ends)
        for op_id in sorted(graph.nodes)
    )
    dependencies = _build_dependencies(graph)
    qubit_resources, link_registry = _build_qubit_and_seed_link_resources(
        network
    )
    epr_demands = _build_epr_demands(
        graph, order, starts, remaining_path, link_registry
    )
    resources = tuple(
        sorted(
            (*qubit_resources, *link_registry.values()),
            key=lambda resource: resource.resource_id,
        )
    )

    nominal_makespan = max(ends.values(), default=0.0)
    metadata = _build_metadata(
        options, profile, compiler_version, timing_model
    )
    schema_version = (
        SCHEDULING_INSTANCE_SCHEMA_VERSION
        if any(op.cat_proxy_x for op in operations)
        else 1
    )
    metadata["schema_version"] = schema_version

    instance = SchedulingInstance(
        schema_version=schema_version,
        instance_id=f"inst-{source_fingerprint[:16]}",
        compiler_version=compiler_version,
        source_fingerprint=source_fingerprint,
        time_unit=TIME_UNIT,
        operations=operations,
        dependencies=dependencies,
        resources=resources,
        epr_demands=epr_demands,
        nominal_makespan=nominal_makespan,
        metadata=metadata,
    )
    validate_scheduling_instance(instance)
    return instance

plot_schedule_gantt

plot_schedule_gantt(
    schedule: OperationSchedule,
    *,
    ax: Axes | None = None,
    title: str | None = None,
    show: bool = False,
    explicit_ops: bool = False,
    display: Literal["pretty", "legacy"] = "pretty",
) -> Axes

Render a scheduler-produced operation timeline as a Gantt chart.

Parameters:

Name Type Description Default
schedule OperationSchedule

Scheduler output to render.

required
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 "pretty" display, which is captioned externally for a paper).

None
show bool

Whether to call matplotlib.pyplot.show after rendering.

False
explicit_ops bool

Whether to render one row per scheduled event instead of one row per physical qubit.

False
display Literal['pretty', 'legacy']

Which rendering to produce. "pretty" (the default) is the publication-ready variant: a print-safe, grayscale-friendly memQ palette (pale-purple local vs solid-purple remote gates, neutral-gray measurement, teal entanglement), monospace identifiers, module-grouped rows with labelled brackets, subtle gridlines, and a compact legend suitable for a journal figure. "legacy" is the original on-screen/diagnostic chart (pastel palette, communication-qubit hatching, inside legend).

'pretty'

Returns:

Type Description
Axes

The Matplotlib axes containing the rendered schedule.

Raises:

Type Description
ValueError

If display is not a recognized value, if the schedule does not contain any qubit timelines, or if explicit_ops is enabled and the schedule has no operations.

Source code in src/memq_dqc/scheduler/schedule_visualizer.py
def plot_schedule_gantt(
    schedule: OperationSchedule,
    *,
    ax: Axes | None = None,
    title: str | None = None,
    show: bool = False,
    explicit_ops: bool = False,
    display: Literal["pretty", "legacy"] = "pretty",
) -> Axes:
    """Render a scheduler-produced operation timeline as a Gantt chart.

    Args:
        schedule: Scheduler output to render.
        ax: Existing axes to draw into. A new figure and axes are created when
            omitted.
        title: Optional chart title (ignored in ``"pretty"`` display, which is
            captioned externally for a paper).
        show: Whether to call ``matplotlib.pyplot.show`` after rendering.
        explicit_ops: Whether to render one row per scheduled event instead of
            one row per physical qubit.
        display: Which rendering to produce. ``"pretty"`` (the default) is the
            publication-ready variant: a print-safe, grayscale-friendly memQ
            palette (pale-purple local vs solid-purple remote gates,
            neutral-gray measurement, teal entanglement), monospace
            identifiers, module-grouped rows with labelled brackets, subtle
            gridlines, and a compact legend suitable for a journal figure.
            ``"legacy"`` is the original on-screen/diagnostic chart (pastel
            palette, communication-qubit hatching, inside legend).

    Returns:
        The Matplotlib axes containing the rendered schedule.

    Raises:
        ValueError: If ``display`` is not a recognized value, if the schedule
            does not contain any qubit timelines, or if ``explicit_ops`` is
            enabled and the schedule has no operations.
    """
    if display not in ("pretty", "legacy"):
        raise ValueError(
            f"display must be 'pretty' or 'legacy', got {display!r}."
        )
    if not schedule.timelines:
        raise ValueError("schedule must contain at least one qubit timeline.")
    if explicit_ops and not schedule.operations:
        raise ValueError("schedule must contain at least one operation.")

    if display == "pretty":
        with plt.rc_context(_PRETTY_RC):
            return _render_pretty_gantt(
                schedule,
                ax=ax,
                title=title,
                show=show,
                explicit_ops=explicit_ops,
            )

    style = _default_style()
    with plt.rc_context(style.rc):
        return _render_schedule_gantt(
            schedule,
            style=style,
            ax=ax,
            title=title,
            show=show,
            explicit_ops=explicit_ops,
        )

schedule_to_json

schedule_to_json(
    schedule: OperationSchedule,
    path: str | PathLike[str] | None = None,
    *,
    indent: int | None = 2,
) -> str

Serialize an operation schedule to a JSON document.

This is an opt-in helper; scheduling never serializes automatically. The document has a makespan field and a flat, time-ordered operations list. Each operation carries a type discriminator ("operation" or "entanglement"), its stored fields, and the derived end_time.

Parameters:

Name Type Description Default
schedule OperationSchedule

The operation schedule to serialize.

required
path str | PathLike[str] | None

Optional destination file. When given, the JSON document is written there as UTF-8 text in addition to being returned.

None
indent int | None

Indentation forwarded to json.dumps. Pass None for the most compact single-line output.

2

Returns:

Type Description
str

The JSON document as a string.

Source code in src/memq_dqc/scheduler/serialize.py
def schedule_to_json(
    schedule: OperationSchedule,
    path: str | PathLike[str] | None = None,
    *,
    indent: int | None = 2,
) -> str:
    """Serialize an operation schedule to a JSON document.

    This is an opt-in helper; scheduling never serializes automatically. The
    document has a ``makespan`` field and a flat, time-ordered ``operations``
    list. Each operation carries a ``type`` discriminator (``"operation"`` or
    ``"entanglement"``), its stored fields, and the derived ``end_time``.

    Args:
        schedule: The operation schedule to serialize.
        path: Optional destination file. When given, the JSON document is
            written there as UTF-8 text in addition to being returned.
        indent: Indentation forwarded to `json.dumps`. Pass ``None`` for
            the most compact single-line output.

    Returns:
        The JSON document as a string.
    """
    document = json.dumps(_schedule_to_dict(schedule), indent=indent)
    if path is not None:
        Path(path).write_text(document, encoding="utf-8")
    return document