Struct QuantumDevice

Struct Documentation

struct QuantumDevice

struct API for backend quantum devices.

This device API contains,

  • a set of methods to manage qubit allocations and deallocations, device shot noise, and quantum tape recording as well as reference values for the result data-type; these are used to implement Quantum Runtime (QR) instructions.

  • a set of methods for quantum operations, observables, measurements, and gradient of the device; these are used to implement Quantum Instruction Set (QIS) instructions.

Public Functions

QuantumDevice() = default
virtual ~QuantumDevice() = default
QuantumDevice &operator=(const QuantumDevice&) = delete
QuantumDevice(const QuantumDevice&) = delete
QuantumDevice(QuantumDevice&&) = delete
QuantumDevice &operator=(QuantumDevice&&) = delete
virtual auto AllocateQubit() -> QubitIdType = 0

Allocate a qubit.

Returns

QubitIdType

virtual auto AllocateQubits(size_t num_qubits) -> std::vector<QubitIdType> = 0

Allocate a vector of qubits.

Parameters

num_qubits – The number of qubits to allocate.

Returns

std::vector<QubitIdType>

virtual void ReleaseQubit(QubitIdType qubit) = 0

Release a qubit.

Parameters

qubit – The id of the qubit

virtual void ReleaseAllQubits() = 0

Release all qubits.

virtual auto GetNumQubits() const -> size_t = 0

Get the number of allocated qubits.

Returns

size_t

virtual void SetDeviceShots(size_t shots) = 0

Set the number of device shots.

Parameters

shots – The number of noise shots

virtual auto GetDeviceShots() const -> size_t = 0

Get the number of device shots.

Returns

size_t

virtual void StartTapeRecording() = 0

Start recording a quantum tape if provided.

Note

This is backed by the Catalyst::Runtime::CacheManager<ComplexT> property in the device implementation.

virtual void StopTapeRecording() = 0

Stop recording a quantum tape if provided.

Note

This is backed by the Catalyst::Runtime::CacheManager<ComplexT> property in the device implementation.

virtual auto Zero() const -> Result = 0

Result value for “Zero” used in the measurement process.

Returns

Result

virtual auto One() const -> Result = 0

Result value for “One” used in the measurement process.

Returns

Result

virtual void PrintState() = 0

A helper method to print the state vector of a device.

virtual void NamedOperation(const std::string &name, const std::vector<double> &params, const std::vector<QubitIdType> &wires, [[maybe_unused]] bool inverse = false, [[maybe_unused]] const std::vector<QubitIdType> &controlled_wires = {}, [[maybe_unused]] const std::vector<bool> &controlled_values = {}) = 0

Apply a single gate to the state vector of a device with its name if this is supported.

Parameters
  • name – The name of the gate to apply

  • params – Optional parameter list for parametric gates

  • wires – Wires to apply gate to

  • inverse – Indicates whether to use inverse of gate

  • controlled_wires – Optional controlled wires applied to the operation

  • controlled_values – Optional controlled values applied to the operation

virtual void MatrixOperation(const std::vector<std::complex<double>> &matrix, const std::vector<QubitIdType> &wires, [[maybe_unused]] bool inverse = false, [[maybe_unused]] const std::vector<QubitIdType> &controlled_wires = {}, [[maybe_unused]] const std::vector<bool> &controlled_values = {}) = 0

Apply a given matrix directly to the state vector of a device.

Parameters
  • matrix – The matrix of data in row-major format

  • wires – Wires to apply gate to

  • inverse – Indicates whether to use inverse of gate

  • controlled_wires – Controlled wires applied to the operation

  • controlled_values – Controlled values applied to the operation

virtual auto Observable(ObsId id, const std::vector<std::complex<double>> &matrix, const std::vector<QubitIdType> &wires) -> ObsIdType = 0

Construct a named (Identity, PauliX, PauliY, PauliZ, and Hadamard) or Hermitian observable.

Parameters
  • id – The type of the observable

  • matrix – The matrix of data to construct a hermitian observable

  • wires – Wires to apply observable to

Returns

ObsIdType Index of the constructed observable

virtual auto TensorObservable(const std::vector<ObsIdType> &obs) -> ObsIdType = 0

Construct a tensor product of observables.

Parameters

obs – The vector of observables indices of type ObsIdType

Returns

ObsIdType Index of the constructed observable

virtual auto HamiltonianObservable(const std::vector<double> &coeffs, const std::vector<ObsIdType> &obs) -> ObsIdType = 0

Construct a Hamiltonian observable.

Parameters
  • coeffs – The vector of coefficients

  • obs – The vector of observables indices of size coeffs

Returns

ObsIdType Index of the constructed observable

virtual auto Expval(ObsIdType obsKey) -> double = 0

Compute the expected value of an observable.

Parameters

obsKey – The index of the constructed observable

Returns

double The expected value

virtual auto Var(ObsIdType obsKey) -> double = 0

Compute the variance of an observable.

Parameters

obsKey – The index of the constructed observable

Returns

double The variance

virtual void State(DataView<std::complex<double>, 1> &state) = 0

Get the state-vector of a device.

Parameters

state – The pre-allocated DataView<complex<double>, 1>

virtual void Probs(DataView<double, 1> &probs) = 0

Compute the probabilities of each computational basis state.

Parameters

probs – The pre-allocated DataView<double, 1>

virtual void PartialProbs(DataView<double, 1> &probs, const std::vector<QubitIdType> &wires) = 0

Compute the probabilities for a subset of the full system.

Parameters
  • probs – The pre-allocated DataView<double, 1>

  • wires – Wires will restrict probabilities to a subset of the full system

virtual void Sample(DataView<double, 2> &samples, size_t shots) = 0

Compute samples with the number of shots on the entire wires, returing raw samples.

Parameters
  • samples – The pre-allocated DataView<double, 2>representing a matrix of shape shots * numQubits. The built-in iterator in DataView<double, 2> iterates over all elements of samples row-wise.

  • shots – The number of shots

virtual void PartialSample(DataView<double, 2> &samples, const std::vector<QubitIdType> &wires, size_t shots) = 0

Compute partial samples with the number of shots on wires, returing raw samples.

Parameters
  • samples – The pre-allocated DataView<double, 2>representing a matrix of shape shots * numWires. The built-in iterator in DataView<double, 2> iterates over all elements of samples row-wise.

  • wires – Wires to compute samples on

  • shots – The number of shots

virtual void Counts(DataView<double, 1> &eigvals, DataView<int64_t, 1> &counts, size_t shots) = 0

Sample with the number of shots on the entire wires, returning the number of counts for each sample.

Parameters
  • eigvals – The pre-allocated DataView<double, 1>

  • counts – The pre-allocated DataView<int64_t, 1>

  • shots – The number of shots

virtual void PartialCounts(DataView<double, 1> &eigvals, DataView<int64_t, 1> &counts, const std::vector<QubitIdType> &wires, size_t shots) = 0

Partial sample with the number of shots on wires, returning the number of counts for each sample.

Parameters
  • eigvals – The pre-allocated DataView<double, 1>

  • counts – The pre-allocated DataView<int64_t, 1>

  • wires – Wires to compute samples on

  • shots – The number of shots

virtual auto Measure(QubitIdType wire, std::optional<int32_t> postselect) -> Result = 0

A general measurement method that acts on a single wire.

Parameters
  • wire – The wire to compute Measure on

  • postselect – Which basis state to postselect after a mid-circuit measurement (-1 denotes no post-selection)

Returns

Result The measurement result

virtual void Gradient(std::vector<DataView<double, 1>> &gradients, const std::vector<size_t> &trainParams) = 0

Compute the gradient of a quantum tape, that is cached using Catalyst::Runtime::Simulator::CacheManager, for a specific set of trainable parameters.

Parameters
  • gradients – The vector of pre-allocated DataView<double, 1>* to store gradients resutls for the list of cached observables.

  • trainParams – The vector of trainable parameters; if none, all parameters would be assumed trainable