mqt.ionshuttler.linear¶

Compile circuits for a linear ion-shuttling architecture.

Submodules¶

Package Contents¶

DEFAULT_ACTION_TYPES: tuple[type[Action], ...]¶

class Architecture[source]¶

Describe the available sites, processing zones, and control capabilities.

num_sites: int¶

processing_zones: Mapping[str, Sequence[int]] | None = None¶

field_profile: FieldProfile | None = None¶

supported_action_types: tuple[type[Action], ...]¶

valid_two_qubit_site_pairs: tuple[tuple[int, int], ...]¶

__post_init__() → None[source]¶

Check the hardware description and store zone sites in order.

Raises:: ValueError – If the site count, zones, or field profile are invalid.

get_processing_zone(site: int) → str | None[source]¶: Return the processing zone containing a site, if any.

field_at(site: int) → float[source]¶: Return the configured field value at one site.

has_nontrivial_field_profile() → bool[source]¶: Return whether any site differs from the unit field profile.

supports(action_type: type[Action]) → bool[source]¶: Return whether the hardware exposes an action type.

sites_share_processing_zone(*sites: int) → bool[source]¶: Return whether all supplied sites belong to one processing zone.

initial_pzs_busy_until() → tuple[tuple[str, int], ...][source]¶: Return every processing zone as available at the start of a schedule.

to_dict() → dict[str, object][source]¶: Return JSON-compatible architecture metadata.

to_json() → str[source]¶

Serialize architecture metadata as JSON.

Returns:: The serialized architecture object.

classmethod from_dict(data: object, *, action_types: Sequence[type[Action]] | None = None) → Architecture[source]¶

Construct an architecture from a JSON-style mapping.

Parameters:

data – Architecture mapping.
action_types – Additional action classes available when resolving the serialized supported-action catalog.

Returns:

A validated architecture.

Raises:

TypeError – If the architecture or site count has the wrong type.
ValueError – If the mapping has an invalid shape or values.

classmethod from_json(raw: str, *, action_types: Sequence[type[Action]] | None = None) → Architecture[source]¶

Deserialize an architecture from JSON.

Returns:: A validated architecture.

classmethod load(filename: str | Path, *, action_types: Sequence[type[Action]] | None = None) → Architecture[source]¶

Load an architecture from a UTF-8 JSON file.

Returns:: A validated architecture.

class GateTiming[source]¶

Configure gate durations and virtual single-ion rotations.

Rx and Ry use physical controls by default. Rz defaults to a zero-duration virtual frame update, as is common on trapped-ion hardware.

rx: int = 1¶

ry: int = 1¶

rz: int = 0¶

rxx: int = 2¶

ryy: int = 2¶

rzz: int = 2¶

virtual_single_qubit_gates: frozenset[str]¶

__post_init__() → None[source]¶

Ensure the configured timings describe usable gate implementations.

Raises:: ValueError – If a gate name or duration is invalid.

duration_for(gate_name: str) → int[source]¶

Return how many timesteps a gate takes.

Raises:

TypeError – If the stored duration is not an integer.
ValueError – If the hardware does not offer gate_name.

is_virtual(gate_name: str) → bool[source]¶

Return whether a single-ion rotation is implemented virtually.

Raises:: ValueError – If gate_name is not a supported single-ion rotation.

property gate_durations: dict[str, int]¶: Duration of each supported gate, keyed by its lowercase name.

class HardwareTiming[source]¶

Describe the timing and gate implementations offered by the hardware.

transport: TransportTiming¶

gates: GateTiming¶

class LinearCompilerConfig[source]¶

Group the hardware timing and schedule-search settings.

hardware_timing: HardwareTiming¶

search: SearchConfig¶

class SearchConfig[source]¶

Configure how the compiler searches for a schedule.

A finite horizon plans a few gates at a time and commits committed_gates before planning again. Set horizon to None to search the complete circuit at once. heuristic selects the remaining-cost estimate that guides the search: the default None uses a quality-oriented estimate that finds useful schedules faster but may overestimate the remaining time, while zero_heuristic() is admissible and supports exact search when all other limits and shortcuts are also disabled. Any other callable matching HeuristicFn may be supplied instead.

horizon: int | None = 3¶

committed_gates: int = 2¶

iterative_diving_search: bool = True¶

informed_action_prioritization: bool = False¶

num_solutions: int = 1¶

max_frontier_size: int | None = 1000¶

max_compile_time: float | None = 1800.0¶

use_dependencies: bool = True¶

heuristic: HeuristicFn | None = None¶

pre_partition_config: FineGrainedTabuConfig | None = None¶

__post_init__() → None[source]¶

Ensure all search limits are meaningful and mutually consistent.

Raises:

TypeError – If a Boolean option is not Boolean.
ValueError – If a numeric bound or horizon relationship is invalid.

class TransportTiming[source]¶

Configure how many timesteps ion transport operations take.

shuttle: int = 1¶

swap: int = 3¶

__post_init__() → None[source]¶: Ensure every transport operation takes at least one timestep.

class HeuristicFn[source]¶

Bases: Protocol

Estimate the remaining schedule work for one search state.

A custom heuristic supplied through heuristic must accept these arguments. The search always passes them positionally, so an implementation may name its parameters freely. The built-in heuristic() additionally accepts optional caching arguments, which the search passes only to that default.

__call__(state: State, architecture: Architecture, gate_order: Sequence[int], gates: Mapping[int, GateAction], predecessors: Mapping[int, frozenset[int]] | None = None, /) → int[source]¶

Estimate the work still needed to finish the requested gates.

Parameters:

state – Search state to score.
architecture – Hardware layout the schedule targets.
gate_order – Gates to schedule, including completed and running ones; filter with state.completed_gates and state.in_progress_gates.
gates – Gate actions indexed by identifier.
predecessors – Optional map of which gates must precede others.

Returns:

A nonnegative estimate of the remaining schedule time.

zero_heuristic(state: State, architecture: Architecture, gate_order: Sequence[int], gates: Mapping[int, GateAction], predecessors: Mapping[int, frozenset[int]] | None = None, /) → int[source]¶

Estimate nothing about the work left to finish the requested gates.

This admissible estimate turns the search into a uniform-cost search, so the first complete schedule has the minimum makespan among the schedules the configured hardware and action model can express. It usually explores many more states than the default heuristic().

Parameters:

state – Search state to score.
architecture – Hardware layout the schedule targets.
gate_order – Gates to schedule, including completed and running ones.
gates – Gate actions indexed by identifier.
predecessors – Optional map of which gates must precede others.

Returns:

Always 0.

class CompilationResult[source]¶

Contain an executable schedule and compiler diagnostics.

The architecture and action schedule are parallel compilation artifacts. This result also owns search completion, cost, runtime, explored-node count, and the compiler state reached at termination.

status: CompilationStatus¶

schedule: ActionSchedule¶

architecture: Architecture¶

wall_clock_s: float = 0.0¶

score: int | None = None¶

final_state: State | None = None¶

explored_nodes: int | None = None¶

__post_init__() → None[source]¶

Validate compiler diagnostics and the schedule boundary.

Raises:

TypeError – If a result field has the wrong type.
ValueError – If a numeric diagnostic is outside its valid range.

property path: list[Action]¶: A mutable copy of the schedule’s ordered executable operations.

property num_timesteps: int¶: The schedule’s makespan.

property initial_state: MachineState¶: The schedule’s machine-only initial state.

to_dict() → dict[str, object][source]¶: Return the compilation result using JSON-compatible values.

classmethod from_dict(data: object, *, action_types: Sequence[type[Action]] | None = None, action_decoders: ActionDecoders | None = None) → CompilationResult[source]¶

Restore a result from its JSON-compatible representation.

Returns:: The restored compilation result.
Raises:: ValueError – If the document is malformed.

to_json() → str[source]¶

Serialize this compilation result as JSON text.

Returns:: The JSON document.

classmethod from_json(raw: str, *, action_types: Sequence[type[Action]] | None = None, action_decoders: ActionDecoders | None = None) → CompilationResult[source]¶

Restore a result from JSON text.

Returns:: The restored compilation result.

save(filename: str | Path, directory: str | Path = 'outputs/results/json') → Path[source]¶

Write this result to a UTF-8 JSON file.

Parameters:

filename – Output filename, with .json added when omitted.
directory – Directory in which to create the file.

Returns:

The path written.

classmethod load(filename: str | Path, *, action_types: Sequence[type[Action]] | None = None, action_decoders: ActionDecoders | None = None) → CompilationResult[source]¶

Load a result from a UTF-8 JSON file.

Returns:: The restored compilation result.

class CompilationStatus[source]¶

Bases: enum.StrEnum

Describe how compilation ended.

SUCCESS = 'SUCCESS'¶

TIMEOUT = 'TIMEOUT'¶

FAILED = 'FAILED'¶

INTERRUPTED = 'INTERRUPTED'¶

class ActionSchedule[source]¶

Contain the immutable executable boundary shared by downstream stages.

Action IDs are unique within a schedule and remain attached to preserved actions when a transformation inserts or replaces operations. Compiler search status and dynamical-decoupling reports are intentionally absent.

scheduled_actions: tuple[ScheduledAction, ...]¶

num_timesteps: int¶

initial_state: MachineState¶

__post_init__() → None[source]¶

Freeze and validate the executable schedule.

Raises:

TypeError – If a schedule field has the wrong type.
ValueError – If identifiers or timing are inconsistent.

property path: tuple[Action, ...]¶: The ordered executable operations without their metadata.

property next_action_id: int¶: An unused identifier suitable for the next inserted action.

classmethod from_actions(actions: Sequence[Action], initial_state: State | MachineState) → ActionSchedule[source]¶

Create a schedule and assign deterministic action identifiers.

Parameters:

actions – Ordered executable operations.
initial_state – Initial hardware or compiler state. Compiler progress fields are deliberately discarded.

Returns:

The immutable action schedule.

to_dict() → dict[str, object][source]¶: Return the action schedule using JSON-compatible values.

classmethod from_dict(data: object, *, action_types: Sequence[type[Action]] | None = None, action_decoders: ActionDecoders | None = None) → ActionSchedule[source]¶

Restore a schedule from its JSON-compatible representation.

Returns:: The restored action schedule.
Raises:: ValueError – If the action stream or metadata is malformed.

to_json() → str[source]¶

Serialize this schedule as JSON text.

Returns:: The JSON document.

classmethod from_json(raw: str, *, action_types: Sequence[type[Action]] | None = None, action_decoders: ActionDecoders | None = None) → ActionSchedule[source]¶

Restore a schedule from JSON text.

Returns:: The restored action schedule.

save(filename: str | Path) → Path[source]¶

Write this schedule to an explicit UTF-8 JSON file.

Returns:: The path written.

classmethod load(filename: str | Path, *, action_types: Sequence[type[Action]] | None = None, action_decoders: ActionDecoders | None = None) → ActionSchedule[source]¶

Load a schedule from an explicit UTF-8 JSON file.

Returns:: The restored action schedule.

class MachineState[source]¶

Describe hardware state without compiler circuit-progress fields.

positions: tuple[tuple[int, int], ...]¶

ions_busy_until: tuple[tuple[int, int], ...]¶

pzs_busy_until: tuple[tuple[str, int], ...]¶

time: int = 0¶

__post_init__() → None[source]¶

Normalize and validate machine-state values.

Raises:

TypeError – If the machine clock has the wrong type.
ValueError – If state mappings, occupancy, or timestamps are inconsistent.

classmethod from_compiler_state(state: State) → MachineState[source]¶

Copy only hardware fields from a compiler state.

Availability timestamps in a compiler state may refer to resources that became free before its current clock. The machine-only view canonicalizes those timestamps to the current clock.

Parameters:: state – Compiler state whose circuit progress is discarded.
Returns:: The canonical machine-only state.

to_replay_state() → State[source]¶

Return a state suitable for schedule replay.

Returns:: A compiler-state value with empty circuit-progress fields.

to_dict() → dict[str, object][source]¶: Return this machine state using JSON-compatible values.

classmethod from_dict(data: object) → MachineState[source]¶

Restore a machine state from JSON-compatible values.

Returns:: The restored machine-only state.

class ScheduledAction[source]¶

Pair one operation with an ID stable across schedule passes.

action_id: int¶

action: Action¶

__post_init__() → None[source]¶

Validate the action ID and value.

Raises:

TypeError – If a field has the wrong type.
ValueError – If the ID is invalid.