qoolqit

source package qoolqit

A Python library for algorithm development in the Rydberg Analog Model.

Classes

DataGraph — The main graph structure to represent problem data.
InteractionEmbedder — A matrix to graph embedder using the interaction embedding algorithm.
InteractionEmbeddingConfig — Configuration parameters for the interaction embedding.
SpringLayoutConfig — Configuration parameters for the spring-layout embedding.
SpringLayoutEmbedder — A graph to graph embedder using the spring layout algorithm.
Blackman — A Blackman window of a specified duration and area under the curve.
Constant — A constant waveform over a given duration.
Delay — An empty waveform.
Interpolated — A waveform created from interpolation of a set of data points.
PiecewiseLinear — A piecewise linear waveform.
Ramp — A ramp that linearly interpolates between an initial and final value.
Sin — An arbitrary sine over a given duration.
Drive — The drive Hamiltonian acting over a duration.
Register — The Register in QoolQit, representing a set of qubits with coordinates.
QuantumProgram — A program representing a Sequence acting on a Register of qubits.
CompilerProfile
SequenceCompiler — Compiles a QoolQit Register and Drive to a Device.
AnalogDevice — A realistic device for analog sequence execution.
DigitalAnalogDevice — A device with digital and analog capabilities.
MockDevice — A virtual device for unconstrained prototyping.
Device — QoolQit Device wrapper around a Pulser BaseDevice.

Functions

available_default_devices — Show the default available devices in QooQit.

source class DataGraph(edges: Iterable = [])

Bases : BaseGraph

The main graph structure to represent problem data.

Default constructor for the BaseGraph.

Parameters

edges : Iterable — set of edge tuples (i, j)

Attributes

adj — Graph adjacency object holding the neighbors of each node.
name — String identifier of the graph.
nodes — A NodeView of the Graph as G.nodes or G.nodes().
edges — An EdgeView of the Graph as G.edges or G.edges().
degree — A DegreeView for the Graph as G.degree or G.degree().
sorted_edges : set — Returns the set of edges (u, v) such that (u < v).
all_node_pairs : set — Return a list of all possible node pairs in the graph.
has_coords : bool — Check if the graph has coordinates.
has_edges : bool — Check if the graph has edges.
coords : dict — Return the dictionary of node coordinates.
node_weights : dict — Return the dictionary of node weights.
edge_weights : dict — Return the dictionary of edge weights.
has_node_weights : bool — Check if the graph has node weights.
has_edge_weights : bool — Check if the graph has edge weights.

Methods

line — Constructs a line graph, with the respective coordinates.
circle — Constructs a circle graph, with the respective coordinates.
random_er — Constructs an Erdős–Rényi random graph.
triangular — Constructs a triangular lattice graph, with respective coordinates.
hexagonal — Constructs a hexagonal lattice graph, with respective coordinates.
heavy_hexagonal — Constructs a heavy-hexagonal lattice graph, with respective coordinates.
square — Constructs a square lattice graph, with respective coordinates.
random_ud — Constructs a random unit-disk graph.
from_matrix — Constructs a graph from a symmetric square matrix.
set_ud_edges — Reset the set of edges to be equal to the set of unit-disk edges.

source classmethod DataGraph.line(n: int, spacing: float = 1.0) → DataGraph

Constructs a line graph, with the respective coordinates.

Parameters

n : int — number of nodes.
spacing : float — distance between each node.

source classmethod DataGraph.circle(n: int, spacing: float = 1.0, center: tuple = (0.0, 0.0)) → DataGraph

Constructs a circle graph, with the respective coordinates.

Parameters

n : int — number of nodes.
spacing : float — distance between each node.
center : tuple — point (x, y) to set as the center of the graph.

source classmethod DataGraph.random_er(n: int, p: float, seed: int | None = None) → DataGraph

Constructs an Erdős–Rényi random graph.

Parameters

n : int — number of nodes.
p : float — probability that any two nodes connect.
seed : int | None — random seed.

source classmethod DataGraph.triangular(m: int, n: int, spacing: float = 1.0) → DataGraph

Constructs a triangular lattice graph, with respective coordinates.

Parameters

m : int — Number of rows of triangles.
n : int — Number of columns of triangles.
spacing : float — The distance between adjacent nodes on the final lattice.

source classmethod DataGraph.hexagonal(m: int, n: int, spacing: float = 1.0) → DataGraph

Constructs a hexagonal lattice graph, with respective coordinates.

Parameters

m : int — Number of rows of hexagons.
n : int — Number of columns of hexagons.
spacing : float — The distance between adjacent nodes on the final lattice.

source classmethod DataGraph.heavy_hexagonal(m: int, n: int, spacing: float = 1.0) → DataGraph

Constructs a heavy-hexagonal lattice graph, with respective coordinates.

Parameters

m : int — Number of rows of hexagons.
n : int — Number of columns of hexagons.
spacing : float — The distance between adjacent nodes on the final lattice.

Notes

The heavy-hexagonal lattice is a regular hexagonal lattice where each edge is decorated with an additional lattice site.

source classmethod DataGraph.square(m: int, n: int, spacing: float = 1.0) → DataGraph

Constructs a square lattice graph, with respective coordinates.

Parameters

m : int — Number of rows of square.
n : int — Number of columns of square.
spacing : float — The distance between adjacent nodes on the final lattice.

source classmethod DataGraph.random_ud(n: int, radius: float = 1.0, L: float | None = None) → DataGraph

Constructs a random unit-disk graph.

The nodes are sampled uniformly from a square of size (L x L). If L is not given, it is estimated based on a rough heuristic that of packing N nodes on a square of side L such that the expected minimum distance is R, leading to L ~ (R / 2) * sqrt(π * n).

Parameters

n : int — number of nodes.
radius : float — radius to use for defining the unit-disk edges.
L : float | None — size of the square on which to sample the node coordinates.

source classmethod DataGraph.from_matrix(data: ArrayLike) → DataGraph

Constructs a graph from a symmetric square matrix.

The diagonal values are set as the node weights. For each entry (i, j) where M[i, j] != 0 an edge (i, j) is added to the graph and the value M[i, j] is set as its weight.

Parameters

data : ArrayLike — symmetric square matrix.

Raises

ValueError

source property DataGraph.node_weights: dict

Return the dictionary of node weights.

source property DataGraph.edge_weights: dict

Return the dictionary of edge weights.

source property DataGraph.has_node_weights: bool

Check if the graph has node weights.

Requires all nodes to have a weight.

source property DataGraph.has_edge_weights: bool

Check if the graph has edge weights.

Requires all edges to have a weight.

source method DataGraph.set_ud_edges(radius: float) → None

Reset the set of edges to be equal to the set of unit-disk edges.

source class InteractionEmbedder()

Bases : MatrixToGraphEmbedder[InteractionEmbeddingConfig]

A matrix to graph embedder using the interaction embedding algorithm.

Attributes

config : ConfigType — Returns the config for the embedding algorithm.
algorithm : Callable — Returns the callable to the embedding algorithm.
info : str — Prints info about the embedding algorithm.

source dataclass InteractionEmbeddingConfig(method: str = 'Nelder-Mead', maxiter: int = 200000, tol: float = 1e-08)

Bases : EmbeddingConfig

Configuration parameters for the interaction embedding.

source dataclass SpringLayoutConfig(k: float | None = None, iterations: int = 50, threshold: float = 0.0001, seed: int | None = None)

Bases : EmbeddingConfig

Configuration parameters for the spring-layout embedding.

source class SpringLayoutEmbedder()

Bases : GraphToGraphEmbedder[SpringLayoutConfig]

A graph to graph embedder using the spring layout algorithm.

Attributes

config : ConfigType — Returns the config for the embedding algorithm.
algorithm : Callable — Returns the callable to the embedding algorithm.
info : str — Prints info about the embedding algorithm.

source class Blackman(duration: float, area: float)

Bases : Waveform

A Blackman window of a specified duration and area under the curve.

Implements the Blackman window shaped waveform blackman(t) = A(0.42 - 0.5cos(αt) + 0.08cos(2αt)) A = area/(0.42duration) α = 2π/duration

Initializes a new Blackman waveform.

See

https://en.wikipedia.org/wiki/Window_function#:~:text=Blackman%20window

Parameters

duration : float — The waveform duration.
area : float — The integral of the waveform.

Example

blackman_wf = Blackman(100.0, area=3.14)

Attributes

duration : float — Returns the duration of the waveform.
params : dict[str, float | np.ndarray] — Dictionary of parameters used by the waveform.

Methods

source method Blackman.function(t: float) → float

source method Blackman.max() → float

source method Blackman.min() → float

source class Constant(duration: float, value: float)

Bases : Waveform

A constant waveform over a given duration.

Parameters

duration : float — the total duration.
value : float — the value to take during the duration.

Attributes

duration : float — Returns the duration of the waveform.
params : dict[str, float | np.ndarray] — Dictionary of parameters used by the waveform.

Methods

source method Constant.function(t: float) → float

source method Constant.max() → float

source method Constant.min() → float

source class Delay(duration: float, *args: float, **kwargs: float | np.ndarray)

Bases : Waveform

An empty waveform.

Initializes the Waveform.

Parameters

duration : float — the total duration of the waveform.

Attributes

duration : float — Returns the duration of the waveform.
params : dict[str, float | np.ndarray] — Dictionary of parameters used by the waveform.

Methods

source method Delay.function(t: float) → float

source method Delay.max() → float

source method Delay.min() → float

source class Interpolated(duration: float, values: ArrayLike, times: Optional[ArrayLike] = None, interpolator: str = 'PchipInterpolator', **interpolator_kwargs: Any)

Bases : Waveform

A waveform created from interpolation of a set of data points.

Initializes a new Interpolated waveform.

Parameters

duration : int — The waveform duration (in ns).
values : ArrayLike — Values of the interpolation points. Must be a list of castable to float or a parametrized object.
times : ArrayLike — Fractions of the total duration (between 0 and 1), indicating where to place each value on the time axis. Must be a list of castable to float or a parametrized object. If not given, the values are spread evenly throughout the full duration of the waveform.
interpolator : str — The SciPy interpolation class to use. Supports "PchipInterpolator" and "interp1d".

Attributes

duration : float — Returns the duration of the waveform.
params : dict[str, float | np.ndarray] — Dictionary of parameters used by the waveform.

Methods

source method Interpolated.function(t: float) → float

source method Interpolated.min() → float

source method Interpolated.max() → float

source class PiecewiseLinear(durations: list | tuple, values: list | tuple)

Bases : CompositeWaveform

A piecewise linear waveform.

Creates a composite waveform of N ramps that linearly interpolate through the given N+1 values.

Parameters

durations : list | tuple — list or tuple of N duration values.
values : list | tuple — list or tuple of N+1 waveform values.

Attributes

duration : float — Returns the duration of the waveform.
params : dict[str, float | np.ndarray] — Dictionary of parameters used by the waveform.
durations : list[float] — Returns the list of durations of each individual waveform.
times : list[float] — Returns the list of times when each individual waveform starts.
waveforms : list[Waveform] — Returns a list of the individual waveforms.
n_waveforms : int — Returns the number of waveforms.

source class Ramp(duration: float, initial_value: float, final_value: float)

Bases : Waveform

A ramp that linearly interpolates between an initial and final value.

Parameters

duration : float — the total duration.
initial_value : float — the initial value at t = 0.
final_value : float — the final value at t = duration.

Attributes

duration : float — Returns the duration of the waveform.
params : dict[str, float | np.ndarray] — Dictionary of parameters used by the waveform.

Methods

source method Ramp.function(t: float) → float

source method Ramp.max() → float

source method Ramp.min() → float

source class Sin(duration: float, amplitude: float = 1.0, omega: float = 1.0, phi: float = 0.0, shift: float = 0.0)

Bases : Waveform

An arbitrary sine over a given duration.

Parameters

duration : float — the total duration.
amplitude : float — the amplitude of the sine wave.
omega : float — the frequency of the sine wave.
phi : float — the phase of the sine wave.
shift : float — the vertical shift of the sine wave.

Attributes

duration : float — Returns the duration of the waveform.
params : dict[str, float | np.ndarray] — Dictionary of parameters used by the waveform.

Methods

function

source method Sin.function(t: float) → float

source class Drive(*args: Any, amplitude: Waveform | None = None, detuning: Waveform | None = None, weighted_detunings: list[WeightedDetuning] | None = None, phase: float = 0.0)

The drive Hamiltonian acting over a duration.

Default constructor for the Drive.

Must be instantiated with keyword arguments. Accepts either an amplitude waveform, a detuning waveform, or both. A phase value can also be passed.

Parameters

amplitude : Waveform | None — waveform representing Ω(t) in the drive Hamiltonian.
detuning : Waveform | None — waveform representing δ(t) in the drive Hamiltonian.
phase : float — phase value ɸ for the amplitude term.
weighted_detunings : list[WeightedDetuning] | None — additional waveforms and weights applied to individual qubits. Note that these detunings are not supported on all devices.

Attributes

amplitude : Waveform — The amplitude waveform in the drive.
detuning : Waveform — The detuning waveform in the drive.
weighted_detunings : Sequence[WeightedDetuning] — Detunings applied to individual qubits.
phase : float — The phase value in the drive.

Methods

draw

source property Drive.amplitude: Waveform

The amplitude waveform in the drive.

source property Drive.detuning: Waveform

The detuning waveform in the drive.

source property Drive.weighted_detunings: Sequence[WeightedDetuning]

Detunings applied to individual qubits.

source property Drive.phase: float

The phase value in the drive.

source property Drive.duration: float

source method Drive.draw(n_points: int = 500, return_fig: bool = False) → Figure | None

source class Register(qubits: dict)

The Register in QoolQit, representing a set of qubits with coordinates.

Default constructor for the Register.

Parameters

qubits : dict — a dictionary of qubits and respective coordinates {q: (x, y), ...}.

Attributes

qubits : dict — Returns the dictionary of qubits and respective coordinates.
qubits_ids : list — Returns the qubit keys.
n_qubits : int — Number of qubits in the Register.

Methods

from_graph — Initializes a Register from a graph that has coordinates.
from_coordinates — Initializes a Register from a list of coordinates.
distances — Distance between each qubit pair.
min_distance — Minimum distance between all qubit pairs.
interactions — Interaction 1/r^6 between each qubit pair.
draw — Draw the register.

source classmethod Register.from_graph(graph: DataGraph) → Register

Initializes a Register from a graph that has coordinates.

Parameters

graph : DataGraph — a DataGraph instance.

Raises

ValueError

source classmethod Register.from_coordinates(coords: list) → Register

Initializes a Register from a list of coordinates.

Parameters

coords : list — a list of coordinates [(x, y), ...]

Raises

TypeError

source property Register.qubits: dict

Returns the dictionary of qubits and respective coordinates.

source property Register.qubits_ids: list

Returns the qubit keys.

source property Register.n_qubits: int

Number of qubits in the Register.

source method Register.distances() → dict

Distance between each qubit pair.

source method Register.min_distance() → float

Minimum distance between all qubit pairs.

source method Register.interactions() → dict

Interaction 1/r^6 between each qubit pair.

source method Register.draw(return_fig: bool = False) → plt.Figure | None

Draw the register.

Parameters

return_fig : bool — boolean argument to return the plt.Figure instance.

source class QuantumProgram(register: Register, drive: Drive)

A program representing a Sequence acting on a Register of qubits.

Parameters

register : Register — the register of qubits, defining their positions.
drive : Drive — the drive acting on qubits, defining amplitude, detuning and phase.

Attributes

register : Register — The register of qubits.
drive : Drive — The driving waveforms.
is_compiled : bool — Check if the program has been compiled.
compiled_sequence : PulserSequence — The Pulser sequence compiled to a specific device.

Methods

compile_to — Compiles the given program to a device.
draw

source property QuantumProgram.register: Register

The register of qubits.

source property QuantumProgram.drive: Drive

The driving waveforms.

source property QuantumProgram.is_compiled: bool

Check if the program has been compiled.

source property QuantumProgram.compiled_sequence: PulserSequence

The Pulser sequence compiled to a specific device.

source method QuantumProgram.compile_to(device: Device, profile: CompilerProfile = CompilerProfile.DEFAULT) → None

Compiles the given program to a device.

Parameters

device : Device — the Device to compile to.
profile : CompilerProfile — the compiler profile to use during compilation.

source method QuantumProgram.draw(n_points: int = 500, compiled: bool = False, return_fig: bool = False) → Figure | None

Raises

ValueError

source enum CompilerProfile(*args, **kwds)

Bases : StrEnum

Attributes

DEFAULT
MAX_AMPLITUDE
MAX_DURATION
MIN_DISTANCE

source class SequenceCompiler(register: Register, drive: Drive, device: Device)

Compiles a QoolQit Register and Drive to a Device.

Initializes the compiler.

Parameters

register : Register — the QoolQit Register.
drive : Drive — the QoolQit Drive.
device : Device — the QoolQit Device.

Attributes

profile : CompilerProfile — The compiler profile to use.

Methods

compile_sequence

source property SequenceCompiler.register: Register

source property SequenceCompiler.drive: Drive

source property SequenceCompiler.device: Device

source property SequenceCompiler.profile: CompilerProfile

The compiler profile to use.

source method SequenceCompiler.compile_sequence() → PulserSequence

Raises

ValueError
CompilationError

source available_default_devices() → None

Show the default available devices in QooQit.

source class AnalogDevice()

Bases : Device

A realistic device for analog sequence execution.

Attributes

specs : dict — Return the device specification constrains.

source class DigitalAnalogDevice()

Bases : Device

A device with digital and analog capabilities.

Attributes

specs : dict — Return the device specification constrains.

source class MockDevice()

Bases : Device

A virtual device for unconstrained prototyping.

Attributes

specs : dict — Return the device specification constrains.

source class Device(pulser_device: BaseDevice, default_converter: Optional[UnitConverter] = None)

QoolQit Device wrapper around a Pulser BaseDevice.

Parameters

pulser_device : BaseDevice — a BaseDevice to build the QoolQit device from.
default_converter : Optional[UnitConverter] — optional unit converter to handle unit conversion. Defaults to the unit converter that rescales energies by the maximum allowed amplitude by the device.

Examples

From Pulser device:

qoolqit_device = Device(pulser_device=pulser_device)

From remote Pulser device:

from pulser_pasqal import PasqalCloud
from qoolqit import Device

# Fetch the remote device from the connection
connection = PasqalCloud()
pulser_fresnel_device = connection.fetch_available_devices()["FRESNEL"]

# Wrap a Pulser device object into a QoolQit Device
fresnel_device = Device(pulser_device=PulserFresnelDevice)

From custom Pulser device:

from dataclasses import replace
from pulser import AnalogDevice
from qoolqit import Device

# Converting the pulser Device object in a VirtualDevice object
VirtualAnalog = AnalogDevice.to_virtual()
# Replacing desired values
ModdedAnalogDevice = replace(
    VirtualAnalog,
    max_radial_distance=100,
    max_sequence_duration=7000
    )

# Wrap a Pulser device object into a QoolQit Device
mod_analog_device = Device(pulser_device=ModdedAnalogDevice)

Attributes

specs : dict — Return the device specification constrains.

Methods

reset_converter — Resets the unit converter to the default one.
set_time_unit — Changes the unit converter according to a reference time unit.
set_energy_unit — Changes the unit converter according to a reference energy unit.
set_distance_unit — Changes the unit converter according to a reference distance unit.
info — Show the device short description and constrains.
from_connection — Return the specified device from the selected device from a connection.

source property Device.converter: UnitConverter

source method Device.reset_converter() → None

Resets the unit converter to the default one.

source method Device.set_time_unit(time: float) → None

Changes the unit converter according to a reference time unit.

source method Device.set_energy_unit(energy: float) → None

Changes the unit converter according to a reference energy unit.

source method Device.set_distance_unit(distance: float) → None

Changes the unit converter according to a reference distance unit.

source property Device.specs: dict

Return the device specification constrains.

source property Device.name: str

source method Device.info() → None

Show the device short description and constrains.

source classmethod Device.from_connection(connection: RemoteConnection, name: str) → Device

Return the specified device from the selected device from a connection.

Available devices through the provided connection are can be seen with the connection.fetch_available_devices() method.

Parameters

connection : RemoteConnection — connection object to fetch the available devices.
name : str — The name of the desired device.

Example

fresnel_device = Device.from_connection(connection=PasqalCloud(), name="FRESNEL")

Raises

ValueError