Base Classes

The base classes below are defined in pulser. Different backends inherit from and specialize them if needed.

Backend

Bases: ABC

The backend abstract base class.

Starts a new backend instance.

`run()` `abstractmethod`

Executes the sequence on the backend.

`validate_sequence(sequence, mimic_qpu=False)` `staticmethod`

Validates a sequence prior to submission.

EmulatorBackend

Bases: Backend

The emulator backend parent class.

Initializes the backend.

EmulationConfig

Bases: BackendConfig, Generic[StateType]

Configures an emulation on a backend.

PARAMETER	DESCRIPTION
`observables`	A sequence of observables to compute at specific evaluation times. The observables without specified evaluation times will use this configuration's 'default_evaluation_times'. TYPE: `Sequence[Observable]` DEFAULT: `()`
`default_evaluation_times`	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. TYPE: `Sequence[SupportsFloat] \| Literal['Full']` DEFAULT: `(1.0,)`
`initial_state`	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. TYPE: `StateType \| None` DEFAULT: `None`
`with_modulation`	Whether to emulate the sequence with the programmed input or the expected output. TYPE: `bool` DEFAULT: `False`
`interaction_matrix`	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. TYPE: `ArrayLike \| None` DEFAULT: `None`
`prefer_device_noise_model`	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. TYPE: `bool` DEFAULT: `False`
`noise_model`	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`. TYPE: `NoiseModel` DEFAULT: `NoiseModel()`

Note

Additional parameters may be provided. It is up to the emulation backend that receives a configuration with extra parameters to assess whether it recognizes them and how it will use them. To know all parameters expected by an EmulatorBackend, consult its associated EmulationConfig subclass found under 'EmulatorBackend.default_config'.

Initializes the EmulationConfig.

`from_abstract_repr(obj_str)` `classmethod`

Deserialize an EmulationConfig from an abstract JSON object.

PARAMETER	DESCRIPTION
`obj_str`	the JSON string representing the sequence encoded in the abstract JSON format. TYPE: `str`

RETURNS	DESCRIPTION
`EmulationConfig`	The EmulationConfig instance. TYPE: `EmulationConfig`

`is_evaluation_time(t, tol=1e-06)`

Assesses whether a relative time is an evaluation time.

`is_time_in_evaluation_times(t, evaluation_times, tol=1e-06)` `staticmethod`

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

`to_abstract_repr(skip_validation=False)`

Serialize EmulationConfig to a JSON formatted str.

Results

A collection of results.

PARAMETER	DESCRIPTION
`atom_order`	The order of the atoms/qudits in the results. TYPE: `tuple[str, ...]`
`total_duration`	The total duration of the sequence, in ns. TYPE: `int`

`from_abstract_repr(repr)` `classmethod`

Deserializes a Results object from json.

RETURNS	DESCRIPTION
`Results`	The deserialized Results object.

`get_result(observable, time)`

Get the a specific result at a given time.

PARAMETER	DESCRIPTION
`observable`	The observable instance used to calculate the result or its tag. TYPE: `Observable \| str`
`time`	Relative time at which to get the result. TYPE: `float`

RETURNS	DESCRIPTION
`Any`	The result.

`get_result_tags()`

Get a list of results tags present in this object.

`get_result_times(observable)`

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

PARAMETER	DESCRIPTION
`observable`	The observable instance used to calculate the result or its tag. TYPE: `Observable \| str`

RETURNS	DESCRIPTION
`list[float]`	List of relative times.

`get_tagged_results()`

Gets the results for every tag.

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

`to_abstract_repr(skip_validation=False)`

Serializes this object into a json string.

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

PARAMETER	DESCRIPTION
`skip_validation`	Whether to skip validating the json against the schema used for deserialization. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`str`	The json string

State

Bases: ABC, Generic[ArgScalarType, ReturnScalarType]

Base class enforcing an API for quantum states.

Each backend will implement its own type of state and the methods below.

Initializes a State.

`eigenstates` `property`

The eigenstates that form a qudit's eigenbasis.

The order of the states should match the order in a numerical (ie state vector or density matrix) representation. For example, with eigenstates ("a", "b", ...), "a" will be associated to eigenvector (1, 0, ...), "b" to (0, 1, ...) and so on.

`n_qudits` `abstractmethod` `property`

The number of qudits in the state.

`qudit_dim` `property`

The dimensions (ie number of eigenstates) of a qudit.

`from_state_amplitudes(*, eigenstates, amplitudes)` `classmethod`

Construct the state from its basis states' amplitudes.

Only states constructed with this method are allowed in remote backend.

PARAMETER	DESCRIPTION
`eigenstates`	The basis states (e.g., ('r', 'g')). TYPE: `Sequence[Eigenstate]`
`amplitudes`	A mapping between basis state combinations and complex amplitudes (e.g., {"rgr": 0.5, "grg": 0.5}). TYPE: `Mapping[str, ArgScalarType]`

RETURNS	DESCRIPTION
`StateType`	The state constructed from the amplitudes.

`get_basis_state_from_index(index)`

Generates a basis state combination from its index in the state.

Assumes a state vector representation regardless of the actual support of the state.

PARAMETER	DESCRIPTION
`index`	The position of the state in a state vector. TYPE: `int`

RETURNS	DESCRIPTION
`str`	The basis state combination for the desired index.

`infer_one_state()`

Infers the state measured as 1 from the eigenstates.

Only works when the eigenstates form a known eigenbasis with a well-defined "one state".

`overlap(other)` `abstractmethod`

Compute the overlap between this state and another of the same type.

Generally computes Tr[AB] for mixed states A and B, which corresponds to |<a|b>|^2 for pure states A=|a><a| and B=|b><b|.

PARAMETER	DESCRIPTION
`other`	The other state. TYPE: `StateType`

RETURNS	DESCRIPTION
`ReturnScalarType`	The overlap between the two states.

`sample(*, num_shots, one_state=None, p_false_pos=0.0, p_false_neg=0.0)` `abstractmethod`

Sample bitstrings from the state, taking into account error rates.

PARAMETER	DESCRIPTION
`num_shots`	How many bitstrings to sample. TYPE: `int`
`one_state`	The eigenstate that measures to 1. Can be left undefined if the state's eigenstates form a known eigenbasis with a defined "one state". TYPE: `Eigenstate \| None` DEFAULT: `None`
`p_false_pos`	The rate at which a 0 is read as a 1. TYPE: `float` DEFAULT: `0.0`
`p_false_neg`	The rate at which a 1 is read as a 0. TYPE: `float` DEFAULT: `0.0`

RETURNS	DESCRIPTION
`Counter[str]`	The measured bitstrings, by count.

StateRepr

Bases: State

Define a backend-independent quantum state representation.

Allows the user to define a quantum state with the usual dedicated class method from_state_amplitudes, which requires: - eigenstates: The basis states (e.g., ('r', 'g')). - amplitudes: A mapping between basis state combinations and complex amplitudes (e.g., {"rgr": 0.5, "grg": 0.5}).

The created state, supports de/serialization methods for remote backend execution.

Example:

eigenstates = ("r", "g")
amplitudes = {"rgr"=0.5, "grg"=0.5}
state = StateRepr.from_state_amplitudes(
    eigenstates=eigenstates, amplitudes=amplitudes
)

`n_qudits` `property`

The number of qudits in the state.

`overlap(other)`

overlap not implemented in StateRepr.

`sample(*, num_shots, one_state=None, p_false_pos=0.0, p_false_neg=0.0)`

sample not implemented in StateRepr.

Operator

Bases: ABC, Generic[ArgScalarType, ReturnScalarType, StateType]

Base class enforcing an API for quantum operator.

Each backend will implement its own type of state and the methods below.

Initializes an Operator.

`add(other)` `abstractmethod`

Computes the sum of two operators.

PARAMETER	DESCRIPTION
`other`	The other operator. TYPE: `OperatorType`

RETURNS	DESCRIPTION
`OperatorType`	The summed operator.

`matmul(other)` `abstractmethod`

Compose two operators where 'self' is applied after 'other'.

PARAMETER	DESCRIPTION
`other`	The operator to compose with self. TYPE: `OperatorType`

RETURNS	DESCRIPTION
`OperatorType`	The composed operator.

`rmul(scalar)` `abstractmethod`

Scale the operator by a scalar factor.

PARAMETER	DESCRIPTION
`scalar`	The scalar factor. TYPE: `ArgScalarType`

RETURNS	DESCRIPTION
`OperatorType`	The scaled operator.

`apply_to(state)` `abstractmethod`

Apply the operator to a state.

PARAMETER	DESCRIPTION
`state`	The state to apply this operator to. TYPE: `StateType`

RETURNS	DESCRIPTION
`StateType`	The resulting state.

`expect(state)` `abstractmethod`

Compute the expectation value of self on the given state.

PARAMETER	DESCRIPTION
`state`	The state with which to compute. TYPE: `StateType`

RETURNS	DESCRIPTION
`ReturnScalarType`	The expectation value.

`from_operator_repr(*, eigenstates, n_qudits, operations)` `classmethod`

Create an operator from the operator representation.

Only operators constructed with this method are allowed in remote backend.

The full operator representation (FullOp) is a weigthed sum of tensor operators (TensorOp), written as a sequence of coefficient and tensor operator pairs, ie

FullOp = Sequence[tuple[ScalarType, TensorOp]]

Each TensorOp is itself a sequence of qudit operators (QuditOp) applied to mutually exclusive sets of qudits (represented by their indices), ie

TensorOp = Sequence[tuple[QuditOp, Collection[int]]]

Qudits without an associated QuditOp are applied the identity operator.

Finally, each QuditOp is represented as weighted sum of pre-defined single-qudit operators. It is given as a mapping between a string representation of the single-qudit operator and its respective coefficient, ie

QuditOp = Mapping[str, ScalarType]

By default it identifies strings "ij" as single-qudit operators, where i and j are eigenstates that denote |i><j|.

PARAMETER	DESCRIPTION
`eigenstates`	The eigenstates to use. TYPE: `Sequence[Eigenstate]`
`n_qubits`	How many qubits there are in the system.
`operations`	The full operator representation. TYPE: `FullOp[ArgScalarType]`

RETURNS	DESCRIPTION
`OperatorType`	The constructed operator.

OperatorRepr

Bases: Operator

Define a backend-independent quantum operator representation.

Allows the user to define a quantum operator with the dedicated class method from_operator_repr, which requires: - eigenstates: The basis states (e.g., ('r', 'g')). - n_qudits: Number of qudits in the system. - operations: A sequence of tuples weight, tensor operators on each qudit, as described in from_operator_repr.

The created operator, supports de/serialization methods for remote backend execution.

Example:

eigenstates = ("r", "g")
n_qudits = 4
# define X,Y,Z
X = {"gr": 1.0, "rg": 1.0}
Y = {"gr": 1.0j, "rg": -1.0j}
Z = {"rr": 1.0, "gg": -1.0}
# build for example 0.5*X0Y1X2Z3
operations = [
    (
        0.5,
        [
            (X, [0, 2]), # acts on qudit 0 and 2
            (Y, [1]),
            (Z, [3]),
        ],
    )
]
op = OperatorRepr.from_operator_repr(
    eigenstates=eigenstates,
    n_qudits=n_qudits,
    operations=operations
)

`add(other)`

__add__ not implemented in OperatorRepr.

`matmul(other)`

__matmul__ not implemented in OperatorRepr.

`rmul(scalar)`

__rmul__ not implemented in OperatorRepr.

`apply_to(state)`

apply_to not implemented in OperatorRepr.

`expect(state)`

expect not implemented in OperatorRepr.

Observable

Bases: Callback

The Observable abstract base class.

PARAMETER	DESCRIPTION
`evaluation_times`	The times at which to add a result to Results. If left as `None`, uses the `default_evaluation_times` of the backend's `EmulationConfig`. TYPE: `Sequence[float] \| None` DEFAULT: `None`
`tag_suffix`	An optional suffix to append to the tag. Needed if multiple instances of the same observable are given to the same EmulationConfig. TYPE: `str \| None` DEFAULT: `None`

Initializes the observable.

`tag` `property`

Label for the observable, used to index the Results object.

Within a Results instance, all computed observables must have different tags.

RETURNS	DESCRIPTION
`str`	The tag of the observable.

`call(config, t, state, hamiltonian, result)`

Specifies a call to the observable at a specific time.

This is called after each time step performed by the emulator. By default it calls apply() to compute a result and put it in Results if t in self.evaluation_times. It can be overloaded to define general callbacks that don't put results in the Results object.

PARAMETER	DESCRIPTION
`config`	The config object passed to the backend. TYPE: `EmulationConfig`
`t`	The relative time as a float between 0 and 1. TYPE: `float`
`state`	The current state. TYPE: `State`
`hamiltonian`	The Hamiltonian at this time. TYPE: `Operator`
`result`	The Results object to store the result in. TYPE: `Results`
`time_tol`	Tolerance below which two time values are considered equal.

`apply(*, config, state, hamiltonian)` `abstractmethod`

Calculates the observable to store in the Results.

PARAMETER	DESCRIPTION
`config`	The config object passed to the backend. TYPE: `EmulationConfig`
`state`	The current state. TYPE: `State`
`hamiltonian`	The Hamiltonian at this time. TYPE: `Operator`

RETURNS	DESCRIPTION
`Any`	The result to put in Results.

Base Classes

Backend

run() abstractmethod

validate_sequence(sequence, mimic_qpu=False) staticmethod

EmulatorBackend

EmulationConfig

from_abstract_repr(obj_str) classmethod

is_evaluation_time(t, tol=1e-06)

is_time_in_evaluation_times(t, evaluation_times, tol=1e-06) staticmethod

to_abstract_repr(skip_validation=False)

Results

from_abstract_repr(repr) classmethod

get_result(observable, time)

get_result_tags()

get_result_times(observable)

get_tagged_results()

to_abstract_repr(skip_validation=False)

State

eigenstates property

n_qudits abstractmethod property

qudit_dim property

from_state_amplitudes(*, eigenstates, amplitudes) classmethod

get_basis_state_from_index(index)

infer_one_state()

overlap(other) abstractmethod

sample(*, num_shots, one_state=None, p_false_pos=0.0, p_false_neg=0.0) abstractmethod

StateRepr

n_qudits property

overlap(other)

sample(*, num_shots, one_state=None, p_false_pos=0.0, p_false_neg=0.0)

Operator

__add__(other) abstractmethod

__matmul__(other) abstractmethod

__rmul__(scalar) abstractmethod

apply_to(state) abstractmethod

expect(state) abstractmethod

from_operator_repr(*, eigenstates, n_qudits, operations) classmethod

OperatorRepr

__add__(other)

__matmul__(other)

__rmul__(scalar)

apply_to(state)

expect(state)

Observable

tag property

__call__(config, t, state, hamiltonian, result)

apply(*, config, state, hamiltonian) abstractmethod

`run()` `abstractmethod`

`validate_sequence(sequence, mimic_qpu=False)` `staticmethod`

`from_abstract_repr(obj_str)` `classmethod`

`is_evaluation_time(t, tol=1e-06)`

`is_time_in_evaluation_times(t, evaluation_times, tol=1e-06)` `staticmethod`

`to_abstract_repr(skip_validation=False)`

`from_abstract_repr(repr)` `classmethod`

`get_result(observable, time)`

`get_result_tags()`

`get_result_times(observable)`

`get_tagged_results()`

`to_abstract_repr(skip_validation=False)`

`eigenstates` `property`

`n_qudits` `abstractmethod` `property`

`qudit_dim` `property`

`from_state_amplitudes(*, eigenstates, amplitudes)` `classmethod`

`get_basis_state_from_index(index)`

`infer_one_state()`

`overlap(other)` `abstractmethod`

`sample(*, num_shots, one_state=None, p_false_pos=0.0, p_false_neg=0.0)` `abstractmethod`

`n_qudits` `property`

`overlap(other)`

`sample(*, num_shots, one_state=None, p_false_pos=0.0, p_false_neg=0.0)`

`add(other)` `abstractmethod`

`matmul(other)` `abstractmethod`

`rmul(scalar)` `abstractmethod`

`apply_to(state)` `abstractmethod`

`expect(state)` `abstractmethod`

`from_operator_repr(*, eigenstates, n_qudits, operations)` `classmethod`

`add(other)`

`matmul(other)`

`rmul(scalar)`

`apply_to(state)`

`expect(state)`

`tag` `property`

`call(config, t, state, hamiltonian, result)`

`apply(*, config, state, hamiltonian)` `abstractmethod`