mqt.ionshuttler.linear.state

Ion placement, hardware availability, and circuit progress.

Module Contents

class State

Describe the current state of a Linear compilation.

Ion positions, availability times, and the current time describe the hardware. Completed and running gate identifiers describe progress through the circuit. Physical actions change only the hardware-related information; the compiler updates circuit progress separately.

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

completed_gates: frozenset[int]

in_progress_gates: tuple[tuple[int, int], ...]

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

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

time: int

__post_init__() → None

Normalize tuple fields so equality and hashing are order-independent.

to_dict(state: State) → dict[int, int]

Return the ion-to-site position mapping.

ions_busy_dict(state: State) → dict[int, int]

Return the ion-to-free-time mapping.

pzs_busy_dict(state: State) → dict[str, int]

Return the processing-zone-to-free-time mapping.

in_progress_dict(state: State) → dict[int, int]

Return the gate-to-finish-time mapping.

has_pending_timed_work(state: State) → bool

Return whether advancing time could let scheduled work finish.

The compiler uses this to avoid exploring pointless idle time. Waiting is still a valid schedule operation when no work is running.

to_site_occupancy(state: State, num_sites: int) → list[int | None]

Convert ion positions to a site-indexed occupancy list.

Parameters:

• state – State to convert.

• num_sites – Length of the architecture.

Returns:

Ion identifiers indexed by site, with None for empty sites.

Raises:

ValueError – If an ion position is outside the requested site range.

to_metadata_dict(state: State, num_sites: int) → dict[str, object]

Return the JSON-compatible initial-state metadata.

create_initial_state(num_ions: int, architecture: Architecture, initial_positions: list[int] | tuple[int, ...] | None = None) → State

Create a starting state with centered or explicitly placed ions.

Parameters:

• num_ions – Number of logical ions to place.

• architecture – Architecture providing sites and processing zones.

• initial_positions – Optional site for each ion, ordered by ion identifier. Defaults to None, which uses the centered-placement formula.

Returns:

The initial state at time zero, before any gates have started.

Raises:

ValueError – If the ion count or explicit positions are invalid.

normalize_initial_state(state: State, architecture: Architecture) → State

Check a starting state against the hardware model and fill in missing zones.

Parameters:

• state – Candidate initial compiler state.

• architecture – Hardware model against which to validate the state.

Returns:

A state containing an availability time for every processing zone.

Raises:

ValueError – If occupancy or processing-zone references are invalid.