qoolqit.execution

package

qoolqit.execution

Classes

• SequenceCompiler — Compiles a QoolQit Register and Drive to a Device.

• CompilerProfile

• LocalEmulator — Run QoolQit QuantumPrograms on a Pasqal local emulator backends.

• RemoteEmulator — Run QoolQit QuantumPrograms on a Pasqal remote emulator backends.

• QPU — Run QoolQit QuantumPrograms on a Pasqal QPU.

• EmulationConfig — Configures an emulation on a backend.

• BitStrings — Stores bitstrings sampled from the state at the evaluation times.

• CorrelationMatrix — Stores the correlation matrix for the current state.

• Energy — Stores the energy of the system at the evaluation times.

• EnergySecondMoment — Stores the expectation value of H(t)^2 at the evaluation times.

• EnergyVariance — Stores the variance of the Hamiltonian at the evaluation times.

• Expectation — Stores the expectation of the given operator on the current state.

• Fidelity — Stores the fidelity with a pure state at the evaluation times.

• Occupation — Stores the occupation number of an eigenstate on each qudit.

• StateResult — Stores the quantum state at the evaluation times.

• Results — A collection of results.

• RemoteResults — A collection of results obtained through a remote connection.

Modules

• BackendType — A module gathering all available backends.

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

property

register : Register

property

drive : Drive

property

device : Device

property

profile : CompilerProfile

The compiler profile to use.

method

compile_sequence () → PulserSequence

Raises

• error

• CompilationError

enum

CompilerProfile (*args, **kwds)

Bases : StrEnum

Attributes

• DEFAULT

• MAX_AMPLITUDE

• MAX_DURATION

• MIN_DISTANCE

class

LocalEmulator (*, backend_type: type[EmulatorBackend] = QutipBackendV2, emulation_config: Optional[EmulationConfig] = None, runs: int = 100)

Bases : PulserEmulatorBackend

Run QoolQit QuantumPrograms on a Pasqal local emulator backends.

This class serves as a primary interface between tools written using QoolQit (including solvers) and local emulator backends.

Parameters

• backend_type : type — backend type. Must be a subtype of pulser.backend.EmulatorBackend.

• emulation_config : EmulationConfig — optional configuration object emulators.

• runs : int — number of bitstring samples to collect from the final quantum state. It emulates running the program runs times to collect bitstrings statistics.

Examples

from qoolqit.execution import LocalEmulator, BackendType
backend = LocalEmulator(backend_type=BackendType.QutipBackendV2)
result = backend.run(program)

Methods

• run — Run a compiled QuantumProgram and return the results.

method

run (program: QuantumProgram) → Sequence[Results]

Run a compiled QuantumProgram and return the results.

class

RemoteEmulator (*, backend_type: type[RemoteEmulatorBackend] = EmuFreeBackendV2, connection: RemoteConnection, emulation_config: Optional[EmulationConfig] = None, runs: int = 100)

Bases : PulserEmulatorBackend, PulserRemoteBackend

Run QoolQit QuantumPrograms on a Pasqal remote emulator backends.

This class serves as a primary interface between tools written using QoolQit (including solvers) and remote emulator backends. The behavior is similar to LocalEmulator, but here, requires credentials through a connection to submit/run a program. To get your credentials and to create a connection object, please refer to the Pasqal Cloud interface documentation (external).

Parameters

• backend_type : type — backend type. Must be a subtype of pulser_pasqal.backends.RemoteEmulatorBackend.

• connection : RemoteConnection — connection to execute the program on remote backends.

• emulation_config : EmulationConfig — optional configuration object emulators.

• runs : int — number of bitstring samples to collect from the final quantum state. It emulates running the program runs times to collect bitstrings statistics.

Examples

from pulser_pasqal import PasqalCloud
from qoolqit.execution import RemoteEmulator, BackendType
connection = PasqalCloud(username=..., password=..., project_id=...)
backend = RemoteEmulator(backend_type=BackendType.EmuFreeBackendV2, connection=connection)

then

remote_results = backend.submit(program)

or

results = backend.run(program)

Methods

• submit — Submit a compiled QuantumProgram and return a remote handler of the results.

• run — Run a compiled QuantumProgram remotely and return the results.

method

submit (program: QuantumProgram, wait: bool = False) → RemoteResults

Submit a compiled QuantumProgram and return a remote handler of the results.

The returned handler `RemoteResults` can be used to

• query the job status with remote_results.get_batch_status()
• when DONE, retrieve results with remote_results.results

Parameters

• program : QuantumProgram — the compiled quantum program to run.

• wait : bool — Wait for remote backend to complete the job.

method

run (program: QuantumProgram) → Sequence[Results]

Run a compiled QuantumProgram remotely and return the results.

class

QPU (*, connection: RemoteConnection, runs: int = 100)

Bases : PulserRemoteBackend

Run QoolQit QuantumPrograms on a Pasqal QPU.

This class serves as a primary interface between tools written using QoolQit (including solvers) and QPU backend. It requires credentials through a connection to submit/run a program. Please, contact your provider to get your credentials and get help on how create a connection object: - Pasqal Cloud interface documentation (external) - Atos MyQML framework (external)

Parameters

• connection : RemoteConnection — connection to execute the program on remote backends.

• runs : int — run the program runs times to collect bitstrings statistics.

Examples

from pulser_pasqal import PasqalCloud
from qoolqit.execution import QPU
connection = PasqalCloud(username=..., password=..., project_id=...)
backend = QPU(connection=connection)
remote_results = backend.submit(program)

Methods

• submit — Submit a compiled QuantumProgram and return a remote handler of the results.

• run — Run a compiled QuantumProgram remotely and return the results.

method

submit (program: QuantumProgram, wait: bool = False) → RemoteResults

Submit a compiled QuantumProgram and return a remote handler of the results.

The returned handler `RemoteResults` can be used to

• query the job status with remote_results.get_batch_status()
• when DONE, retrieve results with remote_results.results

Parameters

• program : QuantumProgram — the compiled quantum program to run.

• wait : bool — Wait for remote backend to complete the job.

method

run (program: QuantumProgram) → Sequence[Results]

Run a compiled QuantumProgram remotely and return the results.

class

EmulationConfig (*, callbacks: Sequence[Callback] = (), observables: Sequence[Observable] = (), default_evaluation_times: Sequence[SupportsFloat] | Literal['Full'] = (1.0,), initial_state: StateType | None = None, with_modulation: bool = False, interaction_matrix: ArrayLike | None = None, prefer_device_noise_model: bool = False, noise_model: NoiseModel = NoiseModel(), **backend_options: Any)

Bases : BackendConfig, Generic[StateType]

Configures an emulation on a backend.

Initializes the EmulationConfig.

Parameters

• observables : Sequence[Observable] — A sequence of observables to compute at specific evaluation times. The observables without specified evaluation times will use this configuration's 'default_evaluation_times'.

• callbacks : Sequence[Callback] — A general callback that is not an observable. Observables must be fed into the observables arg, since they all interact with the Results, and are subject to additional validation. Unlike observables, these are called at every emulation step.

• default_evaluation_times : Sequence[SupportsFloat] | Literal['Full'] — The default times at which observables are computed. Can be a sequence of unique relative times between 0 (the start of the sequence) and 1 (the end of the sequence), in ascending order. Can also be specified as "Full", in which case every step in the emulation will also be an evaluation time.

• initial_state : StateType | None — The initial state from which emulation starts. If specified, the state type needs to be compatible with the emulator backend. If left undefined, defaults to starting with all qudits in the ground state.

• with_modulation : bool — Whether to emulate the sequence with the programmed input or the expected output.

• interaction_matrix : ArrayLike | None — An optional interaction matrix to replace the interaction terms in the Hamiltonian. For an N-qudit system, must be an NxN symmetric matrix where entry (i, j) dictates the interaction coefficient between qudits i and j, ie it replaces the C_n/r_{ij}^n term.

• prefer_device_noise_model : bool — If True, uses the noise model of the sequence's device (if the sequence's device has one), regardless of the noise model given with this configuration.

• noise_model : NoiseModel — An optional noise model to emulate the sequence with. Ignored if the sequence's device has default noise model and prefer_device_noise_model=True.

Methods

• is_evaluation_time — Assesses whether a relative time is an evaluation time.

• is_time_in_evaluation_times — Checks if a time is within a collection of evaluation times.

• to_abstract_repr — Serialize EmulationConfig to a JSON formatted str.

• from_abstract_repr — Deserialize an EmulationConfig from an abstract JSON object.

method

is_evaluation_time (t: float, tol: float = 1e-06) → bool

Assesses whether a relative time is an evaluation time.

staticmethod

is_time_in_evaluation_times (t: float, evaluation_times: ArrayLike, tol: float = 1e-06) → bool

Checks if a time is within a collection of evaluation times.

method

to_abstract_repr (skip_validation: bool = False) → str

Serialize EmulationConfig to a JSON formatted str.

classmethod

from_abstract_repr (obj_str: str) → EmulationConfig

Deserialize an EmulationConfig from an abstract JSON object.

Parameters

• obj_str : str — the JSON string representing the sequence encoded in the abstract JSON format.

Returns

• EmulationConfig — The EmulationConfig instance.

Raises

• TypeError

class

BitStrings (*, evaluation_times: Sequence[float] | None = None, num_shots: int = 1000, one_state: Eigenstate | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores bitstrings sampled from the state at the evaluation times.

Error rates are taken from the NoiseModel passed to the backend via the EmulationConfig. The bitstrings are stored as a Counter[str].

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to sample bitstrings. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• num_shots : int — How many bitstrings to sample each time this observable is computed.

• one_state : Eigenstate | None — The eigenstate that measures to 1. Can be left undefined if the state's eigenstates form a known eigenbasis with a defined "one state".

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, config: EmulationConfig, state: State, **kwargs: Any) → Counter[str]

Calculates the observable to store in the Results.

class

CorrelationMatrix (*, evaluation_times: Sequence[float] | None = None, one_state: Eigenstate | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the correlation matrix for the current state.

The correlation matrix is calculated as [[<φ(t)|n_i n_j|φ(t)> for j in qubits] for i in qubits] where n_k = |one_state><one_state|.

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to compute the correlation matrix. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• one_state : Eigenstate | None — The eigenstate to measure the population of in the correlation matrix. Can be left undefined if the state's eigenstates form a known eigenbasis with a defined "one state".

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: State, hamiltonian: Operator, **kwargs: Any) → list[list]

Calculates the observable to store in the Results.

class

Energy (*, evaluation_times: Sequence[float] | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the energy of the system at the evaluation times.

The energy is calculated as the expectation value of the Hamiltonian, i.e. <φ(t)|H(t)|φ(t)>.

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to compute the energy. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: State, hamiltonian: Operator, **kwargs: Any) → Any

Calculates the observable to store in the Results.

class

EnergySecondMoment (*, evaluation_times: Sequence[float] | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the expectation value of H(t)^2 at the evaluation times.

Useful for computing the variance when averaging over many executions of the program.

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to compute the variance. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: State, hamiltonian: Operator, **kwargs: Any) → Any

Calculates the observable to store in the Results.

class

EnergyVariance (*, evaluation_times: Sequence[float] | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the variance of the Hamiltonian at the evaluation times.

The variance of the Hamiltonian at time t is calculated by <φ(t)|H(t)^2|φ(t)> - <φ(t)|H(t)|φ(t)>^2

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to compute the variance. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: State, hamiltonian: Operator, **kwargs: Any) → Any

Calculates the observable to store in the Results.

class

Expectation (operator: Operator, *, evaluation_times: Sequence[float] | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the expectation of the given operator on the current state.

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to compute the expectation value. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• operator : Operator — The operator to measure. Must be of the appropriate type for the backend.

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: State, **kwargs: Any) → Any

Calculates the observable to store in the Results.

class

Fidelity (state: State, *, evaluation_times: Sequence[float] | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the fidelity with a pure state at the evaluation times.

The fidelity uses the overlap between the given state and the state of the system at each evaluation time. For pure states, this corresponds to |<ψ|φ(t)>|^2 for the given state |ψ> and the state |φ(t)> obtained by time evolution.

Initializes the observable.

Parameters

• state : State — The state |ψ>. Note that this must be of an appropriate type for the backend.

• evaluation_times : Sequence[float] | None — The relative times at which to compute the fidelity. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: State, **kwargs: Any) → Any

Calculates the observable to store in the Results.

class

Occupation (*, evaluation_times: Sequence[float] | None = None, one_state: Eigenstate | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the occupation number of an eigenstate on each qudit.

For every qudit i, calculates <φ(t)|n_i|φ(t)>, where n_i = |one_state><one_state|.

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to compute the correlation matrix. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• one_state : Eigenstate | None — The eigenstate to measure the population of. Can be left undefined if the state's eigenstates form a known eigenbasis with a defined "one state".

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: State, hamiltonian: Operator, **kwargs: Any) → list

Calculates the observable to store in the Results.

class

StateResult (*, evaluation_times: Sequence[float] | None = None, tag_suffix: str | None = None)

Bases : Observable

Stores the quantum state at the evaluation times.

Initializes the observable.

Parameters

• evaluation_times : Sequence[float] | None — The relative times at which to store the state. If left as None, uses the default_evaluation_times of the backend's EmulationConfig.

• tag_suffix : str | None — An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig.

Attributes

• uuid : uuid.UUID — A universal unique identifier for this instance.

• tag : str — Label for the observable, used to index the Results object.

Methods

• apply — Calculates the observable to store in the Results.

method

apply (*, state: StateType, **kwargs: Any) → StateType

Calculates the observable to store in the Results.

dataclass

Results (atom_order: tuple[str, ...], total_duration: int)

A collection of results.

Parameters

• atom_order : tuple[str, ...] — The order of the atoms/qudits in the results.

• total_duration : int — The total duration of the sequence, in ns.

Attributes

• final_bitstrings : dict[str, int] — Returns the bitstrings at the end of the sequence, if available.

• final_state : State — Returns the state at the end of the sequence, if available.

Methods

• get_result_tags — Get a list of results tags present in this object.

• get_result_times — Get a list of times for which the given result has been stored.

• get_result — Get the a specific result at a given time.

• get_tagged_results — Gets the results for every tag.

• to_abstract_repr — Serializes this object into a json string.

• from_abstract_repr — Deserializes a Results object from json.

• aggregate — Aggregate a Sequence of Results objects into a single Results.

property

final_bitstrings : dict[str, int]

Returns the bitstrings at the end of the sequence, if available.

property

final_state : State

Returns the state at the end of the sequence, if available.

method

get_result_tags () → list[str]

Get a list of results tags present in this object.

method

get_result_times (observable: Observable | str) → list[float]

Get a list of times for which the given result has been stored.

Parameters

• observable : Observable | str — The observable instance used to calculate the result or its tag.

Returns

• list[float] — List of relative times.

method

get_result (observable: Observable | str, time: float) → Any

Get the a specific result at a given time.

Parameters

• observable : Observable | str — The observable instance used to calculate the result or its tag.

• time : float — Relative time at which to get the result.

Returns

• Any — The result.

Raises

• ValueError

method

get_tagged_results () → dict[str, list[Any]]

Gets the results for every tag.

Returns

• dict[str, list[Any]] — A mapping between a tag and the results associated to it, at every evaluation time.

method

to_abstract_repr (skip_validation: bool = False) → str

Serializes this object into a json string.

Numpy arrays and torch Tensors are converted into lists, and their original class is lost forever.

Parameters

• skip_validation : bool — Whether to skip validating the json against the schema used for deserialization.

Returns

• str — The json string

classmethod

from_abstract_repr (repr: str) → Results

Deserializes a Results object from json.

Returns

• Results — The deserialized Results object.

classmethod

aggregate (results_to_aggregate: typing.Sequence[Results], **aggregation_functions: Callable[[Any], Any]) → Results

Aggregate a Sequence of Results objects into a single Results.

This is meant to accumulate the results of several runs with different noise trajectories into a single averaged Results. By default, results are averaged, with the exception of BitStrings, where the counters are joined. StateResult and EnergyVariance are not supported by default.

Parameters

• results_to_aggregate : typing.Sequence[Results] — The list of Results to aggregate

Keyword Args

observable_tag: Overrides the default aggregator. The argument name should be the tag of the Observable. The value is a Callable taking a list of the type to aggregate. Note that this does not override the default aggregation behaviour of the aggregated results.

Returns

• Results — The averaged Results object

Raises

• ValueError

• NotImplementedError

class

RemoteResults (batch_id: str, connection: RemoteConnection, job_ids: list[str] | None = None)

Bases : ResultsSequence

A collection of results obtained through a remote connection.

Instantiates a new collection of remote results.

Parameters

• batch_id : str — The ID that identifies the batch linked to the results.

• connection : RemoteConnection — The remote connection over which to get the batch's status and fetch the results.

• job_ids : list[str] | None — If given, specifies which jobs within the batch should be included in the results and in what order. If left undefined, all jobs are included.

Attributes

• results : tuple[Results, ...] — The actual results, obtained after execution is done.

• batch_id : str — The ID of the batch containing these results.

• job_ids : list[str] — The IDs of the jobs within these results' batch.

Methods

• get_batch_status — Gets the status of the batch linked to these results.

• get_available_results — Returns the available results.

property

results : tuple[Results, ...]

The actual results, obtained after execution is done.

property

batch_id : str

The ID of the batch containing these results.

property

job_ids : list[str]

The IDs of the jobs within these results' batch.

method

get_batch_status () → BatchStatus

Gets the status of the batch linked to these results.

method

get_available_results () → dict[str, Results]

Returns the available results.

Unlike the results property, this method does not raise an error if some of the jobs do not have results.

Returns

• dict[str, Results] — A dictionary mapping the job ID to its results. Jobs with no result are omitted.

module

BackendType

A module gathering all available backends.

This module is a single-point access to backends spread across different packages. As long as the appropriate package is installed, the Backend instances defined within it should be importable via this module, like so::

import pulser.backends as backends

backends.QPUBackend  # Same as pulser.QPUBackend
backends.QutipBackendV2  # Same as pulser_simulation.QutipBackendV2

Attributes

• QPUBackend — See :py:class:pulser.backend.QPUBackend.

• QutipBackend — See :py:class:pulser_simulation.QutipBackend.

• QutipBackendV2 — See :py:class:pulser_simulation.QutipBackendV2.

• EmuFreeBackend — See :py:class:pulser_pasqal.EmuFreeBackend.

• EmuFreeBackendV2 — See :py:class:pulser_pasqal.EmuFreeBackendV2.

• EmuTNBackend — See :py:class:pulser_pasqal.EmuTNBackend.

• EmuMPSBackend — See :py:class:pulser_pasqal.EmuMPSBackend.

• MPSBackend — See emu_mps.MPSBackend <https://pypi.org/project/emu-mps/>_.

• SVBackend — See emu_sv.SVBackend <https://pypi.org/project/emu-sv/>_.