qek.data.extractors

module
qek.data.extractors

High-Level API to compile raw data (graphs) and process it on a quantum device, either a local emulator, a remote emulator or a physical QPI.

Classes

Compiled — The result of compiling a graph for execution on a quantum device.
Feature — A feature extracted from raw data.
BaseExtracted — Data extracted by one of the subclasses of BaseExtractor.
SyncExtracted — Data extracted synchronously, i.e. no need to wait for a remote server.
BaseExtractor — The base of the hierarchy of extractors.
QutipExtractor — A Extractor that uses the Qutip Emulator to run sequences compiled from graphs.
EmuMPSExtractor — A Extractor that uses the emu-mps Emulator to run sequences compiled from graphs.
PasqalCloudExtracted — Data extracted from the cloud API, i.e. we need wait for a remote server.
BaseRemoteExtractor — An Extractor that uses a remote Quantum Device published on Pasqal Cloud, to run sequences compiled from graphs.
RemoteQPUExtractor — An Extractor that uses a remote QPU published on Pasqal Cloud, to run sequences compiled from graphs.
RemoteEmuMPSExtractor — An Extractor that uses a remote high-performance emulator (EmuMPS) published on Pasqal Cloud, to run sequences compiled from graphs.

dataclass
Compiled (graph: BaseGraph, sequence: pl.Sequence)

The result of compiling a graph for execution on a quantum device.

dataclass
Feature (data: NDArray[np.floating])

A feature extracted from raw data.

class
BaseExtracted (device: Device)

Bases : abc.ABC

Data extracted by one of the subclasses of BaseExtractor.

Note that the list of processed data will generally not contain all the graphs ingested by the Extractor, as not all graphs may not be compiled for a given device.

Attributes

raw_data : list[BaseGraph] — A subset of the graphs ingested by the Extractor.
targets : list[int] | None — If available, the machine-learning targets for these graphs, in the same order and with the same number of entrie as raw_data.
states : list[dict[str, int]] — The quantum states extracted from raw_data by executing sequences on the device, in the same order and with the same number of entries as raw_data.

Methods

features — The features extracted from raw_data by processing states, in the same order and with the same number of entries as raw_data.
save_dataset — Saves the processed dataset to a JSON file.

property
processed_data : list[processed_data.ProcessedData]

property
raw_data : list[BaseGraph]

A subset of the graphs ingested by the Extractor.

property
targets : list[int] | None

If available, the machine-learning targets for these graphs, in the same order and with the same number of entrie as raw_data.

property
states : list[dict[str, int]]

The quantum states extracted from raw_data by executing sequences on the device, in the same order and with the same number of entries as raw_data.

method
features (size_max: int | None) → list[Feature]

The features extracted from raw_data by processing states, in the same order and with the same number of entries as raw_data.

By default, the features extracted are the distribution of excitation levels based on states. However, subclasses may override this method to provide custom features extraction.

Parameters

size_max (optional) Performance/precision lever. If specified, specifies the number of qubits to take into account from all — the states. If size_max is lower than the number of qubits used to extract self.states[i] (i.e. the number of qubits in self.sequences[i]), then only take into account the size_max first qubits of this state to extract self.features(size_max)[i]. If, on the other hand, size_max is greater than the number of qubits used to extract self.states[i], pad self.features(size_max)[i] with 0s. If unspecified, use the largest number of qubits in selfsequences.

method
save_dataset (file_path: Path) → None

Saves the processed dataset to a JSON file.

Note: This does NOT attempt to save the graphs.

Parameters

dataset — The dataset to be saved.
file_path : Path — The path where the dataset will be saved as a JSON file.

class
SyncExtracted (raw_data: list[BaseGraph], targets: list[int] | None, sequences: list[pl.Sequence], states: list[dict[str, int]])

Bases : BaseExtracted

Data extracted synchronously, i.e. no need to wait for a remote server.

property
processed_data : list[ProcessedData]

property
raw_data : list[BaseGraph]

property
targets : list[int] | None

property
sequences : list[pl.Sequence]

property
states : list[dict[str, int]]

class
BaseExtractor (device: Device, compiler: BaseGraphCompiler[GraphType], path: Path | None = None)

Bases : abc.ABC, Generic[GraphType]

The base of the hierarchy of extractors.

The role of extractors is to take a list of raw data (here, labelled graphs) into processed data containing machine-learning features (here, excitation vectors).

Parameters

path : Path | None — If specified, the processed data will be saved to this file as JSON once the execution is complete.
device : Device — A quantum device for which the data should be prepared.
compiler : BaseGraphCompiler[GraphType] — A graph compiler, in charge of converting graphs to Pulser Sequences, the format that can be executed on a quantum device.

Methods

save — Saves a dataset to a JSON file.
compile — Compile all pending graphs into Pulser sequences that the Quantum Device may execute.
add_graphs — Add new graphs to compile and run.
run — Run compiled graphs.

method
save (snapshot: list[ProcessedData]) → None

Saves a dataset to a JSON file.

Parameters

dataset : list[ProcessedData] — The dataset to be saved, containing RegisterData instances.
file_path : str — The path where the dataset will be saved as a JSON file.

method
compile (filter: Callable[[BaseGraph, pl.Sequence, int], bool] | None = None) → list[Compiled]

Compile all pending graphs into Pulser sequences that the Quantum Device may execute.

Once this method has succeeded, the results are stored in self.sequences.

Raises

Exception

method
add_graphs (graphs: Sequence[GraphType] | Dataset[GraphType]) → None

Add new graphs to compile and run.

method
run () → BaseExtracted

Run compiled graphs.

You will need to call self.compile first, to make sure that the graphs are compiled.

Returns

BaseExtracted — Data extracted by this extractor.

Not all extractors may return the same data, so please take a look at the documentation of the extractor you are using.

Raises

Exception

class
QutipExtractor (compiler: BaseGraphCompiler[GraphType], device: Device = pl.devices.AnalogDevice, path: Path | None = None)

Bases : BaseExtractor[GraphType]

A Extractor that uses the Qutip Emulator to run sequences compiled from graphs.

Performance note: emulating a quantum device on a classical computer requires considerable amount of resources, so this Extractor may be slow or require too much memory.

Parameters

path : Path | None — Path to store the result of the run, for future uses. To reload the result of a previous run, use LoadExtractor.
compiler : BaseGraphCompiler[GraphType] — A graph compiler, in charge of converting graphs to Pulser Sequences, the format that can be executed on a quantum device.
device : Device — A device to use. For general experiments, the default device AnalogDevice is a perfectly reasonable choice.

Methods

run — Run the compiled graphs.

method
run (max_qubits: int = 8) → SyncExtracted

Run the compiled graphs.

As emulating a quantum device is slow consumes resources and time exponential in the number of qubits, for the sake of performance, we limit the number of qubits in the execution of this extractor.

Parameters

max_qubits : int — Skip any sequence that require strictly more than max_qubits. Defaults to 8.

Returns

SyncExtracted — Processed data for all the sequences that were executed.

class
EmuMPSExtractor (compiler: BaseGraphCompiler[GraphType], device: Device = pl.devices.AnalogDevice, path: Path | None = None)

Bases : BaseExtractor[GraphType]

A Extractor that uses the emu-mps Emulator to run sequences compiled from graphs.

Performance note: emulating a quantum device on a classical computer requires considerable amount of resources, so this Extractor may be slow or require too much memory. If should, however, be faster than QutipExtractor in most cases.

Parameters

path : Path | None — Path to store the result of the run, for future uses. To reload the result of a previous run, use LoadExtractor.
compiler : BaseGraphCompiler[GraphType] — A graph compiler, in charge of converting graphs to Pulser Sequences, the format that can be executed on a quantum device.
device : Device — A device to use. For general experiments, the default device AnalogDevice is a perfectly reasonable choice.

Methods

run — Run the compiled graphs.

method
run (max_qubits: int = 10, dt: int = 10) → BaseExtracted

Run the compiled graphs.

As emulating a quantum device is slow consumes resources and time exponential in the number of qubits, for the sake of performance, we limit the number of qubits in the execution of this extractor.

Parameters

max_qubits : int — Skip any sequence that require strictly more than max_qubits. Defaults to 8.
dt : int — The duration of the simulation step, in us. Defaults to 10.

Returns

BaseExtracted — Processed data for all the sequences that were executed.

class
PasqalCloudExtracted (compiled: list[Compiled], job_ids: list[str], sdk: SDK, state_extractor: Callable[[Job, pl.Sequence], dict[str, int] | None], path: Path | None = None)

Bases : BaseExtracted

Data extracted from the cloud API, i.e. we need wait for a remote server.

Prepare for reception of data.

Performance note

If your code is meant to be executed as part of an interactive application or a server, you should consider calling await extracted before your first call to any of the methods of extracted. Otherwise, you will block the main thread.

If you are running this as part of an experiment, a Jupyter notebook, etc. you do not need to do so.

Parameters

compiled : list[Compiled] — The result of compiling a set of graphs.
job_ids : list[str] — The ids of the jobs on the cloud API, in the same order as compiled.
state_extractor : Callable[[Job, pl.Sequence], dict[str, int] | None] — A callback used to extract the counter from a job. Used as various cloud back-ends return different formats.
path : Path | None — If provided, a path at which to save the results once they're available.

property
processed_data : list[ProcessedData]

property
raw_data : list[BaseGraph]

property
targets : list[int] | None

property
sequences : list[pl.Sequence]

property
states : list[dict[str, int]]

class
BaseRemoteExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str, password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

Bases : BaseExtractor[GraphType], Generic[GraphType]

An Extractor that uses a remote Quantum Device published on Pasqal Cloud, to run sequences compiled from graphs.

Performance note (servers and interactive applications only)

If you are running this as part of an experiment, a Jupyter notebook, etc. you may ignore this performance note.

Parameters

path : Path | None — Path to store the result of the run, for future uses. To reload the result of a previous run, use LoadExtractor.
project_id : str — The ID of the project on the Pasqal Cloud API.
username : str — Your username on the Pasqal Cloud API.
password : str | None — Your password on the Pasqal Cloud API. If you leave this to None, you will need to enter your password manually.
device_name : str — The name of the device to use. As of this writing, the default value of "FRESNEL" represents the latest QPU available through the Pasqal Cloud API.
job_id — Use this to resume a workflow e.g. after turning off your computer while the QPU was executing your sequences. Warning: A job started with one executor MUST NOT be resumed with a different executor.

Methods

run — Launch the extraction.

property
job_ids : list[str] | None

method
run () → PasqalCloudExtracted

Launch the extraction.

Raises

NotImplementedError

class
RemoteQPUExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str = 'FRESNEL', password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

Bases : BaseRemoteExtractor[GraphType]

An Extractor that uses a remote QPU published on Pasqal Cloud, to run sequences compiled from graphs.

Performance note

as of this writing, the waiting lines for a QPU may be very long. You may use this Extractor to resume your workflow with a computation that has been previously started.

Performance note (servers and interactive applications only)

If you are running this as part of an experiment, a Jupyter notebook, etc. you may ignore this performance note.

Parameters

path : Path | None — Path to store the result of the run, for future uses. To reload the result of a previous run, use LoadExtractor.
project_id : str — The ID of the project on the Pasqal Cloud API.
username : str — Your username on the Pasqal Cloud API.
password : str | None — Your password on the Pasqal Cloud API. If you leave this to None, you will need to enter your password manually.
device_name : str — The name of the device to use. As of this writing, the default value of "FRESNEL" represents the latest QPU available through the Pasqal Cloud API.
job_id — Use this to resume a workflow e.g. after turning off your computer while the QPU was executing your sequences.

Methods

run

method
run () → PasqalCloudExtracted

class
RemoteEmuMPSExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str = 'FRESNEL', password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

Bases : BaseRemoteExtractor[GraphType]

An Extractor that uses a remote high-performance emulator (EmuMPS) published on Pasqal Cloud, to run sequences compiled from graphs.

Performance note (servers and interactive applications only)

If you are running this as part of an experiment, a Jupyter notebook, etc. you may ignore this performance note.

Parameters

path : Path | None — Path to store the result of the run, for future uses. To reload the result of a previous run, use LoadExtractor.
project_id : str — The ID of the project on the Pasqal Cloud API.
username : str — Your username on the Pasqal Cloud API.
password : str | None — Your password on the Pasqal Cloud API. If you leave this to None, you will need to enter your password manually.
device_name : str — The name of the device to use. As of this writing, the default value of "FRESNEL" represents the latest QPU available through the Pasqal Cloud API.
job_id — Use this to resume a workflow e.g. after turning off your computer while the QPU was executing your sequences.

Methods

run

method
run (dt: int = 10) → PasqalCloudExtracted

Previous
Overview Next
qek.data.graphs

qek.data.extractors

module qek.data.extractors

dataclass Compiled (graph: BaseGraph, sequence: pl.Sequence)

dataclass Feature (data: NDArray[np.floating])

class BaseExtracted (device: Device)

property processed_data : list[processed_data.ProcessedData]

property raw_data : list[BaseGraph]

property targets : list[int] | None

property states : list[dict[str, int]]

method features (size_max: int | None) → list[Feature]

method save_dataset (file_path: Path) → None

class SyncExtracted (raw_data: list[BaseGraph], targets: list[int] | None, sequences: list[pl.Sequence], states: list[dict[str, int]])

property processed_data : list[ProcessedData]

property raw_data : list[BaseGraph]

property targets : list[int] | None

property sequences : list[pl.Sequence]

property states : list[dict[str, int]]

class BaseExtractor (device: Device, compiler: BaseGraphCompiler[GraphType], path: Path | None = None)

method save (snapshot: list[ProcessedData]) → None

method compile (filter: Callable[[BaseGraph, pl.Sequence, int], bool] | None = None) → list[Compiled]

method add_graphs (graphs: Sequence[GraphType] | Dataset[GraphType]) → None

method run () → BaseExtracted

class QutipExtractor (compiler: BaseGraphCompiler[GraphType], device: Device = pl.devices.AnalogDevice, path: Path | None = None)

method run (max_qubits: int = 8) → SyncExtracted

class EmuMPSExtractor (compiler: BaseGraphCompiler[GraphType], device: Device = pl.devices.AnalogDevice, path: Path | None = None)

method run (max_qubits: int = 10, dt: int = 10) → BaseExtracted

class PasqalCloudExtracted (compiled: list[Compiled], job_ids: list[str], sdk: SDK, state_extractor: Callable[[Job, pl.Sequence], dict[str, int] | None], path: Path | None = None)

property processed_data : list[ProcessedData]

property raw_data : list[BaseGraph]

property targets : list[int] | None

property sequences : list[pl.Sequence]

property states : list[dict[str, int]]

class BaseRemoteExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str, password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

property job_ids : list[str] | None

method run () → PasqalCloudExtracted

class RemoteQPUExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str = 'FRESNEL', password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

method run () → PasqalCloudExtracted

class RemoteEmuMPSExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str = 'FRESNEL', password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

method run (dt: int = 10) → PasqalCloudExtracted

module
qek.data.extractors

dataclass
Compiled (graph: BaseGraph, sequence: pl.Sequence)

dataclass
Feature (data: NDArray[np.floating])

class
BaseExtracted (device: Device)

property
processed_data : list[processed_data.ProcessedData]

property
raw_data : list[BaseGraph]

property
targets : list[int] | None

property
states : list[dict[str, int]]

method
features (size_max: int | None) → list[Feature]

method
save_dataset (file_path: Path) → None

class
SyncExtracted (raw_data: list[BaseGraph], targets: list[int] | None, sequences: list[pl.Sequence], states: list[dict[str, int]])

property
processed_data : list[ProcessedData]

property
raw_data : list[BaseGraph]

property
targets : list[int] | None

property
sequences : list[pl.Sequence]

property
states : list[dict[str, int]]

class
BaseExtractor (device: Device, compiler: BaseGraphCompiler[GraphType], path: Path | None = None)

method
save (snapshot: list[ProcessedData]) → None

method
compile (filter: Callable[[BaseGraph, pl.Sequence, int], bool] | None = None) → list[Compiled]

method
add_graphs (graphs: Sequence[GraphType] | Dataset[GraphType]) → None

method
run () → BaseExtracted

class
QutipExtractor (compiler: BaseGraphCompiler[GraphType], device: Device = pl.devices.AnalogDevice, path: Path | None = None)

method
run (max_qubits: int = 8) → SyncExtracted

class
EmuMPSExtractor (compiler: BaseGraphCompiler[GraphType], device: Device = pl.devices.AnalogDevice, path: Path | None = None)

method
run (max_qubits: int = 10, dt: int = 10) → BaseExtracted

class
PasqalCloudExtracted (compiled: list[Compiled], job_ids: list[str], sdk: SDK, state_extractor: Callable[[Job, pl.Sequence], dict[str, int] | None], path: Path | None = None)

property
processed_data : list[ProcessedData]

property
raw_data : list[BaseGraph]

property
targets : list[int] | None

property
sequences : list[pl.Sequence]

property
states : list[dict[str, int]]

class
BaseRemoteExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str, password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

property
job_ids : list[str] | None

method
run () → PasqalCloudExtracted

class
RemoteQPUExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str = 'FRESNEL', password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

method
run () → PasqalCloudExtracted

class
RemoteEmuMPSExtractor (compiler: BaseGraphCompiler[GraphType], project_id: str, username: str, device_name: str = 'FRESNEL', password: str | None = None, job_ids: list[str] | None = None, path: Path | None = None)

method
run (dt: int = 10) → PasqalCloudExtracted