qek.data.extractors

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

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

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

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

A feature extracted from raw data.

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

source property BaseExtracted.processed_data: list[processed_data.ProcessedData]

source property BaseExtracted.raw_data: list[BaseGraph]

A subset of the graphs ingested by the Extractor.

source property BaseExtracted.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.

source property BaseExtracted.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.

source method BaseExtracted.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.

source method BaseExtracted.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.

Note

The data is stored in a format suitable for loading with load_dataset.

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

source property SyncExtracted.processed_data: list[ProcessedData]

source property SyncExtracted.raw_data: list[BaseGraph]

source property SyncExtracted.targets: list[int] | None

source property SyncExtracted.sequences: list[pl.Sequence]

source property SyncExtracted.states: list[dict[str, int]]

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

source method BaseExtractor.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.

Note

The data is stored in a format suitable for loading with load_dataset.

source method BaseExtractor.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

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

Add new graphs to compile and run.

source method BaseExtractor.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

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

See Also

• EmuMPSExtractor (alternative emulator, generally much faster)
• QPUExtractor (run on a physical QPU)

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.

source method QutipExtractor.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.

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

See Also

• QPUExtractor (run on a physical QPU)

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.

source method EmuMPSExtractor.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.

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

source property PasqalCloudExtracted.processed_data: list[ProcessedData]

source property PasqalCloudExtracted.raw_data: list[BaseGraph]

source property PasqalCloudExtracted.targets: list[int] | None

source property PasqalCloudExtracted.sequences: list[pl.Sequence]

source property PasqalCloudExtracted.states: list[dict[str, int]]

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

source property BaseRemoteExtractor.job_ids: list[str] | None

source method BaseRemoteExtractor.run() → PasqalCloudExtracted

Launch the extraction.

Raises

• NotImplementedError

source 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 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 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

source method RemoteQPUExtractor.run() → PasqalCloudExtracted

source 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 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 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

source method RemoteEmuMPSExtractor.run(dt: int = 10) → PasqalCloudExtracted